codex-account-orchestrator 1.0.2 → 1.1.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.1] - 2026-01-27
+
+### Fixed
+
+- Made `npm run test` bash-compatible by using `node --test test/*.test.js`
+- Restored CI stability across the GitHub Actions Node.js matrix
+
+## [1.1.0] - 2026-01-27
+
+### Added
+
+- `cao status` command for detailed per-account inspection
+- `cao list --details` for quick detailed status views
+- Persisted account signals in `account_status.json` (attempt/success/quota/cooldown)
+- Node.js test suite for the account status store
+
+### Changed
+
+- Gateway and fallback flows now update persisted account status signals
+- CI now runs tests (build + Node test runner)
+- README refreshed with badges, observability guidance, and clearer quick-start flows
+
+### Fixed
+
+- Eliminated shared empty-registry state in account status loading
+
 ## [1.0.2] - 2026-01-27
 
 ### Added

package/README.md

@@ -1,6 +1,23 @@
-# codex-account-orchestrator
+# codex-account-orchestrator (CAO)
 
-Codex OAuth account fallback orchestrator. It keeps **separate `CODEX_HOME` directories per account** and automatically falls back to the next account when quota is exhausted.
+[![CI](https://github.com/DAWNCR0W/codex-account-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/DAWNCR0W/codex-account-orchestrator/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/codex-account-orchestrator.svg)](https://www.npmjs.com/package/codex-account-orchestrator)
+[![npm downloads](https://img.shields.io/npm/dm/codex-account-orchestrator.svg)](https://www.npmjs.com/package/codex-account-orchestrator)
+[![license](https://img.shields.io/npm/l/codex-account-orchestrator.svg)](LICENSE)
+[![node](https://img.shields.io/node/v/codex-account-orchestrator.svg)](https://nodejs.org/)
+[![typescript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+
+Codex OAuth account fallback orchestrator. CAO keeps **separate `CODEX_HOME` directories per account** and automatically falls back to the next account when quota is exhausted.
+
+> If you juggle multiple Codex accounts, CAO removes the friction and keeps you moving.
+
+## Highlights
+
+- Per-account isolation via separate `CODEX_HOME` directories
+- Automatic fallback on quota exhaustion (keyword-based detector)
+- Gateway mode for seamless account switching without session drops
+- Lightweight observability via `cao status` and `cao list --details`
+- Strict TypeScript build with a small, dependency-light CLI
 
 ## Requirements
 
@@ -23,9 +40,9 @@ npm run build
 npm link  # Makes 'cao' command available globally
 ```
 
-## Usage
+## Quick Start
 
-### Add accounts
+### 1. Add accounts
 
 ```bash
 cao add accountA
@@ -44,70 +61,64 @@ If you prefer device auth:
 cao add accountA --device-auth
 ```
 
-### Set default account
+### 2. Set the default account
 
 ```bash
 cao use accountA
 ```
 
-### List accounts
+### 3. Run with fallback
 
 ```bash
-cao list
+cao run
 ```
 
-### Remove an account
+To pass arguments to Codex, put them after `--`:
 
 ```bash
-cao remove accountB
+cao run -- exec "summarize README"
 ```
 
-To keep files on disk:
+To recheck all accounts when everyone is quota-limited, use multiple passes:
 
 ```bash
-cao remove accountB --keep-files
+cao run --max-passes 2 --retry-delay 5
 ```
 
-### Run with fallback
-
-```bash
-cao run
-```
+## Account Status & Observability
 
-To pass arguments to Codex, put them after `--`:
+### List accounts (quick)
 
 ```bash
-cao run -- exec "summarize README"
+cao list
 ```
 
-To recheck all accounts when everyone is quota-limited, use multiple passes:
+### Detailed status (recommended)
 
 ```bash
-cao run --max-passes 2 --retry-delay 5
+cao status
 ```
 
-### Run a specific account (no fallback)
+You can also use:
 
 ```bash
-cao run --no-fallback --account accountB -- codex
+cao list --details
 ```
 
-### Custom data directory
+### JSON output for scripting
 
 ```bash
-cao --data-dir /path/to/data run -- codex
+cao status --json
 ```
 
-## How it works
+This includes useful signals such as:
 
-- Each account is stored in its own `CODEX_HOME` directory under:
-  - `~/.codex-account-orchestrator/<account>/`
-- A `config.toml` is created with:
-  - `cli_auth_credentials_store = "file"`
-  - `forced_login_method = "chatgpt"`
-- On quota errors (detected via output keywords), the CLI re-runs Codex with the next account and can recheck all accounts for a configurable number of passes.
+- Token expiry time
+- Last refresh time
+- Last attempt / success / quota-hit timestamps
+- Cooldown window and consecutive failures
 
-## Gateway mode (no session drop)
+## Gateway Mode (No Session Drop)
 
 Gateway mode keeps the Codex session open while switching accounts on quota errors. It requires routing Codex traffic through the local gateway.
 
@@ -153,17 +164,59 @@ If `~/.local/bin` is not in your PATH, add it so the shim is used.
 cao gateway status
 ```
 
-### Debug logging
+## How It Works
+
+- Each account is stored in its own `CODEX_HOME` directory: `~/.codex-account-orchestrator/<account>/`
+- A `config.toml` is created with the following values:
+
+```toml
+cli_auth_credentials_store = "file"
+forced_login_method = "chatgpt"
+```
+
+- On quota errors (detected via output keywords), the CLI re-runs Codex with the next account and can recheck all accounts for a configurable number of passes.
+- CAO now persists lightweight status signals to `account_status.json` for visibility.
+
+## Data Layout
+
+Default base directory:
+
+```text
+~/.codex-account-orchestrator/
+```
+
+Key files:
+
+- `registry.json`: registered accounts and default account
+- `account_status.json`: persisted last-attempt/success/quota/cooldown signals
+- `<account>/auth.json`: account-scoped tokens managed by Codex
+- `<account>/config.toml`: account-scoped Codex configuration
+
+## Development
+
+Build:
+
+```bash
+npm run build
+```
+
+Test (build + Node test runner):
 
-Set `CAO_DEBUG_HEADERS=1` to log sanitized request/response headers in the gateway process. To capture the last request body for inspection, also set `CAO_CAPTURE_BODY=1` (saved to `/tmp/cao-last-body.json` by default).
+```bash
+npm run test
+```
 
-Additional debug flags:
+Run locally after build:
 
-- `CAO_DEBUG_BODY=1` to log a sanitized body snippet.
-- `CAO_CAPTURE_BODY_PATH=/path/to/file.json` to override the capture path.
-- `CAO_FORCE_QUOTA_ACCOUNTS=accountA,accountB` to simulate quota failures for specific accounts.
+```bash
+node dist/cli_main.js --help
+```
 
 ## Notes
 
 - Fallback requires capturing output; this may make Codex detect a non-TTY stdout. If you want a pure TTY session, use `--no-fallback`.
 - The quota detector is keyword-based and can be extended in `src/constants.ts`.
+
+## Changelog
+
+See `CHANGELOG.md` for release notes and version history.

package/dist/account_inspector.d.ts

@@ -0,0 +1,14 @@
+import { type AccountStatus } from "./account_status_store";
+import { type TokenDetails } from "./gateway/token_utils";
+export interface AccountInspection {
+    name: string;
+    isDefault: boolean;
+    accountDir: string;
+    authFilePath: string;
+    loggedIn: boolean;
+    lastRefreshAtMs?: number;
+    accountId?: string;
+    tokenDetails?: TokenDetails;
+    status?: AccountStatus;
+}
+export declare function inspectAccounts(baseDir: string): AccountInspection[];

package/dist/account_inspector.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectAccounts = inspectAccounts;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const account_status_store_1 = require("./account_status_store");
+const paths_1 = require("./paths");
+const constants_1 = require("./constants");
+const registry_store_1 = require("./registry_store");
+const token_utils_1 = require("./gateway/token_utils");
+function parseLastRefresh(lastRefresh) {
+    if (typeof lastRefresh !== "string" || lastRefresh.trim().length === 0) {
+        return undefined;
+    }
+    const ms = Date.parse(lastRefresh);
+    return Number.isFinite(ms) && ms > 0 ? ms : undefined;
+}
+function loadAuthInspection(accountDir) {
+    const authFilePath = path_1.default.join(accountDir, constants_1.AUTH_FILE_NAME);
+    if (!fs_1.default.existsSync(authFilePath)) {
+        return { loggedIn: false };
+    }
+    let parsed;
+    try {
+        const raw = fs_1.default.readFileSync(authFilePath, "utf8");
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { loggedIn: false };
+    }
+    const accessToken = parsed.tokens?.access_token;
+    const idToken = parsed.tokens?.id_token;
+    if (!accessToken || typeof accessToken !== "string") {
+        return { loggedIn: false };
+    }
+    const tokenDetails = (0, token_utils_1.deriveTokenDetails)(accessToken, idToken);
+    const lastRefreshAtMs = parseLastRefresh(parsed.last_refresh);
+    return {
+        loggedIn: true,
+        lastRefreshAtMs,
+        accountId: parsed.tokens?.account_id ?? tokenDetails.chatgptAccountId,
+        tokenDetails
+    };
+}
+function inspectAccounts(baseDir) {
+    const registry = (0, registry_store_1.loadRegistry)(baseDir);
+    if (registry.accounts.length === 0) {
+        return [];
+    }
+    const statuses = (0, account_status_store_1.loadAccountStatuses)(baseDir);
+    const inspections = [];
+    for (const name of registry.accounts) {
+        const accountDir = (0, paths_1.getAccountDir)(baseDir, name);
+        const authFilePath = path_1.default.join(accountDir, constants_1.AUTH_FILE_NAME);
+        const authInspection = loadAuthInspection(accountDir);
+        const status = statuses[name];
+        inspections.push({
+            name,
+            isDefault: registry.default_account === name,
+            accountDir,
+            authFilePath,
+            loggedIn: authInspection.loggedIn,
+            lastRefreshAtMs: authInspection.lastRefreshAtMs,
+            accountId: authInspection.accountId,
+            tokenDetails: authInspection.tokenDetails,
+            status
+        });
+    }
+    return inspections;
+}

package/dist/account_manager.js

@@ -13,6 +13,7 @@ exports.removeAccount = removeAccount;
 exports.getAccountOrder = getAccountOrder;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const account_status_store_1 = require("./account_status_store");
 const constants_1 = require("./constants");
 const paths_1 = require("./paths");
 const registry_store_1 = require("./registry_store");
@@ -55,6 +56,7 @@ function addAccount(baseDir, accountName) {
     if (!registry.default_account) {
         registry.default_account = normalizedName;
     }
+    (0, account_status_store_1.updateAccountStatus)(baseDir, normalizedName, () => ({}));
     (0, registry_store_1.saveRegistry)(baseDir, registry);
     return registry;
 }
@@ -87,6 +89,7 @@ function removeAccount(baseDir, accountName, removeFiles) {
             fs_1.default.rmSync(accountDir, { recursive: true, force: true });
         }
     }
+    (0, account_status_store_1.deleteAccountStatus)(baseDir, normalizedName);
     (0, registry_store_1.saveRegistry)(baseDir, registry);
     return registry;
 }

package/dist/account_status_store.d.ts

@@ -0,0 +1,24 @@
+export interface AccountStatus {
+    lastAttemptAtMs?: number;
+    lastSuccessAtMs?: number;
+    lastQuotaAtMs?: number;
+    cooldownUntilMs?: number;
+    consecutiveFailures?: number;
+    lastError?: string;
+}
+export interface AccountStatusRegistry {
+    statuses: Record<string, AccountStatus>;
+}
+/**
+ * Loads the persisted per-account status registry. If the file is missing or
+ * invalid, a safe empty registry is returned.
+ */
+export declare function loadAccountStatusRegistry(baseDir: string): AccountStatusRegistry;
+export declare function loadAccountStatuses(baseDir: string): Record<string, AccountStatus>;
+export declare function getAccountStatus(baseDir: string, accountName: string): AccountStatus | undefined;
+/**
+ * Updates the stored status for a single account using a functional updater
+ * to avoid accidental partial writes.
+ */
+export declare function updateAccountStatus(baseDir: string, accountName: string, updater: (previous: AccountStatus) => AccountStatus): AccountStatus;
+export declare function deleteAccountStatus(baseDir: string, accountName: string): void;

package/dist/account_status_store.js

@@ -0,0 +1,121 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadAccountStatusRegistry = loadAccountStatusRegistry;
+exports.loadAccountStatuses = loadAccountStatuses;
+exports.getAccountStatus = getAccountStatus;
+exports.updateAccountStatus = updateAccountStatus;
+exports.deleteAccountStatus = deleteAccountStatus;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const paths_1 = require("./paths");
+function createEmptyRegistry() {
+    return { statuses: {} };
+}
+function sanitizeTimestamp(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return undefined;
+    }
+    return Math.floor(value);
+}
+function sanitizeCount(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        return undefined;
+    }
+    return Math.floor(value);
+}
+function sanitizeStatus(status) {
+    if (!status) {
+        return {};
+    }
+    const lastAttemptAtMs = sanitizeTimestamp(status.lastAttemptAtMs);
+    const lastSuccessAtMs = sanitizeTimestamp(status.lastSuccessAtMs);
+    const lastQuotaAtMs = sanitizeTimestamp(status.lastQuotaAtMs);
+    const cooldownUntilMs = sanitizeTimestamp(status.cooldownUntilMs);
+    const consecutiveFailures = sanitizeCount(status.consecutiveFailures);
+    const lastError = typeof status.lastError === "string" && status.lastError.trim().length > 0
+        ? status.lastError.trim()
+        : undefined;
+    return {
+        lastAttemptAtMs,
+        lastSuccessAtMs,
+        lastQuotaAtMs,
+        cooldownUntilMs,
+        consecutiveFailures,
+        lastError
+    };
+}
+function normalizeStatuses(statuses) {
+    if (!statuses || typeof statuses !== "object") {
+        return {};
+    }
+    const normalized = {};
+    for (const [name, status] of Object.entries(statuses)) {
+        const trimmedName = name.trim();
+        if (!trimmedName) {
+            continue;
+        }
+        normalized[trimmedName] = sanitizeStatus(status);
+    }
+    return normalized;
+}
+/**
+ * Loads the persisted per-account status registry. If the file is missing or
+ * invalid, a safe empty registry is returned.
+ */
+function loadAccountStatusRegistry(baseDir) {
+    const statusPath = (0, paths_1.getAccountStatusPath)(baseDir);
+    if (!fs_1.default.existsSync(statusPath)) {
+        return createEmptyRegistry();
+    }
+    const raw = fs_1.default.readFileSync(statusPath, "utf8");
+    try {
+        const parsed = JSON.parse(raw);
+        return { statuses: normalizeStatuses(parsed.statuses) };
+    }
+    catch {
+        const backupPath = `${statusPath}.corrupt-${Date.now()}`;
+        fs_1.default.writeFileSync(backupPath, raw, "utf8");
+        process.stderr.write(`Warning: account status file was invalid and has been backed up to ${backupPath}.\n`);
+        return createEmptyRegistry();
+    }
+}
+function loadAccountStatuses(baseDir) {
+    const registry = loadAccountStatusRegistry(baseDir);
+    return { ...registry.statuses };
+}
+function saveAccountStatusRegistry(baseDir, registry) {
+    const statusPath = (0, paths_1.getAccountStatusPath)(baseDir);
+    const dir = path_1.default.dirname(statusPath);
+    if (!fs_1.default.existsSync(dir)) {
+        fs_1.default.mkdirSync(dir, { recursive: true });
+    }
+    const payload = JSON.stringify(registry, null, 2) + "\n";
+    fs_1.default.writeFileSync(statusPath, payload, "utf8");
+}
+function getAccountStatus(baseDir, accountName) {
+    const registry = loadAccountStatusRegistry(baseDir);
+    return registry.statuses[accountName];
+}
+/**
+ * Updates the stored status for a single account using a functional updater
+ * to avoid accidental partial writes.
+ */
+function updateAccountStatus(baseDir, accountName, updater) {
+    const registry = loadAccountStatusRegistry(baseDir);
+    const previous = sanitizeStatus(registry.statuses[accountName]);
+    const next = sanitizeStatus(updater(previous));
+    registry.statuses[accountName] = next;
+    saveAccountStatusRegistry(baseDir, registry);
+    return next;
+}
+function deleteAccountStatus(baseDir, accountName) {
+    const registry = loadAccountStatusRegistry(baseDir);
+    if (!(accountName in registry.statuses)) {
+        return;
+    }
+    delete registry.statuses[accountName];
+    saveAccountStatusRegistry(baseDir, registry);
+}

package/dist/cli_main.js

@@ -8,6 +8,8 @@ const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const account_manager_1 = require("./account_manager");
+const account_inspector_1 = require("./account_inspector");
+const account_status_store_1 = require("./account_status_store");
 const codex_auth_1 = require("./codex_auth");
 const constants_1 = require("./constants");
 const codex_config_1 = require("./gateway/codex_config");
@@ -61,21 +63,38 @@ program
 program
     .command("list")
     .description("List registered accounts")
-    .action(() => {
+    .option("--details", "Show detailed account and usage status")
+    .action((options) => {
     const baseDir = (0, paths_1.getBaseDir)(program.opts().dataDir);
     (0, account_manager_1.ensureBaseDir)(baseDir);
-    const registry = (0, registry_store_1.loadRegistry)(baseDir);
-    if (registry.accounts.length === 0) {
+    const inspections = (0, account_inspector_1.inspectAccounts)(baseDir);
+    if (inspections.length === 0) {
+        process.stdout.write("No accounts registered. Use `cao add <name>` first.\n");
+        return;
+    }
+    if (!options.details) {
+        renderAccountSummary(inspections);
+        return;
+    }
+    renderAccountDetails(inspections);
+});
+program
+    .command("status")
+    .description("Show detailed account status and cooldown/usage signals")
+    .option("--json", "Output account status as JSON")
+    .action((options) => {
+    const baseDir = (0, paths_1.getBaseDir)(program.opts().dataDir);
+    (0, account_manager_1.ensureBaseDir)(baseDir);
+    const inspections = (0, account_inspector_1.inspectAccounts)(baseDir);
+    if (inspections.length === 0) {
         process.stdout.write("No accounts registered. Use `cao add <name>` first.\n");
         return;
     }
-    for (const name of registry.accounts) {
-        const marker = registry.default_account === name ? "*" : " ";
-        const accountDir = (0, paths_1.getAccountDir)(baseDir, name);
-        const loggedIn = fs_1.default.existsSync(getAuthFilePath(accountDir));
-        const status = loggedIn ? "logged-in" : "not-logged-in";
-        process.stdout.write(`${marker} ${name} (${status})\n`);
+    if (options.json) {
+        renderAccountDetailsJson(inspections);
+        return;
     }
+    renderAccountDetails(inspections);
 });
 program
     .command("use")
@@ -156,17 +175,24 @@ gateway
     .description("Show gateway config and account readiness")
     .action(() => {
     const baseDir = (0, paths_1.getBaseDir)(program.opts().dataDir);
+    (0, account_manager_1.ensureBaseDir)(baseDir);
     const config = (0, gateway_config_1.resolveGatewayConfig)((0, gateway_config_1.loadGatewayConfig)());
     const pool = account_pool_1.AccountPool.loadFromRegistry(baseDir);
+    const inspections = (0, account_inspector_1.inspectAccounts)(baseDir);
+    const inspectionsByName = new Map(inspections.map((inspection) => [inspection.name, inspection]));
+    const nowMs = Date.now();
     process.stdout.write(`Bind: ${config.bindAddress}:${config.port}\n`);
     process.stdout.write(`Upstream: ${config.baseUrl}\n`);
     process.stdout.write(`Override auth: ${config.overrideAuth ? "yes" : "no"}\n`);
     process.stdout.write(`Accounts: ${pool.getAccounts().length}\n`);
     for (const account of pool.getAccounts()) {
-        const cooldown = account.cooldownUntilMs > Date.now()
-            ? `cooldown ${Math.ceil((account.cooldownUntilMs - Date.now()) / 1000)}s`
+        const inspection = inspectionsByName.get(account.name);
+        const cooldown = account.cooldownUntilMs > nowMs
+            ? `cooldown ${Math.ceil((account.cooldownUntilMs - nowMs) / 1000)}s`
             : "ready";
-        process.stdout.write(`- ${account.name} (${cooldown})\n`);
+        const tokenExpiry = formatTimestampWithRelative(inspection?.tokenDetails?.expiresAtMs, nowMs);
+        const lastRefresh = formatTimestampWithRelative(inspection?.lastRefreshAtMs, nowMs);
+        process.stdout.write(`- ${account.name} (${cooldown}) | token_expires_at: ${tokenExpiry} | last_refresh_at: ${lastRefresh}\n`);
     }
 });
 gateway
@@ -250,6 +276,122 @@ function normalizeCodexArgs(args, codexBin) {
 function getAuthFilePath(accountDir) {
     return path_1.default.join(accountDir, constants_1.AUTH_FILE_NAME);
 }
+function renderAccountSummary(inspections) {
+    for (const inspection of inspections) {
+        const marker = inspection.isDefault ? "*" : " ";
+        const status = inspection.loggedIn ? "logged-in" : "not-logged-in";
+        process.stdout.write(`${marker} ${inspection.name} (${status})\n`);
+    }
+}
+function toAccountDetailRecord(inspection, referenceMs) {
+    const status = inspection.status ?? {};
+    const tokenExpiresAtMs = inspection.tokenDetails?.expiresAtMs;
+    const cooldownUntilMs = status.cooldownUntilMs;
+    const cooldownRemainingMs = cooldownUntilMs && cooldownUntilMs > referenceMs ? cooldownUntilMs - referenceMs : 0;
+    return {
+        name: inspection.name,
+        isDefault: inspection.isDefault,
+        loggedIn: inspection.loggedIn,
+        accountId: inspection.accountId ?? null,
+        organizationId: inspection.tokenDetails?.organizationId ?? null,
+        tokenExpiresAtMs: tokenExpiresAtMs ?? null,
+        tokenExpiresAtIso: tokenExpiresAtMs ? new Date(tokenExpiresAtMs).toISOString() : null,
+        tokenExpiresInMs: tokenExpiresAtMs ? Math.max(0, tokenExpiresAtMs - referenceMs) : null,
+        lastRefreshAtMs: inspection.lastRefreshAtMs ?? null,
+        lastRefreshAtIso: inspection.lastRefreshAtMs
+            ? new Date(inspection.lastRefreshAtMs).toISOString()
+            : null,
+        lastAttemptAtMs: status.lastAttemptAtMs ?? null,
+        lastAttemptAtIso: status.lastAttemptAtMs
+            ? new Date(status.lastAttemptAtMs).toISOString()
+            : null,
+        lastSuccessAtMs: status.lastSuccessAtMs ?? null,
+        lastSuccessAtIso: status.lastSuccessAtMs
+            ? new Date(status.lastSuccessAtMs).toISOString()
+            : null,
+        lastQuotaAtMs: status.lastQuotaAtMs ?? null,
+        lastQuotaAtIso: status.lastQuotaAtMs
+            ? new Date(status.lastQuotaAtMs).toISOString()
+            : null,
+        cooldownUntilMs: cooldownUntilMs ?? null,
+        cooldownUntilIso: cooldownUntilMs
+            ? new Date(cooldownUntilMs).toISOString()
+            : null,
+        cooldownRemainingMs,
+        consecutiveFailures: status.consecutiveFailures ?? 0,
+        lastError: status.lastError ?? null,
+        accountDir: inspection.accountDir,
+        authFilePath: inspection.authFilePath
+    };
+}
+function renderAccountDetails(inspections, referenceMs = Date.now()) {
+    const indent = "  ";
+    for (const inspection of inspections) {
+        const marker = inspection.isDefault ? "*" : " ";
+        const status = inspection.status ?? {};
+        const loginStatus = inspection.loggedIn ? "logged-in" : "not-logged-in";
+        process.stdout.write(`${marker} ${inspection.name}\n`);
+        process.stdout.write(`${indent}status: ${loginStatus}\n`);
+        process.stdout.write(`${indent}account_id: ${inspection.accountId ?? "(unknown)"}\n`);
+        process.stdout.write(`${indent}organization_id: ${inspection.tokenDetails?.organizationId ?? "(unknown)"}\n`);
+        process.stdout.write(`${indent}token_expires_at: ${formatTimestampWithRelative(inspection.tokenDetails?.expiresAtMs, referenceMs)}\n`);
+        process.stdout.write(`${indent}last_refresh_at: ${formatTimestampWithRelative(inspection.lastRefreshAtMs, referenceMs)}\n`);
+        process.stdout.write(`${indent}last_attempt_at: ${formatTimestampWithRelative(status.lastAttemptAtMs, referenceMs)}\n`);
+        process.stdout.write(`${indent}last_success_at: ${formatTimestampWithRelative(status.lastSuccessAtMs, referenceMs)}\n`);
+        process.stdout.write(`${indent}last_quota_at: ${formatTimestampWithRelative(status.lastQuotaAtMs, referenceMs)}\n`);
+        process.stdout.write(`${indent}cooldown_until: ${formatCooldown(status.cooldownUntilMs, referenceMs)}\n`);
+        process.stdout.write(`${indent}consecutive_failures: ${status.consecutiveFailures ?? 0}\n`);
+        process.stdout.write(`${indent}last_error: ${status.lastError ?? "none"}\n`);
+        process.stdout.write(`${indent}account_dir: ${inspection.accountDir}\n`);
+        process.stdout.write("\n");
+    }
+}
+function renderAccountDetailsJson(inspections) {
+    const referenceMs = Date.now();
+    const payload = inspections.map((inspection) => toAccountDetailRecord(inspection, referenceMs));
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+}
+function formatDuration(durationMs) {
+    const totalSeconds = Math.max(0, Math.floor(durationMs / 1000));
+    if (totalSeconds < 60) {
+        return `${totalSeconds}s`;
+    }
+    const minutes = Math.floor(totalSeconds / 60);
+    if (minutes < 60) {
+        const seconds = totalSeconds % 60;
+        return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+    }
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24) {
+        const remainingMinutes = minutes % 60;
+        return remainingMinutes > 0 ? `${hours}h ${remainingMinutes}m` : `${hours}h`;
+    }
+    const days = Math.floor(hours / 24);
+    const remainingHours = hours % 24;
+    return remainingHours > 0 ? `${days}d ${remainingHours}h` : `${days}d`;
+}
+function formatTimestampWithRelative(timestampMs, referenceMs) {
+    if (!timestampMs) {
+        return "(unknown)";
+    }
+    const iso = new Date(timestampMs).toISOString();
+    const diffMs = timestampMs - referenceMs;
+    if (Math.abs(diffMs) < 5_000) {
+        return `${iso} (now)`;
+    }
+    const relative = diffMs > 0 ? `in ${formatDuration(diffMs)}` : `${formatDuration(-diffMs)} ago`;
+    return `${iso} (${relative})`;
+}
+function formatCooldown(cooldownUntilMs, referenceMs) {
+    if (!cooldownUntilMs) {
+        return "none";
+    }
+    if (cooldownUntilMs <= referenceMs) {
+        const iso = new Date(cooldownUntilMs).toISOString();
+        return `${iso} (elapsed)`;
+    }
+    return formatTimestampWithRelative(cooldownUntilMs, referenceMs);
+}
 function buildGatewayOverrides(options) {
     const overrides = {};
     overrides.bindAddress = options.bind;
@@ -300,22 +442,59 @@ async function runWithFallback(options, baseDir, accounts, codexArgs) {
             const name = accounts[index];
             const accountDir = (0, account_manager_1.ensureAccountDir)(baseDir, name);
             (0, account_manager_1.ensureAccountConfig)(accountDir);
+            const attemptAtMs = Date.now();
+            (0, account_status_store_1.updateAccountStatus)(baseDir, name, (previous) => ({
+                ...previous,
+                lastAttemptAtMs: attemptAtMs
+            }));
             process.stderr.write(`Using account: ${name}\n`);
             const result = await (0, process_runner_1.runCodexOnce)(codexBin, codexArgs, accountDir, options.fallback);
             lastExitCode = result.exitCode;
             if (result.exitCode === 0) {
+                (0, account_status_store_1.updateAccountStatus)(baseDir, name, (previous) => ({
+                    ...previous,
+                    lastAttemptAtMs: attemptAtMs,
+                    lastSuccessAtMs: Date.now(),
+                    consecutiveFailures: 0,
+                    cooldownUntilMs: undefined,
+                    lastError: undefined
+                }));
                 process.exit(0);
                 return;
             }
             if (!options.fallback) {
+                (0, account_status_store_1.updateAccountStatus)(baseDir, name, (previous) => ({
+                    ...previous,
+                    lastAttemptAtMs: attemptAtMs,
+                    consecutiveFailures: (previous.consecutiveFailures ?? 0) + 1,
+                    cooldownUntilMs: undefined,
+                    lastError: `exit_code_${result.exitCode}`
+                }));
                 process.exit(result.exitCode);
                 return;
             }
             if (!result.quotaError) {
+                (0, account_status_store_1.updateAccountStatus)(baseDir, name, (previous) => ({
+                    ...previous,
+                    lastAttemptAtMs: attemptAtMs,
+                    consecutiveFailures: (previous.consecutiveFailures ?? 0) + 1,
+                    cooldownUntilMs: undefined,
+                    lastError: `exit_code_${result.exitCode}`
+                }));
                 process.exit(result.exitCode);
                 return;
             }
             quotaFailures += 1;
+            const quotaAtMs = Date.now();
+            const cooldownUntilMs = retryDelayMs > 0 ? quotaAtMs + retryDelayMs : undefined;
+            (0, account_status_store_1.updateAccountStatus)(baseDir, name, (previous) => ({
+                ...previous,
+                lastAttemptAtMs: attemptAtMs,
+                lastQuotaAtMs: quotaAtMs,
+                cooldownUntilMs,
+                consecutiveFailures: (previous.consecutiveFailures ?? 0) + 1,
+                lastError: "usage_limit_reached"
+            }));
             const nextName = accounts[index + 1];
             if (nextName) {
                 process.stderr.write(`Quota exhausted. Falling back to: ${nextName}\n`);

package/dist/constants.d.ts

@@ -1,5 +1,6 @@
 export declare const REGISTRY_FILE_NAME = "registry.json";
 export declare const AUTH_FILE_NAME = "auth.json";
+export declare const ACCOUNT_STATUS_FILE_NAME = "account_status.json";
 export declare const DEFAULT_CONFIG_TOML: string;
 export declare const QUOTA_ERROR_PATTERNS: RegExp[];
 export declare const MAX_CAPTURED_LINES = 200;

package/dist/constants.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_CAPTURED_LINES = exports.QUOTA_ERROR_PATTERNS = exports.DEFAULT_CONFIG_TOML = exports.AUTH_FILE_NAME = exports.REGISTRY_FILE_NAME = void 0;
+exports.MAX_CAPTURED_LINES = exports.QUOTA_ERROR_PATTERNS = exports.DEFAULT_CONFIG_TOML = exports.ACCOUNT_STATUS_FILE_NAME = exports.AUTH_FILE_NAME = exports.REGISTRY_FILE_NAME = void 0;
 exports.REGISTRY_FILE_NAME = "registry.json";
 exports.AUTH_FILE_NAME = "auth.json";
+exports.ACCOUNT_STATUS_FILE_NAME = "account_status.json";
 exports.DEFAULT_CONFIG_TOML = [
     "# Codex config for this account",
     "cli_auth_credentials_store = \"file\"",

package/dist/gateway/account_pool.d.ts

@@ -8,15 +8,17 @@ export interface AccountState {
     consecutiveFailures: number;
 }
 export declare class AccountPool {
+    private readonly baseDir;
     private readonly accounts;
     private readonly sessionAssignments;
-    constructor(accounts: AccountState[]);
+    constructor(baseDir: string, accounts: AccountState[]);
     static loadFromRegistry(baseDir: string): AccountPool;
     getAccounts(): AccountState[];
     getStickyAccount(sessionKey: string): AccountState | undefined;
     assignAccount(sessionKey: string, accountName: string): void;
     clearAssignment(sessionKey: string): void;
     pickNextAvailable(excluded: Set<string>): AccountState | undefined;
+    markAttempt(account: AccountState): void;
     markQuota(account: AccountState, cooldownSeconds: number, resetsAtMs?: number): void;
     markAuthFailure(account: AccountState, message: string): void;
     markSuccess(account: AccountState): void;

package/dist/gateway/account_pool.js

@@ -6,14 +6,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AccountPool = void 0;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const account_status_store_1 = require("../account_status_store");
 const paths_1 = require("../paths");
 const registry_store_1 = require("../registry_store");
 const account_manager_1 = require("../account_manager");
 const token_utils_1 = require("./token_utils");
 class AccountPool {
+    baseDir;
     accounts;
     sessionAssignments = new Map();
-    constructor(accounts) {
+    constructor(baseDir, accounts) {
+        this.baseDir = baseDir;
         this.accounts = accounts;
     }
     static loadFromRegistry(baseDir) {
@@ -34,7 +37,7 @@ class AccountPool {
                 consecutiveFailures: 0
             });
         }
-        return new AccountPool(accounts);
+        return new AccountPool(baseDir, accounts);
     }
     getAccounts() {
         return this.accounts;
@@ -65,24 +68,65 @@ class AccountPool {
         }
         return undefined;
     }
+    markAttempt(account) {
+        const attemptAtMs = Date.now();
+        (0, account_status_store_1.updateAccountStatus)(this.baseDir, account.name, (previous) => ({
+            ...previous,
+            lastAttemptAtMs: attemptAtMs
+        }));
+    }
     markQuota(account, cooldownSeconds, resetsAtMs) {
+        const quotaAtMs = Date.now();
         account.consecutiveFailures += 1;
         account.lastError = "usage_limit_reached";
-        const until = resetsAtMs && resetsAtMs > Date.now() ? resetsAtMs : Date.now() + cooldownSeconds * 1000;
+        const until = resetsAtMs && resetsAtMs > quotaAtMs ? resetsAtMs : quotaAtMs + cooldownSeconds * 1000;
         account.cooldownUntilMs = until;
+        (0, account_status_store_1.updateAccountStatus)(this.baseDir, account.name, (previous) => ({
+            ...previous,
+            lastAttemptAtMs: quotaAtMs,
+            lastQuotaAtMs: quotaAtMs,
+            cooldownUntilMs: until,
+            consecutiveFailures: (previous.consecutiveFailures ?? 0) + 1,
+            lastError: "usage_limit_reached"
+        }));
     }
     markAuthFailure(account, message) {
+        const failureAtMs = Date.now();
+        const cooldownUntilMs = failureAtMs + 60 * 1000;
         account.consecutiveFailures += 1;
         account.lastError = message;
-        account.cooldownUntilMs = Date.now() + 60 * 1000;
+        account.cooldownUntilMs = cooldownUntilMs;
+        (0, account_status_store_1.updateAccountStatus)(this.baseDir, account.name, (previous) => ({
+            ...previous,
+            lastAttemptAtMs: failureAtMs,
+            cooldownUntilMs,
+            consecutiveFailures: (previous.consecutiveFailures ?? 0) + 1,
+            lastError: message
+        }));
     }
     markSuccess(account) {
+        const successAtMs = Date.now();
         account.consecutiveFailures = 0;
         account.lastError = undefined;
+        (0, account_status_store_1.updateAccountStatus)(this.baseDir, account.name, (previous) => ({
+            ...previous,
+            lastAttemptAtMs: successAtMs,
+            lastSuccessAtMs: successAtMs,
+            consecutiveFailures: 0,
+            cooldownUntilMs: undefined,
+            lastError: undefined
+        }));
     }
     updateTokens(account, tokens) {
         account.tokens = tokens;
         persistTokens(account.accountDir, tokens);
+        (0, account_status_store_1.updateAccountStatus)(this.baseDir, account.name, (previous) => ({
+            ...previous,
+            lastSuccessAtMs: Date.now(),
+            consecutiveFailures: 0,
+            cooldownUntilMs: undefined,
+            lastError: undefined
+        }));
     }
     isTokenFresh(account, bufferSeconds) {
         return (0, token_utils_1.isTokenFresh)(account.tokens.expiresAtMs, bufferSeconds);

package/dist/gateway/openai_gateway.js

@@ -84,11 +84,13 @@ class OpenAiGateway {
     selectAccount(sessionKey, excluded) {
         const sticky = this.pool.getStickyAccount(sessionKey);
         if (sticky && !excluded.has(sticky.name) && sticky.cooldownUntilMs <= Date.now()) {
+            this.pool.markAttempt(sticky);
             return sticky;
         }
         const picked = this.pool.pickNextAvailable(excluded);
         if (picked) {
             this.pool.assignAccount(sessionKey, picked.name);
+            this.pool.markAttempt(picked);
         }
         return picked;
     }

package/dist/paths.d.ts

@@ -1,3 +1,4 @@
 export declare function getBaseDir(dataDir?: string): string;
 export declare function getAccountDir(baseDir: string, accountName: string): string;
 export declare function getRegistryPath(baseDir: string): string;
+export declare function getAccountStatusPath(baseDir: string): string;

package/dist/paths.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getBaseDir = getBaseDir;
 exports.getAccountDir = getAccountDir;
 exports.getRegistryPath = getRegistryPath;
+exports.getAccountStatusPath = getAccountStatusPath;
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const constants_1 = require("./constants");
@@ -21,3 +22,6 @@ function getAccountDir(baseDir, accountName) {
 function getRegistryPath(baseDir) {
     return path_1.default.join(baseDir, constants_1.REGISTRY_FILE_NAME);
 }
+function getAccountStatusPath(baseDir) {
+    return path_1.default.join(baseDir, constants_1.ACCOUNT_STATUS_FILE_NAME);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-account-orchestrator",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Codex OAuth account fallback orchestrator with seamless gateway mode",
   "main": "dist/cli_main.js",
   "types": "dist/cli_main.d.ts",
@@ -11,6 +11,8 @@
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",
+    "test": "npm run build && node --test test/*.test.js",
+    "check": "npm run test",
     "prepublishOnly": "npm run clean && npm run build",
     "start": "node dist/cli_main.js"
   },