@indigoai-us/hq-cli 5.342.14 → 5.342.15

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+## [5.342.15] — 2026-10-04
+- Preserve bounded integration subcommand and RPC error context on asynchronous gateway failures, and retain diagnostics for malformed HTTP 200 gateway errors (HQ-CLI-C8/C9).
+- Claude admission can prioritize lanes that are seniors of live lanes and keep configurable per-host capacity reserved for them when `lanes.lead-admission-priority` is enabled.
+
 ## [5.342.14] — 2026-10-04
 - Fixed native HQ subprocess launching and job-lock command resolution on Windows.
 - Fixed Windows delegate/job shell parity while preserving embedded carriage returns and POSIX command/path bytes.

package/dist/commands/integrations-core.d.ts

@@ -110,11 +110,9 @@ export interface AdminSurface {
 }
 interface GatewayMessage {
     result?: unknown;
-    error?: {
-        code?: number;
-        message?: string;
-    };
+    error?: unknown;
 }
+export type GatewayErrorShape = "string_error" | "object_no_code" | "object_code" | "string_code" | "nested_code" | "empty" | "redacted_empty";
 export declare class IntegrationsCliError extends Error {
     /**
      * True when the error is the caller's request/state/permission (a client 4xx
@@ -152,6 +150,8 @@ export declare class IntegrationsCliError extends Error {
     readonly rpcCode?: number;
     /** Fixed vocabulary for the integrations subcommand that called the gateway. */
     readonly gatewaySubcommand?: "tools_list" | "tools_call" | "other";
+    /** Fixed vocabulary describing the shape of an upstream JSON-RPC error. */
+    readonly gatewayErrorShape?: GatewayErrorShape;
     /**
      * HQ's own OAuth callback URL, carried on the errors that say a provider
      * refused to register HQ automatically. The provider must register the exact
@@ -167,6 +167,7 @@ export declare class IntegrationsCliError extends Error {
         oauthProtected?: boolean;
         rpcCode?: number;
         gatewaySubcommand?: "tools_list" | "tools_call" | "other";
+        gatewayErrorShape?: GatewayErrorShape;
         redirectUri?: string;
     });
 }

package/dist/commands/integrations-core.js

@@ -57,6 +57,8 @@ export class IntegrationsCliError extends Error {
     rpcCode;
     /** Fixed vocabulary for the integrations subcommand that called the gateway. */
     gatewaySubcommand;
+    /** Fixed vocabulary describing the shape of an upstream JSON-RPC error. */
+    gatewayErrorShape;
     /**
      * HQ's own OAuth callback URL, carried on the errors that say a provider
      * refused to register HQ automatically. The provider must register the exact
@@ -79,6 +81,8 @@ export class IntegrationsCliError extends Error {
             this.rpcCode = opts.rpcCode;
         if (opts.gatewaySubcommand !== undefined)
             this.gatewaySubcommand = opts.gatewaySubcommand;
+        if (opts.gatewayErrorShape !== undefined)
+            this.gatewayErrorShape = opts.gatewayErrorShape;
         if (opts.redirectUri !== undefined) {
             Object.defineProperty(this, "redirectUri", {
                 value: opts.redirectUri,
@@ -191,6 +195,54 @@ function expectedGatewayErrorFallback(code) {
             return undefined;
     }
 }
+function recordValue(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function numericGatewayCode(value) {
+    if (typeof value === "number" && Number.isSafeInteger(value))
+        return value;
+    if (typeof value === "string" && /^-?\d+$/.test(value.trim())) {
+        const parsed = Number(value.trim());
+        if (Number.isSafeInteger(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+/** Read the known JSON-RPC error fields without stringifying arbitrary payload data. */
+function gatewayErrorDetails(error) {
+    if (typeof error === "string") {
+        const message = redactErrorText(error);
+        return {
+            message,
+            shape: message ? "string_error" : "redacted_empty",
+        };
+    }
+    const record = recordValue(error);
+    if (!record)
+        return { message: "", shape: "empty" };
+    const data = recordValue(record.data);
+    const rawMessage = typeof record.message === "string" ? record.message : undefined;
+    const message = rawMessage === undefined ? "" : redactErrorText(rawMessage);
+    const directCode = record.code;
+    const nestedCode = data?.code;
+    const directRpcCode = numericGatewayCode(directCode);
+    const nestedRpcCode = numericGatewayCode(nestedCode);
+    const rpcCode = directRpcCode ?? nestedRpcCode;
+    const hasStringCode = typeof directCode === "string" || typeof nestedCode === "string";
+    const redactedEmptyMessage = rawMessage !== undefined && rawMessage.length > 0 && !message;
+    const shape = redactedEmptyMessage
+        ? "redacted_empty"
+        : nestedCode !== undefined
+            ? "nested_code"
+            : hasStringCode
+                ? "string_code"
+                : directCode !== undefined
+                    ? "object_code"
+                    : message ? "object_no_code" : "empty";
+    return { message, ...(rpcCode === undefined ? {} : { rpcCode }), shape };
+}
 // A 401 from ANY integration-gateway vault call means the caller's HQ session
 // is expired or missing — an expected auth state fixed by `hq login`, not an
 // hq-cli defect. Raise the same typed AuthError the vault company-resolution
@@ -446,16 +498,16 @@ export async function callGateway(token, params, idempotencyKey) {
         const accepted = message;
         const jobId = accepted && typeof accepted.jobId === "string" ? accepted.jobId : "";
         if (accepted?.status !== "pending" || !/^imj_[A-Za-z0-9_-]+$/.test(jobId)) {
-            throw new IntegrationsCliError(`Integration gateway returned an invalid async job response (job id: ${jobId || "missing"}).`, { expected: false, status: 202 });
+            throw new IntegrationsCliError(`Integration gateway returned an invalid async job response (job id: ${jobId || "missing"}).`, { expected: false, status: 202, gatewaySubcommand });
         }
         const companyUid = typeof params.companyUid === "string" ? params.companyUid : "";
         if (!companyUid) {
             throw new IntegrationsCliError(`Cannot poll integration job ${jobId}: the company id is missing.`, { expected: true });
         }
         if (!idempotencyKey) {
-            throw new IntegrationsCliError(`Integration gateway accepted async job ${jobId} without an idempotency key.`, { expected: false, status: 202 });
+            throw new IntegrationsCliError(`Integration gateway accepted async job ${jobId} without an idempotency key.`, { expected: false, status: 202, gatewaySubcommand });
         }
-        const terminal = await pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline);
+        const terminal = await pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline, gatewaySubcommand);
         terminalMessage = terminal.message;
         terminalStatus = terminal.status;
     }
@@ -470,6 +522,7 @@ export async function callGateway(token, params, idempotencyKey) {
         throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status, gatewaySubcommand });
     }
     if (terminalMessage?.error) {
+        const gatewayError = gatewayErrorDetails(terminalMessage.error);
         // The gateway's error text is minted UPSTREAM (hq-pro, the integration
         // factory, and beyond it the third-party provider), so it is untrusted:
         // scrub credentials and bound the length here, at the throw site, because
@@ -478,21 +531,22 @@ export async function callGateway(token, params, idempotencyKey) {
         // The chain is idempotent, so the unexpected path scrubbing again is a
         // no-op. This preserves PR #298's user-visible diagnostic; it only makes
         // it safe on the newly-expected path.
-        throw new IntegrationsCliError(redactErrorText(terminalMessage.error.message ?? "") ||
-            expectedGatewayErrorFallback(terminalMessage.error.code) ||
+        throw new IntegrationsCliError(gatewayError.message ||
+            expectedGatewayErrorFallback(gatewayError.rpcCode) ||
             "Integration gateway returned an error.", {
-            expected: isExpectedGatewayError(terminalMessage.error.code),
+            expected: isExpectedGatewayError(gatewayError.rpcCode),
             status: terminalStatus,
             gatewaySubcommand,
+            gatewayErrorShape: gatewayError.shape,
             // Carry the protocol code to the capture site as a bounded grouping
             // discriminator (HQ-CLI collision, Sentry 7642756130). This does not
             // alter the `expected` decision above; it only labels the error.
-            ...(terminalMessage.error.code !== undefined ? { rpcCode: terminalMessage.error.code } : {}),
+            ...(gatewayError.rpcCode === undefined ? {} : { rpcCode: gatewayError.rpcCode }),
         });
     }
     return terminalMessage;
 }
-async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline) {
+async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, deadline, gatewaySubcommand) {
     const jobPath = `/v1/integrations/mcp/jobs/${encodeURIComponent(jobId)}`;
     while (Date.now() < deadline) {
         const requestRemainingMs = deadline - Date.now();
@@ -526,7 +580,7 @@ async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, dea
             if (res.status === 404) {
                 throw new IntegrationsCliError(`Integration job ${jobId} was not found or is no longer available.`, { expected: true, status: 404 });
             }
-            throw new IntegrationsCliError(`Integration job ${jobId} polling failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status });
+            throw new IntegrationsCliError(`Integration job ${jobId} polling failed (HTTP ${res.status}).`, { expected: isClientError(res.status), status: res.status, gatewaySubcommand });
         }
         if (!poll || typeof poll !== "object") {
             throw new IntegrationsCliError(`Integration job ${jobId} returned an invalid poll response.`, { expected: true });
@@ -549,7 +603,7 @@ async function pollAsyncGatewayJob(token, companyUid, jobId, idempotencyKey, dea
                 hasResult !== hasError &&
                 (!hasError || validError);
             if (!hasJsonRpcOutcome) {
-                throw new IntegrationsCliError(`Integration job ${jobId} returned an invalid JSON-RPC response.`, { expected: false });
+                throw new IntegrationsCliError(`Integration job ${jobId} returned an invalid JSON-RPC response.`, { expected: false, gatewaySubcommand });
             }
             return { message: response, status: res.status };
         }

package/dist/commands/lanes-accounts.js

@@ -10,6 +10,7 @@ import { resolveLaneEffort } from "../lib/lanes/effort.js";
 import { LanesError } from "../lib/lanes/errors.js";
 import { accountQuotaView, clearAccountQuota, loadQuotaState } from "../lib/lanes/quota.js";
 import { resolveLaneModel } from "../lib/lanes/spawn.js";
+import { leadLaneIds } from "../lib/lanes/admission.js";
 export function createLaneAccountsHandlers(deps) {
     const { automaticBalanceMoveHistoryReason, ensureDir, laneWithRecoveredProviderSession, loadClaudeBalanceHostSnapshots, parseRemoteJson, prepareAccountMove, printJson, reconcileHostFromCtx, resolveCallerPath } = deps;
     const VENDOR_LOGIN = {
@@ -269,6 +270,13 @@ export function createLaneAccountsHandlers(deps) {
             balance_gate_enabled: balanceGateEnabled,
             accounts,
             selections,
+            lead_reserve_per_host: config.lead_reserve_per_host,
+            queued_leads: loaded.snapshots.flatMap((host) => {
+                const leads = leadLaneIds(host.lanes);
+                return host.lanes
+                    .filter((lane) => lane.provider === "claude" && lane.state === "queued" && leads.has(lane.lane_id))
+                    .map((lane) => ({ lane_id: lane.lane_id, host: host.capacity.host, queued_reason: lane.queued_reason ?? null }));
+            }),
             unavailable_hosts: loaded.unavailableHosts,
             suggestions,
             ...(opts.apply ? { moved, skipped } : {}),

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

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