@oddessentials/agent-guild 0.2.0 → 0.4.0

package/src/manager/self-update.mjs

@@ -0,0 +1,205 @@
+// The manager's own version against the npm registry, and the npm session
+// that upgrades it. The running process keeps its code after an upgrade:
+// the new version is used once the manager is restarted.
+
+import fs from 'node:fs';
+import { EventEmitter } from 'node:events';
+import { compareVersions, fetchManifest } from './versions.mjs';
+import { formatCommand } from './install-channels.mjs';
+import { buildSpawnSpec } from './command-resolver.mjs';
+
+const CHECK_TTL_MS = 60 * 60 * 1000;
+const FAILED_CHECK_TTL_MS = 5 * 60 * 1000;
+
+/** Shown as the provider of the upgrade session. */
+export const SELF_PROVIDER = Object.freeze({
+  id: 'agent-guild',
+  vendor: 'Agent Guild',
+  tool: 'Agent Guild',
+  color: '#5B5BD6',
+  monogram: 'AG',
+  iconUrl: null,
+  modelPattern: null,
+  env: {},
+});
+
+/** True for a build that is not a published release, such as a git checkout. */
+export function isDevelopmentBuild(version) {
+  return !version || /^0\.0\.0(?:-|$)/.test(String(version));
+}
+
+function refusal(status, code, message) {
+  return Object.assign(new Error(message), { status, code });
+}
+
+export class SelfUpdate extends EventEmitter {
+  /**
+   * @param {object} opts
+   * @param {string} opts.pkg            the manager's npm package name
+   * @param {string} opts.version        the running version
+   * @param {string|null} [opts.packageFile]  the package.json the manager runs from; read again after an install
+   * @param {import('./providers.mjs').ProviderRegistry} opts.registry  for the registry URL, npm, and fetch
+   */
+  constructor({ pkg, version, packageFile = null, registry }) {
+    super();
+    this.pkg = pkg;
+    this.version = version;
+    this.packageFile = packageFile;
+    this.registry = registry;
+    this.latest = null;
+    this.error = null;
+    this.checkedAt = 0;
+    this.lastInstall = null;
+    /** True from the start of an upgrade session until its npm process has exited. */
+    this.installing = false;
+    /** The on-disk version a failed upgrade left behind, not to be trusted until an upgrade completes. */
+    this.suspectVersion = null;
+    this._refreshing = null;
+  }
+
+  /** Ask the registry for the latest release, hourly unless `force`. Emits "updated" on a change. */
+  refresh({ force = false } = {}) {
+    const run = () => this._refresh(force);
+    const pending = this._refreshing ? this._refreshing.then(run, run) : run();
+    this._refreshing = pending;
+    pending.finally(() => { if (this._refreshing === pending) this._refreshing = null; }).catch(() => {});
+    return pending;
+  }
+
+  async _refresh(force) {
+    if (!this.registry.checkUpdates || isDevelopmentBuild(this.version)) return;
+    const now = Date.now();
+    const ttl = this.error ? FAILED_CHECK_TTL_MS : CHECK_TTL_MS;
+    if (!force && now - this.checkedAt < ttl) return;
+    this.checkedAt = now;
+    const registryUrl = await this.registry.npmRegistryUrl();
+    const { manifest, error } = await fetchManifest(this.pkg, 'latest', { registryUrl, fetchImpl: this.registry.fetchImpl });
+    // A failed check keeps the release already known; it is still published.
+    const latest = manifest?.version ?? this.latest;
+    const changed = latest !== this.latest || error !== this.error;
+    this.latest = latest;
+    this.error = error;
+    if (changed) this.emit('updated');
+  }
+
+  /** Forget an upgrade's outcome once a newer release or a different install supersedes it. */
+  _pruneLastInstall(installed) {
+    const last = this.lastInstall;
+    if (last && (last.version !== this.latest || last.installedVersion !== installed)) this.lastInstall = null;
+  }
+
+  /** The version of the package files on disk, or null when unreadable (for example mid-install). */
+  installedVersion() {
+    if (!this.packageFile) return null;
+    try {
+      const version = JSON.parse(fs.readFileSync(this.packageFile, 'utf8')).version;
+      return typeof version === 'string' ? version : null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * True while the files on disk are what an upgrade that did not finish
+   * left behind: npm may have replaced package.json before it was stopped.
+   * Kept apart from `lastInstall`, which a newer release supersedes; the
+   * files stay suspect until an upgrade completes or they change again.
+   */
+  _diskSuspect(installed) {
+    return this.suspectVersion !== null && installed === this.suspectVersion;
+  }
+
+  /** A version installed on disk that the running manager does not use yet, or null. */
+  pendingVersion(installed = this.installedVersion()) {
+    if (this._diskSuspect(installed)) return null;
+    return installed && installed !== this.version && compareVersions(installed, this.version) > 0 ? installed : null;
+  }
+
+  /** True when the latest release is newer than the running manager and not yet, or not reliably, on disk. */
+  available(installed = this.installedVersion()) {
+    if (!this.latest || compareVersions(this.latest, this.version) <= 0) return false;
+    return this._diskSuspect(installed) || compareVersions(this.latest, installed || this.version) > 0;
+  }
+
+  args() {
+    return this.registry.npmArgs({ args: ['install', '-g'], package: this.pkg }, this.latest);
+  }
+
+  /** The npm command that performs the upgrade, or null without npm on PATH or a known release. */
+  command() {
+    const npm = this.registry.resolveNpm();
+    return npm && this.latest ? formatCommand(npm, this.args()) : null;
+  }
+
+  /** Public description, sent in `/info`, `hello` and `manager.upgrade`. */
+  describe() {
+    // While npm runs, the files on disk are in flux: package.json may already
+    // be new while dependencies are still being written, so nothing is
+    // offered or announced until the process has exited.
+    if (this.installing) {
+      return {
+        version: this.version, latestVersion: this.latest, available: false, command: null, guidance: null,
+        pendingVersion: null, installing: true, lastInstall: null,
+      };
+    }
+    const installed = this.installedVersion();
+    this._pruneLastInstall(installed);
+    const available = this.available(installed);
+    const command = available ? this.command() : null;
+    return {
+      version: this.version,
+      latestVersion: this.latest,
+      available,
+      command,
+      guidance: available && !command ? `npm was not found on PATH. Install Node.js from https://nodejs.org, then run: npm install -g ${this.pkg}@${this.latest}` : null,
+      pendingVersion: this.pendingVersion(installed),
+      installing: false,
+      lastInstall: this.lastInstall,
+    };
+  }
+
+  /** Spawn spec for the upgrade session and the version it installs, or throws with a user-facing message. */
+  async spec() {
+    if (this.installing) throw refusal(409, 'upgrade_in_progress', 'Agent Guild is already being upgraded');
+    if (isDevelopmentBuild(this.version)) {
+      throw refusal(400, 'not_updatable', `This is a development build of Agent Guild (${this.version}); it is not upgraded from the registry.`);
+    }
+    if (!this.registry.checkUpdates) {
+      throw refusal(400, 'not_updatable', 'Version checks are off (AGENT_GUILD_NO_UPDATE_CHECK), so Agent Guild cannot upgrade itself.');
+    }
+    await this.refresh();
+    const installed = this.installedVersion();
+    this._pruneLastInstall(installed);
+    if (!this.available(installed)) {
+      throw refusal(400, 'not_updatable', this.latest
+        ? `Agent Guild ${this.latest} is the latest release${this.pendingVersion(installed) ? ' and is installed; restart the manager to use it' : ''}.`
+        : `Could not read the latest Agent Guild release${this.error ? `: ${this.error}` : ''}. Nothing was changed.`);
+    }
+    const npm = this.registry.resolveNpm();
+    if (!npm) {
+      throw refusal(409, 'npm_unavailable', 'npm was not found on PATH. Install Node.js from https://nodejs.org and restart the session manager.');
+    }
+    // buildSpawnSpec wraps npm.cmd in cmd.exe on Windows, which a PTY needs.
+    return { spec: buildSpawnSpec(npm, this.args(), this.registry.env, this.registry.platform), version: this.latest };
+  }
+
+  /** An upgrade session started; hold the lock until finishInstall. Emits "updated". */
+  beginInstall() {
+    this.installing = true;
+    this.emit('updated');
+  }
+
+  /** Record how the upgrade session ended, once its process has exited. The files on disk say whether the running copy was replaced. */
+  finishInstall({ exitCode = null, version = this.latest } = {}) {
+    this.installing = false;
+    const installed = this.installedVersion();
+    let outcome;
+    if (exitCode !== 0) outcome = 'failed';
+    else if (installed && version && compareVersions(installed, version) >= 0) outcome = 'installed';
+    else outcome = 'unchanged';
+    if (outcome === 'failed') this.suspectVersion = installed;
+    else if (outcome === 'installed') this.suspectVersion = null;
+    this.lastInstall = { outcome, exitCode, version, installedVersion: installed, at: Date.now() };
+    this.emit('updated');
+  }
+}

package/src/manager/server.mjs

@@ -101,14 +101,17 @@ export function createManagerServer({
   registry,
   usage,
   modelStats,
+  news = null,
   token,
   host = '127.0.0.1',
   port = 0,
   webDir,
   version = '0.0.0',
+  selfUpdate = null,
   extraOrigins = [],
   onShutdownRequest = () => {},
 }) {
+  const upgradeInfo = () => (selfUpdate ? selfUpdate.describe() : null);
   const startedAt = new Date().toISOString();
   const vendor = vendorFiles();
   let boundPort = port;
@@ -198,6 +201,7 @@ export function createManagerServer({
     requireAuth(req, url);
 
     if (route === '/info' && method === 'GET') {
+      selfUpdate?.refresh().catch(() => {});
       return sendJson(res, 200, {
         name: 'agent-guild',
         version,
@@ -205,8 +209,13 @@ export function createManagerServer({
         platform: process.platform,
         startedAt,
         warnings: registry.warnings,
+        upgrade: upgradeInfo(),
       });
     }
+    if (route === '/upgrade' && method === 'POST') {
+      const session = await manager.upgrade();
+      return sendJson(res, 201, { session: session.toJSON() });
+    }
     if (route === '/providers' && method === 'GET') {
       registry.refreshVersions().catch(() => {});
       return sendJson(res, 200, { providers: registry.list() });
@@ -222,6 +231,9 @@ export function createManagerServer({
     if (route === '/model-stats' && method === 'GET') {
       return sendJson(res, 200, await modelStats.snapshot(manager.list()));
     }
+    if (route === '/news' && method === 'GET' && news) {
+      return sendJson(res, 200, news.snapshot());
+    }
     const installMatch = route.match(/^\/providers\/([a-z0-9][a-z0-9_-]{0,31})\/install$/);
     if (installMatch && method === 'POST') {
       const body = await readJsonBody(req);
@@ -333,10 +345,12 @@ export function createManagerServer({
   }
   manager.on('event', broadcast);
   registry.on('updated', () => broadcast({ type: 'providers.updated', providers: registry.list() }));
+  selfUpdate?.on('updated', () => broadcast({ type: 'manager.upgrade', upgrade: upgradeInfo() }));
+  news?.on('updated', () => broadcast({ type: 'news.updated' }));
 
   function handleEvents(ws) {
     eventClients.add(ws);
-    safeSend(ws, { type: 'hello', version, sessions: manager.list() });
+    safeSend(ws, { type: 'hello', version, upgrade: upgradeInfo(), sessions: manager.list() });
     ws.on('close', () => eventClients.delete(ws));
     ws.on('message', () => { /* events socket is server -> client only */ });
   }

package/src/manager/session-manager.mjs

@@ -6,11 +6,14 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
-import { Session, newId, clampDimension } from './session.mjs';
+import { fileURLToPath } from 'node:url';
+import { Session, newId, clampDimension, cleanName } from './session.mjs';
 import { prependPath } from './report-shims.mjs';
 import { CHANNEL_LABELS } from './install-channels.mjs';
+import { SELF_PROVIDER } from './self-update.mjs';
 
 export const MAX_SESSIONS = 32;
+const examplesDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../examples');
 
 function httpError(status, message, code) {
   return Object.assign(new Error(message), { status, code });
@@ -46,14 +49,16 @@ export class SessionManager extends EventEmitter {
    * @param {() => string} opts.getApiUrl  base URL handed to tools for reporting
    * @param {object} [opts.sessionDefaults] passed through to Session
    * @param {string|null} [opts.shimDir]  folder with the agent-guild-report launchers, put first on PATH
+   * @param {import('./self-update.mjs').SelfUpdate|null} [opts.selfUpdate]  the manager's own upgrade
    */
-  constructor({ registry, baseEnv, getApiUrl, sessionDefaults = {}, shimDir = null }) {
+  constructor({ registry, baseEnv, getApiUrl, sessionDefaults = {}, shimDir = null, selfUpdate = null }) {
     super();
     this.registry = registry;
     this.baseEnv = baseEnv;
     this.getApiUrl = getApiUrl;
     this.sessionDefaults = sessionDefaults;
     this.shimDir = shimDir;
+    this.selfUpdate = selfUpdate;
     this.sessions = new Map();
     /** Removed sessions whose process has not exited yet. */
     this.exiting = new Set();
@@ -83,21 +88,44 @@ export class SessionManager extends EventEmitter {
     return dir;
   }
 
-  create({ providerId, cwd, cols, rows, name, args, resume } = {}) {
+  create({ providerId, cwd, cols, rows, name, args, resume, account } = {}) {
     const provider = this.registry.get(String(providerId || ''));
     if (!provider) throw httpError(404, `unknown provider "${providerId}"`, 'unknown_provider');
     if (args !== undefined && (!Array.isArray(args) || args.some((a) => typeof a !== 'string'))) {
       throw httpError(400, 'args must be an array of strings', 'bad_args');
     }
+    if (account !== undefined && account !== null && typeof account !== 'string') throw httpError(400, 'account must be a string', 'bad_account');
     const resumeId = cleanResumeId(resume);
     const workDir = this.resolveCwd(cwd);
+    const signIn = this.registry.account(provider, account);
     const spawnSpec = this.registry.spawnSpec(provider, args || [], resumeId);
-    const session = this._spawn({ provider, spawnSpec, cwd: workDir, cols, rows, name, resume: resumeId });
+    this.prepareAccount(provider, signIn);
+    const sessionName = cleanName(name) || (provider.accounts.length > 1 ? `${provider.tool} · ${signIn.label}` : null);
+    const session = this._spawn({ provider, spawnSpec, cwd: workDir, cols, rows, name: sessionName, resume: resumeId, account: signIn });
     const model = modelFromArgs([...provider.args, ...(args || [])]);
     if (model) session.setModel({ name: model }, 'args');
     return session;
   }
 
+  prepareAccount(provider, account) {
+    if (!account.dir) return;
+    try {
+      fs.mkdirSync(account.dir, { recursive: true, mode: 0o700 });
+      if (!provider.hooks) return;
+      const target = path.join(account.dir, ...provider.hooks.path.split('/'));
+      const example = path.join(examplesDir, provider.hooks.example);
+      if (fs.existsSync(target)) return;
+      if (!fs.existsSync(example)) {
+        console.warn(`[accounts] no hooks example ${example} for ${provider.tool}; ${target} was not written`);
+        return;
+      }
+      fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+      fs.copyFileSync(example, target, fs.constants.COPYFILE_EXCL);
+    } catch (err) {
+      throw httpError(500, `could not prepare the ${account.label} account folder ${account.dir}: ${err.message}`, 'account_unavailable');
+    }
+  }
+
   /**
    * Refuses while sessions of that provider are running unless `force` is
    * set, because replacing a tool under a running process can break it.
@@ -140,6 +168,29 @@ export class SessionManager extends EventEmitter {
     return n;
   }
 
+  /**
+   * Upgrade the manager itself: a visible session running npm. Sessions
+   * keep running; the new version is used once the manager is restarted.
+   */
+  async upgrade() {
+    if (!this.selfUpdate) throw httpError(400, 'this manager cannot upgrade itself', 'not_updatable');
+    if (this.closing) throw httpError(503, 'the session manager is stopping', 'manager_stopping');
+    const inProgress = () => httpError(409, 'Agent Guild is already being upgraded', 'upgrade_in_progress');
+    if (this.selfUpdate.installing) throw inProgress();
+    const { spec, version } = await this.selfUpdate.spec();
+    if (this.selfUpdate.installing) throw inProgress();
+    const session = this._spawn({
+      provider: SELF_PROVIDER, description: SELF_PROVIDER, spawnSpec: spec,
+      cwd: os.homedir(), name: `Upgrade Agent Guild to ${version}`, task: 'upgrade',
+    });
+    // The lock is held until the npm process has exited, not until the
+    // session is removed: a removed session's process may still be writing
+    // the package, and two installers must not touch it at once.
+    this.selfUpdate.beginInstall();
+    session.exited.then(() => this.selfUpdate.finishInstall({ exitCode: session.exitCode, version }));
+    return session;
+  }
+
   runningFor(providerId) {
     let n = 0;
     for (const s of this.sessions.values()) if (s.status === 'running' && s.task === null && s.provider.id === providerId) n++;
@@ -153,18 +204,17 @@ export class SessionManager extends EventEmitter {
     return n;
   }
 
-  _spawn({ provider, spawnSpec, cwd, cols, rows, name, resume = null, task = null, installKind = null }) {
+  _spawn({ provider, description = this.registry.describe(provider), spawnSpec, cwd, cols, rows, name, resume = null, task = null, installKind = null, account = null }) {
     if (this.closing) throw httpError(503, 'the session manager is stopping', 'manager_stopping');
     if (this.sessions.size >= MAX_SESSIONS) {
       throw httpError(429, `session limit reached (${MAX_SESSIONS}); remove finished sessions first`, 'too_many_sessions');
     }
-    const description = this.registry.describe(provider);
     const id = newId();
     const reportToken = crypto.randomBytes(16).toString('hex');
 
     // The tool's hooks run `agent-guild-report` by name, so the launchers
     // go first on PATH, after any provider PATH override.
-    const env = prependPath(mergeEnv([this.baseEnv, provider.env, {
+    const env = prependPath(mergeEnv([this.baseEnv, provider.env, account?.env, {
       TERM: 'xterm-256color',
       COLORTERM: 'truecolor',
       AGENT_GUILD_SESSION_ID: id,
@@ -194,6 +244,7 @@ export class SessionManager extends EventEmitter {
         reportToken,
         resume,
         task,
+        account: account ? { id: account.id, label: account.label } : null,
       });
     } catch (err) {
       throw httpError(500, `could not start ${provider.tool}: ${err.message}`, 'spawn_failed');

package/src/manager/session.mjs

@@ -54,7 +54,8 @@ export class Session extends EventEmitter {
    * @param {number} opts.rows
    * @param {string} [opts.name]
    * @param {string|null} [opts.resume]  id of the tool's own session being resumed
-   * @param {string|null} [opts.task]    "install" for a package install, else null
+   * @param {string|null} [opts.task]    "install" for a package install, "upgrade" for the manager's own, else null
+   * @param {{id: string, label: string}|null} [opts.account]  the tool sign-in the session runs under
    * @param {string} opts.reportToken
    * @param {number} [opts.scrollback]
    * @param {number} [opts.activityIdleMs]
@@ -68,6 +69,7 @@ export class Session extends EventEmitter {
     this.name = cleanName(opts.name) || opts.provider.tool;
     this.resume = opts.resume ?? null;
     this.task = opts.task ?? null;
+    this.account = opts.account ?? null;
     this.cwd = opts.cwd;
     this.cols = opts.cols;
     this.rows = opts.rows;
@@ -505,6 +507,7 @@ export class Session extends EventEmitter {
       cwd: this.cwd,
       resume: this.resume,
       task: this.task,
+      account: this.account,
       pid: this.pid,
       status: this.status,
       exitCode: this.exitCode,

package/src/manager/usage.mjs

@@ -19,6 +19,10 @@ const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
 
 export class UsageError extends Error {}
 
+function notSignedIn(message) {
+  return Object.assign(new UsageError(message), { notSignedIn: true });
+}
+
 function shortPath(file) {
   const home = os.homedir();
   return file.startsWith(home) ? `~${file.slice(home.length)}` : file;
@@ -112,7 +116,7 @@ export async function readClaudeCredentials({
     try {
       raw = await fs.promises.readFile(file, 'utf8');
     } catch {
-      throw new UsageError(`Claude Code is not signed in on this machine (no ${keychain ? 'keychain item or ' : ''}${shortPath(file)})`);
+      throw notSignedIn(`Claude Code is not signed in on this machine (no ${keychain ? 'keychain item or ' : ''}${shortPath(file)})`);
     }
   }
   let creds;
@@ -195,7 +199,7 @@ export async function readCodexCredentials({ file = codexAuthFile() } = {}) {
   try {
     raw = await fs.promises.readFile(file, 'utf8');
   } catch {
-    throw new UsageError(`Codex CLI is not signed in on this machine (no ${shortPath(file)})`);
+    throw notSignedIn(`Codex CLI is not signed in on this machine (no ${shortPath(file)})`);
   }
   let auth;
   try { auth = JSON.parse(raw); } catch { throw new UsageError('Codex CLI credentials could not be parsed'); }
@@ -260,11 +264,37 @@ export function geminiCredentialsFile(env = process.env) {
   return path.join(env.GEMINI_CLI_HOME || os.homedir(), '.gemini', 'oauth_creds.json');
 }
 
+export function geminiKeychainFile(env = process.env) {
+  return path.join(env.GEMINI_CLI_HOME || os.homedir(), '.gemini', 'gemini-credentials.json');
+}
+
+export function geminiFileKey({ hostname = os.hostname(), username = os.userInfo().username } = {}) {
+  return crypto.scryptSync(GEMINI_KEYCHAIN_SERVICE, `${hostname}-${username}-gemini-cli`, 32);
+}
+
 /**
- * Gemini CLI keeps its OAuth token in the OS keychain (service
- * "gemini-cli-oauth", account "main-account") and, before it did, in
- * oauth_creds.json. Its encrypted-file fallback cannot be read from here.
+ * The item Gemini CLI keeps in its own encrypted file when it does not use
+ * the OS keychain: AES-256-GCM as iv:tag:ciphertext in hex, over a JSON
+ * map of service to account to secret.
  */
+export async function readGeminiFileKeychain(file, { key = geminiFileKey() } = {}) {
+  let raw;
+  try {
+    raw = await fs.promises.readFile(file, 'utf8');
+  } catch {
+    return null;
+  }
+  try {
+    const [iv, tag, encrypted] = raw.trim().split(':').map((part) => Buffer.from(part, 'hex'));
+    const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv, { authTagLength: 16 });
+    decipher.setAuthTag(tag);
+    const json = Buffer.concat([decipher.update(encrypted), decipher.final()]).toString('utf8');
+    return JSON.parse(json)?.[GEMINI_KEYCHAIN_SERVICE]?.[GEMINI_KEYCHAIN_ACCOUNT] ?? null;
+  } catch {
+    throw new UsageError(`Gemini CLI credentials file ${shortPath(file)} could not be decrypted`);
+  }
+}
+
 export function geminiKeychainLookup(platform) {
   if (platform === 'darwin') return { file: 'security', args: ['find-generic-password', '-s', GEMINI_KEYCHAIN_SERVICE, '-a', GEMINI_KEYCHAIN_ACCOUNT, '-w'] };
   // keytar stores libsecret items with the attributes "service" and "account".
@@ -272,18 +302,54 @@ export function geminiKeychainLookup(platform) {
   return null;
 }
 
-function readGeminiKeychainItem(platform) {
+/**
+ * What the OS keychain holds for Gemini CLI: the item, or that it is
+ * absent, that there is no keychain to ask (so the tool keeps its own
+ * encrypted file instead), or that it is one this manager cannot read.
+ */
+export async function readGeminiKeychainItem(platform) {
   const spec = geminiKeychainLookup(platform);
-  if (!spec) return Promise.resolve(null);
-  return runSpec(spec, { timeoutMs: 30000 }).then((r) => r.stdout, () => null);
+  if (!spec) return { status: platform === 'win32' ? 'unreadable' : 'unavailable' };
+  try {
+    const { stdout } = await runSpec(spec, { timeoutMs: 30000 });
+    return stdout.trim() ? { status: 'found', item: stdout } : { status: 'absent' };
+  } catch (err) {
+    // security exits 44 for a missing item; secret-tool exits 1 for one and
+    // says why on stderr when it has no Secret Service at all.
+    if (platform === 'darwin' && err.code === 44) return { status: 'absent' };
+    if (platform === 'linux' && err.code === 1 && !String(err.stderr || '').trim()) return { status: 'absent' };
+    return { status: 'unavailable' };
+  }
 }
 
+/** Gemini CLI's own storage choice, read from the environment the tool runs with. */
+export function geminiStorageMode(env = process.env) {
+  return { encrypted: env.GEMINI_FORCE_ENCRYPTED_FILE_STORAGE === 'true', fileStorage: env.GEMINI_FORCE_FILE_STORAGE === 'true' };
+}
+
+/**
+ * Reads the sign-in from where Gemini CLI keeps it: oauth_creds.json, or
+ * with GEMINI_FORCE_ENCRYPTED_FILE_STORAGE the OS keychain item, or its
+ * encrypted file when GEMINI_FORCE_FILE_STORAGE is set or there is no
+ * keychain. An absent item falls back to oauth_creds.json, as the tool
+ * itself migrates it from there.
+ */
 export async function readGeminiCredentials({
   file = geminiCredentialsFile(),
+  keychainFile = geminiKeychainFile(),
   platform = process.platform,
+  encrypted = false,
+  fileStorage = false,
   readKeychain = readGeminiKeychainItem,
+  readFileKeychain = readGeminiFileKeychain,
 } = {}) {
-  const raw = await readKeychain(platform);
+  let raw = null;
+  if (encrypted) {
+    const keychain = fileStorage ? { status: 'unavailable' } : await readKeychain(platform);
+    if (keychain.status === 'found') raw = keychain.item;
+    else if (keychain.status === 'unavailable') raw = await readFileKeychain(keychainFile);
+    else if (keychain.status === 'unreadable') throw new UsageError('Gemini CLI keeps its sign-in in the Windows Credential Manager, which cannot be read from here');
+  }
   if (raw && raw.trim()) {
     let item;
     try { item = JSON.parse(raw); } catch { throw new UsageError('Gemini CLI credentials could not be parsed'); }
@@ -295,7 +361,7 @@ export async function readGeminiCredentials({
   try {
     legacy = JSON.parse(await fs.promises.readFile(file, 'utf8'));
   } catch {
-    throw new UsageError(`Gemini CLI is not signed in on this machine (no "${GEMINI_KEYCHAIN_SERVICE}" keychain item or ${shortPath(file)})`);
+    throw notSignedIn(`Gemini CLI is not signed in on this machine (no "${GEMINI_KEYCHAIN_SERVICE}" keychain item or ${shortPath(file)})`);
   }
   if (typeof legacy?.access_token !== 'string' || !legacy.access_token) throw new UsageError('Gemini CLI credentials could not be parsed');
   const client = typeof legacy.client_id === 'string' && typeof legacy.client_secret === 'string'
@@ -471,28 +537,35 @@ export class UsageMonitor {
     this.gemini = new Map();
   }
 
-  /** Snapshots for every provider that has a usage source. */
+  /** Snapshots for every account of every provider that has a usage source. */
   all() {
-    return Promise.all(this.registry.providers.filter((p) => p.usage).map((p) => this.snapshot(p)));
+    const jobs = [];
+    for (const provider of this.registry.providers) {
+      if (!provider.usage) continue;
+      for (const account of this.registry.accountsFor(provider)) jobs.push(this.snapshot(provider, account));
+    }
+    return Promise.all(jobs);
   }
 
-  snapshot(provider) {
-    const entry = this.cache.get(provider.id);
+  snapshot(provider, account = this.registry.account(provider)) {
+    const key = `${provider.id}\0${account.id}`;
+    const entry = this.cache.get(key);
     const now = Date.now();
     if (entry?.inflight) return entry.inflight;
     if (entry && now - entry.at < entry.ttl) return Promise.resolve(entry.snapshot);
-    const inflight = this._fetch(provider).then((snapshot) => {
+    const inflight = this._fetch(provider, account, key).then((snapshot) => {
       const ttl = snapshot.rateLimited ? RATE_LIMITED_TTL_MS : this.ttlMs;
-      this.cache.set(provider.id, { snapshot, at: Date.now(), ttl });
+      this.cache.set(key, { snapshot, at: Date.now(), ttl });
       return snapshot;
     });
-    this.cache.set(provider.id, { ...entry, inflight });
+    this.cache.set(key, { ...entry, inflight });
     return inflight;
   }
 
-  async _fetch(provider) {
-    const base = { providerId: provider.id, plan: null, windows: [], credits: null, fetchedAt: new Date().toISOString(), error: null };
-    const env = { ...this.env, ...provider.env };
+  async _fetch(provider, account, key) {
+    const base = { providerId: provider.id, accountId: account.id, plan: null, windows: [], credits: null, signedIn: null, fetchedAt: new Date().toISOString(), error: null };
+    const env = { ...this.env, ...provider.env, ...account.env };
+    let signedIn = null;
     try {
       let result;
       if (provider.usage === 'claude') {
@@ -501,16 +574,24 @@ export class UsageMonitor {
           keychain: this.platform === 'darwin',
           service: claudeKeychainService(env),
         });
+        signedIn = true;
         result = await fetchClaudeUsage({ ...creds, version: this.registry.versions.get(provider.id)?.installed, fetchImpl: this.fetchImpl });
       } else if (provider.usage === 'codex') {
         const creds = await this.readers.codex({ file: codexAuthFile(env) });
+        signedIn = true;
         result = await fetchCodexUsage({ ...creds, fetchImpl: this.fetchImpl });
       } else if (provider.usage === 'gemini') {
-        const creds = await this.readers.gemini({ file: geminiCredentialsFile(env), platform: this.platform });
+        const creds = await this.readers.gemini({
+          file: geminiCredentialsFile(env),
+          keychainFile: geminiKeychainFile(env),
+          platform: this.platform,
+          ...geminiStorageMode(env),
+        });
+        signedIn = true;
         // The refreshed token, project and plan belong to one sign-in; a new
         // sign-in (another account, or the same one again) starts over.
         const signIn = creds.refreshToken || creds.accessToken;
-        const cached = this.gemini.get(provider.id);
+        const cached = this.gemini.get(key);
         const known = cached?.signIn === signIn ? cached : {};
         const fresh = known.token && known.token.expiresAt > Date.now() + 60000 ? known.token : null;
         const { plan, windows, project, token } = await fetchGeminiUsage({
@@ -521,15 +602,15 @@ export class UsageMonitor {
           version: this.registry.versions.get(provider.id)?.installed,
           fetchImpl: this.fetchImpl,
         });
-        this.gemini.set(provider.id, { signIn, project, token, plan: plan ?? known.plan ?? null });
+        this.gemini.set(key, { signIn, project, token, plan: plan ?? known.plan ?? null });
         result = { plan: plan ?? known.plan ?? null, windows };
       } else {
         result = await commandUsage(provider.usage, env, this.platform);
       }
-      return { ...base, ...result };
+      return { ...base, signedIn, ...result };
     } catch (err) {
       const message = err instanceof UsageError ? err.message : `usage check failed: ${err.name === 'TimeoutError' ? 'timed out' : err.message}`;
-      return { ...base, error: message, ...(err.rateLimited ? { rateLimited: true } : {}) };
+      return { ...base, signedIn: err.notSignedIn ? false : signedIn, error: message, ...(err.rateLimited ? { rateLimited: true } : {}) };
     }
   }
 }