@indigoai-us/hq-cli 5.342.14 → 5.342.16

package/dist/lib/flag-snapshot-file.js

@@ -4,6 +4,104 @@ import * as os from "node:os";
 import * as path from "node:path";
 export const FLAG_SNAPSHOT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const COMPANY_UID_RE = /^cmp_[A-Za-z0-9]{3,128}$/;
+function markWriteFailure(error, context) {
+    if (!error || (typeof error !== "object" && typeof error !== "function"))
+        return;
+    const failure = error;
+    let dirOwnerMatchesUid = "unknown";
+    if (typeof process.getuid === "function") {
+        try {
+            dirOwnerMatchesUid = fs.statSync(context.directory).uid === process.getuid()
+                ? "true"
+                : "false";
+        }
+        catch {
+            // A missing or inaccessible directory has no safely knowable owner.
+        }
+    }
+    try {
+        Object.defineProperties(failure, {
+            flagSnapshotStep: { value: context.step, configurable: true },
+            cacheRootKind: { value: context.cacheRootKind, configurable: true },
+            dirOwnerMatchesUid: { value: dirOwnerMatchesUid, configurable: true },
+        });
+    }
+    catch {
+        // Preserve the original filesystem error if it cannot carry diagnostics.
+    }
+}
+function atWriteStep(context, operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        markWriteFailure(error, context);
+        throw error;
+    }
+}
+export function flagSnapshotWriteFailureTags(error) {
+    const failure = error;
+    const code = failure && typeof failure.code === "string" ? failure.code : "";
+    const allowedCodes = new Set(["EACCES", "EPERM", "EROFS", "ENOSPC"]);
+    const step = failure?.flagSnapshotStep;
+    const rootKind = failure?.cacheRootKind;
+    const owner = failure?.dirOwnerMatchesUid;
+    const tags = {
+        flag_snapshot_step: step && ["mkdir", "chmod_dir", "open_tmp", "write_tmp", "rename", "chmod_file"].includes(step)
+            ? step
+            : "other",
+        errno_code: allowedCodes.has(code) ? code : "other",
+        cache_root_kind: rootKind === "xdg" || rootKind === "home" ? rootKind : "unknown",
+        dir_owner_matches_uid: owner === "true" || owner === "false" ? owner : "unknown",
+    };
+    if (fallbackCacheUsed)
+        tags.cache_root = "fallback";
+    if (failure?.fallbackFailed)
+        tags.fallback = "failed";
+    return tags;
+}
+let fallbackCacheUsed = false;
+export function _resetFlagSnapshotCacheForTests() {
+    fallbackCacheUsed = false;
+}
+function markFallbackFailed(error) {
+    if (!error || (typeof error !== "object" && typeof error !== "function"))
+        return;
+    try {
+        Object.defineProperty(error, "fallbackFailed", { value: true, configurable: true });
+    }
+    catch {
+        // Keep the original filesystem error intact if it cannot carry diagnostics.
+    }
+}
+function isPermissionFailure(error) {
+    const code = error?.code;
+    return code === "EACCES" || code === "EPERM";
+}
+function fallbackSnapshotPath(companyUid, create) {
+    if (typeof process.getuid !== "function")
+        return undefined;
+    const uid = process.getuid();
+    const root = path.join(os.tmpdir(), `hq-cli-flag-snapshots-${uid}`);
+    const directories = [root, path.join(root, "hq"), path.join(root, "hq", "flags")];
+    for (const directory of directories) {
+        try {
+            if (create)
+                fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+            const stat = fs.lstatSync(directory);
+            if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== uid)
+                return undefined;
+            if (create)
+                fs.chmodSync(directory, 0o700);
+            else if ((stat.mode & 0o077) !== 0)
+                return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return path.join(directories[2], `snapshot-${companyUid}.json`);
+}
 export function flagSnapshotPath(companyUid, env = process.env) {
     if (!COMPANY_UID_RE.test(companyUid))
         return undefined;
@@ -12,7 +110,8 @@ export function flagSnapshotPath(companyUid, env = process.env) {
 }
 /** Write just the validated flag decisions and company scope, never auth data. */
 export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
-    const file = flagSnapshotPath(companyUid, options.env);
+    const env = options.env ?? process.env;
+    const file = flagSnapshotPath(companyUid, env);
     if (!file)
         throw new Error("Cannot persist a flag snapshot without a valid company uid");
     const normalizedFlags = Object.fromEntries(Object.entries(flags).filter((entry) => Boolean(entry[0].trim()) && typeof entry[1] === "boolean"));
@@ -24,39 +123,78 @@ export function writeFlagSnapshotFile(companyUid, flags, options = {}) {
     if (!Number.isFinite(Date.parse(snapshot.fetched_at))) {
         throw new Error("Cannot persist a flag snapshot with an invalid fetched_at timestamp");
     }
-    const directory = path.dirname(file);
-    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
-    fs.chmodSync(directory, 0o700);
-    const temporary = `${file}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
-    let fd;
-    try {
-        fd = fs.openSync(temporary, "wx", 0o600);
-        fs.writeFileSync(fd, `${JSON.stringify(snapshot)}\n`, "utf8");
-        fs.fsyncSync(fd);
-        fs.closeSync(fd);
-        fd = undefined;
-        fs.renameSync(temporary, file);
-        fs.chmodSync(file, 0o600);
-    }
-    catch (error) {
-        if (fd !== undefined)
-            fs.closeSync(fd);
+    const cacheRootKind = env.XDG_CACHE_HOME?.trim() ? "xdg" : "home";
+    const writeAt = (destination) => {
+        const directory = path.dirname(destination);
+        const context = (step) => ({
+            step,
+            cacheRootKind,
+            directory,
+        });
+        atWriteStep(context("mkdir"), () => fs.mkdirSync(directory, { recursive: true, mode: 0o700 }));
+        const temporary = `${destination}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+        let fd;
         try {
-            fs.unlinkSync(temporary);
+            fd = atWriteStep(context("open_tmp"), () => fs.openSync(temporary, "wx", 0o600));
+            atWriteStep(context("write_tmp"), () => {
+                fs.writeFileSync(fd, `${JSON.stringify(snapshot)}\n`, "utf8");
+                fs.fsyncSync(fd);
+                fs.closeSync(fd);
+                fd = undefined;
+            });
+            atWriteStep(context("rename"), () => fs.renameSync(temporary, destination));
         }
-        catch (cleanupError) {
-            if (cleanupError.code !== "ENOENT")
-                throw cleanupError;
+        catch (error) {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+            try {
+                fs.unlinkSync(temporary);
+            }
+            catch (cleanupError) {
+                if (cleanupError.code !== "ENOENT")
+                    throw cleanupError;
+            }
+            throw error;
         }
-        throw error;
+        return destination;
+    };
+    const writeFallback = (originalError) => {
+        const fallbackFile = fallbackSnapshotPath(companyUid, true);
+        if (!fallbackFile) {
+            if (originalError) {
+                markFallbackFailed(originalError);
+                throw originalError;
+            }
+            const error = Object.assign(new Error("Flag snapshot fallback directory is unavailable"), { code: "EACCES" });
+            markFallbackFailed(error);
+            throw error;
+        }
+        try {
+            const written = writeAt(fallbackFile);
+            fallbackCacheUsed = true;
+            return written;
+        }
+        catch (fallbackError) {
+            if (originalError) {
+                markFallbackFailed(originalError);
+                throw originalError;
+            }
+            markFallbackFailed(fallbackError);
+            throw fallbackError;
+        }
+    };
+    if (fallbackCacheUsed)
+        return writeFallback();
+    try {
+        return writeAt(file);
+    }
+    catch (error) {
+        if (!isPermissionFailure(error))
+            throw error;
+        return writeFallback(error);
     }
-    return file;
 }
-/** Return null for every miss, malformed file, company mismatch, or stale file. */
-export function readFlagSnapshotFile(companyUid, options = {}) {
-    const file = flagSnapshotPath(companyUid, options.env);
-    if (!file)
-        return null;
+function parseSnapshotFile(companyUid, file, options) {
     let parsed;
     try {
         parsed = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -71,7 +209,7 @@ export function readFlagSnapshotFile(companyUid, options = {}) {
         value.company_uid !== companyUid ||
         typeof value.fetched_at !== "string" ||
         !value.flags || typeof value.flags !== "object" || Array.isArray(value.flags))
-        return null; // Expected on missing, malformed, unreadable, or cross-company cache data.
+        return null;
     const fetchedAt = Date.parse(value.fetched_at);
     const age = (options.now ?? Date.now()) - fetchedAt;
     if (!Number.isFinite(fetchedAt) || age < 0 || age > (options.maxAgeMs ?? FLAG_SNAPSHOT_MAX_AGE_MS)) {
@@ -88,4 +226,26 @@ export function readFlagSnapshotFile(companyUid, options = {}) {
         flags: flags,
     };
 }
+/** Return null for every miss, malformed file, company mismatch, or stale file. */
+export function readFlagSnapshotFile(companyUid, options = {}) {
+    const file = flagSnapshotPath(companyUid, options.env);
+    if (!file)
+        return null;
+    if (fallbackCacheUsed) {
+        const fallback = fallbackSnapshotPath(companyUid, false);
+        const snapshot = fallback ? parseSnapshotFile(companyUid, fallback, options) : null;
+        if (snapshot)
+            return snapshot;
+    }
+    const primary = parseSnapshotFile(companyUid, file, options);
+    if (primary)
+        return primary;
+    const fallback = fallbackSnapshotPath(companyUid, false);
+    if (!fallback)
+        return null;
+    const snapshot = parseSnapshotFile(companyUid, fallback, options);
+    if (snapshot)
+        fallbackCacheUsed = true;
+    return snapshot;
+}
 //# sourceMappingURL=flag-snapshot-file.js.map

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

@@ -1,4 +1,5 @@
-import type { LaneRecord, LanesConfig } from "./types.js";
+import { type QuotaState } from "./quota.js";
+import { type LaneRecord, type LanesConfig } from "./types.js";
 export interface AdmissionHost {
     hostname: string;
     outpostId: string | null;
@@ -11,6 +12,11 @@ export declare function withLaneAdmissionLock<T>(hqRoot: string, provider: LaneR
 export declare function withAllLaneAdmissionLocks<T>(hqRoot: string, fn: () => Promise<T>, sleep?: (ms: number) => Promise<void>): Promise<T>;
 export declare function laneRunsOnHost(lane: LaneRecord, host: AdmissionHost): boolean;
 export declare function compareLaneQueueOrder(a: LaneRecord, b: LaneRecord): number;
+/** A lead is identified by another live lane naming it as its lane senior. */
+export declare function leadLaneIds(lanes: readonly LaneRecord[]): Set<string>;
+export declare function compareLaneQueueOrderWithLeads(a: LaneRecord, b: LaneRecord, leads: ReadonlySet<string>): number;
+/** Capacity remaining across enabled Claude accounts on one host. */
+export declare function freeClaudeAccountSlots(lanes: readonly LaneRecord[], config: LanesConfig, host: AdmissionHost, nowMs?: number, quotaState?: QuotaState): number;
 export declare function hasActiveAdmissionReservation(lane: LaneRecord, nowMs: number): boolean;
 export declare function hasActivePendingResume(lane: LaneRecord, nowMs: number): boolean;
 /** Whether a lane currently owns a running slot for its host/provider caps. */

package/dist/lib/lanes/admission.js

@@ -2,6 +2,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { accountMaxRunning } from "./config.js";
 import { LanesError } from "./errors.js";
+import { quotaBlockFor } from "./quota.js";
+import { isTerminalLaneState } from "./types.js";
 export const ADMISSION_LOCK_STALE_MS = 30_000;
 export const ADMISSION_LOCK_TIMEOUT_MS = 5_000;
 export const ADMISSION_RESERVATION_GRACE_MS = 30_000;
@@ -123,6 +125,38 @@ export function compareLaneQueueOrder(a, b) {
     const byQueueAge = Date.parse(a.queued_at ?? a.created_at) - Date.parse(b.queued_at ?? b.created_at);
     return byQueueAge || a.lane_id.localeCompare(b.lane_id);
 }
+/** A lead is identified by another live lane naming it as its lane senior. */
+export function leadLaneIds(lanes) {
+    const leads = new Set(lanes.filter((lane) => lane.keep_alive === true).map((lane) => lane.lane_id));
+    for (const lane of lanes) {
+        if (!isTerminalLaneState(lane.state) && lane.senior.kind === "lane" && lane.senior.id) {
+            leads.add(lane.senior.id);
+        }
+    }
+    return leads;
+}
+export function compareLaneQueueOrderWithLeads(a, b, leads) {
+    if (a.provider === "claude" && b.provider === "claude") {
+        const aLead = leads.has(a.lane_id);
+        const bLead = leads.has(b.lane_id);
+        if (aLead !== bLead)
+            return aLead ? -1 : 1;
+    }
+    return compareLaneQueueOrder(a, b);
+}
+/** Capacity remaining across enabled Claude accounts on one host. */
+export function freeClaudeAccountSlots(lanes, config, host, nowMs = Date.now(), quotaState) {
+    return Object.entries(config.providers.claude.accounts).reduce((total, [account, accountConfig]) => {
+        if (accountConfig.enabled !== true)
+            return total;
+        const model = accountConfig.model ?? config.providers.claude.model;
+        if (quotaState && quotaBlockFor(quotaState, "claude", account, model, new Date(nowMs)).blocked)
+            return total;
+        const occupied = lanes.filter((lane) => lane.provider === "claude" && lane.account === account &&
+            laneOccupiesRunningSlot(lane, nowMs) && laneRunsOnHost(lane, host)).length;
+        return total + Math.max(0, accountMaxRunning(config.providers.claude, account) - occupied);
+    }, 0);
+}
 export function hasActiveAdmissionReservation(lane, nowMs) {
     if (lane.state !== "queued" || lane.queued_reason !== undefined || !lane.admission_reserved_at) {
         return false;

package/dist/lib/lanes/config.js

@@ -152,6 +152,14 @@ function positiveInt(value, field, fallback) {
     }
     return value;
 }
+function nonNegativeInt(value, field, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new LanesConfigError("invalid_config", `${field} must be a non-negative integer`, { field, value });
+    }
+    return value;
+}
 function positiveNumber(value, field, fallback) {
     if (value === undefined)
         return fallback;
@@ -459,6 +467,7 @@ export function documentedDefaultConfig(deps = defaultDeps()) {
         tracker: { checks: { ...DEFAULT_TRACKER_CHECKS } },
         runaway_search_guard: { ...DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG },
         low_disk_min_free_bytes: DEFAULT_LOW_DISK_MIN_FREE_BYTES,
+        lead_reserve_per_host: 1,
         codex_rollout_compress_after_hours: DEFAULT_CODEX_ROLLOUT_COMPRESS_AFTER_HOURS,
         codex_rollout_delete_after_days: DEFAULT_CODEX_ROLLOUT_DELETE_AFTER_DAYS,
         session_question_timeout_secs: DEFAULT_SESSION_QUESTION_TIMEOUT_SECS,
@@ -499,6 +508,7 @@ export function parseLanesConfig(raw, deps = defaultDeps()) {
     }
     const compressAfterHours = positiveInt(raw.codex_rollout_compress_after_hours, "codex_rollout_compress_after_hours", DEFAULT_CODEX_ROLLOUT_COMPRESS_AFTER_HOURS);
     const deleteAfterDays = positiveInt(raw.codex_rollout_delete_after_days, "codex_rollout_delete_after_days", DEFAULT_CODEX_ROLLOUT_DELETE_AFTER_DAYS);
+    const leadReservePerHost = nonNegativeInt(raw.lead_reserve_per_host, "lead_reserve_per_host", 1);
     if (deleteAfterDays * 24 < compressAfterHours) {
         throw new LanesConfigError("invalid_config", "codex_rollout_delete_after_days must be at least codex_rollout_compress_after_hours / 24", { codex_rollout_compress_after_hours: compressAfterHours, codex_rollout_delete_after_days: deleteAfterDays });
     }
@@ -512,6 +522,7 @@ export function parseLanesConfig(raw, deps = defaultDeps()) {
         tracker: { checks: parseTrackerChecks(raw.tracker) },
         runaway_search_guard: parseRunawaySearchGuard(raw.runaway_search_guard),
         low_disk_min_free_bytes: positiveInt(raw.low_disk_min_free_bytes, "low_disk_min_free_bytes", DEFAULT_LOW_DISK_MIN_FREE_BYTES),
+        lead_reserve_per_host: leadReservePerHost,
         codex_rollout_compress_after_hours: compressAfterHours,
         codex_rollout_delete_after_days: deleteAfterDays,
         session_question_timeout_secs: positiveInt(raw.session_question_timeout_secs, "session_question_timeout_secs", DEFAULT_SESSION_QUESTION_TIMEOUT_SECS),

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

@@ -1,5 +1,7 @@
 /** hq-flags keys used by lane command behavior. */
 export declare const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
+/** Gives live senior lanes Claude admission precedence and reserves host capacity for them. */
+export declare const LANE_LEAD_ADMISSION_PRIORITY_FLAG = "lanes.lead-admission-priority";
 /** Refresh provider/model/effort from a worker profile when a done lane takes a new story. */
 export declare const LANE_REUSE_REFRESHES_PROFILE_FLAG = "lanes.reuse-refreshes-profile";
 /** Enables one automatic continuation after a missing-envelope repair. */

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

@@ -1,5 +1,7 @@
 /** hq-flags keys used by lane command behavior. */
 export const LANE_OUTPOST_LOAD_BALANCING_FLAG = "lanes.outpost-load-balancing";
+/** Gives live senior lanes Claude admission precedence and reserves host capacity for them. */
+export const LANE_LEAD_ADMISSION_PRIORITY_FLAG = "lanes.lead-admission-priority";
 /** Refresh provider/model/effort from a worker profile when a done lane takes a new story. */
 export const LANE_REUSE_REFRESHES_PROFILE_FLAG = "lanes.reuse-refreshes-profile";
 /** Enables one automatic continuation after a missing-envelope repair. */

package/dist/lib/lanes/reconcile.js

@@ -8,7 +8,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { parseUserYaml } from "../../utils/user-yaml-error.js";
-import { compareLaneQueueOrder, hasActiveAdmissionReservation, hasActivePendingResume, laneAdmissionCapReason, laneRunsOnHost, withAllLaneAdmissionLocks, } from "./admission.js";
+import { compareLaneQueueOrder, compareLaneQueueOrderWithLeads, freeClaudeAccountSlots, leadLaneIds, hasActiveAdmissionReservation, hasActivePendingResume, laneAdmissionCapReason, laneRunsOnHost, withAllLaneAdmissionLocks, } from "./admission.js";
 import { accountStatus, isCredentialProven, resolveAccount } from "./accounts.js";
 import { effectiveAccountHome } from "./account-home.js";
 import { enforceRegistryApprovalGate } from "./approval-gate.js";
@@ -22,7 +22,7 @@ import { ANSWERED_QUESTIONS_FILE, armLaneWatcher, envelopeRepairMode, isPidRecor
 import { appendCappedHistory, lanesStoreRoot, parseLaneRecord, parseQuestionRecord, readLane, readQuestion, listQuestionIds, updateLane, updateQuestion, } from "./store.js";
 import { applyThrottleDecision, decideAdmission, defaultThrottleDeps, emptyThrottleState, evaluateThrottle, isCpuCheckEnabled, readAvailableMemMb, readThrottleState, resolveCpuBusyFraction, sampleCpuBusyObservation, recordCpuBusyObservation, throttleStatePath, writeThrottleState, } from "./throttle.js";
 import { readLanesRegistryFlag, readLanesRegistryFlagFailOff } from "./registry-flag.js";
-import { LANE_HIRE_GRANT_FINISHED_LANES_FLAG } from "./flag-keys.js";
+import { LANE_HIRE_GRANT_FINISHED_LANES_FLAG, LANE_LEAD_ADMISSION_PRIORITY_FLAG } from "./flag-keys.js";
 import { checkLaneDiskSpace, configuredCodexRolloutHomes, lowDiskGuardEnabledForLane, retainCodexRollouts } from "./disk-guard.js";
 import { laneCompanyUidSource, resolveLaneCompany } from "./lane-company.js";
 import { appendDropboxMessage } from "./dropbox.js";
@@ -30,7 +30,7 @@ import { DEFAULT_RUNAWAY_SEARCH_GUARD_CONFIG, listHostProcesses, runRunawayToolG
 import { LEAD_LANE_KEEP_ALIVE_FLAG, LEAD_LANE_KEEP_ALIVE_RESUME_BLOCKED_FLAG, LEAD_LANE_KEEP_ALIVE_IMMEDIATE_FIRST_RESUME_FLAG, LEAD_LANE_KEEP_ALIVE_FIRST_RESUME_SETTLE_MS, LEAD_LANE_KEEP_ALIVE_NEXT_CHECK_MAX_DELAY_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_GRACE_MS, LEAD_LANE_KEEP_ALIVE_BLOCKED_RESUME_TEXT, queueLaneTerminalResume, LEAD_LANE_KEEP_ALIVE_INTERRUPTED_RESUME_TEXT, LEAD_LANE_KEEP_ALIVE_MAX_RESUMES, LEAD_LANE_KEEP_ALIVE_RESUME_TEXT, LANE_SUPERSESSION_LINEAGE_AWARE_FLAG, doneKeepAliveVerdict, hasPendingKeepAliveWork, keepAliveNextCheckAtMs, keepAliveExclusion, loadRetiredLaneIds, leadLaneKeepAliveBackoffMs, undeliveredAnsweredQuestions, } from "./keep-alive.js";
 import { providerSupportsSessionResume } from "./delivery.js";
 import { isIsoDateTime } from "./types.js";
-import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, readQuotaSignal, recordAccountQuota, } from "./quota.js";
+import { applyDefaultQuotaHold, clearAccountQuotaAfterSuccessfulTurnBestEffort, loadQuotaState, readQuotaSignal, recordAccountQuota, } from "./quota.js";
 import { answeredQuestionEntries, questionRecordRefusalCode, raiseEnvelopeQuestions, resolveQuestionCompanyWithFallback, } from "./questions.js";
 import { SILENCE_MS, appendWatcherEvent, classifyLaneExit, isPidAlive, missingExpectedEnvelopeFile, readLatestEnvelopeFile, readLatestEnvelopeRecord, watcherEventsPath, watcherOutLogPath, writeWatcherDecision, } from "./watcher.js";
 import { createLaneMesh, emitLaneDecisionEvents, emitLaneTerminalStateEvent, laneMeshCompany, } from "./mesh-events.js";
@@ -1808,11 +1808,35 @@ async function admitQueued(hqRoot, lanes, summary, deps, now, onlyLaneIds, exclu
         (excludeLaneIds === undefined || !excludeLaneIds.has(lane.lane_id)) &&
         lane.pickup_validation_pending !== true &&
         laneRunsHere(lane, deps.host))
-        .filter((lane) => !hasFreshAdmissionReservation(lane, now.getTime()))
-        .sort(compareLaneQueueOrder);
+        .filter((lane) => !hasFreshAdmissionReservation(lane, now.getTime()));
     if (localQueued.length === 0 || deps.skipAdmissionWithoutCpuSample === true)
         return;
     const config = loadLanesConfig(hqRoot);
+    const admissionQuotaState = loadQuotaState(hqRoot);
+    const candidateLeadIds = leadLaneIds(lanes);
+    const flagReader = deps.readRegistryFlag ?? readLanesRegistryFlag;
+    const leadAdmissionEnabledById = new Map();
+    const leadFlagByCompany = new Map();
+    for (const leadId of candidateLeadIds) {
+        const lead = lanes.find((lane) => lane.lane_id === leadId && lane.provider === "claude");
+        if (!lead)
+            continue;
+        const resolution = resolveLaneCompany(hqRoot, lead);
+        const company = resolution.company ?? undefined;
+        const key = company?.uid ?? company?.slug ?? lead.company?.uid ?? lead.company?.slug ?? lead.lane_id;
+        let enabled = leadFlagByCompany.get(key);
+        if (!enabled) {
+            enabled = readLanesRegistryFlagFailOff(LANE_LEAD_ADMISSION_PRIORITY_FLAG, {
+                company,
+                ...(company ? { companyUidSource: laneCompanyUidSource(resolution.source) } : {}),
+                env: deps.env,
+            }, flagReader);
+            leadFlagByCompany.set(key, enabled);
+        }
+        leadAdmissionEnabledById.set(leadId, await enabled);
+    }
+    const priorityLeads = new Set([...leadAdmissionEnabledById].filter(([, enabled]) => enabled).map(([id]) => id));
+    localQueued.sort((a, b) => compareLaneQueueOrderWithLeads(a, b, priorityLeads));
     const throttleDeps = deps.throttleDeps ?? defaultThrottleDeps(deps.env ?? process.env);
     const filePath = throttleStatePath(hqRoot);
     const loaded = readThrottleState(filePath, throttleDeps);
@@ -1884,6 +1908,25 @@ async function admitQueued(hqRoot, lanes, summary, deps, now, onlyLaneIds, exclu
             }
         }
         const projected = [...running, ...spawned];
+        const laneResolution = lane.provider === "claude" ? resolveLaneCompany(hqRoot, lane) : undefined;
+        const laneCompany = laneResolution?.company ?? undefined;
+        const laneCompanyKey = laneCompany?.uid ?? laneCompany?.slug ?? lane.company?.uid ?? lane.company?.slug;
+        let reserveEnabled = false;
+        if (lane.provider === "claude" && laneCompanyKey) {
+            let enabled = leadFlagByCompany.get(laneCompanyKey);
+            if (!enabled) {
+                enabled = readLanesRegistryFlagFailOff(LANE_LEAD_ADMISSION_PRIORITY_FLAG, {
+                    company: laneCompany,
+                    ...(laneCompany && laneResolution ? { companyUidSource: laneCompanyUidSource(laneResolution.source) } : {}),
+                    env: deps.env,
+                }, flagReader);
+                leadFlagByCompany.set(laneCompanyKey, enabled);
+            }
+            reserveEnabled = await enabled;
+        }
+        const reserveBlocked = reserveEnabled && lane.provider === "claude" &&
+            !priorityLeads.has(lane.lane_id) &&
+            freeClaudeAccountSlots(projected, config, deps.host, now.getTime(), admissionQuotaState) <= config.lead_reserve_per_host;
         const alternateAccount = availableBalancedAccount(hqRoot, lane, projected, config, deps.host, profileMaxConcurrent, now.getTime());
         const admittedLane = alternateAccount !== undefined
             ? writeAdmissionAccount(hqRoot, lane, alternateAccount, deps.dryRun)
@@ -1891,7 +1934,10 @@ async function admitQueued(hqRoot, lanes, summary, deps, now, onlyLaneIds, exclu
         const baseCap = laneAdmissionCapReason(running, admittedLane, config, deps.host, profileMaxConcurrent, now.getTime());
         const currentCap = laneAdmissionCapReason([...running, ...spawned], admittedLane, config, deps.host, profileMaxConcurrent, now.getTime());
         let blockedBy;
-        if (currentCap !== undefined) {
+        if (reserveBlocked) {
+            blockedBy = "lead_reserve";
+        }
+        else if (currentCap !== undefined) {
             blockedBy = baseCap ?? "queue_position";
         }
         if (!blockedBy && !decision.admit)

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

@@ -177,7 +177,7 @@ export declare const TERMINAL_LANE_STATES: readonly ["done", "failed", "interrup
 export type TerminalLaneState = (typeof TERMINAL_LANE_STATES)[number];
 export declare const LANE_PROVIDERS: readonly ["claude", "codex", "grok"];
 export type LaneProvider = (typeof LANE_PROVIDERS)[number];
-export declare const QUEUED_REASONS: readonly ["cap", "provider_cap", "account_cap", "profile_cap", "queue_position", "throttle", "provider_binary_missing", "account_retry", "worker_profile_changed", "low_disk", "admit_failed"];
+export declare const QUEUED_REASONS: readonly ["cap", "provider_cap", "account_cap", "profile_cap", "queue_position", "throttle", "provider_binary_missing", "account_retry", "lead_reserve", "worker_profile_changed", "low_disk", "admit_failed"];
 export type QueuedReason = (typeof QUEUED_REASONS)[number];
 export type QueuedDetails = {
     reason: "worker_profile_changed";
@@ -1029,6 +1029,8 @@ export interface LanesConfig {
     runaway_search_guard?: RunawaySearchGuardConfig;
     /** Optional free-space threshold override for the low-disk admission gate. */
     low_disk_min_free_bytes?: number;
+    /** Claude account slots kept available per host for senior lead lanes. */
+    lead_reserve_per_host: number;
     /** Retention ages for Codex session rollout maintenance. */
     codex_rollout_compress_after_hours?: number;
     codex_rollout_delete_after_days?: number;

package/dist/lib/lanes/types.js

@@ -111,6 +111,7 @@ export const QUEUED_REASONS = [
     "throttle",
     "provider_binary_missing",
     "account_retry",
+    "lead_reserve",
     "worker_profile_changed",
     "low_disk",
     "admit_failed",

package/dist/lib/log-follow.d.ts

@@ -0,0 +1,3 @@
+/** Follow append-only log bytes without importing package code after startup. */
+export declare function followLogFile(file: string, initialOffset: number, write: (chunk: string) => void): Promise<void>;
+//# sourceMappingURL=log-follow.d.ts.map

package/dist/lib/log-follow.js

@@ -0,0 +1,20 @@
+import * as fs from "node:fs";
+/** Follow append-only log bytes without importing package code after startup. */
+export async function followLogFile(file, initialOffset, write) {
+    let offset = initialOffset;
+    await new Promise(() => {
+        fs.watchFile(file, { interval: 500 }, (curr) => {
+            if (curr.size < offset)
+                offset = 0;
+            if (curr.size === offset)
+                return;
+            const fd = fs.openSync(file, "r");
+            const buf = Buffer.alloc(curr.size - offset);
+            fs.readSync(fd, buf, 0, buf.length, offset);
+            fs.closeSync(fd);
+            offset = curr.size;
+            write(buf.toString("utf8"));
+        });
+    });
+}
+//# sourceMappingURL=log-follow.js.map

package/dist/main.js

@@ -362,12 +362,23 @@ function qmdSpawnFailureCaptureContext(err) {
     return { contexts: { qmd_spawn_failure: diagnostics } };
 }
 const GATEWAY_RPC_CODE_TAGS = new Map([
+    [-32700, "parse_error"],
+    [-32601, "method_not_found"],
     [-32603, "internal_error"],
     [-32009, "conflict"],
     [-32003, "unauthorized"],
     [-32602, "invalid_params"],
     [-32050, "provider_error"],
 ]);
+const GATEWAY_ERROR_SHAPES = new Set([
+    "string_error",
+    "object_no_code",
+    "object_code",
+    "string_code",
+    "nested_code",
+    "empty",
+    "redacted_empty",
+]);
 function integrationsGatewayCaptureContext(err) {
     if (err === null || typeof err !== "object")
         return undefined;
@@ -386,11 +397,16 @@ function integrationsGatewayCaptureContext(err) {
     const codeTag = typeof rpcCode === "number" && Number.isInteger(rpcCode)
         ? GATEWAY_RPC_CODE_TAGS.get(rpcCode) ?? "other"
         : rpcCode === undefined ? "missing" : "other";
+    const errorShape = record.gatewayErrorShape;
+    const errorShapeTag = typeof errorShape === "string" && GATEWAY_ERROR_SHAPES.has(errorShape)
+        ? errorShape
+        : "unknown";
     return {
         tags: {
             integration_gateway_status: statusTag,
             integration_gateway_code: codeTag,
             integration_subcommand: subcommandTag,
+            integration_gateway_error_shape: errorShapeTag,
         },
     };
 }

package/dist/utils/resident-package-preload.d.ts

@@ -1,5 +1,5 @@
-export type ResidentPackagePath = "agent-kit" | "agent-mcp" | "auth-login" | "bot" | "childWrapper" | "coreJobRun" | "login" | "mcp" | "daemon" | "mesh-daemon" | "lanes-watch" | "monitor-wait" | "monitor-run";
-/** Package imports reachable lazily from each resident command's runtime graph. */
+export type ResidentPackagePath = "agent-kit" | "agent-mcp" | "auth-login" | "agents-terminal" | "bot" | "bot-logs-follow" | "childWrapper" | "coreJobRun" | "login" | "mcp" | "daemon" | "daemon-logs-follow" | "mesh-daemon" | "lanes-watch" | "monitor-wait" | "monitor-run" | "agents-message-wait" | "integrations-oauth-wait";
+/** Runtime modules that resident commands may need after a wait starts. */
 export declare const RESIDENT_PACKAGE_MODULES: Record<ResidentPackagePath, readonly string[]>;
 export declare class ResidentPackagePreloadError extends Error {
     readonly moduleSpecifier: string;