@indigoai-us/hq-cli 5.345.145 → 5.345.146

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+## [5.345.146] — 2026-10-17
+- `hq capacity route` and `hq lanes create --account auto` can now use a Claude account whose weekly limit is used up but whose paid extra usage is on. Pass `--allow-extra-usage` to allow it; the account is picked last. Without the flag, the refusal now says extra usage is on and names the flag.
+
 ## [5.345.145] — 2026-10-17
 - `hq core checkpoint`: the background checkpoint helper now fills in automatic
   saves that were queued before it started. It writes its own report first,

package/dist/command-catalog.generated.d.ts

@@ -10375,6 +10375,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly description: "Minimum headroom percent the pick must clear (0-100)";
             readonly hidden: false;
             readonly defaultValue: "15";
+        }, {
+            readonly flags: "--allow-extra-usage";
+            readonly description: "Rank a Claude account whose plan limit is used up but whose paid extra usage is on (ranked last)";
+            readonly hidden: false;
         }, {
             readonly flags: "--json";
             readonly description: "Print the route result as JSON (default)";
@@ -14052,6 +14056,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--account <id>";
             readonly description: "Provider account id, or 'auto' to pick the account with the most room (all accounts are one pool across companies)";
             readonly hidden: false;
+        }, {
+            readonly flags: "--allow-extra-usage";
+            readonly description: "With --account auto, allow a Claude account whose plan limit is used up but whose paid extra usage is on; ranked last";
+            readonly hidden: false;
         }, {
             readonly flags: "--model <id>";
             readonly description: "Model id for the provider CLI";

package/dist/command-catalog.generated.js

@@ -12573,6 +12573,11 @@ export const COMMAND_CATALOG = [
                         "hidden": false,
                         "defaultValue": "15"
                     },
+                    {
+                        "flags": "--allow-extra-usage",
+                        "description": "Rank a Claude account whose plan limit is used up but whose paid extra usage is on (ranked last)",
+                        "hidden": false
+                    },
                     {
                         "flags": "--json",
                         "description": "Print the route result as JSON (default)",
@@ -17082,6 +17087,11 @@ export const COMMAND_CATALOG = [
                         "description": "Provider account id, or 'auto' to pick the account with the most room (all accounts are one pool across companies)",
                         "hidden": false
                     },
+                    {
+                        "flags": "--allow-extra-usage",
+                        "description": "With --account auto, allow a Claude account whose plan limit is used up but whose paid extra usage is on; ranked last",
+                        "hidden": false
+                    },
                     {
                         "flags": "--model <id>",
                         "description": "Model id for the provider CLI",

package/dist/commands/capacity.js

@@ -358,6 +358,7 @@ export function registerCapacityCommand(program) {
         .option("--model <id>", "Model id. Narrows --provider any to the mapped provider")
         .option("--prefer <list>", "Comma-separated preferred provider order", "claude,codex,grok")
         .option("--floor <percent>", "Minimum headroom percent the pick must clear (0-100)", "15")
+        .option("--allow-extra-usage", "Rank a Claude account whose plan limit is used up but whose paid extra usage is on (ranked last)")
         .option("--json", "Print the route result as JSON (default)")
         .option("--text", "Print a single-line text summary instead of JSON")
         .action((_opts, command) => {
@@ -394,6 +395,7 @@ export function registerCapacityCommand(program) {
                     collectorEnabled: mark ? mark.enabled : null,
                     capacityStale: freshness.stale,
                     lanesError,
+                    allowExtraUsage: opts.allowExtraUsage === true,
                 });
             }
             catch (err) {

package/dist/commands/lanes.js

@@ -3483,6 +3483,7 @@ async function runCreate(ctx, opts) {
             collectorEnabled: readCollectorMark(ledgerOptions)?.enabled ?? null,
             capacityStale: capacityViewAge(view.generatedAt, ctx.now().getTime()).stale,
             lanesError: routeLanesError,
+            allowExtraUsage: opts.allowExtraUsage === true,
         });
         if (!result.ok || !result.pick) {
             const resetSuffix = result.next_reset ? `; next reset ${result.next_reset}` : "";
@@ -9935,6 +9936,7 @@ export function registerLanesCommand(parent, deps = {}) {
         .option("--remote-control", "Open a Claude lane in Remote Control using account a for login and the selected account for inference")
         .option("--title <text>", "Human-readable Claude Remote Control session title; required with --remote-control")
         .option("--account <id>", "Provider account id, or 'auto' to pick the account with the most room (all accounts are one pool across companies)")
+        .option("--allow-extra-usage", "With --account auto, allow a Claude account whose plan limit is used up but whose paid extra usage is on; ranked last")
         .option("--model <id>", "Model id for the provider CLI")
         .option("--effort <level>", "Effort level; claude: low|medium|high|xhigh|max, codex: minimal|low|medium|high|xhigh|max|ultra, grok: low|medium|high|xhigh")
         .option("--senior <ref>", "session:<id> | lane:<id> | user")

package/dist/lib/capacity/route.d.ts

@@ -1,6 +1,6 @@
 import type { LaneRecord, LaneState, LanesConfig } from "../lanes/types.js";
 import { type LaneProvider } from "../lanes/types.js";
-import { type NowLimit, type NowView } from "./ledger.js";
+import { type NowAccount, type NowLimit, type NowView } from "./ledger.js";
 /** All lane providers, in the stable order boss-route uses for ranking ties. */
 export declare const ROUTE_PROVIDERS: readonly LaneProvider[];
 /** Lane states that count against an account's live load. */
@@ -28,6 +28,12 @@ export declare const OLD_READING_PENALTY = 10;
  * view stale). Sits below any account with fresh known headroom.
  */
 export declare const UNKNOWN_USAGE_SCORE = -100;
+/**
+ * Score for an account whose plan limit is used up but which still runs on
+ * paid extra usage. Ranked only with --allow-extra-usage, below every account
+ * with plan room or unknown usage.
+ */
+export declare const EXTRA_USAGE_SCORE = -200;
 /** Default --floor applied by the CLI (percent headroom to clear). */
 export declare const DEFAULT_FLOOR = 15;
 /** Default --prefer order applied by the CLI. */
@@ -85,6 +91,8 @@ export interface RouteRanked {
     lane_flags: string;
     /** True when no usable reading exists and the account is ranked as unknown. */
     usage_unknown: boolean;
+    /** True when a plan limit is used up and the lane would spend paid extra usage. */
+    extra_usage?: boolean;
 }
 /** Live lane on an account the router would avoid; command names a replacement. */
 export interface RouteMove {
@@ -130,6 +138,12 @@ export interface PickAccountInput {
     capacityStale?: boolean;
     /** Error summary when the lanes list could not be read. */
     lanesError?: string | null;
+    /**
+     * Owner opt-in (2026-10-17): rank an account whose plan limit is used up
+     * but whose Claude extra usage is enabled and not capped. Off by default so
+     * lanes never spend paid usage without being asked to.
+     */
+    allowExtraUsage?: boolean;
 }
 export declare class RouteUsageError extends Error {
     readonly code = "route_usage";
@@ -141,6 +155,12 @@ export declare function resolveRequestedProviders(raw: readonly string[] | undef
 export declare function resolvePreferOrder(raw: readonly string[] | undefined): LaneProvider[];
 /** Parse `--floor <n>`; 0..100 inclusive, default DEFAULT_FLOOR when missing. */
 export declare function resolveFloor(raw: string | number | undefined): number;
+/**
+ * True when the account's Claude extra usage reading says the provider will
+ * keep serving it after a plan limit runs out: enabled, not at its monthly
+ * cap, and not stopped by a spend control.
+ */
+export declare function hasExtraUsageRoom(account: NowAccount): boolean;
 /**
  * Pure routing decision over a snapshot: scores every signed-in lane account,
  * applies the --prefer order under the --floor headroom, returns the pick (or

package/dist/lib/capacity/route.js

@@ -47,6 +47,12 @@ export const OLD_READING_PENALTY = 10;
  * view stale). Sits below any account with fresh known headroom.
  */
 export const UNKNOWN_USAGE_SCORE = -100;
+/**
+ * Score for an account whose plan limit is used up but which still runs on
+ * paid extra usage. Ranked only with --allow-extra-usage, below every account
+ * with plan room or unknown usage.
+ */
+export const EXTRA_USAGE_SCORE = -200;
 /** Default --floor applied by the CLI (percent headroom to clear). */
 export const DEFAULT_FLOOR = 15;
 /** Default --prefer order applied by the CLI. */
@@ -178,6 +184,27 @@ function liveLaneCount(lanes, provider, account) {
     }
     return count;
 }
+/**
+ * True when the account's Claude extra usage reading says the provider will
+ * keep serving it after a plan limit runs out: enabled, not at its monthly
+ * cap, and not stopped by a spend control.
+ */
+export function hasExtraUsageRoom(account) {
+    const limits = account.limits ?? [];
+    const extra = limits.find((l) => l.kind === "credits" && l.limitId === "extra_usage");
+    if (!extra || extra.hasCredits !== true)
+        return false;
+    if (extra.spendControlReached === true)
+        return false;
+    if (typeof extra.usedPercent === "number" && extra.usedPercent >= 100)
+        return false;
+    const spend = limits.find((l) => l.kind === "credits" && l.limitId === "spend");
+    if (spend?.spendControlReached === true)
+        return false;
+    if (spend && typeof spend.usedPercent === "number" && spend.usedPercent >= 100)
+        return false;
+    return true;
+}
 function limitAgeMs(view, nowMs) {
     if (!view.resetPassed || !view.limit.resetsAt)
         return view.readAge;
@@ -368,9 +395,49 @@ export function pickAccount(input) {
                 && row.readAge <= LIMIT_STALE_MS
                 && (row.limit.state === "exhausted" || (typeof row.used === "number" && row.used >= 100)));
             if (exhausted) {
+                const extraRoom = providerId === "claude" && hasExtraUsageRoom(account);
+                if (extraRoom && input.allowExtraUsage === true) {
+                    const live = liveLaneCount(lanes, providerId, laneMatch.id);
+                    const weekly = applicable.find((l) => l.kind === "weekly_all");
+                    const whyParts = [
+                        `${labelLimit(exhausted.limit)} used up; runs on paid extra usage (--allow-extra-usage)`,
+                    ];
+                    if (live)
+                        whyParts.push(`${live} live lane${live === 1 ? "" : "s"} already on it`);
+                    if (tokenExpired)
+                        whyParts.push("sign-in renews when the lane starts");
+                    ranked.push({
+                        provider: providerId,
+                        account: laneMatch.id,
+                        label,
+                        organization: account.organization ?? null,
+                        headroom: 0,
+                        score: EXTRA_USAGE_SCORE - live * LANE_PENALTY,
+                        live_lanes: live,
+                        reset_soon: false,
+                        token_expired: tokenExpired,
+                        reading_age_h: Math.round(limitAgeMs(exhausted, nowMs) / 36e5),
+                        binding: {
+                            limit: labelLimit(exhausted.limit),
+                            used_percent: typeof exhausted.used === "number" ? exhausted.used : 100,
+                            resets_at: exhausted.limit.resetsAt ?? null,
+                        },
+                        weekly_resets_at: weekly?.resetsAt ?? null,
+                        why: whyParts.join("; "),
+                        lane_flags: `--provider ${providerId} --account ${laneMatch.id}`,
+                        usage_unknown: false,
+                        extra_usage: true,
+                    });
+                    continue;
+                }
                 skipped.push({
                     ...base,
-                    reason: `${labelLimit(exhausted.limit)} used up`,
+                    reason: extraRoom
+                        ? `${labelLimit(exhausted.limit)} used up; extra usage is on`
+                        : `${labelLimit(exhausted.limit)} used up`,
+                    ...(extraRoom
+                        ? { fix: "pass --allow-extra-usage to run on paid extra usage" }
+                        : {}),
                     resets_at: exhausted.limit.resetsAt ?? null,
                 });
                 continue;

package/package.json

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