@phnx-labs/agents-cli 1.22.44 → 1.22.46

package/dist/commands/view.js

@@ -1314,7 +1314,7 @@ export async function collectAgentsJson(filterAgentId, resourceSections) {
             unavailable: snapshot?.unavailable
                 ? {
                     reason: snapshot.unavailable.reason,
-                    resetsAt: snapshot.unavailable.resetsAt.toISOString(),
+                    resetsAt: snapshot.unavailable.resetsAt?.toISOString(),
                 }
                 : undefined,
             lastActive: info.lastActive ? info.lastActive.toISOString() : null,

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

@@ -91,10 +91,16 @@ export interface UsageSnapshot {
     capturedAt: Date | null;
     windows: UsageWindow[];
     plan?: string | null;
-    /** A refusal observed from a real harness run, independent of API windows. */
+    /**
+     * A refusal observed from a real harness run, independent of API windows.
+     * `session_limit` recovers on a clock (`resetsAt`). `out_of_credits` is a
+     * tokens/balance exhaustion that does NOT reset on a clock — it has no
+     * `resetsAt` and is cleared only by a later successful run on the account
+     * (clearClaudeAccountRefusal). Both exclude the account from rotation while set.
+     */
     unavailable?: {
-        reason: 'session_limit';
-        resetsAt: Date;
+        reason: 'session_limit' | 'out_of_credits';
+        resetsAt?: Date;
     };
 }
 /** Usage data plus any error encountered while fetching. */
@@ -515,6 +521,19 @@ export declare function readClaudeUsageCache(usageKey: string, cachePath?: strin
 export declare function pruneExpiredClaudeUsageCacheEntry(usageKey: string, cachePath?: string, now?: Date): void;
 /** Write a usage snapshot to the on-disk cache. */
 export declare function writeClaudeUsageCache(usageKey: string, snapshot: UsageSnapshot, cachePath?: string): void;
+/**
+ * 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
+ * on a clock, so no reset time is stored — rotation excludes the account until a
+ * later successful run clears it via {@link clearClaudeAccountRefusal}.
+ */
+export declare function noteClaudeOutOfCredits(usageKey: string, cachePath?: string): void;
+/**
+ * Clear any persisted refusal marker for an account after a run SUCCEEDS on it.
+ * This is the recovery path for `out_of_credits` (which has no clock) and also
+ * proactively clears a stale `session_limit` the moment the account serves again.
+ */
+export declare function clearClaudeAccountRefusal(usageKey: string, cachePath?: string): void;
 /**
  * Persist a Claude session-limit refusal from a real run until its stated reset.
  * This quota is not part of Anthropic's five-hour/weekly usage response.

package/dist/lib/accounting/usage.js

@@ -398,7 +398,10 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
         parts.push(chalk.gray(plan.padEnd(planWidth)));
     }
     if (snapshot) {
-        if (snapshot.unavailable?.reason === 'session_limit') {
+        if (snapshot.unavailable?.reason === 'out_of_credits') {
+            parts.push(chalk.red('out of credits'));
+        }
+        else if (snapshot.unavailable?.reason === 'session_limit' && snapshot.unavailable.resetsAt) {
             parts.push(chalk.yellow(`session-limited (${formatResetHint(snapshot.unavailable.resetsAt)})`));
         }
         // Compact rows show BLOCKING windows — the same set
@@ -472,8 +475,14 @@ export function formatUsageSummary(plan, snapshot, planWidth = 3, opts) {
 export function deriveUsageStatusFromSnapshot(snapshot) {
     if (!snapshot)
         return null;
-    if (snapshot.unavailable && snapshot.unavailable.resetsAt.getTime() > Date.now()) {
-        return 'rate_limited';
+    if (snapshot.unavailable) {
+        // out_of_credits has no clock — it stays blocking until a successful run
+        // clears it. session_limit blocks only until its reset time.
+        if (snapshot.unavailable.reason === 'out_of_credits')
+            return 'rate_limited';
+        if (snapshot.unavailable.resetsAt && snapshot.unavailable.resetsAt.getTime() > Date.now()) {
+            return 'rate_limited';
+        }
     }
     if (snapshot.windows.length === 0)
         return null;
@@ -1487,12 +1496,9 @@ export function writeClaudeUsageCache(usageKey, snapshot, cachePath = getClaudeU
             // refresh cannot drop another account's row (lost update).
             const cache = readClaudeUsageCacheFile(cachePath);
             const prior = cache[usageKey];
-            const priorReset = parseDateValue(prior?.unavailable?.resetsAt);
             cache[usageKey] = serializeClaudeUsageSnapshot({
                 ...snapshot,
-                unavailable: priorReset && priorReset.getTime() > Date.now()
-                    ? { reason: 'session_limit', resetsAt: priorReset }
-                    : snapshot.unavailable,
+                unavailable: carryForwardUnavailable(prior?.unavailable, snapshot.unavailable),
             });
             atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
         });
@@ -1530,7 +1536,10 @@ function serializeClaudeUsageSnapshot(snapshot) {
         capturedAt: snapshot.capturedAt?.toISOString() || null,
         plan: snapshot.plan ?? null,
         unavailable: snapshot.unavailable
-            ? { reason: snapshot.unavailable.reason, resetsAt: snapshot.unavailable.resetsAt.toISOString() }
+            ? {
+                reason: snapshot.unavailable.reason,
+                resetsAt: snapshot.unavailable.resetsAt?.toISOString(),
+            }
             : undefined,
         windows: snapshot.windows.map((window) => ({
             key: window.key,
@@ -1565,10 +1574,7 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         windowMinutes: window.windowMinutes,
     }))
         .filter((window) => isCachedUsageWindowFresh(window, capturedAt, now));
-    const unavailableReset = parseDateValue(snapshot.unavailable?.resetsAt);
-    const unavailable = unavailableReset && unavailableReset.getTime() > now.getTime()
-        ? { reason: 'session_limit', resetsAt: unavailableReset }
-        : undefined;
+    const unavailable = deserializeUnavailable(snapshot.unavailable, now);
     if (windows.length === 0 && !unavailable) {
         return null;
     }
@@ -1581,6 +1587,82 @@ function deserializeClaudeUsageSnapshot(snapshot, now) {
         unavailable,
     };
 }
+/**
+ * Carry a prior refusal marker forward across a daemon usage refresh, and drop
+ * an expired one. A live `snapshot.unavailable` (a refusal just observed) wins.
+ * `out_of_credits` survives refreshes with no reset — only a successful run
+ * clears it (clearClaudeAccountRefusal). A `session_limit` survives only while
+ * its reset time is still in the future.
+ */
+function carryForwardUnavailable(prior, live) {
+    if (live)
+        return live;
+    if (!prior)
+        return undefined;
+    if (prior.reason === 'out_of_credits')
+        return { reason: 'out_of_credits' };
+    const reset = parseDateValue(prior.resetsAt);
+    return reset && reset.getTime() > Date.now()
+        ? { reason: 'session_limit', resetsAt: reset }
+        : undefined;
+}
+/**
+ * Deserialize a cached `unavailable` marker, dropping an expired session_limit
+ * but keeping a clock-less out_of_credits.
+ */
+function deserializeUnavailable(cached, now) {
+    if (!cached)
+        return undefined;
+    if (cached.reason === 'out_of_credits')
+        return { reason: 'out_of_credits' };
+    const reset = parseDateValue(cached.resetsAt);
+    return reset && reset.getTime() > now.getTime()
+        ? { reason: 'session_limit', resetsAt: reset }
+        : undefined;
+}
+/**
+ * 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
+ * on a clock, so no reset time is stored — rotation excludes the account until a
+ * later successful run clears it via {@link clearClaudeAccountRefusal}.
+ */
+export function noteClaudeOutOfCredits(usageKey, cachePath = getClaudeUsageCachePath()) {
+    try {
+        ensureLockTarget(cachePath, '{}');
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            const existing = cache[usageKey] ?? { capturedAt: null, windows: [] };
+            cache[usageKey] = { ...existing, unavailable: { reason: 'out_of_credits' } };
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write — lock busy or disk full */
+    }
+}
+/**
+ * Clear any persisted refusal marker for an account after a run SUCCEEDS on it.
+ * This is the recovery path for `out_of_credits` (which has no clock) and also
+ * proactively clears a stale `session_limit` the moment the account serves again.
+ */
+export function clearClaudeAccountRefusal(usageKey, cachePath = getClaudeUsageCachePath()) {
+    try {
+        if (!fs.existsSync(cachePath))
+            return;
+        withFileLock(cachePath, () => {
+            const cache = readClaudeUsageCacheFile(cachePath);
+            const existing = cache[usageKey];
+            if (!existing?.unavailable)
+                return;
+            const { unavailable: _drop, ...rest } = existing;
+            cache[usageKey] = rest;
+            atomicWriteFileSync(cachePath, JSON.stringify(cache, null, 2), 'utf-8');
+        });
+    }
+    catch {
+        /* best-effort cache write */
+    }
+}
 /**
  * Persist a Claude session-limit refusal from a real run until its stated reset.
  * This quota is not part of Anthropic's five-hour/weekly usage response.

package/dist/lib/agent-spec/agents.js

@@ -21,6 +21,7 @@ import chalk from 'chalk';
 import { execFileShellSpec } from '../platform/index.js';
 import { latestFileMtimeMs } from '../fs-walk.js';
 import { damerauLevenshtein } from '../fuzzy.js';
+import { probeCapture } from '../probe.js';
 import { getCacheDir, getVersionsDir, getShimsDir, getHistoryDir, getCliVersionCachePath } from '../state.js';
 import { resolveVersion, getVersionHomePath, getBinaryPath } from '../installations/versions.js';
 import { supports } from '../capabilities.js';
@@ -1194,7 +1195,11 @@ async function getCachedVersionForBinary(agentId, binaryPath) {
     const agent = AGENTS[agentId];
     let version = null;
     try {
-        const { stdout } = await execFileAsync(agent.cliCommand, ['--version'], { timeout: 3000 });
+        // probeCapture, not bare execFileAsync: a probed harness can fork its own
+        // children (copilot's platform-binary downloader), and a timeout kill of
+        // the direct child would orphan them mid-write (RUSH-3028). The probe runs
+        // in its own process group and the whole group is reaped on settle.
+        const { stdout } = await probeCapture(agent.cliCommand, ['--version'], 3000);
         const versionRe = agent.versionStdoutMatch === 'openclaw'
             ? /openclaw\/(\d+\.\d+\.\d+)/
             : /(\d+\.\d+\.\d+)/;

package/dist/lib/cli-resources.js

@@ -21,6 +21,7 @@ import * as path from 'path';
 import { spawnSync, execFile } from 'child_process';
 import * as yaml from 'yaml';
 import { listResources, resolveResource } from './resources.js';
+import { probeCapture } from './probe.js';
 import { composeWin32CommandLine } from './platform/index.js';
 import { localBinDir } from './platform/posixpath.js';
 // ─── Validation primitives ───────────────────────────────────────────────────
@@ -318,22 +319,23 @@ export function isCliInstalledAsync(manifest) {
         cmdExistsCache.delete(c.cmd);
         return Promise.resolve(hasCommand(c.cmd));
     }
-    return new Promise((resolve) => {
-        execFile(c.cmd, c.args, { timeout: 10_000 }, (err) => {
-            if (!err)
-                return resolve(true);
-            // A spawn failure (as opposed to a non-zero exit) surfaces as a string
-            // errno code (ENOENT/EINVAL); a non-zero exit surfaces as a numeric code.
-            // On Windows a `.cmd`/`.bat` shim spawn-fails without a shell — retry once
-            // through the shell, exactly as the sync path does.
-            const spawnFailed = typeof err.code === 'string';
-            if (process.platform === 'win32' && spawnFailed) {
-                const line = composeWin32CommandLine(c.cmd, c.args);
+    // probeCapture, not bare execFile: a checked CLI can fork children of its
+    // own (copilot's platform-binary downloader), and settling without reaping
+    // the probe's process group would orphan them mid-write (RUSH-3028).
+    return probeCapture(c.cmd, c.args, 10_000).then(() => true, (err) => {
+        // A spawn failure (as opposed to a non-zero exit) surfaces as a string
+        // errno code (ENOENT/EINVAL) on the rejection; a non-zero exit or
+        // timeout carries no errno. On Windows a `.cmd`/`.bat` shim spawn-fails
+        // without a shell — retry once through the shell, exactly as the sync
+        // path does.
+        const spawnFailed = typeof err.code === 'string';
+        if (process.platform === 'win32' && spawnFailed) {
+            const line = composeWin32CommandLine(c.cmd, c.args);
+            return new Promise((resolve) => {
                 execFile(line, { timeout: 10_000, shell: true }, (retryErr) => resolve(!retryErr));
-                return;
-            }
-            resolve(false);
-        });
+            });
+        }
+        return false;
     });
 }
 // ─── Method selection ────────────────────────────────────────────────────────

package/dist/lib/devices/harness-inventory.js

@@ -27,15 +27,32 @@ import { listNativeAccounts } from '../account-registry.js';
  */
 export function summarizeQuota(snapshot, unavailableReason = null, accountStatus = null) {
     if (!snapshot || snapshot.windows.length === 0) {
-        const status = accountStatus;
+        // An active refusal marker (persisted out_of_credits, or an unexpired
+        // session_limit) blocks even when there are no live utilization windows —
+        // which is the normal state hours/days after a run, once cached windows
+        // expire. Check it BEFORE trusting the coarse account status, which is
+        // hardcoded 'available' for a signed-in Claude; otherwise a tokens-exhausted
+        // account reads ready:true here (RUSH-3018 finding, `agents devices harnesses`).
+        const marker = snapshot?.unavailable;
+        let status = accountStatus;
+        let reason = unavailableReason;
+        if (marker?.reason === 'out_of_credits') {
+            status = 'out_of_credits';
+            reason = 'out of credits';
+        }
+        else if (marker?.reason === 'session_limit' &&
+            (!marker.resetsAt || marker.resetsAt.getTime() > Date.now())) {
+            status = 'rate_limited';
+            reason = 'session-limited';
+        }
         return {
             status,
             verdict: status ?? 'unavailable',
             usedPercent: null,
             stale: false,
             capturedAt: snapshot?.capturedAt?.toISOString() ?? null,
-            resetsAt: null,
-            unavailableReason: status ? null : (unavailableReason ?? 'usage unavailable'),
+            resetsAt: marker?.resetsAt?.toISOString() ?? null,
+            unavailableReason: status ? null : (reason ?? 'usage unavailable'),
         };
     }
     const blocking = snapshot.windows.filter((w) => w.key !== 'sonnet_week');

package/dist/lib/exec.d.ts

@@ -482,6 +482,26 @@ export declare const UNKNOWN_OUTCOME_EXIT_CODE = 1;
 export declare const RATE_LIMIT_PATTERNS: RegExp[];
 /** Return true if the text contains any known rate-limit or overload indicator. */
 export declare function detectRateLimit(text: string): boolean;
+export declare function detectOutOfCredits(text: string): boolean;
+/**
+ * Classify what a Claude run's output + exit code means for the account's
+ * persisted refusal marker. Pure and exported so the persist/clear decision is
+ * unit-tested on the real path (runWithFallback can't be driven with a real
+ * `claude` spawn in tests). Precedence: a session-limit reset wins (it carries a
+ * clock), then a clock-less billing exhaustion, then a clean success clears any
+ * stale marker; anything else leaves the marker untouched.
+ */
+export type ClaudeRefusalAction = {
+    action: 'note_session';
+    resetsAt: Date;
+} | {
+    action: 'note_out_of_credits';
+} | {
+    action: 'clear';
+} | {
+    action: 'none';
+};
+export declare function classifyClaudeRunRefusal(output: string, exitCode: number): ClaudeRefusalAction;
 /**
  * Patterns that indicate an authentication failure — the agent is logged out,
  * its token was revoked, or the session expired. These are the user-visible

package/dist/lib/exec.js

@@ -38,7 +38,7 @@ import { applyActiveRulesPresetAtRun } from './rules/run-sync.js';
 import { resolveHarnessAdapter, stripForeignConfigDir } from './harness/index.js';
 import { resolveConfigVersion } from './harness/exec-config-version.js';
 import { getAccountInfo } from './agents.js';
-import { getUsageLookupKey, noteClaudeSessionLimit, parseClaudeSessionLimitReset } from './accounting/usage.js';
+import { getUsageLookupKey, noteClaudeSessionLimit, noteClaudeOutOfCredits, clearClaudeAccountRefusal, parseClaudeSessionLimitReset } from './accounting/usage.js';
 /**
  * Map a raw mode string (CLI flag, YAML field, env var) to the canonical Mode.
  *
@@ -1865,6 +1865,29 @@ export const RATE_LIMIT_PATTERNS = [
 export function detectRateLimit(text) {
     return RATE_LIMIT_PATTERNS.some(pattern => pattern.test(text));
 }
+/**
+ * Narrow detector for a BILLING exhaustion — tokens/credits run out or the
+ * monthly spend cap is hit — as opposed to a time-window rate limit. This class
+ * does NOT recover on a clock, so rotation must remember it per-account
+ * (noteClaudeOutOfCredits) until a later successful run clears it.
+ */
+const OUT_OF_CREDITS_PATTERNS = [
+    /out of (?:usage )?credits/i,
+    /spend[\s-]?limit/i,
+];
+export function detectOutOfCredits(text) {
+    return OUT_OF_CREDITS_PATTERNS.some(pattern => pattern.test(text));
+}
+export function classifyClaudeRunRefusal(output, exitCode) {
+    const sessionLimitReset = parseClaudeSessionLimitReset(output);
+    if (sessionLimitReset)
+        return { action: 'note_session', resetsAt: sessionLimitReset };
+    if (detectOutOfCredits(output))
+        return { action: 'note_out_of_credits' };
+    if (exitCode === 0)
+        return { action: 'clear' };
+    return { action: 'none' };
+}
 /**
  * Patterns that indicate an authentication failure — the agent is logged out,
  * its token was revoked, or the session expired. These are the user-visible
@@ -2086,12 +2109,26 @@ export async function runWithFallback(options) {
             throw err;
         }
         const output = `${result.stderr}\n${result.stdout}`;
+        // Persist a per-account refusal marker so rotation stops re-picking a
+        // known-dead account: a session-limit recovers on its clock, a billing
+        // exhaustion (tokens/credits) recovers only on a later successful run, and a
+        // clean run clears any stale marker. Decision extracted + unit-tested in
+        // classifyClaudeRunRefusal.
         const sessionLimitReset = agent === 'claude' ? parseClaudeSessionLimitReset(output) : null;
-        if (sessionLimitReset && version) {
-            const account = await getAccountInfo(agent, getVersionHomePath(agent, version));
-            const usageKey = getUsageLookupKey(account);
-            if (usageKey)
-                noteClaudeSessionLimit(usageKey, sessionLimitReset);
+        if (agent === 'claude' && version) {
+            const refusal = classifyClaudeRunRefusal(output, result.exitCode ?? 1);
+            if (refusal.action !== 'none') {
+                const account = await getAccountInfo(agent, getVersionHomePath(agent, version));
+                const usageKey = getUsageLookupKey(account);
+                if (usageKey) {
+                    if (refusal.action === 'note_session')
+                        noteClaudeSessionLimit(usageKey, refusal.resetsAt);
+                    else if (refusal.action === 'note_out_of_credits')
+                        noteClaudeOutOfCredits(usageKey);
+                    else if (refusal.action === 'clear')
+                        clearClaudeAccountRefusal(usageKey);
+                }
+            }
         }
         if (result.exitCode === 0 && !sessionLimitReset)
             return 0;

package/dist/lib/identity/client.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The ONE place agents-cli talks to its account backend (Phoenix ID).
+ *
+ * Why a seam at all: the removed Prix-coupled layer (RUSH-2581) had no single
+ * entry point — the backend URL was hardcoded in five files and the session
+ * token was re-read from `~/.rush/user.yaml` by seven separate functions, so
+ * re-pointing identity meant editing a dozen call sites and rewriting error
+ * strings scattered through the tree. This module is the correction: one base
+ * URL, one token reader, one HTTP funnel, one error type. Commands import from
+ * here and nothing else.
+ *
+ * The shape mirrors the seams this repo already proved elsewhere —
+ * `SyncBackend` (`lib/secrets/sync-backend.ts`) and `CloudProvider`
+ * (`lib/cloud/types.ts`) — so a second identity backend, if one is ever
+ * needed, is a swap here rather than a sweep across commands.
+ */
+/**
+ * Where the account backend lives. Config, never a literal at a call site.
+ *
+ * The default is the deployed Phoenix ID Worker. It is a `workers.dev` URL
+ * rather than a vanity hostname because no custom domain is attached yet — and
+ * a default naming an unregistered domain is worse than an ugly one: every
+ * `agents auth login` would fail DNS with nothing to point at.
+ */
+export declare const PHOENIX_ID_BASE: string;
+/** Our own session file. agents-cli never reads another product's credentials. */
+export declare function sessionFilePath(): string;
+export interface PhoenixSession {
+    access_token: string;
+    email?: string;
+    userId?: string;
+    /** Unix ms; absent means the server did not scope the token's lifetime. */
+    expires_at?: number;
+}
+export declare function readSession(): PhoenixSession | null;
+export declare function writeSession(session: PhoenixSession): void;
+export declare function clearSession(): void;
+/** An error carrying the server's status and message, so callers can branch on it. */
+export declare class PhoenixApiError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+interface RequestOptions {
+    body?: unknown;
+    /** Send the stored session token. Default true; the device-flow start does not. */
+    auth?: boolean;
+    /** Use this token instead of the stored one (mid-login, before the write). */
+    token?: string;
+    timeoutMs?: number;
+}
+/** The single HTTP funnel. Every request to the account backend goes through here. */
+export declare function phoenixRequest<T>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', route: string, opts?: RequestOptions): Promise<T>;
+export {};

package/dist/lib/identity/client.js

@@ -0,0 +1,106 @@
+/**
+ * The ONE place agents-cli talks to its account backend (Phoenix ID).
+ *
+ * Why a seam at all: the removed Prix-coupled layer (RUSH-2581) had no single
+ * entry point — the backend URL was hardcoded in five files and the session
+ * token was re-read from `~/.rush/user.yaml` by seven separate functions, so
+ * re-pointing identity meant editing a dozen call sites and rewriting error
+ * strings scattered through the tree. This module is the correction: one base
+ * URL, one token reader, one HTTP funnel, one error type. Commands import from
+ * here and nothing else.
+ *
+ * The shape mirrors the seams this repo already proved elsewhere —
+ * `SyncBackend` (`lib/secrets/sync-backend.ts`) and `CloudProvider`
+ * (`lib/cloud/types.ts`) — so a second identity backend, if one is ever
+ * needed, is a swap here rather than a sweep across commands.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getRuntimeStateDir } from '../state.js';
+/**
+ * Where the account backend lives. Config, never a literal at a call site.
+ *
+ * The default is the deployed Phoenix ID Worker. It is a `workers.dev` URL
+ * rather than a vanity hostname because no custom domain is attached yet — and
+ * a default naming an unregistered domain is worse than an ugly one: every
+ * `agents auth login` would fail DNS with nothing to point at.
+ */
+export const PHOENIX_ID_BASE = process.env.PHOENIX_ID_BASE ?? 'https://phoenix-id.muqsitnawaz.workers.dev';
+/** Our own session file. agents-cli never reads another product's credentials. */
+export function sessionFilePath() {
+    return path.join(getRuntimeStateDir(), 'phoenix-session.json');
+}
+export function readSession() {
+    try {
+        const raw = fs.readFileSync(sessionFilePath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed.access_token ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSession(session) {
+    const file = sessionFilePath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(session, null, 2), { mode: 0o600 });
+}
+export function clearSession() {
+    try {
+        fs.rmSync(sessionFilePath(), { force: true });
+    }
+    catch {
+        // Already gone: logging out twice is not an error.
+    }
+}
+/** An error carrying the server's status and message, so callers can branch on it. */
+export class PhoenixApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = 'PhoenixApiError';
+    }
+}
+/** The single HTTP funnel. Every request to the account backend goes through here. */
+export async function phoenixRequest(method, route, opts = {}) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (opts.auth !== false) {
+        const token = opts.token ?? readSession()?.access_token;
+        if (!token)
+            throw new PhoenixApiError("Not signed in. Run 'agents auth login'.", 401);
+        headers.Authorization = `Bearer ${token}`;
+    }
+    let response;
+    try {
+        response = await fetch(`${PHOENIX_ID_BASE}${route}`, {
+            method,
+            headers,
+            body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
+        });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new PhoenixApiError(`Could not reach the account service (${detail}).`, 0);
+    }
+    if (response.status === 204)
+        return undefined;
+    const text = await response.text();
+    let payload = null;
+    if (text) {
+        try {
+            payload = JSON.parse(text);
+        }
+        catch {
+            payload = null;
+        }
+    }
+    if (!response.ok) {
+        const message = payload && typeof payload === 'object' && 'error' in payload
+            ? String(payload.error)
+            : `${response.status} ${response.statusText}`;
+        throw new PhoenixApiError(message, response.status);
+    }
+    return payload;
+}