@indigoai-us/hq-cli 5.276.0 → 5.277.0

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 = {}) {

package/dist/lib/lanes/spawn.js

@@ -1726,9 +1726,11 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
     const recordedModel = repairRecordedAccount && existing.model_source === "account"
         ? existing.model
         : undefined;
-    let pinnedModel = existing.model_source === undefined || existing.model_source === "cli" || existing.model_source === "preserved"
+    // `hq lanes set` on a running lane leaves the change pending until this spawn.
+    const pendingSettings = existing.pending_settings;
+    let pinnedModel = pendingSettings?.model ?? (existing.model_source === undefined || existing.model_source === "cli" || existing.model_source === "preserved"
         ? existing.model
-        : undefined;
+        : undefined);
     const accountDeps = {
         probe: modelDeps.probe ?? defaultProbe,
         env,
@@ -1860,13 +1862,15 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
         providerModel: config.providers[lane.provider].model,
     });
     const pendingResumeEffort = pendingResume !== undefined
-        ? {
-            ...(existing.effort !== undefined ? { effort: existing.effort } : {}),
-            source: existing.effort_source ?? "none",
-        }
+        ? pendingSettings?.effort !== undefined
+            ? { effort: pendingSettings.effort, source: "cli" }
+            : {
+                ...(existing.effort !== undefined ? { effort: existing.effort } : {}),
+                source: existing.effort_source ?? "none",
+            }
         : undefined;
     const effort = launch.effort ?? pendingResumeEffort ?? resolveLaneEffort({
-        cliEffort: existing.effort_source === "cli" ? existing.effort : undefined,
+        cliEffort: pendingSettings?.effort ?? (existing.effort_source === "cli" ? existing.effort : undefined),
         profileEffort,
         accountEffort: accountCfg?.effort,
         providerEffort: config.providers[lane.provider].effort,
@@ -2026,15 +2030,18 @@ export function spawnLaneWorker(hqRoot, lane, deps = {}, launch = {}) {
             terminal_details: undefined,
             // An account move's reservation ends with the claim.
             pending_resume: undefined,
+            pending_settings: undefined,
             account: resolved.id,
             provider_home_at_spawn: resolved.home,
             ...(model !== undefined ? { model } : {}),
             ...(model !== undefined
                 ? {
                     model_source: pinnedModel !== undefined
-                        ? preservedAccountModel !== undefined || existing.model_source === "preserved"
-                            ? "preserved"
-                            : "cli"
+                        ? preservedAccountModel === undefined && pendingSettings?.model !== undefined
+                            ? "cli"
+                            : preservedAccountModel !== undefined || existing.model_source === "preserved"
+                                ? "preserved"
+                                : "cli"
                         : profileModel !== undefined
                             ? "profile"
                             : accountCfg?.model !== undefined

package/dist/lib/lanes/store.js

@@ -475,6 +475,7 @@ export function parseLaneRecord(raw, filePath) {
         "keep_alive_next_eligible_at",
         "keep_alive_exhausted_at",
         "interrupted_at",
+        "last_run_usage_at",
     ]) {
         if (raw[field] !== undefined)
             requireTimestamp(raw[field], field, filePath);
@@ -694,6 +695,40 @@ export function parseLaneRecord(raw, filePath) {
             requireTimestamp(entry.at, `${field}.at`, filePath);
         }
     }
+    if (raw.settings_history !== undefined) {
+        if (!Array.isArray(raw.settings_history)) {
+            throw new LaneSchemaError("settings_history must be an array when present", {
+                path: filePath,
+                field: "settings_history",
+            });
+        }
+        for (const [index, entry] of raw.settings_history.entries()) {
+            const field = `settings_history[${index}]`;
+            if (!isPlainObject(entry) ||
+                Object.keys(entry).some((key) => !["at", "actor", "model", "effort", "reason"].includes(key)) ||
+                (entry.model === undefined && entry.effort === undefined)) {
+                throw new LaneSchemaError(`${field} must be a settings history entry`, { path: filePath, field });
+            }
+            requireTimestamp(entry.at, `${field}.at`, filePath);
+            if (typeof entry.actor !== "string" || entry.actor.trim() === "") {
+                throw new LaneSchemaError(`${field}.actor must be a non-empty string`, { path: filePath, field });
+            }
+            if (entry.reason !== undefined && (typeof entry.reason !== "string" || entry.reason.trim() === "")) {
+                throw new LaneSchemaError(`${field}.reason must be a non-empty string when present`, { path: filePath, field });
+            }
+            for (const key of ["model", "effort"]) {
+                const change = entry[key];
+                if (change === undefined)
+                    continue;
+                if (!isPlainObject(change) ||
+                    Object.keys(change).some((k) => k !== "from" && k !== "to") ||
+                    typeof change.to !== "string" || change.to.trim() === "" ||
+                    (change.from !== null && typeof change.from !== "string")) {
+                    throw new LaneSchemaError(`${field}.${key} must be a {from, to} change`, { path: filePath, field });
+                }
+            }
+        }
+    }
     if (raw.worker_profile_repin_history !== undefined) {
         if (!Array.isArray(raw.worker_profile_repin_history)) {
             throw new LaneSchemaError("worker_profile_repin_history must be an array when present", {
@@ -751,7 +786,7 @@ function parseLaneAccountSelection(value, filePath) {
     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")
+    if (selection.signal !== "usage" && selection.signal !== "recent_usage" && selection.signal !== "lane_count" && selection.signal !== "explicit")
         throw failure("signal");
     if (selection.reason !== "least_loaded" && selection.reason !== "explicit")
         throw failure("reason");
@@ -773,6 +808,10 @@ function parseLaneAccountSelection(value, filePath) {
             throw failure(`considered.${index}`);
         if (row.ineligible_reason !== undefined && typeof row.ineligible_reason !== "string")
             throw failure(`considered.${index}.ineligible_reason`);
+        if (row.recent_usage_at !== undefined && row.recent_usage_at !== null &&
+            (typeof row.recent_usage_at !== "string" || !Number.isFinite(Date.parse(row.recent_usage_at)))) {
+            throw failure(`considered.${index}.recent_usage_at`);
+        }
         if (row.usage !== null) {
             if (!isPlainObject(row.usage))
                 throw failure(`considered.${index}.usage`);
@@ -1015,6 +1054,11 @@ export function mergeLaneRecords(live, sidecars) {
                 failed_resume_history: unionHistory(all.map((record) => record.failed_resume_history ?? []), entryIdentity, base.failed_resume_history ?? []),
             }
             : {}),
+        ...(all.some((record) => record.settings_history !== undefined)
+            ? {
+                settings_history: unionHistory(all.map((record) => record.settings_history ?? []), entryIdentity, base.settings_history ?? []),
+            }
+            : {}),
         ...(all.some((record) => record.stop_history !== undefined)
             ? {
                 stop_history: unionHistory(all.map((record) => record.stop_history ?? []), entryIdentity, base.stop_history ?? []),

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

@@ -253,12 +253,14 @@ export interface LaneAccountSelectionConsidered {
         weekly_percent?: number;
         sampled_at?: string;
     } | null;
+    /** Latest completed run in the recent-usage window, when lane snapshots are complete. */
+    recent_usage_at?: string | null;
     hosts: LaneAccountSelectionHostCount[];
 }
 /** Decision evidence saved with a Claude lane when account balancing is active. */
 export interface LaneAccountSelection {
     account: string;
-    signal: "usage" | "lane_count" | "explicit";
+    signal: "usage" | "recent_usage" | "lane_count" | "explicit";
     reason: "least_loaded" | "explicit";
     target_host: LaneHost;
     selected_at: string;
@@ -287,6 +289,20 @@ export interface LaneStopHistoryEntry {
     at: string;
     reason: string;
 }
+/** One `hq lanes set` change; it takes effect when the lane next resumes. */
+export interface LaneSettingsHistoryEntry {
+    at: string;
+    actor: string;
+    model?: {
+        from: string | null;
+        to: string;
+    };
+    effort?: {
+        from: string | null;
+        to: string;
+    };
+    reason?: string;
+}
 /** Evidence for a senior-authorized Outpost worker-profile content re-pin. */
 export interface WorkerProfileRepinHistoryEntry {
     old_hash: string | null;
@@ -564,6 +580,17 @@ export interface LaneRecord {
     terminal_reason?: string;
     /** Reasons supplied to explicit stop commands, retained independently of optional project ledgers. */
     stop_history?: LaneStopHistoryEntry[];
+    /** Model and effort changes made with `hq lanes set`. */
+    settings_history?: LaneSettingsHistoryEntry[];
+    /**
+     * Model or effort from `hq lanes set` on a running lane. The running turn
+     * keeps its launched values (quota classification reads `model`); the next
+     * spawn applies these and clears them.
+     */
+    pending_settings?: {
+        model?: string;
+        effort?: string;
+    };
     /** Classification time when this lane entered interrupted; stable across later metadata writes. */
     interrupted_at?: string;
     /**
@@ -598,6 +625,8 @@ export interface LaneRecord {
     last_resume?: LaneResumeRecord;
     /** Cache counters from the last exited run's result. Nothing else from the payload. */
     last_run_usage?: LaneRunUsage;
+    /** Completion time paired with last_run_usage; written by the watcher. */
+    last_run_usage_at?: string;
     /**
      * Spec §4: one repair turn per expected envelope slot when the final output
      * is invalid or missing. Written before repair spawn and updated on repair

package/dist/lib/lanes/types.js

@@ -230,9 +230,9 @@ export const LANE_FIELD_WRITERS = {
     last_envelope: ["watcher", "reconcile"], model: ["creator", "spawn", "command"], model_source: ["creator", "spawn", "command"], effort: ["creator", "spawn", "command"], effort_source: ["creator", "spawn", "command"], fast_mode: ["spawn"],
     last_message_at: ["command"], status_gate: ["spawn", "watcher"], status_gate_history: ["watcher"], blocker_freshness_state: ["watcher"], kr_freshness_state: ["watcher"], last_compaction: ["spawn"], story_complete: ["watcher", "reconcile"], story_complete_reason: ["watcher", "reconcile"], story_status: ["watcher", "reconcile"],
     overdue: ["reconcile"], overdue_at: ["reconcile"], last_host_report_at: ["watcher", "spawn", "reconcile"], stalled: ["watcher"], stalled_at: ["watcher"], stalled_reason: ["watcher"],
-    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command"], interrupted_at: ["watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
+    admitted_reason: ["command", "reconcile"], terminal_reason: ["command", "watcher", "spawn", "reconcile"], stop_history: ["command"], settings_history: ["command"], pending_settings: ["command", "spawn"], interrupted_at: ["command", "watcher", "reconcile"], terminal_details: ["command", "spawn", "watcher", "reconcile"],
     quota_reset_at: ["watcher", "reconcile"], model_quota_marker: ["watcher", "reconcile"], outpost_command_id: ["command"],
-    provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], provider_home_at_spawn: ["spawn"], last_resume: ["spawn"], last_run_usage: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
+    provider_session_id: ["watcher", "command", "spawn"], provider_session_id_absent: ["watcher", "command"], provider_home_at_spawn: ["spawn"], last_resume: ["spawn"], last_run_usage: ["watcher"], last_run_usage_at: ["watcher"], envelope_repair: ["watcher", "reconcile"], envelope_validation_errors: ["watcher"], last_progress_event_at: ["watcher"],
 };
 function isPlainObject(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);

package/dist/lib/lanes/watcher.js

@@ -245,7 +245,7 @@ export function notifySlotFreed(_input) {
  * or unparseable id is recorded as absent with its reason, never invented.
  * Non-resumable providers return null and the record is left as it was.
  */
-function runResultFields(hqRoot, lane) {
+function runResultFields(hqRoot, lane, at) {
     const runDir = laneRunDir(hqRoot, lane.lane_id);
     const result = readWorkerRunResult(runDir, lane.provider, readSpawnManifest(runDir).worker_out_offset ?? 0);
     if (result === null)
@@ -255,6 +255,7 @@ function runResultFields(hqRoot, lane) {
             cache_read_input_tokens: result.cache_read_input_tokens,
             cache_creation_input_tokens: result.cache_creation_input_tokens,
         },
+        last_run_usage_at: at,
     };
     if (result.session_id !== null) {
         fields.provider_session_id = result.session_id;
@@ -366,7 +367,7 @@ export function applyTerminalToLaneWithResult(hqRoot, laneId, classification, op
         }
         const next = {
             ...current,
-            ...runResultFields(hqRoot, current),
+            ...runResultFields(hqRoot, current, at),
             state: effectiveClassification.state,
             queued_reason: undefined,
             stalled: undefined,

package/dist/secrets-env-fast-path.d.ts

@@ -0,0 +1,5 @@
+import type { ParsedSecretsEnvFastRequest } from "./fast-scaffold.js";
+import type { SecretsEnvFastResult } from "./secrets-env-fast-route.js";
+/** Run the shared secret action without importing the full CLI command graph. */
+export declare function runSecretsEnvFastPath(request: ParsedSecretsEnvFastRequest): Promise<SecretsEnvFastResult>;
+//# sourceMappingURL=secrets-env-fast-path.d.ts.map

package/dist/secrets-env-fast-path.js

@@ -0,0 +1,16 @@
+/** Run the shared secret action without importing the full CLI command graph. */
+export async function runSecretsEnvFastPath(request) {
+    if (process.env.HQ_AGENT_DIR?.trim()) {
+        const [os, { agentKitPaths }, { adoptAgentIdentityEnv }] = await Promise.all([
+            import("node:os"),
+            import("./lib/agent-kit/paths.js"),
+            import("./lib/agent-kit/adopt-identity.js"),
+        ]);
+        adoptAgentIdentityEnv(agentKitPaths(os.homedir(), process.env), process.env);
+    }
+    const { runSecretsEnvCommand } = await import("./commands/secrets.js");
+    return runSecretsEnvCommand(request.options, request.scope, {
+        fallbackOnAuthFailure: true,
+    });
+}
+//# sourceMappingURL=secrets-env-fast-path.js.map

package/dist/secrets-env-fast-route.d.ts

@@ -0,0 +1,18 @@
+/** Default-off hq-flags gate for the `secrets env` entry fast path. */
+import type { ParsedSecretsEnvFastRequest } from "./fast-scaffold.js";
+export declare const CLI_SECRETS_ENV_FAST_PATH_FLAG = "cli.secrets-env-fast-path";
+export type SecretsEnvFastResult = "handled" | "fallback";
+export interface SecretsEnvFastDispatchDeps {
+    isEnabled: () => Promise<boolean>;
+    runFast: () => Promise<SecretsEnvFastResult>;
+    runCurrent: () => Promise<void>;
+}
+/** Keep the existing command graph in control when the gate is off or declines. */
+export declare function dispatchSecretsEnvFastRequest(_request: ParsedSecretsEnvFastRequest, deps: SecretsEnvFastDispatchDeps): Promise<void>;
+/**
+ * Fast routes only use an explicit local override or the latest company flag
+ * snapshot. A missing company, stale snapshot, or unreadable cache leaves the
+ * current CLI path in control; it never performs a registry network request.
+ */
+export declare function secretsEnvFastRouteEnabled(request: ParsedSecretsEnvFastRequest, env?: NodeJS.ProcessEnv): Promise<boolean>;
+//# sourceMappingURL=secrets-env-fast-route.d.ts.map

package/dist/secrets-env-fast-route.js

@@ -0,0 +1,54 @@
+/** Default-off hq-flags gate for the `secrets env` entry fast path. */
+import { localOverrideEnvVar, readLocalOverride } from "@indigoai-us/hq-flags-client";
+export const CLI_SECRETS_ENV_FAST_PATH_FLAG = "cli.secrets-env-fast-path";
+/** Keep the existing command graph in control when the gate is off or declines. */
+export async function dispatchSecretsEnvFastRequest(_request, deps) {
+    if (!(await deps.isEnabled())) {
+        await deps.runCurrent();
+        return;
+    }
+    if ((await deps.runFast()) === "fallback") {
+        await deps.runCurrent();
+    }
+}
+/**
+ * Fast routes only use an explicit local override or the latest company flag
+ * snapshot. A missing company, stale snapshot, or unreadable cache leaves the
+ * current CLI path in control; it never performs a registry network request.
+ */
+export async function secretsEnvFastRouteEnabled(request, env = process.env) {
+    const override = readLocalOverride(CLI_SECRETS_ENV_FAST_PATH_FLAG, env);
+    if (override !== null)
+        return override;
+    const rawOverride = env[localOverrideEnvVar(CLI_SECRETS_ENV_FAST_PATH_FLAG)];
+    if (rawOverride === "1")
+        return true;
+    if (rawOverride === "0")
+        return false;
+    if (request.scope.personal)
+        return false;
+    try {
+        const scopedEnv = { ...env };
+        if (request.scope.company) {
+            // An explicit --company scope must override any ambient binding for the
+            // fast-path flag lookup, just as it overrides the secrets command scope.
+            delete scopedEnv.HQ_COMPANY_UID;
+            scopedEnv.HQ_COMPANY_SLUG = request.scope.company;
+        }
+        const [{ resolveProcessFlagCompanyContext }, { readFlagSnapshotFile }] = await Promise.all([
+            import("./lib/process-flag-company-context.js"),
+            import("./lib/flag-snapshot-file.js"),
+        ]);
+        const { companyUid } = resolveProcessFlagCompanyContext(scopedEnv);
+        if (!companyUid)
+            return false;
+        return readFlagSnapshotFile(companyUid, { env: scopedEnv })?.flags[CLI_SECRETS_ENV_FAST_PATH_FLAG] === true;
+    }
+    catch (error) {
+        // This is a performance rollout gate. Failure to read it preserves the
+        // existing full CLI behavior.
+        console.warn("[hq] secrets env fast-path flag lookup failed; using the full CLI path", error instanceof Error ? error.name : typeof error);
+        return false;
+    }
+}
+//# sourceMappingURL=secrets-env-fast-route.js.map