@phnx-labs/agents-cli 1.22.105 → 1.22.106

package/dist/lib/accounting/account-launch.js

@@ -0,0 +1,117 @@
+/**
+ * Canonical target-local account launch resolution (PHNX-3940).
+ *
+ * Callers may carry a selector or a {@link RotateCandidate} across a routing
+ * boundary. This module resolves that intent on the machine that will spawn the
+ * harness, where account slots and credential stores actually live. The result
+ * is deliberately local-only: `execHome` and `env` must never cross SSH or be
+ * written to events.
+ */
+import * as fs from 'node:fs';
+import { resolveSpawnAccount } from '../account-registry.js';
+import { adoptedConfigPointsAtHome, adoptedSymlinkMismatchError, durableSlotEnv, isSymlinkAdoptedHarness, resolveNativeSpawnHome, symlinkAdoptedAccountError, } from '../exec-account-home.js';
+import { getVersionHomePath } from '../installations/versions.js';
+import { readMeta } from '../state.js';
+import { candidateAccountKey } from './rotate.js';
+function launchAccountFromSpawn(account) {
+    return {
+        kind: account.kind,
+        id: account.id,
+        name: account.name,
+        selector: account.name,
+        key: `${account.kind}:${account.id}`,
+    };
+}
+function candidateSelector(candidate) {
+    return candidate.nativeAccount ?? candidate.providerAccount;
+}
+function legacyAccount(candidate) {
+    const key = candidateAccountKey(candidate);
+    const name = candidate.accountLabel || candidate.email || key;
+    return {
+        kind: 'legacy-native',
+        id: candidate.accountKey ?? candidate.email ?? key,
+        name,
+        selector: candidate.email ?? candidate.accountKey ?? name,
+        key,
+    };
+}
+/**
+ * Resolve one account-specific attempt at the local spawn boundary.
+ *
+ * Native selections resolve the registered slot and harness-specific home;
+ * provider selections materialize their credential env exactly here. An
+ * unmigrated version-home candidate remains a compatibility case, but it is
+ * never rediscovered by scanning homes for identity.
+ */
+export async function resolveLocalAccountLaunch(options) {
+    const meta = options.meta ?? readMeta();
+    const selected = options.candidate;
+    const selector = options.selector ?? (selected ? candidateSelector(selected) : undefined);
+    // Compatibility for a candidate already discovered in an unmigrated home.
+    // The candidate is the identity decision; the label only locates that exact
+    // local config home and never participates in account comparison.
+    if (selected && !selector) {
+        const execHome = getVersionHomePath(options.agent, selected.version);
+        if (!fs.existsSync(execHome)) {
+            throw new Error(`${selected.accountLabel || options.agent} has no local account home at ${execHome}.`);
+        }
+        return {
+            agent: options.agent,
+            executableVersion: options.executableVersion,
+            account: legacyAccount(selected),
+            execHome,
+            configVersion: selected.version,
+            env: {},
+            signedIn: selected.signedIn,
+            email: selected.email,
+        };
+    }
+    const spawnAccount = resolveSpawnAccount(selector, options.agent, options.executableVersion, meta, {
+        useDefault: options.useDefault,
+        provider: options.provider,
+        target: options.target,
+    });
+    if (!spawnAccount) {
+        return {
+            agent: options.agent,
+            executableVersion: options.executableVersion,
+            account: null,
+            env: {},
+            signedIn: selected?.signedIn ?? null,
+            email: selected?.email ?? null,
+        };
+    }
+    const account = launchAccountFromSpawn(spawnAccount);
+    if (spawnAccount.kind === 'provider') {
+        return {
+            agent: options.agent,
+            executableVersion: options.executableVersion,
+            account,
+            env: spawnAccount.env,
+            signedIn: selected?.signedIn ?? true,
+            email: selected?.email ?? null,
+        };
+    }
+    if (isSymlinkAdoptedHarness(options.agent)) {
+        const defaultName = meta.accounts?.defaults?.[options.agent];
+        if (spawnAccount.name !== defaultName) {
+            throw new Error(symlinkAdoptedAccountError(options.agent, spawnAccount.name, defaultName));
+        }
+    }
+    const home = await resolveNativeSpawnHome(options.agent, spawnAccount, meta);
+    if (isSymlinkAdoptedHarness(options.agent)
+        && !adoptedConfigPointsAtHome(options.agent, home.execHome)) {
+        throw new Error(adoptedSymlinkMismatchError(options.agent, spawnAccount.name, home.execHome));
+    }
+    return {
+        agent: options.agent,
+        executableVersion: options.executableVersion,
+        account,
+        execHome: home.execHome,
+        configVersion: home.source === 'legacy-home' ? home.label : undefined,
+        env: durableSlotEnv(options.agent, spawnAccount, home, meta),
+        signedIn: selected?.signedIn ?? null,
+        email: selected?.email ?? null,
+    };
+}

package/dist/lib/accounting/account-pool-collect.js

@@ -19,7 +19,7 @@ function localRegistryRecords() {
     try {
         return Object.values(readAccountRegistry().accounts)
             .filter((a) => hasKeychainTokenSync(a.secretRef))
-            .map((a) => ({ name: a.name, provider: a.provider, auth: a.auth, secretPresent: true }));
+            .map((a) => ({ id: a.id, name: a.name, provider: a.provider, auth: a.auth, secretPresent: true }));
     }
     catch (err) {
         if (isSecretsTransportError(err))
@@ -66,6 +66,7 @@ export function foldRegistryCandidates(agent, inputs) {
         authVerdict: null,
         lastActive: null,
         providerAccount: r.name,
+        providerAccountId: r.id,
     }));
     return [...native, ...extra];
 }

package/dist/lib/accounting/account-pool.d.ts

@@ -13,6 +13,7 @@ import type { AccountAuthKind } from '../account-provider-registry.js';
  */
 /** A provider account record as stored in the registry (identity captured separately). */
 export interface RegistryAccountRecord {
+    id?: string;
     name: string;
     provider: string;
     auth: AccountAuthKind;
@@ -29,6 +30,7 @@ export interface RegistryAccountRecord {
 }
 /** A registry account eligible to run one harness, ready to map to a candidate. */
 export interface RegistryAccountInput {
+    id?: string;
     /** Agent-scoped key so `(claude, X)` and `(codex, X)` stay distinct. */
     accountKey: string;
     email: string | null;

package/dist/lib/accounting/account-pool.js

@@ -22,6 +22,7 @@ export function registryPoolCandidates(records, agent) {
         if (!providerAuthenticatesHarness(r.provider, r.auth, agent))
             continue;
         out.push({
+            id: r.id,
             accountKey: `${agent}:name=${r.name}`,
             email: null,
             name: r.name,

package/dist/lib/accounting/rotate.d.ts

@@ -68,6 +68,9 @@ export interface RotateCandidate {
      * binary (managed install) and is no longer the account identity.
      */
     nativeAccount?: string;
+    /** Stable registry id for {@link nativeAccount}; never inferred from version. */
+    nativeAccountId?: string;
+    providerAccountId?: string;
     /** Slot dir when this candidate is a slot — the spawn HOME. */
     slotDir?: string;
     /** True when this row came from `deviceAccounts.slots`, not a version home. */
@@ -242,7 +245,7 @@ export type AccountReadiness = {
     ready: true;
 } | {
     ready: false;
-    reason: 'rate_limited' | 'out_of_credits' | 'signed_out' | 'revoked';
+    reason: 'rate_limited' | 'out_of_credits' | 'signed_out' | 'revoked' | 'model_limited';
     email: string | null;
 };
 /**
@@ -254,8 +257,19 @@ export type AccountReadiness = {
  * snapshot never carries). When a live snapshot exists it wins over the cached
  * status — matching the gate — so a stale `out_of_credits` cache is not
  * reported while the account is actually serving requests.
- */
-export declare function readinessFromCandidate(candidate: RotateCandidate, now?: number): AccountReadiness;
+ *
+ * `model`, when supplied, additionally consults a per-(account, model)
+ * refusal Claude can surface on ONE model family ("You've reached your Fable
+ * limit…") while the account's other models and its global usage windows stay
+ * healthy — a global rate_limited/out_of_credits marker would wrongly exclude
+ * the whole account for an unrelated model. Keyed on the candidate's stable
+ * native account id (never the org-shared usageKey) via
+ * {@link candidateAccountKey}, so a model-only limit on one login can never
+ * poison a sibling account that merely shares the same org usage bucket.
+ * Omitting `model` (every existing caller) leaves generic account status
+ * completely unaffected — the model check runs only when a caller opts in.
+ */
+export declare function readinessFromCandidate(candidate: RotateCandidate, now?: number, model?: string): AccountReadiness;
 /**
  * Whether a human sitting at a terminal can clear this exclusion by launching
  * the agent and signing in. The two unhealthy classes are opposites, and the
@@ -287,6 +301,14 @@ export declare function signInRecoverableCandidates(candidates: RotateCandidate[
  * than the version home carries), so neither is checkable here.
  */
 export declare function checkRunAccountReadiness(agent: AgentId, version: string): Promise<AccountReadiness>;
+/**
+ * Identity a candidate dedups on. Quota is tracked per-org, so two versions
+ * that share an org are the same rate-limit bucket and must collapse — but two
+ * orgs under the same email (e.g. Enterprise + Personal on one Google identity)
+ * are genuinely separate buckets and must stay distinct. Prefer the org usage
+ * key; fall back to email only when no usage identity is available.
+ */
+export declare function candidateAccountKey(c: RotateCandidate): string;
 /**
  * Pick a healthy candidate using weighted random by remaining capacity.
  *
@@ -311,15 +333,19 @@ export declare function checkRunAccountReadiness(agent: AgentId, version: string
  *
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
+ *
+ * `model`, when supplied, additionally excludes an account carrying a live
+ * per-model refusal for that exact model (see {@link readinessFromCandidate}).
+ * Omitted (every pre-existing caller), eligibility is unchanged.
  */
-export declare function pickBalancedCandidate(candidates: RotateCandidate[], nowMs?: number): RotateResult | null;
+export declare function pickBalancedCandidate(candidates: RotateCandidate[], nowMs?: number, model?: string): RotateResult | null;
 export { PROJECTION_HORIZON_MIN, capacityWeight };
 /**
  * Pick an available candidate. Prefers the configured pinned version when that
  * version has usage available; otherwise routes to the candidate with the most
  * usage headroom.
  */
-export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null, nowMs?: number): RotateResult | null;
+export declare function pickAvailableCandidate(candidates: RotateCandidate[], preferredVersion?: string | null, nowMs?: number, model?: string): RotateResult | null;
 /**
  * Per-harness routing summary for `agents run auto` — the cross-harness layer
  * that sits above `pickBalancedCandidate` (which is strictly per-harness).
@@ -463,7 +489,7 @@ export declare function buildRotationDecisionEvent(rotation: RotateResult, agent
  * else is healthy, `exhausted` is set so the caller fails loud instead of
  * spawning into a credential-less home.
  */
-export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string, collect?: (agent: AgentId) => Promise<RotateCandidate[]>): Promise<{
+export declare function resolveRunVersion(agent: AgentId, strategy: RunStrategy, cwd?: string, collect?: (agent: AgentId) => Promise<RotateCandidate[]>, model?: string): Promise<{
     version: string | null;
     rotation: RotateResult | null;
     /**

package/dist/lib/accounting/rotate.js

@@ -9,16 +9,18 @@ import * as path from 'path';
 import { PROJECTION_HORIZON_MIN, capacityWeight } from './capacity.js';
 import { accountDisplayLabel, getAccountInfo, credentialPresence, ALL_AGENT_IDS, } from '../agents.js';
 import { readMeta, writeMeta, getHelpersDir } from '../state.js';
+import { resolveConfiguredModel } from '../models.js';
+import { isTierToken, resolveTier } from '../model-tiers.js';
 import { listInstalledVersions, getVersionHomePath, resolveVersion } from '../installations/versions.js';
 import { resolveManagedInstallation } from '../installations/store.js';
 import { listNativeAccounts } from '../account-registry.js';
-import { readSlots } from '../accounts/slots.js';
+import { resolveNativeSpawnHome } from '../exec-account-home.js';
 import { getProjectRunConfigs } from '../run-config.js';
 import { emit } from '../feed/events.js';
-import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, } from './usage.js';
+import { getUsageInfoByIdentity, getUsageLookupKey, deriveUsageStatusFromSnapshot, getClaudeModelRefusal, claudeModelRefusalKey, } from './usage.js';
 import { readAccountHeadroom } from '../fleet-cache.js';
 import { machineId } from '../machine-id.js';
-import { AUTH_PROBE_MAX_AGE_MS, readAuthHealthCache, authCacheKey, isDeadVerdict } from '../auth-health.js';
+import { AUTH_PROBE_MAX_AGE_MS, readAuthHealthCache, authCacheKey, slotAuthVersionKey, isDeadVerdict } from '../auth-health.js';
 function getRotateDir() {
     const dir = path.join(getHelpersDir(), 'rotate');
     fs.mkdirSync(dir, { recursive: true });
@@ -82,10 +84,10 @@ const LAUNCHABLE_SLOT_VERDICTS = new Set(['live', 'unverified']);
 function isLaunchableSlotVerdict(verdict) {
     return verdict !== null && LAUNCHABLE_SLOT_VERDICTS.has(verdict);
 }
-function isRotationEligible(candidate) {
+function isRotationEligible(candidate, nowMs = Date.now(), model) {
     if (candidate.fromSlot && !isLaunchableSlotVerdict(candidate.authVerdict))
         return false;
-    return readinessFromCandidate(candidate).ready;
+    return readinessFromCandidate(candidate, nowMs, model).ready;
 }
 /**
  * Whether a version home can actually authenticate a launch.
@@ -128,9 +130,6 @@ export async function isVersionLaunchableHere(agent, version) {
     const launchable = isLaunchableSignedIn(info.signedIn, credentialPresence(agent, home));
     return { launchable, email: launchable ? info.email : null };
 }
-function isAvailableEligible(candidate) {
-    return isRotationEligible(candidate);
-}
 /**
  * How old a usage snapshot may be and still settle a routing DECISION.
  *
@@ -238,8 +237,19 @@ function hasUsageAvailable(candidate) {
  * snapshot never carries). When a live snapshot exists it wins over the cached
  * status — matching the gate — so a stale `out_of_credits` cache is not
  * reported while the account is actually serving requests.
+ *
+ * `model`, when supplied, additionally consults a per-(account, model)
+ * refusal Claude can surface on ONE model family ("You've reached your Fable
+ * limit…") while the account's other models and its global usage windows stay
+ * healthy — a global rate_limited/out_of_credits marker would wrongly exclude
+ * the whole account for an unrelated model. Keyed on the candidate's stable
+ * native account id (never the org-shared usageKey) via
+ * {@link candidateAccountKey}, so a model-only limit on one login can never
+ * poison a sibling account that merely shares the same org usage bucket.
+ * Omitting `model` (every existing caller) leaves generic account status
+ * completely unaffected — the model check runs only when a caller opts in.
  */
-export function readinessFromCandidate(candidate, now = Date.now()) {
+export function readinessFromCandidate(candidate, now = Date.now(), model) {
     if (!candidate.signedIn) {
         return { ready: false, reason: 'signed_out', email: candidate.email };
     }
@@ -252,6 +262,16 @@ export function readinessFromCandidate(candidate, now = Date.now()) {
     if (authFresh && candidate.authVerdict !== null && isDeadVerdict(candidate.authVerdict)) {
         return { ready: false, reason: 'revoked', email: candidate.email };
     }
+    const modelKey = claudeModelRefusalKey(candidate.nativeAccountId ?? candidate.providerAccountId, candidate.providerAccount ? undefined : candidate.slotDir ?? getVersionHomePath(candidate.agent, candidate.version));
+    if (candidate.agent === 'claude' && modelKey) {
+        const requested = model ?? resolveConfiguredModel(candidate.agent, candidate.version, candidate.slotDir)?.model;
+        const concrete = requested && isTierToken(requested)
+            ? resolveTier(candidate.agent, candidate.version, requested).model
+            : requested;
+        if (concrete && getClaudeModelRefusal(modelKey, concrete, now)) {
+            return { ready: false, reason: 'model_limited', email: candidate.email };
+        }
+    }
     if (hasUsageAvailable(candidate)) {
         return { ready: true };
     }
@@ -332,13 +352,17 @@ function compareCandidates(a, b) {
  * are genuinely separate buckets and must stay distinct. Prefer the org usage
  * key; fall back to email only when no usage identity is available.
  */
-function candidateIdentity(c) {
-    return c.usageKey ?? c.accountKey ?? c.email ?? `${c.agent}@${c.version}`;
+export function candidateAccountKey(c) {
+    if (c.nativeAccountId)
+        return `native:${c.nativeAccountId}`;
+    if (c.providerAccount)
+        return `provider:${c.providerAccount}`;
+    return c.usageKey ?? c.accountKey ?? c.email ?? `${c.agent}:unregistered:${c.accountLabel || c.version}`;
 }
 function dedupeAndSortCandidates(candidates) {
     const byIdentity = new Map();
     for (const c of candidates) {
-        const id = candidateIdentity(c);
+        const id = candidateAccountKey(c);
         const existing = byIdentity.get(id);
         if (!existing) {
             byIdentity.set(id, c);
@@ -373,12 +397,16 @@ function dedupeAndSortCandidates(candidates) {
  *
  * Returns null if no candidate is eligible — callers fall back to the pinned
  * version so behavior stays predictable.
+ *
+ * `model`, when supplied, additionally excludes an account carrying a live
+ * per-model refusal for that exact model (see {@link readinessFromCandidate}).
+ * Omitted (every pre-existing caller), eligibility is unchanged.
  */
-export function pickBalancedCandidate(candidates, nowMs = Date.now()) {
+export function pickBalancedCandidate(candidates, nowMs = Date.now(), model) {
     const healthy = [];
     const excluded = [];
     for (const c of candidates) {
-        if (!isRotationEligible(c)) {
+        if (!isRotationEligible(c, nowMs, model)) {
             excluded.push(c);
             continue;
         }
@@ -489,11 +517,11 @@ function weightedRandomByCapacity(sorted, nowMs = Date.now()) {
  * version has usage available; otherwise routes to the candidate with the most
  * usage headroom.
  */
-export function pickAvailableCandidate(candidates, preferredVersion, nowMs = Date.now()) {
+export function pickAvailableCandidate(candidates, preferredVersion, nowMs = Date.now(), model) {
     const healthy = [];
     const excluded = [];
     for (const c of candidates) {
-        if (!isAvailableEligible(c)) {
+        if (!isRotationEligible(c, nowMs, model)) {
             excluded.push(c);
             continue;
         }
@@ -538,7 +566,7 @@ export function pickAvailableCandidate(candidates, preferredVersion, nowMs = Dat
 export function classifyHarnessCandidates(byHarness, nowMs = Date.now()) {
     const summaries = [];
     for (const [agent, candidates] of byHarness) {
-        const eligible = candidates.filter(isRotationEligible);
+        const eligible = candidates.filter((c) => isRotationEligible(c));
         if (eligible.length === 0) {
             const counts = new Map();
             for (const c of candidates) {
@@ -697,22 +725,25 @@ export async function collectRunCandidates(agent) {
     const meta = readMeta();
     const binaryLabel = resolveManagedInstallation(agent)?.label ?? versions[0];
     const slotRows = [];
-    const slotIdentities = new Set();
     const slotDirs = new Set();
     if (binaryLabel) {
-        const slots = readSlots(meta);
         const natives = listNativeAccounts(meta).filter((row) => row.agent === agent);
         const probed = await Promise.all(natives.map(async (account) => {
-            const slot = slots[account.id];
-            if (!slot || !fs.existsSync(slot.slotDir))
+            const resolved = await resolveNativeSpawnHome(agent, account, meta, { readOnly: true }).catch(() => null);
+            if (!resolved)
                 return null;
-            const home = slot.slotDir;
+            const slot = resolved.slot;
+            const home = resolved.execHome;
+            const version = resolved.label ?? binaryLabel;
+            const cachedHealth = authCache[authCacheKey(localHost, agent, slot ? slotAuthVersionKey(account.id) : version)];
+            const authHealth = cachedHealth && Date.now() - cachedHealth.checkedAt <= AUTH_PROBE_MAX_AGE_MS ? cachedHealth : undefined;
+            const effectiveVerdict = authHealth?.verdict ?? slot?.verdict ?? null;
             const info = await getAccountInfo(agent, home);
             const launchable = isLaunchableSignedIn(info.signedIn, credentialPresence(agent, home));
-            const slotOk = isLaunchableSlotVerdict(slot.verdict);
+            const slotOk = !slot || isLaunchableSlotVerdict(effectiveVerdict);
             return {
                 agent,
-                version: binaryLabel,
+                version,
                 home,
                 info,
                 accountKey: launchable ? info.accountKey : null,
@@ -721,38 +752,33 @@ export async function collectRunCandidates(agent) {
                 usageStatus: launchable ? info.usageStatus : null,
                 plan: launchable ? info.plan : null,
                 signedIn: launchable && slotOk,
-                authVerdict: slot.verdict,
+                authVerdict: effectiveVerdict,
                 authCheckedAt: (() => {
-                    const ts = slot.checkedAt ? Date.parse(slot.checkedAt) : NaN;
+                    if (authHealth)
+                        return authHealth.checkedAt;
+                    const ts = slot?.checkedAt ? Date.parse(slot.checkedAt) : NaN;
                     return Number.isFinite(ts) ? ts : null;
                 })(),
                 lastActive: info.lastActive,
                 nativeAccount: account.name,
+                nativeAccountId: account.id,
                 slotDir: home,
-                fromSlot: true,
+                fromSlot: !!slot,
             };
         }));
         for (const row of probed) {
             if (!row)
                 continue;
             slotRows.push(row);
-            slotDirs.add(path.resolve(row.home));
-            if (row.info.accountKey)
-                slotIdentities.add(row.info.accountKey);
-            if (row.email)
-                slotIdentities.add(row.email.toLowerCase());
+            slotDirs.add(fs.realpathSync(row.home));
         }
     }
     // Legacy per-account installations (`acct-*` homes) until T7 migrates them.
     const versionRows = await Promise.all(versions.map(async (version) => {
         const home = getVersionHomePath(agent, version);
-        if (slotDirs.has(path.resolve(home)))
+        if (fs.existsSync(home) && slotDirs.has(fs.realpathSync(home)))
             return null;
         const info = await getAccountInfo(agent, home);
-        if (info.accountKey && slotIdentities.has(info.accountKey))
-            return null;
-        if (info.email && slotIdentities.has(info.email.toLowerCase()))
-            return null;
         // We used to additionally call isClaudeAuthValid(home), which reads
         // "Claude Code-credentials-<hash>" from the system keychain. That item is
         // written by Claude Code itself with its own process in the ACL, so our
@@ -849,7 +875,9 @@ export function matchAccountCandidate(candidates, account, preferredLabel) {
     const matching = candidates.filter((c) => c.signedIn &&
         (c.email?.toLowerCase() === needle
             || c.accountKey?.toLowerCase() === needle
-            || c.nativeAccount?.toLowerCase() === needle));
+            || c.nativeAccount?.toLowerCase() === needle
+            || c.nativeAccountId?.toLowerCase() === needle
+            || c.providerAccount?.toLowerCase() === needle));
     return matching.find(candidate => candidate.version === preferredLabel) ?? matching[0] ?? null;
 }
 export function matchAccountVersion(candidates, account, preferredLabel) {
@@ -1064,7 +1092,7 @@ function emitRotationDecision(event, rotation, agent, strategy, extra = {}) {
  * else is healthy, `exhausted` is set so the caller fails loud instead of
  * spawning into a credential-less home.
  */
-export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), collect = collectRunCandidates) {
+export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), collect = collectRunCandidates, model) {
     const fallback = resolveVersion(agent, cwd);
     const candidates = await collect(agent);
     // Entirely stale usage (PHNX-2526): every eligible account carries a
@@ -1089,7 +1117,7 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), co
         // Auth-blocked pin: the home cannot authenticate, so launching it is a
         // guaranteed miss. Prefer a signed-in sibling on this device.
         if (pinnedCandidate && isSignInRecoverable(readinessFromCandidate(pinnedCandidate))) {
-            const rotation = pickAvailableCandidate(candidates, fallback);
+            const rotation = pickAvailableCandidate(candidates, fallback, undefined, model);
             // The auth-blocked pin rotates to a sibling — an initial selection, so it
             // gets the same verified-only gate as balanced/available. Without this, a
             // revoked pin with only stale siblings launched one blind (the yosemite-s1
@@ -1109,8 +1137,8 @@ export async function resolveRunVersion(agent, strategy, cwd = process.cwd(), co
         return { version: fallback, rotation: null };
     }
     const rotation = strategy === 'available'
-        ? pickAvailableCandidate(candidates, fallback)
-        : pickBalancedCandidate(candidates);
+        ? pickAvailableCandidate(candidates, fallback, undefined, model)
+        : pickBalancedCandidate(candidates, undefined, model);
     if (rotation && rotation.noVerifiedUsage)
         return refuseStaleUsage(rotation);
     if (rotation) {

package/dist/lib/accounting/usage.d.ts

@@ -284,6 +284,20 @@ interface CachedUsageWindow {
     resetsAt: string | null;
     windowMinutes: number | null;
 }
+/**
+ * A model-specific refusal ("You've reached your Fable limit…") observed from
+ * a real run. Independent of {@link CachedUsageSnapshot.unavailable}: Claude
+ * can block ONE model family while the account's other models and its global
+ * usage windows stay healthy, so this must never fold into the account-wide
+ * marker (that would wrongly exclude every model on the account for a limit
+ * that only ever named one). No invented reset — `resetsAt` is present only
+ * when the refusal text itself carried a clock; absent means the marker is
+ * sticky until a later successful run on this exact (account, model) clears it.
+ */
+interface CachedModelRefusal {
+    family?: string;
+    resetsAt?: string;
+}
 /** Serialized usage snapshot for the on-disk cache. */
 export interface CachedUsageSnapshot {
     capturedAt: string | null;
@@ -294,6 +308,15 @@ export interface CachedUsageSnapshot {
         reason: 'session_limit' | 'out_of_credits';
         resetsAt?: string;
     };
+    /**
+     * Per-model refusal markers, keyed by the exact model name a refusal was
+     * observed against. Keyed on the account row (itself keyed by a stable
+     * accountId-preferring key — see {@link noteClaudeModelRefusal}), not on
+     * the org-shared usage key alone, so a per-model limit on one login cannot
+     * be misread as blocking a sibling account that merely shares the same org
+     * usage bucket.
+     */
+    modelRefusals?: Record<string, CachedModelRefusal>;
 }
 /** The single registry of agent usage sources and their transport. */
 declare const USAGE_SOURCES: {
@@ -762,6 +785,54 @@ export declare function clearClaudeAccountRefusal(usageKey: string, cachePath?:
  * This quota is not part of Anthropic's five-hour/weekly usage response.
  */
 export declare function noteClaudeSessionLimit(usageKey: string, resetsAt: Date, cachePath?: string): void;
+/**
+ * Persist a Claude MODEL-specific refusal — "You've reached your Fable limit.
+ * Run /usage-credits to continue or switch models with /model." — a distinct
+ * class from {@link noteClaudeOutOfCredits} / {@link noteClaudeSessionLimit}:
+ * those exclude the whole account, this excludes only ONE model on it (an
+ * organization quota group can meter models separately). `accountKey` MUST be
+ * the candidate's stable native-account key (see `candidateAccountKey` in
+ * rotate.ts), never the org-shared `usageKey` — using the org key here would
+ * poison every sibling account under that org for a limit that named one
+ * model on one login. No invented reset: `resetsAt` is written only when the
+ * refusal text carried one; otherwise the marker is sticky until a later
+ * successful run on this exact (account, model) clears it via
+ * {@link clearClaudeModelRefusal}.
+ */
+export declare function claudeModelRefusalKey(accountId?: string | null, home?: string | null): string | undefined;
+export declare function noteClaudeModelRefusal(accountKey: string, model: string, refusal: {
+    family?: string;
+    resetsAt?: Date;
+}, cachePath?: string): void;
+/**
+ * Clear a persisted model-refusal marker for exactly ONE (account, model)
+ * pair after a run SUCCEEDS on that same account+model. Never clears a
+ * sibling model on the same account, and never fires for an interactive
+ * detach or an unknown outcome — the caller must have demonstrated an actual
+ * completed success on this exact model before calling this.
+ */
+export declare function clearClaudeModelRefusal(accountKey: string, model: string, cachePath?: string): void;
+/**
+ * Read a live (non-expired) model-refusal marker for (accountKey, model), or
+ * null when none is recorded or the recorded one has passed its clock. A
+ * marker with no `resetsAt` never expires here — it is sticky until
+ * {@link clearClaudeModelRefusal} observes a real success.
+ */
+export declare function getClaudeModelRefusal(accountKey: string, model: string, nowMs?: number, cachePath?: string): {
+    family?: string;
+    resetsAt: Date | null;
+} | null;
+/**
+ * Parse Claude's model-specific refusal — the CLI's own phrasing when ONE
+ * model's quota is exhausted while the account otherwise keeps serving:
+ * "You've reached your Fable limit. Run /usage-credits to continue or switch
+ * models with /model." Deliberately narrow (unlike the broad RATE_LIMIT_PATTERNS
+ * scan) so a session that merely discusses `/usage-credits` cannot false-positive.
+ * Tolerates both a straight and curly apostrophe.
+ */
+export declare function parseClaudeModelRefusal(text: string): {
+    family: string;
+} | null;
 /** Parse Claude's `hit your session limit · resets …` refusal. */
 export declare function parseClaudeSessionLimitReset(text: string, nowMs?: number): Date | null;
 /**