@phnx-labs/agents-cli 1.22.104 → 1.22.106

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;
 /**

package/dist/lib/accounting/usage.js

@@ -1790,10 +1790,17 @@ export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeU
             // refresh cannot drop another account's row (lost update).
             const cache = readClaudeUsageCacheFile(cachePath);
             const prior = cache[usageKey];
-            cache[usageKey] = serializeClaudeUsageSnapshot({
-                ...snapshot,
-                unavailable: carryForwardUnavailable(prior?.unavailable, snapshot.unavailable),
-            });
+            cache[usageKey] = {
+                ...serializeClaudeUsageSnapshot({
+                    ...snapshot,
+                    unavailable: carryForwardUnavailable(prior?.unavailable, snapshot.unavailable),
+                }),
+                // A per-model refusal has its own independent lifecycle (see
+                // noteClaudeModelRefusal / clearClaudeModelRefusal) — a global usage
+                // write must never drop it, the same reason `unavailable` is carried
+                // forward above rather than overwritten.
+                modelRefusals: prior?.modelRefusals,
+            };
             atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
         });
     }
@@ -1814,12 +1821,16 @@ export function mergeClaudeUsageCacheWindows(usageKey, snapshot, cachePath = get
             const windows = new Map(priorSnapshot?.windows.map((window) => [window.key, window]) ?? []);
             for (const window of snapshot.windows)
                 windows.set(window.key, window);
-            cache[usageKey] = serializeClaudeUsageSnapshot({
-                ...snapshot,
-                windows: [...windows.values()],
-                plan: snapshot.plan ?? priorSnapshot?.plan ?? null,
-                unavailable: carryForwardUnavailable(prior?.unavailable, snapshot.unavailable),
-            });
+            cache[usageKey] = {
+                ...serializeClaudeUsageSnapshot({
+                    ...snapshot,
+                    windows: [...windows.values()],
+                    plan: snapshot.plan ?? priorSnapshot?.plan ?? null,
+                    unavailable: carryForwardUnavailable(prior?.unavailable, snapshot.unavailable),
+                }),
+                // See writeClaudeUsageCache: a per-model refusal survives a windows-only merge too.
+                modelRefusals: prior?.modelRefusals,
+            };
             atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
         });
     }
@@ -2004,7 +2015,8 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         staleWindows.length === 0 &&
         !unavailable &&
         !snapshot.plan &&
-        !snapshot.refreshHint) {
+        !snapshot.refreshHint &&
+        !hasLiveModelRefusal(snapshot.modelRefusals, now)) {
         return null;
     }
     return {
@@ -2051,6 +2063,17 @@ function deserializeUnavailable(cached, now) {
         ? { reason: 'session_limit', resetsAt: reset }
         : undefined;
 }
+/** Whether any per-model refusal in the row is still live (not clock-expired). */
+function hasLiveModelRefusal(modelRefusals, now) {
+    if (!modelRefusals)
+        return false;
+    return Object.values(modelRefusals).some((entry) => {
+        if (!entry.resetsAt)
+            return true; // no clock given — sticky until cleared
+        const reset = parseDateValue(entry.resetsAt);
+        return !reset || reset.getTime() > now.getTime();
+    });
+}
 /**
  * Persist a Claude tokens/credits exhaustion (`out of usage credits` / `monthly
  * spend limit`) from a real run. Unlike a rate/session limit this does NOT reset
@@ -2115,6 +2138,132 @@ export function noteClaudeSessionLimit(usageKey, resetsAt, cachePath = getClaude
         /* best-effort cache write — lock busy or disk full */
     }
 }
+/**
+ * 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 function claudeModelRefusalKey(accountId, home) {
+    if (accountId)
+        return `account:${accountId}`;
+    if (!home)
+        return undefined;
+    try {
+        return `context:${fs.realpathSync(home)}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function modelFamily(model) {
+    const normalized = model.trim().toLowerCase();
+    return /(?:^|[-\s])(fable|sonnet|opus|haiku)(?:$|[-\s\d])/.exec(normalized)?.[1] ?? normalized;
+}
+export function noteClaudeModelRefusal(accountKey, model, refusal, cachePath = getClaudeUsageCachePath()) {
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            const existing = cache[accountKey] ?? { capturedAt: null, windows: [] };
+            const modelRefusals = { ...(existing.modelRefusals ?? {}) };
+            modelRefusals[modelFamily(refusal.family ?? model)] = {
+                family: refusal.family,
+                resetsAt: refusal.resetsAt?.toISOString(),
+            };
+            cache[accountKey] = { ...existing, modelRefusals };
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write — lock busy or disk full */
+    }
+}
+/**
+ * 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 function clearClaudeModelRefusal(accountKey, model, cachePath = getClaudeUsageCachePath()) {
+    model = modelFamily(model);
+    try {
+        if (!fs.existsSync(cachePath))
+            return;
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            const existing = cache[accountKey];
+            if (!existing?.modelRefusals?.[model])
+                return;
+            const modelRefusals = { ...existing.modelRefusals };
+            delete modelRefusals[model];
+            const rest = { ...existing, modelRefusals };
+            if (Object.keys(modelRefusals).length === 0)
+                delete rest.modelRefusals;
+            cache[accountKey] = rest;
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write */
+    }
+}
+/**
+ * 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 function getClaudeModelRefusal(accountKey, model, nowMs = Date.now(), cachePath = getClaudeUsageCachePath()) {
+    const cache = readClaudeUsageCacheFile(cachePath);
+    const entry = cache[accountKey]?.modelRefusals?.[modelFamily(model)];
+    if (!entry)
+        return null;
+    if (entry.resetsAt) {
+        const reset = parseDateValue(entry.resetsAt);
+        if (reset && reset.getTime() <= nowMs)
+            return null;
+        return { family: entry.family, resetsAt: reset };
+    }
+    return { family: entry.family, resetsAt: 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 function parseClaudeModelRefusal(text) {
+    const candidates = [text];
+    for (const line of text.split('\n')) {
+        try {
+            const row = JSON.parse(line);
+            if (row.type === 'result' && row.is_error && typeof row.result === 'string')
+                candidates.push(row.result);
+            if (row.type === 'assistant' && row.isApiErrorMessage && Array.isArray(row.message?.content)) {
+                candidates.push(row.message.content.filter((block) => block.type === 'text').map((block) => block.text ?? '').join('\n'));
+            }
+        }
+        catch { /* Plain terminal output is checked directly. */ }
+    }
+    for (const candidate of candidates) {
+        const match = /(?:^|\n)\s*You['’]ve reached your ([^\n.]+) limit\.\s*Run \/usage-credits to continue or switch models with \/model\./i.exec(candidate);
+        if (match)
+            return { family: match[1].trim() };
+    }
+    return null;
+}
 /** Parse Claude's `hit your session limit · resets …` refusal. */
 export function parseClaudeSessionLimitReset(text, nowMs = Date.now()) {
     if (!/hit your session limit/i.test(text))

package/dist/lib/exec-account-home.d.ts

@@ -54,4 +54,6 @@ export declare function resolveNativeSpawnHome(agent: AgentId, account: {
     id: string;
     name: string;
     agent: AgentId;
-}, meta?: Pick<Meta, 'accounts' | 'deviceAccounts'>): Promise<NativeSpawnHome>;
+}, meta?: Pick<Meta, 'accounts' | 'deviceAccounts'>, options?: {
+    readOnly?: boolean;
+}): Promise<NativeSpawnHome>;