@carjms/codexswitch 0.1.0 → 0.3.0

package/src/cli.js

@@ -12,27 +12,40 @@ const HELP = `codexswitch — multi-account manager for the OpenAI Codex CLI
 Accounts
   login [name]            log in to a new account (isolated "codex login") and store it
   import [name]           import the account currently in ~/.codex/auth.json
+  add-key <name> [key]    register an OpenAI API-key account (or read $OPENAI_API_KEY)
   list                    list stored accounts (alias: accounts, status)
   use <name>              make <name> the active account in ~/.codex
   current                 show the active account
-  next                    rotate to the next usable account
+  next                    switch to the next account in rotation order (wraps around)
   remove <name>           delete a stored account
   rename <old> <new>      rename a stored account
   enable <name>           re-enable a disabled account
   disable <name>          temporarily exclude an account from rotation
-  priority <name> <n>     set rotation priority (lower = preferred, default 0)
+  order [name...]         show or set the rotation order in one command
+  priority <name> <n>     set one account's priority (lower = preferred, default 0)
   clear-limit <name>      forget a recorded rate-limit for an account
 
 Running codex
   run [name] [args...]    run codex as <name> (or active account) in an isolated
                           per-account CODEX_HOME; config/sessions are shared
-  exec [args...]          run "codex exec ..." and auto-rotate to the next
-                          account when a usage/rate limit is hit
+  exec [args...]          run "codex exec ..." and auto-rotate through accounts in
+                          rotation order on usage limits; the next account resumes
+                          the same session (--skip-git-repo-check added automatically)
       -a, --account <n>   start exec with a specific account
+      --no-resume         restart the prompt instead of resuming on rotation
+
+Settings
+  model [name|default]    show/set the default model injected into run/exec
+  threshold [5h%] [wk%]   rotate early when recorded usage reaches these percents
+                          of the 5-hour / weekly window (default 95, one value = both)
+  cooldown [minutes]      show/set rate-limit cooldown (default 60)
+  patterns [add|remove]   extra regex patterns treated as rate-limit errors
 
 Maintenance
   sync                    save tokens refreshed by codex back into the store
-  cooldown [minutes]      show/set rate-limit cooldown (default 60)
+  export <file>           back up all accounts + settings (contains tokens!)
+  restore <file>          restore accounts from a backup file
+  completion <bash|zsh>   print a shell completion script
   help                    show this help
 
 Environment
@@ -119,16 +132,31 @@ function cmdList() {
     return;
   }
   const now = Date.now();
-  const rows = accounts.map((a) => [
-    a.active ? '*' : '',
-    a.name,
-    a.email,
-    a.plan,
-    a.priority,
-    a.disabled ? 'disabled' : a.limitedUntil && a.limitedUntil > now ? `limited ${fmtRemaining(a.limitedUntil)}` : 'ok',
-    fmtDate(a.lastRefresh),
-  ]);
-  out(table(rows, ['', 'name', 'email', 'plan', 'prio', 'status', 'token refreshed']));
+  const meta = store.loadMeta();
+  const pct = (win) => (win && typeof win.pct === 'number' ? `${Math.round(win.pct)}%` : '-');
+  const rows = accounts.map((a) => {
+    const over = store.overThreshold(a, meta, now);
+    const status = a.disabled
+      ? 'disabled'
+      : a.limitedUntil && a.limitedUntil > now
+        ? `limited ${fmtRemaining(a.limitedUntil)}`
+        : over
+          ? `over-${over}`
+          : 'ok';
+    return [
+      a.active ? '*' : '',
+      a.name,
+      a.email,
+      a.plan,
+      a.priority,
+      status,
+      pct(a.usage && a.usage.p5h),
+      pct(a.usage && a.usage.weekly),
+      fmtDate(a.lastRefresh),
+    ];
+  });
+  out(table(rows, ['', 'name', 'email', 'plan', 'prio', 'status', '5h', 'week', 'token refreshed']));
+  out(`(rotate threshold: 5h ${meta.threshold5h}% / weekly ${meta.thresholdWeekly}% — change with "codexswitch threshold")`);
 }
 
 function cmdUse(args) {
@@ -164,12 +192,32 @@ function cmdCurrent() {
 }
 
 function cmdNext() {
-  const meta = store.loadMeta();
-  const next = store.pickAccount(meta.active ? [meta.active] : []);
+  const next = store.nextAccount();
   if (!next) throw new Error('no other usable account available');
   cmdUse([next.name]);
 }
 
+// Register an API-key account (Console/platform billing instead of a
+// ChatGPT plan). The key is stored only inside the account's auth.json.
+function cmdAddKey(args) {
+  const name = requireArg(args, 0, 'account name');
+  const key = args[1] || process.env.OPENAI_API_KEY;
+  if (!key) {
+    throw new Error(
+      'missing API key: pass it as the second argument or set OPENAI_API_KEY in the environment'
+    );
+  }
+  if (!/^sk-/.test(key)) throw new Error('that does not look like an OpenAI API key (should start with "sk-")');
+  storeAccount(name, {
+    auth_mode: 'apikey',
+    OPENAI_API_KEY: key,
+    tokens: null,
+    last_refresh: null,
+  });
+  const meta = store.loadMeta();
+  if (!meta.active) cmdUse([name]);
+}
+
 function cmdRemove(args) {
   const name = requireArg(args, 0, 'account name');
   if (!store.accountExists(name)) throw new Error(`no such account: ${name}`);
@@ -230,6 +278,169 @@ function cmdSync() {
   out(updated ? `synced refreshed tokens into "${updated}"` : 'nothing to sync');
 }
 
+// Set the rotation order in one go: listed accounts get priority 0..k-1,
+// unlisted accounts follow after in their current order.
+function cmdOrder(args) {
+  const accounts = store.listAccounts();
+  if (args.length === 0) {
+    if (accounts.length === 0) {
+      out('no accounts yet');
+      return;
+    }
+    accounts.forEach((a, i) => out(`${i + 1}. ${a.name}${a.active ? ' (active)' : ''}`));
+    return;
+  }
+  for (const name of args) {
+    if (!store.accountExists(name)) throw new Error(`no such account: ${name}`);
+  }
+  const dupe = args.find((n, i) => args.indexOf(n) !== i);
+  if (dupe) throw new Error(`account listed twice: ${dupe}`);
+  const meta = store.loadMeta();
+  let prio = 0;
+  for (const name of args) {
+    meta.accounts[name] = { ...(meta.accounts[name] || {}), priority: prio++ };
+  }
+  for (const a of accounts) {
+    if (args.includes(a.name)) continue;
+    meta.accounts[a.name] = { ...(meta.accounts[a.name] || {}), priority: prio++ };
+  }
+  store.saveMeta(meta);
+  out('rotation order set:');
+  store.listAccounts().forEach((a, i) => out(`${i + 1}. ${a.name}`));
+}
+
+function cmdModel(args) {
+  const meta = store.loadMeta();
+  if (args[0] == null) {
+    out(`model: ${meta.model || '(codex default)'}`);
+    return;
+  }
+  if (args[0] === 'default' || args[0] === 'clear') {
+    delete meta.model;
+    store.saveMeta(meta);
+    out('model reset to codex default');
+    return;
+  }
+  meta.model = args[0];
+  store.saveMeta(meta);
+  out(`default model set to "${meta.model}" (applied to run/exec)`);
+}
+
+// Rotate-early thresholds: how full the 5h / weekly window may get before
+// the account is skipped in rotation.
+function cmdThreshold(args) {
+  const meta = store.loadMeta();
+  if (args.length === 0) {
+    out(`threshold: 5h ${meta.threshold5h}% / weekly ${meta.thresholdWeekly}%`);
+    out('usage: codexswitch threshold <5h%> [weekly%]   (one value sets both)');
+    return;
+  }
+  const parse = (s) => {
+    const n = parseInt(s, 10);
+    if (Number.isNaN(n) || n < 1 || n > 100) throw new Error(`threshold must be 1-100, got "${s}"`);
+    return n;
+  };
+  meta.threshold5h = parse(args[0]);
+  meta.thresholdWeekly = args[1] != null ? parse(args[1]) : meta.threshold5h;
+  store.saveMeta(meta);
+  out(`threshold set: 5h ${meta.threshold5h}% / weekly ${meta.thresholdWeekly}%`);
+}
+
+function cmdPatterns(args) {
+  const meta = store.loadMeta();
+  const [sub, ...rest] = args;
+  if (!sub) {
+    out('built-in: usage limit / rate limit / too many requests / quota exceeded / 429');
+    if (meta.limitPatterns.length === 0) out('custom: (none)');
+    else meta.limitPatterns.forEach((p, i) => out(`custom ${i + 1}: ${p}`));
+    return;
+  }
+  if (sub === 'add') {
+    const pattern = rest.join(' ');
+    if (!pattern) throw new Error('usage: codexswitch patterns add <regex>');
+    new RegExp(pattern, 'i'); // validate — throws on bad regex
+    meta.limitPatterns.push(pattern);
+    store.saveMeta(meta);
+    out(`added pattern: ${pattern}`);
+    return;
+  }
+  if (sub === 'remove') {
+    const key = rest.join(' ');
+    const idx = /^\d+$/.test(key) ? parseInt(key, 10) - 1 : meta.limitPatterns.indexOf(key);
+    if (idx < 0 || idx >= meta.limitPatterns.length) throw new Error(`no such pattern: ${key}`);
+    const [removed] = meta.limitPatterns.splice(idx, 1);
+    store.saveMeta(meta);
+    out(`removed pattern: ${removed}`);
+    return;
+  }
+  throw new Error('usage: codexswitch patterns [add <regex> | remove <n|regex>]');
+}
+
+function cmdExport(args) {
+  const file = requireArg(args, 0, 'output file path');
+  const accounts = {};
+  for (const a of store.listAccounts()) accounts[a.name] = store.readAccountAuth(a.name);
+  if (Object.keys(accounts).length === 0) throw new Error('no accounts to export');
+  writeJSONAtomic(path.resolve(file), { version: 1, exportedAt: new Date().toISOString(), meta: store.loadMeta(), accounts }, 0o600);
+  out(`exported ${Object.keys(accounts).length} account(s) to ${file}`);
+  out('WARNING: this file contains login tokens — treat it like a password.');
+}
+
+function cmdRestore(args) {
+  const file = requireArg(args, 0, 'backup file path');
+  const data = readJSONSafe(path.resolve(file));
+  if (!data || data.version !== 1 || !data.accounts) throw new Error('not a codexswitch backup file');
+  store.ensureDirs();
+  const meta = store.loadMeta();
+  let n = 0;
+  for (const [name, auth] of Object.entries(data.accounts)) {
+    store.writeAccountAuth(name, auth);
+    const backup = (data.meta && data.meta.accounts && data.meta.accounts[name]) || {};
+    meta.accounts[name] = { ...backup, ...(meta.accounts[name] || {}) };
+    n++;
+  }
+  if (!meta.active && data.meta && data.meta.active) meta.active = data.meta.active;
+  store.saveMeta(meta);
+  out(`restored ${n} account(s) from ${file}`);
+}
+
+function cmdNames() {
+  for (const a of store.listAccounts()) out(a.name);
+}
+
+const COMMANDS =
+  'login import add-key list use current next run exec order model remove rename ' +
+  'enable disable priority clear-limit cooldown threshold patterns export restore sync completion help';
+
+function cmdCompletion(args) {
+  const shell = args[0];
+  if (shell !== 'bash' && shell !== 'zsh') {
+    throw new Error('usage: codexswitch completion <bash|zsh>  (append the output to your shell rc file)');
+  }
+  const script = `# codexswitch completion (${shell})
+${shell === 'zsh' ? 'autoload -Uz bashcompinit && bashcompinit\n' : ''}_codexswitch() {
+  local cur="\${COMP_WORDS[COMP_CWORD]}"
+  if [ "\$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( \$(compgen -W "${COMMANDS}" -- "\$cur") )
+  else
+    COMPREPLY=( \$(compgen -W "\$(codexswitch names 2>/dev/null)" -- "\$cur") )
+  fi
+}
+complete -F _codexswitch codexswitch cxs`;
+  out(script);
+}
+
+// Final argv for "codex exec": inject --skip-git-repo-check so it works in
+// non-git folders, and the configured default model — unless the user
+// already passed their own flags.
+function buildExecArgs(rest, meta) {
+  const args = [...rest];
+  if (!args.includes('--skip-git-repo-check')) args.unshift('--skip-git-repo-check');
+  const hasModel = args.some((a) => a === '-m' || a === '--model' || a.startsWith('--model='));
+  if (meta.model && !hasModel) args.unshift('-m', meta.model);
+  return args;
+}
+
 async function cmdRun(args) {
   let name = null;
   let rest = args;
@@ -244,28 +455,43 @@ async function cmdRun(args) {
     name = meta.active && store.accountExists(meta.active) ? meta.active : picked.name;
   }
   if (rest[0] === '--') rest = rest.slice(1);
+  const meta = store.loadMeta();
+  if (rest[0] === 'exec') {
+    rest = ['exec', ...buildExecArgs(rest.slice(1), meta)];
+  } else if (meta.model && rest.length === 0) {
+    rest = ['-m', meta.model];
+  }
   out(`[codexswitch] running codex as "${name}"`);
+  const startTs = Date.now();
   const res = await runner.runCodex(name, rest);
+  runner.recordUsage(name, res.profile, startTs);
   return res.code;
 }
 
+const RESUME_PROMPT = 'Continue the previous task from exactly where it left off.';
+
 async function cmdExec(args) {
   let explicit = null;
+  let allowResume = true;
   const rest = [];
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '-a' || args[i] === '--account') {
       explicit = requireArg(args, ++i, 'account name after --account');
+    } else if (args[i] === '--no-resume') {
+      allowResume = false;
     } else {
       rest.push(args[i]);
     }
   }
   if (explicit && !store.accountExists(explicit)) throw new Error(`no such account: ${explicit}`);
+  if (rest[0] === 'resume') allowResume = false; // user drives resume themselves
 
   const meta = store.loadMeta();
   const total = store.listAccounts().length;
   if (total === 0) throw new Error('no accounts — add one with "codexswitch login"');
 
   const tried = [];
+  let useResume = false;
   for (let attempt = 0; attempt < total; attempt++) {
     let name;
     if (explicit && attempt === 0) {
@@ -276,24 +502,52 @@ async function cmdExec(args) {
       name = picked.name;
     }
     tried.push(name);
-    console.error(`[codexswitch] exec as "${name}"${attempt > 0 ? ` (attempt ${attempt + 1})` : ''}`);
-    const res = await runner.runCodex(name, ['exec', ...rest], { capture: true });
+    console.error(
+      `[codexswitch] exec as "${name}"${attempt > 0 ? ` (attempt ${attempt + 1}${useResume ? ', resuming session' : ''})` : ''}`
+    );
+    // On rotation, continue the same session with the next account instead
+    // of restarting the whole prompt — the session files are shared.
+    const codexArgs = useResume
+      ? ['exec', 'resume', '--last', ...buildExecArgs([], meta), RESUME_PROMPT]
+      : ['exec', ...buildExecArgs(rest, meta)];
+    const startTs = Date.now();
+    const res = await runner.runCodex(name, codexArgs, { capture: true });
+    runner.recordUsage(name, res.profile, startTs);
     if (res.code === 0) {
       store.clearLimited(name);
+      warnIfOverThreshold(name);
       return 0;
     }
-    if (runner.looksRateLimited(res.output)) {
+    if (runner.looksRateLimited(res.output, meta.limitPatterns)) {
       const until = Date.now() + runner.limitCooldownMs(res.output, meta.cooldownMinutes);
       store.markLimited(name, until);
-      console.error(`[codexswitch] "${name}" hit a usage/rate limit (paused until ${fmtDate(until)}) — rotating`);
+      if (allowResume && !useResume && runner.sessionTouchedSince(res.profile, startTs)) {
+        useResume = true;
+      }
+      console.error(
+        `[codexswitch] "${name}" hit a usage/rate limit (paused until ${fmtDate(until)}) — rotating${useResume ? ' and resuming the session' : ''}`
+      );
       continue;
     }
     return res.code; // real failure, don't burn other accounts on it
   }
-  console.error('[codexswitch] all accounts are rate-limited or disabled');
+  console.error('[codexswitch] all accounts are rate-limited, over threshold, or disabled');
   return 2;
 }
 
+function warnIfOverThreshold(name) {
+  const meta = store.loadMeta();
+  const account = store.listAccounts().find((a) => a.name === name);
+  if (!account) return;
+  const blocked = store.overThreshold(account, meta);
+  if (blocked) {
+    const pct = blocked === '5h' ? account.usage.p5h.pct : account.usage.weekly.pct;
+    console.error(
+      `[codexswitch] "${name}" is at ${Math.round(pct)}% of its ${blocked} limit (threshold ${blocked === '5h' ? meta.threshold5h : meta.thresholdWeekly}%) — the next exec will rotate to another account`
+    );
+  }
+}
+
 async function main(argv) {
   const [cmd, ...args] = argv;
   switch (cmd) {
@@ -333,10 +587,29 @@ async function main(argv) {
       return 0;
     case 'priority':
       return cmdPriority(args), 0;
+    case 'order':
+      return cmdOrder(args), 0;
+    case 'model':
+      return cmdModel(args), 0;
+    case 'add-key':
+    case 'apikey':
+      return cmdAddKey(args), 0;
+    case 'threshold':
+      return cmdThreshold(args), 0;
+    case 'patterns':
+      return cmdPatterns(args), 0;
+    case 'export':
+      return cmdExport(args), 0;
+    case 'restore':
+      return cmdRestore(args), 0;
+    case 'names':
+      return cmdNames(), 0;
+    case 'completion':
+      return cmdCompletion(args), 0;
     case 'clear-limit': {
       const name = requireArg(args, 0, 'account name');
-      store.clearLimited(name);
-      out(`cleared rate-limit record for "${name}"`);
+      store.clearLimited(name, { includeUsage: true });
+      out(`cleared rate-limit and usage records for "${name}"`);
       return 0;
     }
     case 'cooldown':

package/src/runner.js

@@ -65,6 +65,10 @@ function buildProfile(name) {
   const profile = path.join(p.profilesDir, name);
   ensureDir(profile);
 
+  // Sessions must exist in the real CODEX_HOME before linking, so that every
+  // profile shares them — resume-on-rotation and usage tracking depend on it.
+  ensureDir(path.join(p.codexHome, 'sessions'), 0o755);
+
   let entries = [];
   try {
     entries = fs.readdirSync(p.codexHome);
@@ -184,7 +188,7 @@ function runCodex(name, args, { capture = false } = {}) {
       collect(child.stdout, process.stdout);
       collect(child.stderr, process.stderr);
     }
-    child.on('error', (err) => resolve({ code: 1, output: out, error: err }));
+    child.on('error', (err) => resolve({ code: 1, output: out, error: err, profile }));
     child.on('close', (code) => {
       // codex may have refreshed the token while running — persist it.
       try {
@@ -192,16 +196,106 @@ function runCodex(name, args, { capture = false } = {}) {
       } catch {
         /* best effort */
       }
-      resolve({ code: code == null ? 1 : code, output: out });
+      resolve({ code: code == null ? 1 : code, output: out, profile });
     });
   });
 }
 
+// ---- usage tracking ---------------------------------------------------
+// Codex writes token_count events into session rollout files; when the
+// backend sends x-codex-* headers they include rate_limits with the 5h
+// (primary) and weekly (secondary) used_percent and reset times. Some
+// exec-mode versions report null there, so all parsing is best-effort.
+
+function listRolloutsSince(sessionsDir, sinceMs) {
+  const found = [];
+  const walk = (dir, depth) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory() && depth < 4) walk(full, depth + 1);
+      else if (e.isFile() && /^rollout-.*\.jsonl$/.test(e.name)) {
+        try {
+          const st = fs.statSync(full);
+          if (st.mtimeMs >= sinceMs) found.push({ full, mtime: st.mtimeMs });
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  };
+  walk(sessionsDir, 0);
+  return found.sort((a, b) => a.mtime - b.mtime);
+}
+
+function windowUsage(win, eventTs) {
+  if (!win || typeof win.used_percent !== 'number') return null;
+  const usage = { pct: win.used_percent, resetAt: null, windowMinutes: win.window_minutes || null };
+  if (typeof win.resets_in_seconds === 'number') usage.resetAt = eventTs + win.resets_in_seconds * 1000;
+  else if (typeof win.resets_at === 'number') usage.resetAt = win.resets_at * 1000;
+  return usage;
+}
+
+// Scan rollouts touched since `sinceMs` for the newest non-null rate_limits
+// snapshot. Returns { p5h, weekly, at } or null when codex reported nothing.
+function scanUsage(sessionsDir, sinceMs) {
+  let result = null;
+  for (const f of listRolloutsSince(sessionsDir, sinceMs)) {
+    let text;
+    try {
+      text = fs.readFileSync(f.full, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const line of text.split('\n')) {
+      if (!line.includes('rate_limits')) continue;
+      try {
+        const obj = JSON.parse(line);
+        const rl = (obj.payload && obj.payload.rate_limits) || obj.rate_limits;
+        if (!rl) continue;
+        const eventTs = obj.timestamp ? Date.parse(obj.timestamp) || Date.now() : Date.now();
+        const p5h = windowUsage(rl.primary, eventTs);
+        const weekly = windowUsage(rl.secondary, eventTs);
+        if (p5h || weekly) result = { p5h, weekly, at: eventTs };
+      } catch {
+        /* malformed line */
+      }
+    }
+  }
+  return result;
+}
+
+// After running codex for an account, persist the freshest usage snapshot.
+function recordUsage(name, profile, sinceMs) {
+  const usage = scanUsage(path.join(profile, 'sessions'), sinceMs);
+  if (usage) store.saveUsage(name, usage);
+  return usage;
+}
+
+// Was a session rollout created/updated during this run? (drives whether a
+// rotated retry can "exec resume" instead of restarting from scratch)
+function sessionTouchedSince(profile, sinceMs) {
+  return listRolloutsSince(path.join(profile, 'sessions'), sinceMs).length > 0;
+}
+
 const LIMIT_RE =
-  /usage limit|rate limit|too many requests|quota (?:exceeded|reached)|\b429\b|hit your (?:usage|weekly|5h) limit/i;
+  /usage[ _]limit|rate[ _]limit|too many requests|quota (?:exceeded|reached)|\b429\b|hit your (?:usage|weekly|5h) limit/i;
 
-function looksRateLimited(output) {
-  return LIMIT_RE.test(output || '');
+function looksRateLimited(output, extraPatterns = []) {
+  if (LIMIT_RE.test(output || '')) return true;
+  for (const p of extraPatterns) {
+    try {
+      if (new RegExp(p, 'i').test(output || '')) return true;
+    } catch {
+      /* invalid user pattern — ignore */
+    }
+  }
+  return false;
 }
 
 // Try to extract "try again in 2 hours 30 minutes" style hints; fall back
@@ -220,4 +314,7 @@ module.exports = {
   runCodex,
   looksRateLimited,
   limitCooldownMs,
+  scanUsage,
+  recordUsage,
+  sessionTouchedSince,
 };

package/src/store.js

@@ -30,6 +30,9 @@ function loadMeta() {
   if (!meta.accounts) meta.accounts = {};
   if (!('active' in meta)) meta.active = null;
   if (!meta.cooldownMinutes) meta.cooldownMinutes = 60;
+  if (!meta.threshold5h) meta.threshold5h = 95;
+  if (!meta.thresholdWeekly) meta.thresholdWeekly = 95;
+  if (!Array.isArray(meta.limitPatterns)) meta.limitPatterns = [];
   return meta;
 }
 
@@ -83,6 +86,7 @@ function listAccounts() {
         priority: m.priority ?? 0,
         disabled: !!m.disabled,
         limitedUntil: m.limitedUntil || null,
+        usage: m.usage || null,
         active: meta.active === name,
       };
     })
@@ -122,24 +126,78 @@ function markLimited(name, untilTs) {
   saveMeta(meta);
 }
 
-function clearLimited(name) {
+function clearLimited(name, { includeUsage = false } = {}) {
   const meta = loadMeta();
-  if (meta.accounts[name] && meta.accounts[name].limitedUntil) {
-    delete meta.accounts[name].limitedUntil;
+  const m = meta.accounts[name];
+  if (m && (m.limitedUntil || (includeUsage && m.usage))) {
+    delete m.limitedUntil;
+    if (includeUsage) delete m.usage;
     saveMeta(meta);
   }
 }
 
+function saveUsage(name, usage) {
+  const meta = loadMeta();
+  if (!meta.accounts[name]) meta.accounts[name] = {};
+  meta.accounts[name].usage = usage;
+  saveMeta(meta);
+}
+
+// An account is "over threshold" when its last recorded 5h/weekly usage
+// exceeds the configured percentage and the window has not reset yet.
+// Returns the blocking window ('5h' | 'weekly') or null.
+function overThreshold(account, meta, now = Date.now()) {
+  const u = account.usage;
+  if (!u) return null;
+  const checks = [
+    ['5h', u.p5h, meta.threshold5h],
+    ['weekly', u.weekly, meta.thresholdWeekly],
+  ];
+  for (const [label, win, threshold] of checks) {
+    if (!win || typeof win.pct !== 'number') continue;
+    if (win.pct < threshold) continue;
+    // Trust the snapshot only while its window can still be in effect.
+    if (win.resetAt) {
+      if (win.resetAt > now) return label;
+    } else if (win.windowMinutes && u.at + win.windowMinutes * 60000 > now) {
+      return label;
+    }
+  }
+  return null;
+}
+
+function isUsable(account, meta, now = Date.now()) {
+  if (account.disabled) return false;
+  if (account.limitedUntil && account.limitedUntil > now) return false;
+  if (overThreshold(account, meta, now)) return false;
+  return true;
+}
+
 // Pick the best usable account: enabled, not currently rate-limited,
-// lowest priority number first. `exclude` skips accounts already tried.
+// lowest priority number first (the order set by "order"/"priority").
+// The active account only wins ties within the same priority, so an
+// explicit order is always respected. `exclude` skips accounts already tried.
 function pickAccount(exclude = []) {
   const now = Date.now();
-  const usable = listAccounts().filter(
-    (a) => !a.disabled && !exclude.includes(a.name) && (!a.limitedUntil || a.limitedUntil <= now)
-  );
+  const meta = loadMeta();
+  const usable = listAccounts().filter((a) => !exclude.includes(a.name) && isUsable(a, meta, now));
   if (usable.length === 0) return null;
-  const active = usable.find((a) => a.active);
-  return active || usable[0];
+  const group = usable.filter((a) => a.priority === usable[0].priority);
+  return group.find((a) => a.active) || group[0];
+}
+
+// Next usable account after the active one, following priority order and
+// wrapping around — so repeated "next" cycles through the configured order.
+function nextAccount() {
+  const all = listAccounts();
+  const now = Date.now();
+  const meta = loadMeta();
+  const start = all.findIndex((a) => a.active);
+  for (let i = 1; i <= all.length; i++) {
+    const cand = all[(start + i) % all.length];
+    if (!cand.active && isUsable(cand, meta, now)) return cand;
+  }
+  return null;
 }
 
 module.exports = {
@@ -155,7 +213,11 @@ module.exports = {
   syncBackFrom,
   markLimited,
   clearLimited,
+  saveUsage,
+  overThreshold,
+  isUsable,
   pickAccount,
+  nextAccount,
   ensureDirs() {
     const p = paths();
     ensureDir(p.home);