@indigoai-us/hq-cli 5.187.0 → 5.188.0

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/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.

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, 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, 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, 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/outpost-dispatch.d.ts

@@ -61,12 +61,21 @@ export declare function parseOutpostPickupPayload(raw: unknown): OutpostPickupPa
 export declare function buildOutpostPickupCommand(payloadUrl: string): string;
 /** Bounded, read-only capacity query executed by the target Outpost CLI. */
 export declare function buildOutpostCapacityCommand(): string;
+/** Read the lane records owned by an Outpost for exact per-account state counts. */
+export declare function buildOutpostLaneListCommand(): string;
 /** Commit a queued lane move on the host that currently owns its state. */
 export declare function buildOutpostMoveTargetCommand(input: {
     laneId: string;
     host: LaneHost;
     account: string;
 }): string;
+/** Move an owned Claude session between accounts while leaving its turn parked. */
+export declare function buildOutpostBalanceMoveCommand(input: {
+    laneId: string;
+    account: string;
+    fromAccount: string;
+    expectedState: LaneRecord["state"];
+}): string;
 /** Idempotently backfill the marker on the selected Outpost. */
 export declare function buildOutpostIdentityBackfillCommand(expectedId: string): string;
 /** Build the same `hq outposts exec` remote command used by lane pickup. */

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

@@ -46,6 +46,10 @@ export function buildOutpostPickupCommand(payloadUrl) {
 export function buildOutpostCapacityCommand() {
     return withRemoteHqDir(joinCommandParts(["hq", "lanes", "capacity", "--json"]));
 }
+/** Read the lane records owned by an Outpost for exact per-account state counts. */
+export function buildOutpostLaneListCommand() {
+    return withRemoteHqDir(joinCommandParts(["hq", "lanes", "list", "--json"]));
+}
 /** Commit a queued lane move on the host that currently owns its state. */
 export function buildOutpostMoveTargetCommand(input) {
     return withRemoteHqDir(joinCommandParts([
@@ -61,6 +65,21 @@ export function buildOutpostMoveTargetCommand(input) {
         input.account,
     ]));
 }
+/** Move an owned Claude session between accounts while leaving its turn parked. */
+export function buildOutpostBalanceMoveCommand(input) {
+    return withRemoteHqDir(joinCommandParts([
+        "hq",
+        "lanes",
+        "balance-move-target",
+        input.laneId,
+        "--account",
+        input.account,
+        "--from-account",
+        input.fromAccount,
+        "--expected-state",
+        input.expectedState,
+    ]));
+}
 /** Idempotently backfill the marker on the selected Outpost. */
 export function buildOutpostIdentityBackfillCommand(expectedId) {
     return withRemoteHqDir(joinCommandParts([

package/dist/lib/lanes/store.js

@@ -473,6 +473,9 @@ export function parseLaneRecord(raw, filePath) {
             path: filePath,
         });
     }
+    if (raw.account_selection !== undefined) {
+        parseLaneAccountSelection(raw.account_selection, filePath);
+    }
     if (raw.placement_default !== undefined) {
         const placement = raw.placement_default;
         if (!isPlainObject(placement) ||
@@ -494,6 +497,89 @@ export function parseLaneRecord(raw, filePath) {
     // a parse/rewrite cycle (spec §5.1 field-preservation).
     return raw;
 }
+function parseLaneAccountSelection(value, filePath) {
+    const failure = (field) => new LaneSchemaError(`Invalid account_selection.${field}`, {
+        path: filePath,
+        field: `account_selection.${field}`,
+    });
+    if (!isPlainObject(value))
+        throw failure("must be an object");
+    const selection = value;
+    if (typeof selection.account !== "string" || selection.account.trim() === "")
+        throw failure("account");
+    if (selection.signal !== "usage" && selection.signal !== "lane_count" && selection.signal !== "explicit")
+        throw failure("signal");
+    if (selection.reason !== "least_loaded" && selection.reason !== "explicit")
+        throw failure("reason");
+    if (typeof selection.selected_at !== "string" || !Number.isFinite(Date.parse(selection.selected_at)))
+        throw failure("selected_at");
+    const parseHost = (host, field) => {
+        if (!isPlainObject(host) || !isHostKind(host.kind) || typeof host.id !== "string" || host.id.trim() === "")
+            throw failure(field);
+    };
+    parseHost(selection.target_host, "target_host");
+    if (!Array.isArray(selection.considered) || !Array.isArray(selection.skipped_accounts) || !Array.isArray(selection.unavailable_hosts)) {
+        throw failure("arrays");
+    }
+    for (const [index, rowValue] of selection.considered.entries()) {
+        if (!isPlainObject(rowValue))
+            throw failure(`considered.${index}`);
+        const row = rowValue;
+        if (typeof row.account !== "string" || row.account.trim() === "" || typeof row.eligible !== "boolean" || typeof row.live_lanes !== "number" || !Number.isInteger(row.live_lanes) || row.live_lanes < 0 || typeof row.counts_complete !== "boolean" || !Array.isArray(row.hosts))
+            throw failure(`considered.${index}`);
+        if (row.ineligible_reason !== undefined && typeof row.ineligible_reason !== "string")
+            throw failure(`considered.${index}.ineligible_reason`);
+        if (row.usage !== null) {
+            if (!isPlainObject(row.usage))
+                throw failure(`considered.${index}.usage`);
+            for (const key of ["five_hour_percent", "weekly_percent"]) {
+                const percent = row.usage[key];
+                if (percent !== undefined && (typeof percent !== "number" || !Number.isFinite(percent) || percent < 0 || percent > 100))
+                    throw failure(`considered.${index}.usage.${key}`);
+            }
+            if (row.usage.sampled_at !== undefined && (typeof row.usage.sampled_at !== "string" || !Number.isFinite(Date.parse(row.usage.sampled_at))))
+                throw failure(`considered.${index}.usage.sampled_at`);
+        }
+        for (const [hostIndex, hostValue] of row.hosts.entries()) {
+            if (!isPlainObject(hostValue))
+                throw failure(`considered.${index}.hosts.${hostIndex}`);
+            const host = hostValue;
+            parseHost(host.host, `considered.${index}.hosts.${hostIndex}.host`);
+            if (typeof host.enabled !== "boolean" || !(host.logged_in === null || typeof host.logged_in === "boolean"))
+                throw failure(`considered.${index}.hosts.${hostIndex}.status`);
+            if (!(host.live_lanes === null || (typeof host.live_lanes === "number" && Number.isInteger(host.live_lanes) && host.live_lanes >= 0)))
+                throw failure(`considered.${index}.hosts.${hostIndex}.live_lanes`);
+            if (!isPlainObject(host.lane_counts))
+                throw failure(`considered.${index}.hosts.${hostIndex}.lane_counts`);
+            for (const key of ["running", "queued", "awaiting_input"]) {
+                const count = host.lane_counts[key];
+                if (!(count === null || (typeof count === "number" && Number.isInteger(count) && count >= 0)))
+                    throw failure(`considered.${index}.hosts.${hostIndex}.lane_counts.${key}`);
+            }
+            if (!["lane_list", "capacity", "capacity_partial", "unavailable"].includes(String(host.count_source)))
+                throw failure(`considered.${index}.hosts.${hostIndex}.count_source`);
+        }
+    }
+    for (const [index, rowValue] of selection.skipped_accounts.entries()) {
+        if (!isPlainObject(rowValue))
+            throw failure(`skipped_accounts.${index}`);
+        const row = rowValue;
+        if (typeof row.account !== "string" || row.account.trim() === "" || typeof row.reason !== "string" || row.reason.trim() === "")
+            throw failure(`skipped_accounts.${index}`);
+        parseHost(row.host, `skipped_accounts.${index}.host`);
+    }
+    for (const [index, rowValue] of selection.unavailable_hosts.entries()) {
+        if (!isPlainObject(rowValue))
+            throw failure(`unavailable_hosts.${index}`);
+        const row = rowValue;
+        if (typeof row.reason !== "string" || row.reason.trim() === "")
+            throw failure(`unavailable_hosts.${index}`);
+        if (isPlainObject(row.host) && row.host.kind === "unknown" && row.host.id === "unknown")
+            continue;
+        parseHost(row.host, `unavailable_hosts.${index}.host`);
+    }
+    return selection;
+}
 export function parseQuestionRecord(raw, filePath) {
     if (!isPlainObject(raw)) {
         throw new LaneSchemaError("Question record must be a JSON object", {