@indigoai-us/hq-cli 5.187.0 → 5.188.1

package/dist/lib/lanes/claude-account-balance.d.ts

@@ -0,0 +1,82 @@
+import type { HostCapacityAccount, HostCapacitySnapshot } from "./host-capacity.js";
+import type { LaneHost, LaneRecord, LanesConfig } from "./types.js";
+export declare const CLAUDE_ACCOUNT_BALANCE_FLAG = "lanes.claude-account-balance";
+export declare const BALANCE_LIVE_STATES: readonly ["running", "queued", "awaiting_input"];
+export declare const BALANCE_MOVABLE_STATES: readonly ["interrupted", "done", "awaiting_input"];
+export interface BalanceHostSnapshot {
+    capacity: HostCapacitySnapshot;
+    lanes: readonly LaneRecord[];
+    /** False means the lane list could not be read; capacity counts may be partial. */
+    laneListAvailable: boolean;
+}
+export interface BalanceHostGap {
+    host: LaneHost | {
+        kind: "unknown";
+        id: "unknown";
+    };
+    reason: string;
+}
+export interface AccountHostLoad {
+    host: LaneHost;
+    enabled: boolean;
+    logged_in: boolean | null;
+    live_lanes: number | null;
+    lane_counts: {
+        running: number | null;
+        queued: number | null;
+        awaiting_input: number | null;
+    };
+    count_source: "lane_list" | "capacity" | "capacity_partial" | "unavailable";
+}
+export interface ClaudeAccountLoad {
+    account: string;
+    target_enabled: boolean;
+    target_logged_in: boolean | null;
+    eligible: boolean;
+    ineligible_reason?: string;
+    live_lanes: number;
+    counts_complete: boolean;
+    usage: NonNullable<HostCapacityAccount["usage"]> | null;
+    hosts: AccountHostLoad[];
+}
+export interface ClaudeAccountSelection {
+    account: string;
+    signal: "usage" | "lane_count" | "explicit";
+    reason: "least_loaded" | "explicit";
+    target_host: LaneHost;
+    considered: ClaudeAccountLoad[];
+    skipped_accounts: Array<{
+        account: string;
+        host: LaneHost;
+        reason: string;
+    }>;
+    unavailable_hosts: BalanceHostGap[];
+}
+export interface BalanceMoveSuggestion {
+    lane_id: string;
+    host: LaneHost;
+    state: LaneRecord["state"];
+    from: string;
+    to: string;
+    reason: "account_load" | "source_unavailable";
+    apply: boolean;
+    skip_reason?: "running_turn" | "state_not_movable" | "no_provider_session" | "pending_resume";
+}
+export declare function selectClaudeAccount(input: {
+    hosts: readonly BalanceHostSnapshot[];
+    targetHost: LaneHost;
+    config: LanesConfig;
+    allowedAccounts?: readonly string[];
+    explicitAccount?: string;
+    unavailableHosts?: readonly BalanceHostGap[];
+}): ClaudeAccountSelection;
+export declare function accountLoadsForReport(input: {
+    hosts: readonly BalanceHostSnapshot[];
+    config: LanesConfig;
+}): ClaudeAccountLoad[];
+export declare function planClaudeBalanceMoves(input: {
+    hosts: readonly BalanceHostSnapshot[];
+    config: LanesConfig;
+}): BalanceMoveSuggestion[];
+export declare function assertBalanceApplyEnabled(enabled: boolean): void;
+//# sourceMappingURL=claude-account-balance.d.ts.map

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

@@ -0,0 +1,253 @@
+import { LanesError } from "./errors.js";
+export const CLAUDE_ACCOUNT_BALANCE_FLAG = "lanes.claude-account-balance";
+export const BALANCE_LIVE_STATES = ["running", "queued", "awaiting_input"];
+export const BALANCE_MOVABLE_STATES = ["interrupted", "done", "awaiting_input"];
+function sameHost(a, b) {
+    return a.kind === b.kind && a.id === b.id;
+}
+function isBalanceLive(lane) {
+    return BALANCE_LIVE_STATES.includes(lane.state);
+}
+function countLaneStates(lanes, account) {
+    const rows = lanes.filter((lane) => lane.provider === "claude" && lane.account === account && isBalanceLive(lane));
+    const running = rows.filter((lane) => lane.state === "running").length;
+    const queued = rows.filter((lane) => lane.state === "queued").length;
+    const awaiting_input = rows.filter((lane) => lane.state === "awaiting_input").length;
+    return { running, queued, awaiting_input, live: running + queued + awaiting_input };
+}
+function accountHostLoad(host, accountId) {
+    const hostCapacity = host.capacity.providers.claude.accounts[accountId];
+    if (!hostCapacity) {
+        return {
+            host: host.capacity.host,
+            enabled: false,
+            logged_in: false,
+            live_lanes: host.laneListAvailable ? countLaneStates(host.lanes, accountId).live : null,
+            lane_counts: host.laneListAvailable
+                ? countLaneStates(host.lanes, accountId)
+                : { running: null, queued: null, awaiting_input: null },
+            count_source: host.laneListAvailable ? "lane_list" : "unavailable",
+        };
+    }
+    if (host.laneListAvailable) {
+        const counts = countLaneStates(host.lanes, accountId);
+        return {
+            host: host.capacity.host,
+            enabled: hostCapacity.enabled,
+            logged_in: hostCapacity.logged_in,
+            live_lanes: counts.live,
+            lane_counts: { running: counts.running, queued: counts.queued, awaiting_input: counts.awaiting_input },
+            count_source: "lane_list",
+        };
+    }
+    if (hostCapacity.lane_counts !== undefined) {
+        return {
+            host: host.capacity.host,
+            enabled: hostCapacity.enabled,
+            logged_in: hostCapacity.logged_in,
+            live_lanes: hostCapacity.lane_counts.live,
+            lane_counts: {
+                running: hostCapacity.lane_counts.running,
+                queued: hostCapacity.lane_counts.queued,
+                awaiting_input: hostCapacity.lane_counts.awaiting_input,
+            },
+            count_source: "capacity",
+        };
+    }
+    return {
+        host: host.capacity.host,
+        enabled: hostCapacity.enabled,
+        logged_in: hostCapacity.logged_in,
+        live_lanes: hostCapacity.running + hostCapacity.queued,
+        lane_counts: { running: hostCapacity.running, queued: hostCapacity.queued, awaiting_input: null },
+        count_source: "capacity_partial",
+    };
+}
+function usageScore(usage) {
+    if (usage?.five_hour_percent === undefined || usage.weekly_percent === undefined)
+        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 targetIneligibilityReason(accountId, globalEnabled, allowedAccounts, target) {
+    if (!globalEnabled || !target.enabled)
+        return "disabled";
+    if (allowedAccounts !== undefined && !allowedAccounts.includes(accountId))
+        return "not_allowed_by_lane";
+    if (target.logged_in === false)
+        return "not_logged_in";
+    if (target.logged_in === null)
+        return "login_status_unknown";
+    return undefined;
+}
+function buildLoads(input) {
+    const configAccounts = input.config.providers.claude.accounts;
+    const targetHost = input.target.capacity.host;
+    const skipped = [];
+    const loads = Object.keys(configAccounts).sort().map((account) => {
+        const hosts = input.hosts.map((host) => accountHostLoad(host, account));
+        const targetLoad = hosts.find((host) => sameHost(host.host, targetHost));
+        const ineligible = targetIneligibilityReason(account, configAccounts[account]?.enabled === true, input.allowedAccounts, targetLoad);
+        if (ineligible !== undefined)
+            skipped.push({ account, host: targetHost, reason: ineligible });
+        const knownCounts = hosts.flatMap((host) => host.live_lanes === null ? [] : [host.live_lanes]);
+        return {
+            account,
+            target_enabled: targetLoad.enabled && configAccounts[account]?.enabled === true,
+            target_logged_in: targetLoad.logged_in,
+            eligible: ineligible === undefined,
+            ...(ineligible !== undefined ? { ineligible_reason: ineligible } : {}),
+            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,
+            hosts,
+        };
+    });
+    return { loads, skipped };
+}
+export function selectClaudeAccount(input) {
+    const target = input.hosts.find((host) => sameHost(host.capacity.host, input.targetHost));
+    if (!target) {
+        throw new LanesError("claude_account_balance_target_host_unavailable", `Cannot verify Claude accounts on target host ${input.targetHost.kind}:${input.targetHost.id}`, {
+            target_host: input.targetHost,
+            unavailable_hosts: input.unavailableHosts ?? [],
+        });
+    }
+    const { loads, skipped } = buildLoads({ ...input, target });
+    if (input.explicitAccount !== undefined) {
+        const selected = loads.find((load) => load.account === input.explicitAccount);
+        if (!selected || !selected.eligible) {
+            throw new LanesError("claude_account_balance_account_unavailable", `Explicit Claude account ${JSON.stringify(input.explicitAccount)} is unavailable on ${input.targetHost.kind}:${input.targetHost.id}`, {
+                account: input.explicitAccount,
+                target_host: input.targetHost,
+                reason: selected?.ineligible_reason ?? "unknown_account",
+                account_reasons: skipped,
+                unavailable_hosts: input.unavailableHosts ?? [],
+            });
+        }
+        return {
+            account: input.explicitAccount,
+            signal: "explicit",
+            reason: "explicit",
+            target_host: input.targetHost,
+            considered: loads,
+            skipped_accounts: skipped,
+            unavailable_hosts: [...(input.unavailableHosts ?? [])],
+        };
+    }
+    const eligible = loads.filter((load) => load.eligible);
+    if (eligible.length === 0) {
+        const unknownAccounts = loads
+            .filter((load) => load.ineligible_reason === "login_status_unknown")
+            .map((load) => load.account);
+        const unknownLoginDetail = unknownAccounts.length > 0
+            ? `; login status is unknown for ${unknownAccounts.join(", ")}`
+            : "";
+        throw new LanesError("claude_account_balance_no_eligible_account", `No enabled, logged-in Claude account is available on ${input.targetHost.kind}:${input.targetHost.id}${unknownLoginDetail}`, {
+            provider: "claude",
+            target_host: input.targetHost,
+            account_reasons: loads.map((load) => ({
+                account: load.account,
+                reason: load.ineligible_reason ?? "unavailable",
+            })),
+            unavailable_hosts: input.unavailableHosts ?? [],
+        });
+    }
+    const signal = selectionSignal(eligible);
+    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);
+    });
+    return {
+        account: eligible[0].account,
+        signal,
+        reason: "least_loaded",
+        target_host: input.targetHost,
+        considered: loads,
+        skipped_accounts: skipped,
+        unavailable_hosts: [...(input.unavailableHosts ?? [])],
+    };
+}
+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) => ({
+        ...load,
+        eligible: false,
+        ineligible_reason: undefined,
+    }));
+}
+export function planClaudeBalanceMoves(input) {
+    const loads = accountLoadsForReport(input);
+    const projected = new Map(loads.map((load) => [load.account, load.live_lanes]));
+    const lanes = input.hosts.flatMap((host) => host.lanes
+        .filter((lane) => lane.provider === "claude" && lane.account && (isBalanceLive(lane) || BALANCE_MOVABLE_STATES.includes(lane.state)))
+        .map((lane) => ({ lane, host: host.capacity.host })))
+        .sort((a, b) => a.lane.created_at.localeCompare(b.lane.created_at) || a.lane.lane_id.localeCompare(b.lane.lane_id));
+    const suggestions = [];
+    for (const { lane, host } of lanes) {
+        const source = lane.account;
+        const sourceLoad = projected.get(source) ?? 0;
+        const hostSnapshot = input.hosts.find((row) => sameHost(row.capacity.host, host));
+        if (!hostSnapshot)
+            continue;
+        const candidates = Object.keys(input.config.providers.claude.accounts)
+            .filter((account) => account !== source && input.config.providers.claude.accounts[account]?.enabled === true)
+            .map((account) => ({
+            account,
+            targetStatus: hostSnapshot.capacity.providers.claude.accounts[account],
+            load: projected.get(account) ?? 0,
+        }))
+            .filter((candidate) => candidate.targetStatus?.enabled === true && candidate.targetStatus.logged_in === true)
+            .sort((a, b) => a.load - b.load || a.account.localeCompare(b.account));
+        const sourceStatus = hostSnapshot.capacity.providers.claude.accounts[source];
+        const sourceUnavailable = sourceStatus?.enabled !== true || sourceStatus.logged_in !== true;
+        const target = candidates[0];
+        const laneIsLive = isBalanceLive(lane);
+        if (!target || (!sourceUnavailable && (!laneIsLive || target.load >= sourceLoad)))
+            continue;
+        const movable = BALANCE_MOVABLE_STATES.includes(lane.state);
+        const sessionId = lane.provider_session_id ?? lane.last_resume?.session_id;
+        const skipReason = lane.state === "running"
+            ? "running_turn"
+            : !movable
+                ? "state_not_movable"
+                : lane.pending_resume !== undefined
+                    ? "pending_resume"
+                    : typeof sessionId !== "string" || sessionId.trim() === ""
+                        ? "no_provider_session"
+                        : undefined;
+        suggestions.push({
+            lane_id: lane.lane_id,
+            host,
+            state: lane.state,
+            from: source,
+            to: target.account,
+            reason: sourceUnavailable ? "source_unavailable" : "account_load",
+            apply: skipReason === undefined,
+            ...(skipReason !== undefined ? { skip_reason: skipReason } : {}),
+        });
+        if (skipReason === undefined) {
+            if (laneIsLive) {
+                projected.set(source, Math.max(0, sourceLoad - 1));
+                projected.set(target.account, target.load + 1);
+            }
+        }
+    }
+    return suggestions;
+}
+export function assertBalanceApplyEnabled(enabled) {
+    if (!enabled) {
+        throw new LanesError("claude_account_balance_disabled", `Applying Claude account balance moves requires hq-flags gate ${CLAUDE_ACCOUNT_BALANCE_FLAG}`, { flag: CLAUDE_ACCOUNT_BALANCE_FLAG });
+    }
+}
+//# sourceMappingURL=claude-account-balance.js.map

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

@@ -0,0 +1,21 @@
+import { type LaneRecord, type LaneState, type SeniorRef } from "./types.js";
+declare const HIRE_GRANT_CONTEXT_SCHEMA: "hq-lane-hire-grant-context.v1";
+export interface HireGrantLaneSnapshot {
+    lane_id: string;
+    state: LaneState;
+    senior: SeniorRef;
+    hire_grant?: number;
+}
+export interface OutpostHireGrantContext {
+    schema_version: typeof HIRE_GRANT_CONTEXT_SCHEMA;
+    enforcement_enabled: boolean;
+    expected_senior: SeniorRef;
+    hierarchy: HireGrantLaneSnapshot[];
+}
+/** Encode only the owner-relevant hierarchy from the primary's complete store. */
+export declare function createOutpostHireGrantContext(target: LaneRecord, lanes: readonly LaneRecord[], enforcementEnabled: boolean): string;
+/** Decode and validate an owner grant context, binding it to the target lane. */
+export declare function parseOutpostHireGrantContext(encoded: string, targetLaneId: string): OutpostHireGrantContext;
+export declare function sameHireGrantSenior(a: SeniorRef, b: SeniorRef): boolean;
+export {};
+//# sourceMappingURL=hire-grant-dispatch.d.ts.map

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

@@ -0,0 +1,167 @@
+import { aliveDirectChildren } from "./hire-grants.js";
+import { LanesError } from "./errors.js";
+import { isLaneState, isSeniorKind, } from "./types.js";
+const HIRE_GRANT_CONTEXT_SCHEMA = "hq-lane-hire-grant-context.v1";
+const MAX_CONTEXT_BYTES = 48 * 1024;
+const MAX_CONTEXT_LANES = 256;
+function contextError(message) {
+    return new LanesError("hire_grant_context_invalid", message, {});
+}
+function sameSenior(a, b) {
+    return a.kind === b.kind && a.id === b.id;
+}
+function copySenior(senior) {
+    return senior.id === undefined
+        ? { kind: senior.kind }
+        : { kind: senior.kind, id: senior.id };
+}
+function snapshot(lane) {
+    return {
+        lane_id: lane.lane_id,
+        state: lane.state,
+        senior: copySenior(lane.senior),
+        ...(lane.hire_grant === undefined ? {} : { hire_grant: lane.hire_grant }),
+    };
+}
+/** Encode only the owner-relevant hierarchy from the primary's complete store. */
+export function createOutpostHireGrantContext(target, lanes, enforcementEnabled) {
+    const current = lanes.find((lane) => lane.lane_id === target.lane_id);
+    if (!current || !sameSenior(current.senior, target.senior)) {
+        throw new LanesError("hire_grant_hierarchy_unavailable", `Cannot build an authoritative hire-grant hierarchy for lane ${target.lane_id}`, { lane_id: target.lane_id });
+    }
+    const relevant = new Map();
+    relevant.set(current.lane_id, current);
+    if (enforcementEnabled) {
+        if (current.senior.kind === "lane") {
+            const parentId = current.senior.id;
+            const parent = parentId ? lanes.find((lane) => lane.lane_id === parentId) : undefined;
+            if (!parent) {
+                throw new LanesError("hire_grant_senior_invalid", `Lane ${target.lane_id} has no senior lane in the primary hierarchy`, { lane_id: target.lane_id, senior_lane_id: parentId ?? null });
+            }
+            relevant.set(parent.lane_id, parent);
+            for (const sibling of aliveDirectChildren(lanes, parent.lane_id)) {
+                relevant.set(sibling.lane_id, sibling);
+            }
+        }
+        for (const child of aliveDirectChildren(lanes, current.lane_id)) {
+            relevant.set(child.lane_id, child);
+        }
+    }
+    const hierarchy = [...relevant.values()]
+        .map(snapshot)
+        .sort((a, b) => a.lane_id.localeCompare(b.lane_id));
+    if (hierarchy.length > MAX_CONTEXT_LANES) {
+        throw new LanesError("hire_grant_hierarchy_too_large", `Lane ${target.lane_id} has too many related lanes to dispatch a bounded grant check`, { lane_id: target.lane_id, related_lane_count: hierarchy.length });
+    }
+    const context = {
+        schema_version: HIRE_GRANT_CONTEXT_SCHEMA,
+        enforcement_enabled: enforcementEnabled,
+        expected_senior: copySenior(current.senior),
+        hierarchy,
+    };
+    const encoded = Buffer.from(JSON.stringify(context), "utf8").toString("base64url");
+    if (Buffer.byteLength(encoded, "utf8") > MAX_CONTEXT_BYTES) {
+        throw new LanesError("hire_grant_hierarchy_too_large", `Lane ${target.lane_id} has too much related state to dispatch a bounded grant check`, { lane_id: target.lane_id, encoded_bytes: Buffer.byteLength(encoded, "utf8") });
+    }
+    return encoded;
+}
+function parseSenior(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (Object.keys(record).some((key) => key !== "kind" && key !== "id"))
+        return null;
+    if (!isSeniorKind(record.kind))
+        return null;
+    if (record.id !== undefined &&
+        (typeof record.id !== "string" || !record.id.trim() || record.id.trim() !== record.id))
+        return null;
+    if ((record.kind === "session" || record.kind === "lane") && record.id === undefined)
+        return null;
+    if (record.kind === "user" && record.id !== undefined)
+        return null;
+    return record.id === undefined
+        ? { kind: record.kind }
+        : { kind: record.kind, id: record.id };
+}
+function parseLaneSnapshot(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (Object.keys(record).some((key) => !["lane_id", "state", "senior", "hire_grant"].includes(key)))
+        return null;
+    if (typeof record.lane_id !== "string" || !record.lane_id.trim())
+        return null;
+    if (!isLaneState(record.state))
+        return null;
+    const senior = parseSenior(record.senior);
+    if (!senior)
+        return null;
+    if (record.hire_grant !== undefined &&
+        (typeof record.hire_grant !== "number" || !Number.isSafeInteger(record.hire_grant) || record.hire_grant < 0)) {
+        return null;
+    }
+    return {
+        lane_id: record.lane_id,
+        state: record.state,
+        senior,
+        ...(record.hire_grant === undefined ? {} : { hire_grant: record.hire_grant }),
+    };
+}
+/** Decode and validate an owner grant context, binding it to the target lane. */
+export function parseOutpostHireGrantContext(encoded, targetLaneId) {
+    if (!encoded || !/^[A-Za-z0-9_-]+$/.test(encoded) ||
+        Buffer.byteLength(encoded, "utf8") > MAX_CONTEXT_BYTES ||
+        Buffer.from(encoded, "base64url").toString("base64url") !== encoded) {
+        throw contextError("Outpost grant context is not canonical base64url");
+    }
+    let raw;
+    try {
+        const decoded = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.from(encoded, "base64url"));
+        raw = JSON.parse(decoded);
+    }
+    catch {
+        throw contextError("Outpost grant context is not valid UTF-8 JSON");
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw contextError("Outpost grant context must be an object");
+    }
+    const record = raw;
+    if (Object.keys(record).some((key) => !["schema_version", "enforcement_enabled", "expected_senior", "hierarchy"].includes(key))) {
+        throw contextError("Outpost grant context contains unknown fields");
+    }
+    if (record.schema_version !== HIRE_GRANT_CONTEXT_SCHEMA ||
+        typeof record.enforcement_enabled !== "boolean" ||
+        !Array.isArray(record.hierarchy) ||
+        record.hierarchy.length === 0 || record.hierarchy.length > MAX_CONTEXT_LANES) {
+        throw contextError("Outpost grant context has an unsupported or incomplete shape");
+    }
+    const expectedSenior = parseSenior(record.expected_senior);
+    const hierarchy = record.hierarchy.map(parseLaneSnapshot);
+    if (!expectedSenior || hierarchy.some((lane) => lane === null)) {
+        throw contextError("Outpost grant context contains an invalid senior or lane snapshot");
+    }
+    const snapshots = hierarchy;
+    const byId = new Map(snapshots.map((lane) => [lane.lane_id, lane]));
+    if (byId.size !== snapshots.length) {
+        throw contextError("Outpost grant context contains duplicate lane snapshots");
+    }
+    const target = byId.get(targetLaneId);
+    if (!target || !sameSenior(target.senior, expectedSenior)) {
+        throw contextError("Outpost grant context does not match the target's expected senior");
+    }
+    if (record.enforcement_enabled && expectedSenior.kind === "lane" &&
+        (!expectedSenior.id || !byId.has(expectedSenior.id))) {
+        throw contextError("Outpost grant context is missing the target's senior lane");
+    }
+    return {
+        schema_version: HIRE_GRANT_CONTEXT_SCHEMA,
+        enforcement_enabled: record.enforcement_enabled,
+        expected_senior: expectedSenior,
+        hierarchy: snapshots,
+    };
+}
+export function sameHireGrantSenior(a, b) {
+    return sameSenior(a, b);
+}
+//# sourceMappingURL=hire-grant-dispatch.js.map

package/dist/lib/lanes/hire-grants.d.ts

@@ -1,7 +1,8 @@
 import { type LaneRecord } from "./types.js";
 export declare const LANE_HIRE_GRANTS_FLAG = "lanes.hire-grants";
-export declare function aliveDirectChildren(lanes: readonly LaneRecord[], parentLaneId: string): LaneRecord[];
-export declare function assignedChildHireGrants(children: readonly LaneRecord[], exceptLaneId?: string): number;
+export type LaneHireGrantRow = Pick<LaneRecord, "lane_id" | "state" | "senior" | "hire_grant">;
+export declare function aliveDirectChildren<T extends LaneHireGrantRow>(lanes: readonly T[], parentLaneId: string): T[];
+export declare function assignedChildHireGrants(children: readonly LaneHireGrantRow[], exceptLaneId?: string): number;
 export interface HireGrantAdmissionSnapshot {
     parent: LaneRecord;
     children: LaneRecord[];

package/dist/lib/lanes/host-capacity.d.ts

@@ -5,6 +5,19 @@ export interface HostCapacityAccount {
     max_running: number;
     running: number;
     queued: number;
+    /** Exact lane states used for Claude account balancing; absent on older Outposts. */
+    lane_counts?: {
+        running: number;
+        queued: number;
+        awaiting_input: number;
+        live: number;
+    };
+    /** Provider-reported usage, when a host can read a recent sample. */
+    usage?: {
+        five_hour_percent?: number;
+        weekly_percent?: number;
+        sampled_at?: string;
+    };
 }
 export interface HostCapacityProvider {
     max_running: number;
@@ -30,6 +43,12 @@ export declare function buildHostCapacitySnapshot(input: {
     lanes: readonly LaneRecord[];
     config: LanesConfig;
     existsSync: (path: string) => boolean;
+    probe?: (command: string, args: string[], env: NodeJS.ProcessEnv) => {
+        status: number | null;
+        stdout: string;
+        stderr: string;
+    };
+    env?: NodeJS.ProcessEnv;
     now: Date;
 }): HostCapacitySnapshot;
 /** Reject malformed remote snapshots before they can influence host selection. */

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

@@ -21,13 +21,23 @@ export function buildHostCapacitySnapshot(input) {
         for (const [id, account] of Object.entries(providerConfig.accounts)) {
             const status = accountStatus(provider, id, input.config, {
                 existsSync: input.existsSync,
+                ...(input.probe !== undefined ? { probe: input.probe } : {}),
+                ...(input.env !== undefined ? { env: input.env } : {}),
             });
+            const accountLanes = providerLanes.filter((lane) => lane.account === id);
+            const liveLanes = accountLanes.filter((lane) => lane.state === "running" || lane.state === "queued" || lane.state === "awaiting_input");
             accounts[id] = {
                 enabled: account.enabled,
                 logged_in: status.logged_in,
                 max_running: accountMaxRunning(providerConfig, id),
                 running: running.filter((lane) => lane.account === id).length,
                 queued: queued.filter((lane) => lane.account === id).length,
+                lane_counts: {
+                    running: liveLanes.filter((lane) => lane.state === "running").length,
+                    queued: liveLanes.filter((lane) => lane.state === "queued").length,
+                    awaiting_input: liveLanes.filter((lane) => lane.state === "awaiting_input").length,
+                    live: liveLanes.length,
+                },
             };
         }
         providers[provider] = {
@@ -101,6 +111,12 @@ export function parseHostCapacitySnapshot(raw) {
                 max_running: requireCount(account.max_running, `${provider}.${id}.max_running`, true),
                 running: requireCount(account.running, `${provider}.${id}.running`),
                 queued: requireCount(account.queued, `${provider}.${id}.queued`),
+                ...(account.lane_counts !== undefined
+                    ? { lane_counts: parseLaneCounts(account.lane_counts, `${provider}.${id}.lane_counts`) }
+                    : {}),
+                ...(account.usage !== undefined
+                    ? { usage: parseUsage(account.usage, `${provider}.${id}.usage`) }
+                    : {}),
             };
         }
         providers[provider] = {
@@ -118,6 +134,58 @@ export function parseHostCapacitySnapshot(raw) {
         providers,
     };
 }
+function parseLaneCounts(value, field) {
+    const counts = objectValue(value);
+    if (counts === undefined) {
+        throw new LanesError("host_capacity_invalid", `Invalid host capacity field ${field}`, { field });
+    }
+    const running = requireCount(counts.running, `${field}.running`);
+    const queued = requireCount(counts.queued, `${field}.queued`);
+    const awaiting_input = requireCount(counts.awaiting_input, `${field}.awaiting_input`);
+    const live = requireCount(counts.live, `${field}.live`);
+    if (running + queued + awaiting_input !== live) {
+        throw new LanesError("host_capacity_invalid", `Inconsistent host capacity field ${field}`, {
+            field,
+            running,
+            queued,
+            awaiting_input,
+            live,
+        });
+    }
+    return { running, queued, awaiting_input, live };
+}
+function parseUsage(value, field) {
+    const usage = objectValue(value);
+    if (usage === undefined) {
+        throw new LanesError("host_capacity_invalid", `Invalid host capacity field ${field}`, { field });
+    }
+    const parsed = {};
+    for (const key of ["five_hour_percent", "weekly_percent"]) {
+        const percentage = usage[key];
+        if (percentage !== undefined) {
+            if (typeof percentage !== "number" || !Number.isFinite(percentage) || percentage < 0 || percentage > 100) {
+                throw new LanesError("host_capacity_invalid", `Invalid host capacity field ${field}.${key}`, {
+                    field: `${field}.${key}`,
+                    value: percentage ?? null,
+                });
+            }
+            parsed[key] = percentage;
+        }
+    }
+    if (Object.keys(parsed).length === 0) {
+        throw new LanesError("host_capacity_invalid", `Empty host capacity field ${field}`, { field });
+    }
+    if (usage.sampled_at !== undefined) {
+        if (typeof usage.sampled_at !== "string" || !Number.isFinite(Date.parse(usage.sampled_at))) {
+            throw new LanesError("host_capacity_invalid", `Invalid host capacity field ${field}.sampled_at`, {
+                field: `${field}.sampled_at`,
+                value: usage.sampled_at ?? null,
+            });
+        }
+        parsed.sampled_at = usage.sampled_at;
+    }
+    return parsed;
+}
 /**
  * Choose the least-loaded eligible host/account from advisory snapshots. The
  * selected host still runs the shared admission check under its own lock.