@ours.network/fleet 1.2.0-nightly.3 → 1.2.0-nightly.31

package/dist/subscriptions/observed.js

@@ -0,0 +1,44 @@
+import { join } from 'node:path';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { OBSERVED_USAGE_FILE } from './store.js';
+const WINDOW_LABELS = {
+    five_hour: { label: '5h', mins: 300 },
+    seven_day: { label: 'weekly', mins: 10_080 },
+    seven_day_opus: { label: 'weekly · Opus', mins: 10_080 },
+    seven_day_sonnet: { label: 'weekly · Sonnet', mins: 10_080 },
+};
+/**
+ * Persist the Claude subscription rate-limit snapshot an agent session just
+ * received (SDK `rate_limit_event`, forwarded by claude-agent-acp as
+ * `usage_update._meta["_claude/rateLimit"]`). Only numbers and window names
+ * are kept. The web backend attributes it to the agent's pinned profile.
+ */
+export function recordClaudeRateLimit(stateDir, info, now = new Date()) {
+    if (!info || typeof info !== 'object')
+        return false;
+    const raw = info;
+    const entries = raw.unifiedWindows && typeof raw.unifiedWindows === 'object'
+        ? Object.entries(raw.unifiedWindows)
+        : typeof raw.rateLimitType === 'string' ? [[raw.rateLimitType, raw]] : [];
+    const windows = [];
+    for (const [id, w] of entries) {
+        if (!/^[a-z0-9_]{1,40}$/.test(id) || !w || typeof w.utilization !== 'number' || !Number.isFinite(w.utilization))
+            continue;
+        const known = WINDOW_LABELS[id];
+        windows.push({
+            id, label: known?.label ?? id.replace(/_/g, ' '),
+            usedPercent: Math.round(Math.max(0, w.utilization) * 1000) / 10,
+            windowMins: known?.mins,
+            resetsAt: typeof w.resetsAt === 'number' ? new Date(w.resetsAt * 1000).toISOString() : undefined,
+        });
+    }
+    if (!windows.length)
+        return false;
+    try {
+        replaceFileAtomically(join(stateDir, OBSERVED_USAGE_FILE), `${JSON.stringify({ windows, observedAt: now.toISOString(), source: 'agent' })}\n`, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/subscriptions/probe.d.ts

@@ -0,0 +1,10 @@
+export interface ClaudeProbeResult {
+    rateLimit?: unknown;
+    exhausted: boolean;
+}
+/**
+ * Ask Haiku for one short reply in the selected Claude home. The JSONL stream
+ * can contain a rate_limit_event; prompts, replies and CLI stderr are discarded.
+ * This runs only after an explicit UI action and has a time and spend bound.
+ */
+export declare function probeClaudeRateLimit(bin: string, profileId: string, timeoutMs?: number): Promise<ClaudeProbeResult | undefined>;

package/dist/subscriptions/probe.js

@@ -0,0 +1,73 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { profileEnv } from './cli.js';
+import { profileHome, subscriptionsRoot } from './store.js';
+const LIMIT_ERROR = /\b(?:hit (?:your |the )?limit|reached (?:your |the )?(?:usage )?limit|usage limits? (?:reached|exceeded)|rate limits? (?:reached|exceeded)|rate_limit_error|quota exceeded|out of (?:usage|credits)|too many requests|429)\b/i;
+/**
+ * Ask Haiku for one short reply in the selected Claude home. The JSONL stream
+ * can contain a rate_limit_event; prompts, replies and CLI stderr are discarded.
+ * This runs only after an explicit UI action and has a time and spend bound.
+ */
+export function probeClaudeRateLimit(bin, profileId, timeoutMs = 75_000) {
+    const cwd = subscriptionsRoot();
+    mkdirSync(cwd, { recursive: true, mode: 0o700 });
+    return new Promise(resolve => {
+        const child = spawn(bin, [
+            '-p', 'Reply OK.', '--model', 'haiku', '--output-format', 'stream-json', '--verbose',
+            '--no-session-persistence', '--strict-mcp-config', '--tools', '',
+            '--system-prompt', 'Reply OK.', '--max-budget-usd', '0.05',
+        ], {
+            cwd, env: profileEnv('CLAUDE_CONFIG_DIR', profileId, profileHome('claude', profileId)),
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let pending = '';
+        let rateLimit;
+        let exhausted = false;
+        let done = false;
+        const finish = (value) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const timer = setTimeout(() => { child.kill('SIGKILL'); finish(); }, timeoutMs);
+        child.stdout.on('data', chunk => {
+            pending += String(chunk);
+            if (pending.length > 64 * 1024 && !pending.includes('\n')) {
+                child.kill('SIGKILL');
+                finish();
+                return;
+            }
+            for (let end = pending.indexOf('\n'); end >= 0; end = pending.indexOf('\n')) {
+                const line = pending.slice(0, end);
+                pending = pending.slice(end + 1);
+                if (line.length > 64 * 1024)
+                    continue;
+                try {
+                    const event = JSON.parse(line);
+                    if (event.type === 'rate_limit_event')
+                        rateLimit = event.rate_limit_info ?? event.rateLimitInfo ?? event.rate_limit ?? event.rateLimit ?? event;
+                    if ((event.type === 'result' && event.is_error === true) || event.type === 'error') {
+                        const error = event.error && typeof event.error === 'object' ? event.error : undefined;
+                        const message = typeof event.result === 'string' ? event.result
+                            : typeof event.error === 'string' ? event.error : error?.message;
+                        if (typeof message === 'string' && LIMIT_ERROR.test(message.slice(0, 4000)))
+                            exhausted = true;
+                    }
+                }
+                catch { /* Other CLI output is never retained. */ }
+            }
+        });
+        // Some CLI failures are reported only on stderr. Inspect a small rolling
+        // fragment for a limit signal; never retain or return the raw text.
+        let stderrTail = '';
+        child.stderr.on('data', chunk => {
+            stderrTail = (stderrTail + String(chunk)).slice(-4000);
+            if (LIMIT_ERROR.test(stderrTail))
+                exhausted = true;
+        });
+        child.once('error', () => finish());
+        child.once('close', () => finish(rateLimit !== undefined || exhausted ? { rateLimit, exhausted } : undefined));
+    });
+}

package/dist/subscriptions/service.d.ts

@@ -0,0 +1,102 @@
+import { type SubscriptionBinaries, type UsageWindow } from './cli.js';
+import { type LoginHandle, type LoginView } from './login.js';
+import { type SubscriptionProvider } from './store.js';
+export type HealthState = 'ok' | 'expiring' | 'expired' | 'signed_out' | 'error' | 'unknown';
+export interface ProfileHealth {
+    state: HealthState;
+    checkedAt?: string;
+    detail?: string;
+    /** When the stored login stops refreshing (Claude, observed field). */
+    loginExpiresAt?: string;
+}
+export interface ProfileUsage {
+    windows: UsageWindow[];
+    observedAt?: string;
+    /** `pull`: asked the provider. `agent`: last value an agent session reported. */
+    source: 'pull' | 'agent' | 'probe' | 'none';
+    /** A probe received an explicit limit error, even if no percentages were sent. */
+    exhausted?: boolean;
+}
+export interface ProfileView {
+    id: string;
+    label: string;
+    active: boolean;
+    account?: {
+        email?: string;
+        plan?: string;
+        org?: string;
+    };
+    health: ProfileHealth;
+    usage: ProfileUsage;
+    /** Running agents whose session is pinned to this profile. */
+    agents: string[];
+}
+export interface ProviderView {
+    provider: SubscriptionProvider;
+    activeProfileId: string;
+    profiles: ProfileView[];
+    /** Running agents still on a profile other than the active one: restart to switch. */
+    staleAgents: Array<{
+        roleId: string;
+        profileId: string;
+    }>;
+    /** Running agents whose credentials come from env, not a Fleet profile. */
+    unmanagedAgents: Array<{
+        roleId: string;
+        via: string[];
+    }>;
+}
+export interface AgentRef {
+    roleId: string;
+    stateDir?: string;
+    running: boolean;
+}
+export interface SubscriptionServiceOptions {
+    agents(): Promise<AgentRef[]>;
+    binaries?: SubscriptionBinaries;
+    now?: () => number;
+    onChange?: () => void;
+}
+interface CheckResult {
+    health: ProfileHealth;
+    account?: ProfileView['account'];
+    usage?: ProfileUsage;
+}
+export declare class SubscriptionService {
+    private readonly options;
+    private readonly bins;
+    private readonly now;
+    private readonly checks;
+    private readonly running;
+    private readonly logins;
+    private readonly probes;
+    constructor(options: SubscriptionServiceOptions);
+    list(): Promise<ProviderView[]>;
+    /** Health + account + (Codex) usage for one profile. Concurrent calls share one run. */
+    check(provider: SubscriptionProvider, profileId: string): Promise<CheckResult>;
+    private checkClaude;
+    private checkCodex;
+    startLogin(provider: SubscriptionProvider, owner: string): Promise<LoginView>;
+    private completeLogin;
+    /** Query the official CLI for each existing profile, including the adopted default. */
+    private accountAlreadyAdded;
+    login(loginId: string, owner: string): LoginHandle;
+    setActive(provider: SubscriptionProvider, profileId: string): Promise<ProviderView>;
+    rename(provider: SubscriptionProvider, profileId: string, label: string): Promise<void>;
+    /**
+     * Remove a profile and its login. Refused while it is active or while any
+     * running agent is still pinned to it; the adopted default is never removed.
+     */
+    remove(provider: SubscriptionProvider, profileId: string): Promise<void>;
+    private profile;
+    /** An explicit, bounded Haiku request can refresh Claude usage for an idle profile. */
+    probeClaudeUsage(profileId: string): Promise<ProfileUsage>;
+    private probeUsageDir;
+    private probedUsage;
+    private pins;
+    /** Latest Claude rate-limit snapshot any agent on this profile reported. */
+    private observedUsage;
+}
+/** Read what `recordClaudeRateLimit` stored, dropping windows that already reset. */
+export declare function readObservedClaudeUsage(stateDir: string, now?: number): ProfileUsage | undefined;
+export {};

package/dist/subscriptions/service.js

@@ -0,0 +1,364 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { FleetError } from '../application/errors.js';
+import { replaceFileAtomically } from '../atomic-file.js';
+import { claudeAuthStatus, claudeLoginExpiry, codexUsageWindows, defaultBinaries, profileEnv, withCodex, } from './cli.js';
+import { HOME_ENV } from './launch.js';
+import { ClaudeLogin, CodexDeviceLogin } from './login.js';
+import { recordClaudeRateLimit } from './observed.js';
+import { probeClaudeRateLimit } from './probe.js';
+import { DEFAULT_PROFILE_ID, OBSERVED_USAGE_FILE, SUBSCRIPTION_PROVIDERS, createProfileHome, profileHome, readPin, readSubscriptionState, removeProfileHome, subscriptionsRoot, updateSubscriptionState, } from './store.js';
+const EXPIRING_MS = 3 * 24 * 3600_000;
+const STALE_CHECK_MS = 10 * 60_000;
+export class SubscriptionService {
+    options;
+    bins;
+    now;
+    checks = new Map();
+    running = new Map();
+    logins = new Map();
+    probes = new Map();
+    constructor(options) {
+        this.options = options;
+        this.bins = options.binaries ?? defaultBinaries();
+        this.now = options.now ?? Date.now;
+    }
+    async list() {
+        const state = readSubscriptionState();
+        const pins = await this.pins();
+        return SUBSCRIPTION_PROVIDERS.map(provider => {
+            const p = state.providers[provider];
+            const profiles = p.profiles.map(profile => {
+                const key = `${provider}/${profile.id}`;
+                const cached = this.checks.get(key);
+                if (!cached || this.now() - Date.parse(cached.health.checkedAt ?? '0') > STALE_CHECK_MS)
+                    void this.check(provider, profile.id).catch(() => { });
+                const observed = provider === 'claude' ? this.observedUsage(pins, profile.id) : undefined;
+                const probed = provider === 'claude' ? this.probedUsage(profile.id) : undefined;
+                const usage = observed && probed
+                    ? (observed.observedAt ?? '') >= (probed.observedAt ?? '') ? observed : probed
+                    : observed ?? probed;
+                return {
+                    id: profile.id, label: profile.label, active: profile.id === p.activeProfileId,
+                    account: cached?.account,
+                    health: cached?.health ?? { state: 'unknown' },
+                    usage: usage ?? cached?.usage ?? { windows: [], source: 'none' },
+                    agents: pins.filter(x => x.running && x.provider === provider && x.profileId === profile.id).map(x => x.roleId),
+                };
+            });
+            return {
+                provider, activeProfileId: p.activeProfileId, profiles,
+                staleAgents: pins.filter(x => x.running && x.provider === provider && x.profileId !== p.activeProfileId)
+                    .map(x => ({ roleId: x.roleId, profileId: x.profileId })),
+                unmanagedAgents: pins.filter(x => x.running && x.provider === provider && x.unmanaged?.length)
+                    .map(x => ({ roleId: x.roleId, via: x.unmanaged })),
+            };
+        });
+    }
+    /** Health + account + (Codex) usage for one profile. Concurrent calls share one run. */
+    check(provider, profileId) {
+        this.profile(provider, profileId);
+        const key = `${provider}/${profileId}`;
+        const inflight = this.running.get(key);
+        if (inflight)
+            return inflight;
+        const run = (provider === 'claude' ? this.checkClaude(profileId) : this.checkCodex(profileId))
+            .catch((error) => ({
+            health: { state: 'error', checkedAt: new Date(this.now()).toISOString(), detail: error?.message?.includes('prerequisite') ? 'subscription state unreadable' : 'health check failed' },
+        }))
+            .then(result => { this.checks.set(key, result); this.options.onChange?.(); return result; })
+            .finally(() => this.running.delete(key));
+        this.running.set(key, run);
+        return run;
+    }
+    async checkClaude(profileId) {
+        const home = profileHome('claude', profileId);
+        const status = await claudeAuthStatus(this.bins.claude, profileEnv(HOME_ENV.claude, profileId, home));
+        const checkedAt = new Date(this.now()).toISOString();
+        const { refreshExpiresAt } = claudeLoginExpiry(home);
+        const loginExpiresAt = refreshExpiresAt ? new Date(refreshExpiresAt).toISOString() : undefined;
+        let state = status.loggedIn ? 'ok' : 'signed_out';
+        // The CLI reports the credential it would actually use (env, settings, helper…).
+        if (status.loggedIn && status.authMethod && status.authMethod !== 'claude.ai') {
+            return {
+                health: { state: 'error', checkedAt, detail: `not using a Claude subscription login (${status.authMethod.slice(0, 40)})` },
+                account: { email: status.email, plan: status.authMethod, org: status.org },
+            };
+        }
+        if (status.loggedIn && refreshExpiresAt !== undefined) {
+            if (refreshExpiresAt <= this.now())
+                state = 'expired';
+            else if (refreshExpiresAt - this.now() < EXPIRING_MS)
+                state = 'expiring';
+        }
+        return {
+            health: { state, checkedAt, loginExpiresAt },
+            account: status.loggedIn ? { email: status.email, plan: status.plan, org: status.org } : undefined,
+        };
+    }
+    async checkCodex(profileId) {
+        const home = profileHome('codex', profileId);
+        return withCodex(this.bins.codex, profileEnv(HOME_ENV.codex, profileId, home), async (server) => {
+            const checkedAt = new Date(this.now()).toISOString();
+            // refreshToken:false — a health check must not rotate a token agents use.
+            const read = await server.call('account/read', { refreshToken: false });
+            if (!read.account)
+                return { health: { state: 'signed_out', checkedAt } };
+            if (read.account.type !== 'chatgpt') {
+                return {
+                    health: { state: 'error', checkedAt, detail: 'not a ChatGPT subscription login' },
+                    account: { plan: read.account.type === 'apiKey' ? 'API key' : read.account.type },
+                };
+            }
+            const account = { email: read.account.email ?? undefined, plan: read.account.planType ?? 'chatgpt' };
+            try {
+                const limits = await server.call('account/rateLimits/read', {});
+                return {
+                    health: { state: 'ok', checkedAt }, account,
+                    usage: { windows: codexUsageWindows(limits), observedAt: checkedAt, source: 'pull' },
+                };
+            }
+            catch (error) {
+                const expired = /401|unauthori[sz]ed|expired|sign in again|log in again/i.test(String(error.message));
+                return { health: { state: expired ? 'expired' : 'error', checkedAt, detail: expired ? 'login expired: sign in again' : 'usage limits unavailable' }, account };
+            }
+        });
+    }
+    async startLogin(provider, owner) {
+        for (const [id, login] of this.logins) {
+            const view = login.view();
+            if (view.provider !== provider)
+                continue;
+            if (view.state === 'starting' || view.state === 'awaiting_user' || view.state === 'verifying')
+                login.cancel();
+            this.logins.delete(id);
+        }
+        const { id: profileId, home } = createProfileHome(provider);
+        const login = provider === 'claude'
+            ? new ClaudeLogin(owner, this.bins, home, profileId)
+            : new CodexDeviceLogin(owner, this.bins, home, profileId);
+        const loginId = login.view().loginId;
+        this.logins.set(loginId, login);
+        void this.completeLogin(provider, profileId, login);
+        // Give the CLI a moment to print its URL so the first response is useful.
+        const deadline = this.now() + 8_000;
+        while (login.view().state === 'starting' && this.now() < deadline)
+            await new Promise(resolve => setTimeout(resolve, 100));
+        return login.view();
+    }
+    async completeLogin(provider, profileId, login) {
+        let label;
+        let email;
+        let error = 'sign-in did not complete';
+        try {
+            if (login instanceof ClaudeLogin) {
+                const code = await login.exited;
+                if (code === 0 && login.view().state === 'verifying') {
+                    const status = await claudeAuthStatus(this.bins.claude, profileEnv(HOME_ENV.claude, profileId, profileHome('claude', profileId)));
+                    if (status.loggedIn) {
+                        email = status.email;
+                        label = status.email ?? 'Claude account';
+                    }
+                }
+                else if (login.view().state === 'verifying')
+                    error = 'the sign-in code was not accepted';
+            }
+            else if (await login.completed) {
+                const result = await this.checkCodex(profileId);
+                // Only a verified ChatGPT subscription login becomes a profile.
+                if (result.health.state === 'ok') {
+                    email = result.account?.email;
+                    label = email ?? 'Codex account';
+                    this.checks.set(`${provider}/${profileId}`, result);
+                }
+            }
+            if (label !== undefined) {
+                if (!email?.trim()) {
+                    label = undefined;
+                    error = 'the CLI did not provide an account email';
+                }
+                else if (await this.accountAlreadyAdded(provider, email)) {
+                    label = undefined;
+                    error = 'this account is already added';
+                }
+            }
+        }
+        catch {
+            label = undefined;
+            error = 'sign-in could not be verified';
+        }
+        let registered = false;
+        if (label !== undefined) {
+            try {
+                // Registration and the login's terminal state change together inside the
+                // lock callback (synchronous), so a cancel or timeout that ran during the
+                // verification awaits wins and nothing is registered.
+                await updateSubscriptionState(state => {
+                    if (login.view().state !== 'verifying' || !existsSync(profileHome(provider, profileId)))
+                        return;
+                    state.providers[provider].profiles.push({ id: profileId, label: label.slice(0, 80), createdAt: new Date(this.now()).toISOString() });
+                    login.complete(true);
+                    registered = true;
+                });
+            }
+            catch {
+                error = 'sign-in could not be saved';
+            }
+        }
+        if (!registered) {
+            login.complete(false, error);
+            removeProfileHome(provider, profileId);
+            this.checks.delete(`${provider}/${profileId}`);
+        }
+        this.options.onChange?.();
+    }
+    /** Query the official CLI for each existing profile, including the adopted default. */
+    async accountAlreadyAdded(provider, email) {
+        const wanted = email.trim().toLowerCase();
+        for (const profile of readSubscriptionState().providers[provider].profiles) {
+            const home = profileHome(provider, profile.id);
+            let existing;
+            if (provider === 'claude') {
+                const status = await claudeAuthStatus(this.bins.claude, profileEnv(HOME_ENV.claude, profile.id, home));
+                if (status.loggedIn)
+                    existing = status.email;
+            }
+            else {
+                existing = await withCodex(this.bins.codex, profileEnv(HOME_ENV.codex, profile.id, home), async (server) => {
+                    const read = await server.call('account/read', { refreshToken: false });
+                    return read.account?.type === 'chatgpt' ? read.account.email ?? undefined : undefined;
+                });
+            }
+            if (existing?.trim().toLowerCase() === wanted)
+                return true;
+        }
+        return false;
+    }
+    login(loginId, owner) {
+        const login = this.logins.get(loginId);
+        // Unknown and foreign logins look the same: no probing of other sessions' logins.
+        if (!login || login.owner !== owner)
+            throw new FleetError('resource_not_found', 'login not found');
+        return login;
+    }
+    async setActive(provider, profileId) {
+        this.profile(provider, profileId);
+        await updateSubscriptionState(state => {
+            if (!state.providers[provider].profiles.some(p => p.id === profileId))
+                throw new FleetError('resource_not_found', 'profile not found');
+            state.providers[provider].activeProfileId = profileId;
+        });
+        this.options.onChange?.();
+        return (await this.list()).find(p => p.provider === provider);
+    }
+    async rename(provider, profileId, label) {
+        const clean = label.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 80);
+        if (!clean)
+            throw new FleetError('invalid_request', 'label is required');
+        await updateSubscriptionState(state => {
+            const profile = state.providers[provider].profiles.find(p => p.id === profileId);
+            if (!profile)
+                throw new FleetError('resource_not_found', 'profile not found');
+            profile.label = clean;
+        });
+        this.options.onChange?.();
+    }
+    /**
+     * Remove a profile and its login. Refused while it is active or while any
+     * running agent is still pinned to it; the adopted default is never removed.
+     */
+    async remove(provider, profileId) {
+        if (profileId === DEFAULT_PROFILE_ID)
+            throw new FleetError('conflict', 'the default profile is your existing CLI login and cannot be removed here');
+        const pinned = (await this.pins()).filter(x => x.running && x.provider === provider && x.profileId === profileId);
+        if (pinned.length)
+            throw new FleetError('conflict', `profile is in use by running agents: ${pinned.map(x => x.roleId).join(', ')}; restart or stop them first`);
+        await updateSubscriptionState(state => {
+            const p = state.providers[provider];
+            if (!p.profiles.some(x => x.id === profileId))
+                throw new FleetError('resource_not_found', 'profile not found');
+            if (p.activeProfileId === profileId)
+                throw new FleetError('conflict', 'switch to another profile before removing the active one');
+            p.profiles = p.profiles.filter(x => x.id !== profileId);
+        });
+        removeProfileHome(provider, profileId);
+        if (provider === 'claude')
+            rmSync(this.probeUsageDir(profileId), { recursive: true, force: true });
+        this.checks.delete(`${provider}/${profileId}`);
+        this.options.onChange?.();
+    }
+    profile(provider, profileId) {
+        if (!readSubscriptionState().providers[provider].profiles.some(p => p.id === profileId))
+            throw new FleetError('resource_not_found', 'profile not found');
+    }
+    /** An explicit, bounded Haiku request can refresh Claude usage for an idle profile. */
+    probeClaudeUsage(profileId) {
+        this.profile('claude', profileId);
+        const inFlight = this.probes.get(profileId);
+        if (inFlight)
+            return inFlight;
+        const run = (async () => {
+            const dir = this.probeUsageDir(profileId);
+            const result = await probeClaudeRateLimit(this.bins.claude, profileId);
+            if (result) {
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                const observedAt = new Date(this.now()).toISOString();
+                const windows = result.rateLimit && recordClaudeRateLimit(dir, result.rateLimit, new Date(this.now()))
+                    ? readObservedClaudeUsage(dir, this.now())?.windows ?? [] : [];
+                if (windows.length || result.exhausted) {
+                    const usage = { windows, observedAt, source: 'probe', ...(result.exhausted ? { exhausted: true } : {}) };
+                    replaceFileAtomically(join(dir, OBSERVED_USAGE_FILE), `${JSON.stringify(usage)}\n`, 0o600);
+                    this.options.onChange?.();
+                    return usage;
+                }
+            }
+            rmSync(join(dir, OBSERVED_USAGE_FILE), { force: true });
+            this.options.onChange?.();
+            return { windows: [], source: 'none' };
+        })().catch(() => ({ windows: [], source: 'none' }))
+            .finally(() => this.probes.delete(profileId));
+        this.probes.set(profileId, run);
+        return run;
+    }
+    probeUsageDir(profileId) {
+        return join(subscriptionsRoot(), 'observed', 'claude', profileId);
+    }
+    probedUsage(profileId) {
+        const usage = readObservedClaudeUsage(this.probeUsageDir(profileId), this.now());
+        return usage && (usage.windows.length || usage.exhausted) ? { ...usage, source: 'probe' } : undefined;
+    }
+    async pins() {
+        const result = [];
+        for (const agent of await this.options.agents()) {
+            if (!agent.stateDir)
+                continue;
+            const pin = readPin(agent.stateDir);
+            if (pin)
+                result.push({ roleId: agent.roleId, stateDir: agent.stateDir, running: agent.running, provider: pin.provider, profileId: pin.profileId, unmanaged: pin.unmanaged });
+        }
+        return result;
+    }
+    /** Latest Claude rate-limit snapshot any agent on this profile reported. */
+    observedUsage(pins, profileId) {
+        let best;
+        for (const pin of pins) {
+            if (pin.provider !== 'claude' || pin.profileId !== profileId)
+                continue;
+            const observed = readObservedClaudeUsage(pin.stateDir);
+            if (observed && (!best || (observed.observedAt ?? '') > (best.observedAt ?? '')))
+                best = observed;
+        }
+        return best;
+    }
+}
+/** Read what `recordClaudeRateLimit` stored, dropping windows that already reset. */
+export function readObservedClaudeUsage(stateDir, now = Date.now()) {
+    try {
+        const raw = JSON.parse(readFileSync(join(stateDir, OBSERVED_USAGE_FILE), 'utf8'));
+        const windows = (raw.windows ?? []).filter(w => !w.resetsAt || Date.parse(w.resetsAt) > now);
+        return { windows, observedAt: raw.observedAt, source: 'agent', ...(raw.exhausted === true ? { exhausted: true } : {}) };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/subscriptions/store.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Fleet-wide Claude Code / Codex subscription profiles.
+ *
+ * A profile is one CLI home directory holding one account's login. Fleet never
+ * reads or returns token values; the official CLIs own the credential files.
+ * The `default` profile adopts the operator's existing `~/.claude` / `~/.codex`
+ * in place, so a fleet that never adds a profile launches exactly as before.
+ * Exactly one profile per provider is active; switching only affects agents
+ * launched afterwards (running sessions stay pinned until restarted).
+ */
+export type SubscriptionProvider = 'claude' | 'codex';
+export declare const SUBSCRIPTION_PROVIDERS: SubscriptionProvider[];
+export declare const DEFAULT_PROFILE_ID = "default";
+export interface SubscriptionProfile {
+    id: string;
+    label: string;
+    createdAt: string;
+}
+export interface ProviderState {
+    activeProfileId: string;
+    profiles: SubscriptionProfile[];
+}
+export interface SubscriptionState {
+    version: 1;
+    providers: Record<SubscriptionProvider, ProviderState>;
+}
+/** Recorded in an agent's state dir at launch: which profile the session uses. */
+export interface SubscriptionPin {
+    provider: SubscriptionProvider;
+    profileId: string;
+    /** Explicit CLI home, absent for the adopted default (the CLI's own default). */
+    home?: string;
+    /**
+     * Default profile only: credential env (role or supervisor) that makes this
+     * session authenticate outside Fleet's profiles. Reported, not managed.
+     */
+    unmanaged?: string[];
+    pinnedAt: string;
+}
+export declare const PIN_FILE = ".subscription-pin.json";
+export declare const OBSERVED_USAGE_FILE = ".subscription-usage.json";
+export declare const PROFILE_ID_RE: RegExp;
+export declare const subscriptionsRoot: () => string;
+/**
+ * The CLI's own default home, adopted as the `default` profile. This follows
+ * `$HOME` like the CLIs do, not OURS_FLEET_HOME (which may relocate Fleet state).
+ */
+export declare const baseHome: (provider: SubscriptionProvider) => string;
+export declare function isProvider(value: unknown): value is SubscriptionProvider;
+export declare function profileHome(provider: SubscriptionProvider, profileId: string): string;
+/**
+ * Read the state. The file is only ever replaced by an atomic rename, so a
+ * reader (including a launching agent) sees either the old or the new active
+ * profile, never a torn write.
+ */
+export declare function readSubscriptionState(): SubscriptionState;
+/** Serialised read-modify-write of the state under a cross-process lock. */
+export declare function updateSubscriptionState<T>(fn: (state: SubscriptionState) => T): Promise<T>;
+/**
+ * Create an empty profile home (not yet registered). Shared, non-history
+ * configuration is symlinked from the base home; credentials and session
+ * history stay per profile.
+ */
+export declare function createProfileHome(provider: SubscriptionProvider): {
+    id: string;
+    home: string;
+};
+/** Remove a non-default profile home. Never touches the adopted default. */
+export declare function removeProfileHome(provider: SubscriptionProvider, profileId: string): void;
+export declare function readPin(stateDir: string, provider?: SubscriptionProvider): SubscriptionPin | undefined;
+export declare function writePin(stateDir: string, pin: SubscriptionPin): void;