agy-crew 0.0.0-stage → 0.9.2

package/companion/pool/lease.mjs

@@ -0,0 +1,89 @@
+import { randomUUID } from 'node:crypto';
+import { accountEnv } from './env.mjs';
+import { accountHome, loadPool, poolExists, updatePool } from './state.mjs';
+import { parseResetsIn } from './results.mjs';
+import { chooseAccount, chooseLender, findAccount } from './select.mjs';
+import { beginLoan, endLoan } from './loans.mjs';
+
+export const boundAccount = (pool, conversation) =>
+  conversation ? pool.conversations[conversation]?.account || 'live' : null;
+
+const request = (req, pool) => ({
+  requested: req.requested, family: req.family, conversation: req.conversation || null,
+  conversationAccount: boundAccount(pool, req.conversation), now: Date.now(),
+});
+
+/** Read-only check used before a background job is registered. Returns an error
+ *  object or null. Never locks or creates anything. */
+export function preflight(req) {
+  const pool = loadPool();
+  return chooseAccount(pool, request(req, pool)).error || null;
+}
+
+const liveHeld = (pool, extra = {}) => ({ account: 'live', env: undefined, pooled: pool.accounts.length > 0, release() {}, ...extra });
+
+/** Selection and lease insertion are one locked update, so two runs starting
+ *  together cannot both see the same account as idle. Returns
+ *  { held } or { error }. held.release() must run after the agy process ends. */
+export function acquireRun(req) {
+  if (!poolExists()) {
+    const pool = loadPool();
+    const pick = chooseAccount(pool, request(req, pool));
+    return pick.error ? { error: pick.error } : { held: liveHeld(pool) };
+  }
+  const outcome = updatePool((pool) => {
+    const pick = chooseAccount(pool, request(req, pool));
+    if (pick.error) return { error: pick.error };
+    if (pick.account === 'live') return { held: { account: 'live', pooled: pool.accounts.length > 0 } };
+    const base = { pid: process.pid, job_id: req.jobId || null, started_at: new Date().toISOString() };
+    const account = findAccount(pool, pick.account);
+    account.last_used_at = base.started_at;
+    if (pick.needsLoan) {
+      const lender = chooseLender(pool, { family: req.family, exclude: [pick.account] });
+      if (!lender) {
+        return { error: { reason: 'quota_exhausted', retry_at: pick.retry_at,
+          message: `account ${pick.account} has no ${req.family} quota until ${pick.retry_at} and no other pool account is idle to lend a credential.` } };
+      }
+      const loan = beginLoan(pool, { borrower: pick.account, lender, jobId: req.jobId });
+      return { held: { account: pick.account, lender, loanId: loan.id, pooled: true } };
+    }
+    const id = randomUUID().slice(0, 8);
+    pool.leases.push({ ...base, id, account: pick.account, role: 'run' });
+    return { held: { account: pick.account, leaseId: id, auto: !!pick.auto, pooled: true } };
+  });
+  if (outcome.error) return outcome;
+  const held = outcome.held;
+  held.env = held.account === 'live' ? undefined : accountEnv(accountHome(held.account));
+  held.release = () => {
+    if (!held.leaseId && !held.loanId) return;
+    const { leaseId, loanId } = held;
+    held.leaseId = held.loanId = null;
+    updatePool((pool) => {
+      if (loanId) endLoan(pool, loanId);
+      if (leaseId) pool.leases = pool.leases.filter((l) => l.id !== leaseId);
+    });
+  };
+  return { held };
+}
+
+const DEFAULT_COOLDOWN_MS = 60 * 60_000;
+
+/** Record a quota cooldown for the account whose credential made the request.
+ *  Returns the cooldown (retry_at is when the reported reset passes, or one
+ *  hour when agy did not say). */
+export function recordCooldown(name, family, text, jobId) {
+  const now = Date.now();
+  const cooldown = { retry_at: new Date(now + (parseResetsIn(text) ?? DEFAULT_COOLDOWN_MS)).toISOString(),
+    reason: 'quota_exhausted', recorded_at: new Date(now).toISOString(), job_id: jobId || null,
+    message: String(text).trim().slice(0, 500) };
+  updatePool((pool) => { pool.cooldowns[`${name}|${family}`] = cooldown; });
+  return cooldown;
+}
+
+/** An authentication failure parks the account until `accounts login`. */
+export function markAuthError(name, text) {
+  updatePool((pool) => {
+    const account = findAccount(pool, name);
+    if (account) { account.auth_error_at = new Date().toISOString(); account.auth_error = String(text).trim().slice(0, 300); }
+  });
+}

package/companion/pool/loans.mjs

@@ -0,0 +1,46 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { replaceFile } from '../state-lock.mjs';
+import { PoolError, LOAN_BACKUP_NAME, accountHome, tokenPath, restoreLoanFiles } from './state.mjs';
+
+/** Credential loan: the borrower's HOME keeps the conversation, the lender's
+ *  token makes the request. Called inside updatePool, so the file swap and the
+ *  loan record are one transaction under the pool lock. */
+export function beginLoan(pool, { borrower, lender, jobId, pid = process.pid }) {
+  const tb = tokenPath(accountHome(borrower));
+  const tl = tokenPath(accountHome(lender));
+  const backup = path.join(path.dirname(tb), LOAN_BACKUP_NAME);
+  if (fs.existsSync(backup)) throw new PoolError(`a loan backup already exists for ${borrower}: ${backup}; resolve it before borrowing again`);
+  if (!fs.existsSync(tl)) throw new PoolError(`lender ${lender} has no token to lend`);
+  const hostHadToken = fs.existsSync(tb);
+  const loan = { id: randomUUID().slice(0, 8), borrower, lender, pid, job_id: jobId || null,
+    host_had_token: hostHadToken, started_at: new Date().toISOString() };
+  try {
+    if (hostHadToken) replaceFile(tb, backup);
+    const tmp = `${tb}.tmp-${process.pid}`;
+    fs.mkdirSync(path.dirname(tb), { recursive: true });
+    fs.copyFileSync(tl, tmp);
+    replaceFile(tmp, tb);
+  } catch (error) {
+    // Put the borrower back exactly as it was before surfacing the failure.
+    try { fs.rmSync(tb, { force: true }); if (hostHadToken && fs.existsSync(backup)) replaceFile(backup, tb); } catch {}
+    throw error;
+  }
+  pool.loans.push(loan);
+  const lease = { pid, job_id: jobId || null, started_at: loan.started_at, loan_id: loan.id };
+  pool.leases.push({ ...lease, id: randomUUID().slice(0, 8), account: lender, role: 'lender' });
+  pool.leases.push({ ...lease, id: randomUUID().slice(0, 8), account: borrower, role: 'run' });
+  return loan;
+}
+
+/** Restore the tokens and forget the loan and its leases. */
+export function endLoan(pool, loanId) {
+  const loan = pool.loans.find((l) => l.id === loanId);
+  if (!loan) return;
+  restoreLoanFiles(loan);
+  pool.loans = pool.loans.filter((l) => l.id !== loanId);
+  pool.leases = pool.leases.filter((l) => l.loan_id !== loanId);
+}
+
+export const accountInLoan = (pool, name) => pool.loans.some((l) => l.borrower === name || l.lender === name);

package/companion/pool/quota.mjs

@@ -0,0 +1,142 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { accountEnv } from './env.mjs';
+import { accountHome, updatePool } from './state.mjs';
+import { quotaPool } from './results.mjs';
+import { readToken } from './token.mjs';
+
+const baseUrl = () => process.env.AGY_CREW_CLOUDCODE_URL || 'https://cloudcode-pa.googleapis.com';
+const WARM_UP_MS = 120_000;
+const projectCache = (home) => path.join(home, '.gemini', 'antigravity-cli', 'cache', 'default_project_id.txt');
+
+/** Run agy once so it refreshes the file-backed token itself. */
+function warmUp(home, agyCommand) {
+  const agy = agyCommand(['-p', 'reply with one word: pong', '--output-format', 'json']);
+  spawnSync(agy.cmd, agy.args, { cwd: home, env: accountEnv(home), encoding: 'utf8', timeout: 60_000, windowsHide: true });
+}
+
+async function post(endpoint, accessToken, body) {
+  const response = await fetch(`${baseUrl()}/v1internal:${endpoint}`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'User-Agent': 'antigravity' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  });
+  let json = null;
+  try { json = await response.json(); } catch { /* non-JSON error body */ }
+  return { status: response.status, json };
+}
+
+const bucketId = (b) => b.id || b.bucketId || b.quotaBucketId || b.name || '';
+
+/** Quota pool of one Cloud Code group: bucket id prefixes first, then its labels. */
+function groupPool(group, buckets) {
+  for (const b of buckets) {
+    const id = String(bucketId(b));
+    if (id.startsWith('gemini-')) return 'gemini';
+    if (id.startsWith('3p-')) return 'other';
+  }
+  const label = `${group.displayName || ''} ${group.description || ''}`.toLowerCase();
+  if (label.includes('gemini')) return 'gemini';
+  if (/claude|gpt/.test(label)) return 'other';
+  return null;
+}
+
+export function parseQuotaSummary(json) {
+  const pools = {};
+  for (const group of json?.groups || []) {
+    const buckets = group.buckets || group.quotaBuckets || [];
+    const name = groupPool(group, buckets);
+    if (!name) continue;
+    for (const b of buckets) {
+      const window = String(b.window || b.windowType || b.period || '').toLowerCase();
+      const key = window === '5h' ? 'short' : window === 'weekly' ? 'weekly' : null;
+      if (!key) continue;
+      // proto3 JSON omits a zero fraction, so a bucket with a reset time but no fraction is empty
+      const remaining = typeof b.remainingFraction === 'number' ? b.remainingFraction : b.resetTime ? 0 : null;
+      if (remaining === null) continue;
+      (pools[name] ||= {})[key] = { remaining, reset_at: b.resetTime ? new Date(b.resetTime).toISOString() : null };
+    }
+  }
+  return pools;
+}
+
+async function queryCloudCode(home, accessToken) {
+  const meta = { metadata: { ideType: 'ANTIGRAVITY', platform: 'PLATFORM_UNSPECIFIED', pluginType: 'GEMINI' } };
+  const load = await post('loadCodeAssist', accessToken, meta);
+  if (load.status === 401) return { status: 401 };
+  if (load.status >= 400) return { status: load.status, error: `loadCodeAssist HTTP ${load.status}` };
+  let project = load.json?.cloudaicompanionProject;
+  project = typeof project === 'string' ? project : project?.id;
+  if (project) {
+    try { fs.mkdirSync(path.dirname(projectCache(home)), { recursive: true }); fs.writeFileSync(projectCache(home), project); } catch {}
+  } else {
+    try { project = fs.readFileSync(projectCache(home), 'utf8').trim(); } catch {}
+  }
+  if (!project) return { status: 200, error: 'no Cloud Code project id available' };
+  const summary = await post('retrieveUserQuotaSummary', accessToken, { project });
+  if (summary.status === 401) return { status: 401 };
+  if (summary.status >= 400) return { status: summary.status, error: `retrieveUserQuotaSummary HTTP ${summary.status}` };
+  return { status: 200, plan_type: load.json?.planInfo?.planType || null, pools: parseQuotaSummary(summary.json) };
+}
+
+const needsWarmUp = (tok) => !tok?.access_token || (tok.expiry_ms !== null && tok.expiry_ms - Date.now() < WARM_UP_MS);
+
+/** Query Cloud Code for one account. Never throws, never prints tokens. */
+export async function fetchSnapshot(name, { agyCommand }) {
+  const home = accountHome(name);
+  const snapshot = { refreshed_at: new Date().toISOString(), plan_type: null, pools: {}, error: null };
+  let authFailed = false;
+  try {
+    let tok = readToken(home);
+    if (needsWarmUp(tok)) { warmUp(home, agyCommand); tok = readToken(home); }
+    if (!tok?.access_token) throw new Error('no access token (run `accounts login`)');
+    let result = await queryCloudCode(home, tok.access_token);
+    if (result.status === 401) {
+      warmUp(home, agyCommand);
+      tok = readToken(home);
+      result = tok?.access_token ? await queryCloudCode(home, tok.access_token) : { status: 401 };
+      if (result.status === 401) { authFailed = true; throw new Error('Cloud Code rejected the credential (HTTP 401)'); }
+    }
+    if (result.error) throw new Error(result.error);
+    snapshot.plan_type = result.plan_type;
+    snapshot.pools = result.pools;
+  } catch (error) {
+    snapshot.error = String(error.message || error).slice(0, 300);
+  }
+  return { snapshot, authFailed };
+}
+
+/** Fetch snapshots, then store them in one locked update. A pool with quota
+ *  left clears that account's cooldowns for its families. */
+export async function refreshQuotas(names, deps) {
+  const fetched = [];
+  for (const name of names) fetched.push([name, await fetchSnapshot(name, deps)]);
+  updatePool((pool) => {
+    for (const [name, { snapshot, authFailed }] of fetched) {
+      const account = pool.accounts.find((a) => a.name === name);
+      if (!account) continue;
+      pool.quota[name] = snapshot;
+      if (authFailed) { account.auth_error_at = snapshot.refreshed_at; account.auth_error = snapshot.error; }
+      for (const [group, windows] of Object.entries(snapshot.pools)) {
+        const values = Object.values(windows).map((w) => w.remaining);
+        if (!values.length || Math.min(...values) <= 0) continue;
+        for (const key of Object.keys(pool.cooldowns)) {
+          const [owner, family] = key.split('|');
+          if (owner === name && quotaPool(family) === group) delete pool.cooldowns[key];
+        }
+      }
+    }
+  });
+  return Object.fromEntries(fetched.map(([name, f]) => [name, f.snapshot]));
+}
+
+/** One-line quota summary for list/quota output. */
+export function summarizeSnapshot(snapshot) {
+  if (!snapshot) return 'quota: not refreshed';
+  if (snapshot.error) return `quota: error (${snapshot.error})`;
+  const pct = (w) => (w ? `${Math.round(w.remaining * 100)}%` : '?');
+  const parts = Object.entries(snapshot.pools).map(([g, w]) => `${g} 5h ${pct(w.short)} weekly ${pct(w.weekly)}`);
+  return `quota: ${parts.join(' | ') || 'no data'}${snapshot.plan_type ? ` (${snapshot.plan_type})` : ''}`;
+}

package/companion/pool/results.mjs

@@ -0,0 +1,41 @@
+/** Classifiers for agy failure text. */
+
+const EFFORT_SUFFIX = /-(minimal|low|medium|high|xhigh|max)$/;
+
+/** gemini-3.8-flash-low -> gemini-3.8-flash */
+export function modelFamily(model) {
+  return String(model || '').replace(EFFORT_SUFFIX, '');
+}
+
+/** Cloud Code reports two quota groups: gemini and everything else. */
+export function quotaPool(family) {
+  return String(family).startsWith('gemini') ? 'gemini' : 'other';
+}
+
+export function isQuotaExhausted(text) {
+  const t = String(text || '').toLowerCase();
+  return t.includes('resource_exhausted') && (t.includes('individual quota reached') || t.includes('weekly quota reached'));
+}
+
+export function isAuthFailed(text) {
+  const t = String(text || '').toLowerCase();
+  return ['401', '403', 'unauthenticated'].some((a) => t.includes(a)) &&
+    ['auth', 'credential', 'login', 'token'].some((b) => t.includes(b));
+}
+
+/** 'quota_exhausted' | 'authentication_failed' | null */
+export function classifyFailureText(text) {
+  if (isQuotaExhausted(text)) return 'quota_exhausted';
+  if (isAuthFailed(text)) return 'authentication_failed';
+  return null;
+}
+
+/** "Resets in 2h3m" / "1d 4h" / "45s" -> milliseconds, or null. */
+export function parseResetsIn(text) {
+  const m = /resets in ((?:\d+\s*[dhms]\s*)+)/i.exec(String(text || ''));
+  if (!m) return null;
+  const unit = { d: 86_400_000, h: 3_600_000, m: 60_000, s: 1000 };
+  let total = 0;
+  for (const part of m[1].matchAll(/(\d+)\s*([dhms])/gi)) total += Number(part[1]) * unit[part[2].toLowerCase()];
+  return total > 0 ? total : null;
+}

package/companion/pool/select.mjs

@@ -0,0 +1,115 @@
+import fs from 'node:fs';
+import { accountHome, tokenPath } from './state.mjs';
+import { quotaPool } from './results.mjs';
+
+export const findAccount = (pool, name) => pool.accounts.find((a) => a.name === name) || null;
+export const leasesOn = (pool, name) => pool.leases.filter((l) => l.account === name);
+const defaultHasToken = (name) => fs.existsSync(tokenPath(accountHome(name)));
+
+export function activeCooldown(pool, name, family, now) {
+  const c = pool.cooldowns[`${name}|${family}`];
+  return c && Date.parse(c.retry_at) > now ? c : null;
+}
+
+/** Cloud Code snapshot says a window of this family's quota pool is empty and not yet reset. */
+export function exhaustedSnapshot(pool, name, family, now) {
+  const group = pool.quota?.[name]?.pools?.[quotaPool(family)];
+  if (!group) return null;
+  for (const window of ['short', 'weekly']) {
+    const w = group[window];
+    if (w && w.remaining === 0 && Date.parse(w.reset_at) > now) return w;
+  }
+  return null;
+}
+
+/** Smallest known remaining fraction across windows, or null when unknown. */
+function knownRemaining(pool, name, family) {
+  const group = pool.quota?.[name]?.pools?.[quotaPool(family)];
+  const values = ['short', 'weekly'].map((w) => group?.[w]?.remaining).filter((v) => typeof v === 'number');
+  return values.length ? Math.min(...values) : null;
+}
+
+function usable(pool, a, family, now, hasToken) {
+  return !a.disabled && !a.auth_error_at && hasToken(a.name) &&
+    !activeCooldown(pool, a.name, family, now) && !exhaustedSnapshot(pool, a.name, family, now);
+}
+
+// fewer leases, then more known quota (unknown after known > 0), then least recently used, then insertion order
+function rank(pool, family, withLeases) {
+  return (a, b) => {
+    if (withLeases) {
+      const d = leasesOn(pool, a.name).length - leasesOn(pool, b.name).length;
+      if (d) return d;
+    }
+    const ra = knownRemaining(pool, a.name, family) ?? -1;
+    const rb = knownRemaining(pool, b.name, family) ?? -1;
+    if (ra !== rb) return rb - ra;
+    const ua = a.last_used_at || '', ub = b.last_used_at || '';
+    if (ua !== ub) return ua < ub ? -1 : 1;
+    return pool.accounts.indexOf(a) - pool.accounts.indexOf(b);
+  };
+}
+
+function coolingError(pool, accounts, family, now, intro) {
+  const rows = accounts.map((a) => {
+    const c = activeCooldown(pool, a.name, family, now);
+    const s = exhaustedSnapshot(pool, a.name, family, now);
+    return { name: a.name, at: c?.retry_at || s?.reset_at || null };
+  });
+  const times = rows.map((r) => r.at).filter(Boolean).sort();
+  const detail = rows.map((r) => `  ${r.name}: ${r.at ? `retry after ${r.at}` : 'unavailable'}`).join('\n');
+  return { error: { reason: 'quota_exhausted', retry_at: times[0] || null,
+    message: `${intro}\n${detail}\nUse \`--account live\` (your own agy login) or another model family.` } };
+}
+
+/** Pick the account for a run. Pure: callers add the lease. Returns
+ *  { account, auto?, needsLoan?, retry_at? } or { error: { message, reason?, retry_at? } }. */
+export function chooseAccount(pool, { requested = 'auto', family, conversation = null, conversationAccount = null, now = Date.now(), hasToken = defaultHasToken }) {
+  const explicit = requested && requested !== 'auto';
+  if (conversationAccount) {
+    if (explicit && requested !== conversationAccount) {
+      return { error: { message: `conversation ${conversation} belongs to account ${conversationAccount}; --account ${requested} cannot continue it` } };
+    }
+    if (conversationAccount === 'live') return { account: 'live' };
+    const a = findAccount(pool, conversationAccount);
+    if (!a) return { error: { message: `conversation ${conversation} belongs to account ${conversationAccount}, which no longer exists` } };
+    if (a.disabled) return { error: { message: `conversation ${conversation} belongs to account ${a.name}, which is disabled (accounts enable ${a.name})` } };
+    if (a.auth_error_at || !hasToken(a.name)) return { error: { message: `conversation ${conversation} belongs to account ${a.name}, which needs login (accounts login ${a.name})` } };
+    const c = activeCooldown(pool, a.name, family, now);
+    if (c) return { account: a.name, needsLoan: true, retry_at: c.retry_at };
+    return { account: a.name };
+  }
+  if (requested === 'live') return { account: 'live' };
+  if (explicit) {
+    const a = findAccount(pool, requested);
+    if (!a) return { error: { message: `unknown account "${requested}" (see \`accounts list\`)` } };
+    if (a.disabled) return { error: { message: `account ${a.name} is disabled (accounts enable ${a.name})` } };
+    if (a.auth_error_at || !hasToken(a.name)) return { error: { message: `account ${a.name} needs login (accounts login ${a.name})` } };
+    const c = activeCooldown(pool, a.name, family, now);
+    if (c) {
+      return { error: { reason: 'quota_exhausted', retry_at: c.retry_at,
+        message: `account ${a.name} has no ${family} quota until ${c.retry_at}. Use \`--account auto\`, another account, or another model family.` } };
+    }
+    return { account: a.name };
+  }
+  const enabled = pool.accounts.filter((a) => !a.disabled);
+  if (!enabled.length) return { account: 'live' };
+  const candidates = enabled.filter((a) => usable(pool, a, family, now, hasToken));
+  if (!candidates.length) {
+    const cooling = enabled.filter((a) => activeCooldown(pool, a.name, family, now) || exhaustedSnapshot(pool, a.name, family, now));
+    if (cooling.length) return coolingError(pool, cooling, family, now, `every pool account is out of ${family} quota (quota_exhausted).`);
+    return { error: { message: 'no pool account is ready: each enabled account needs login (see `accounts list`)' } };
+  }
+  candidates.sort(rank(pool, family, true));
+  return { account: candidates[0].name, auto: true };
+}
+
+/** An idle account that can lend its credential to a borrower. */
+export function chooseLender(pool, { family, exclude = [], now = Date.now(), hasToken = defaultHasToken }) {
+  const inLoan = new Set(pool.loans.flatMap((l) => [l.borrower, l.lender]));
+  const candidates = pool.accounts.filter((a) => !exclude.includes(a.name) && !inLoan.has(a.name) &&
+    leasesOn(pool, a.name).length === 0 && usable(pool, a, family, now, hasToken));
+  candidates.sort(rank(pool, family, false));
+  return candidates[0]?.name || null;
+}
+

package/companion/pool/state.mjs

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { PRODUCT, globalHome } from '../identity.mjs';
+import { withStateLock, replaceFile } from '../state-lock.mjs';
+
+export const POOL_SCHEMA = 1;
+export const RESERVED_NAMES = ['live', 'auto'];
+const NAME_RE = /^[a-z0-9][a-z0-9._-]{0,31}$/;
+export const LOAN_BACKUP_NAME = '.antigravity-oauth-token.agy-crew.loan-backup';
+
+export class PoolError extends Error {}
+
+export function validateAccountName(name) {
+  if (!NAME_RE.test(String(name || ''))) {
+    throw new PoolError(`invalid account name "${name}": use 1-32 chars of a-z 0-9 . _ - starting with a letter or digit`);
+  }
+  if (RESERVED_NAMES.includes(name)) throw new PoolError(`"${name}" is a reserved account name`);
+  return name;
+}
+
+export function poolPaths() {
+  const root = globalHome();
+  return { root, file: path.join(root, 'pool.json'), lock: path.join(root, 'pool.json.lock'),
+    accountsDir: path.join(root, 'accounts'), enrollDir: path.join(root, 'enroll') };
+}
+export const accountDir = (name) => path.join(poolPaths().accountsDir, name);
+export const accountHome = (name) => path.join(accountDir(name), 'home');
+export const tokenPath = (home) => path.join(home, '.gemini', 'antigravity-cli', 'antigravity-oauth-token');
+export const accountSettingsPath = (home) => path.join(home, '.gemini', 'antigravity-cli', 'settings.json');
+
+export const emptyPool = () => ({ schema: POOL_SCHEMA, accounts: [], cooldowns: {}, leases: [], conversations: {}, loans: [], quota: {} });
+
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } };
+
+export function poolExists() {
+  return fs.existsSync(poolPaths().file);
+}
+
+/** Missing file = empty pool. A corrupt or newer-schema file is an error and is
+ *  never reset: the pool holds the only record of conversation bindings. */
+export function loadPool() {
+  const { file } = poolPaths();
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch (error) {
+    if (error.code === 'ENOENT') return emptyPool();
+    throw new PoolError(`cannot read ${file}: ${error.message}`);
+  }
+  let pool;
+  try { pool = JSON.parse(raw); } catch { throw new PoolError(`pool.json is corrupt: ${file} - fix or delete it, then retry`); }
+  if (!pool || typeof pool !== 'object') throw new PoolError(`pool.json is corrupt: ${file} - fix or delete it, then retry`);
+  if (pool.schema > POOL_SCHEMA) throw new PoolError(`pool.json was written by a newer ${PRODUCT} (schema ${pool.schema}); upgrade before using the account pool: ${file}`);
+  return { ...emptyPool(), ...pool };
+}
+
+function savePool(pool) {
+  const { file } = poolPaths();
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(pool, null, 2) + '\n');
+  replaceFile(tmp, file);
+}
+
+const copyAtomic = (from, to) => {
+  const tmp = `${to}.tmp-${process.pid}`;
+  fs.copyFileSync(from, tmp);
+  replaceFile(tmp, to);
+};
+
+/** Undo a credential loan's file swap: the borrower's current token (agy may
+ *  have refreshed the lender's credential in it) goes back to the lender, the
+ *  borrower's own token returns from its backup. Idempotent. */
+export function restoreLoanFiles(loan) {
+  const tb = tokenPath(accountHome(loan.borrower));
+  const tl = tokenPath(accountHome(loan.lender));
+  const backup = path.join(path.dirname(tb), LOAN_BACKUP_NAME);
+  if (fs.existsSync(tb) && fs.existsSync(path.dirname(tl))) copyAtomic(tb, tl);
+  fs.rmSync(tb, { force: true });
+  if (loan.host_had_token && fs.existsSync(backup)) replaceFile(backup, tb);
+}
+
+/** Drop what belongs to dead processes. Runs at the start of every locked
+ *  update so a crashed run never keeps an account busy or a token swapped. */
+export function reap(pool, now = Date.now()) {
+  pool.leases = pool.leases.filter((l) => alive(l.pid));
+  const keep = [];
+  for (const loan of pool.loans) {
+    if (alive(loan.pid)) { keep.push(loan); continue; }
+    try { restoreLoanFiles(loan); } catch { keep.push(loan); continue; } // retry on the next update
+    pool.leases = pool.leases.filter((l) => l.loan_id !== loan.id);
+  }
+  pool.loans = keep;
+  for (const [key, c] of Object.entries(pool.cooldowns)) if (Date.parse(c.retry_at) <= now) delete pool.cooldowns[key];
+  return pool;
+}
+
+export function updatePool(change) {
+  const { root, lock } = poolPaths();
+  fs.mkdirSync(root, { recursive: true });
+  return withStateLock(lock, () => {
+    const pool = reap(loadPool());
+    const value = change(pool);
+    savePool(pool);
+    return value;
+  });
+}

package/companion/pool/token.mjs

@@ -0,0 +1,25 @@
+import fs from 'node:fs';
+import { tokenPath } from './state.mjs';
+
+/** The email claim of an unverified JWT (we only label accounts with it). */
+function jwtEmail(jwt) {
+  try {
+    const part = String(jwt).split('.')[1];
+    const claims = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+    return typeof claims.email === 'string' ? claims.email : null;
+  } catch { return null; }
+}
+
+/** Read a file-backed agy token: access token, expiry (ms) and account email.
+ *  null when the file is absent or unreadable. */
+export function readToken(home) {
+  let json;
+  try { json = JSON.parse(fs.readFileSync(tokenPath(home), 'utf8')); } catch { return null; }
+  const t = json.token && typeof json.token === 'object' ? json.token : {};
+  const expiry = typeof t.expiry === 'number' ? (t.expiry < 1e12 ? t.expiry * 1000 : t.expiry) : Date.parse(t.expiry);
+  return {
+    access_token: t.access_token || null,
+    expiry_ms: Number.isFinite(expiry) ? expiry : null,
+    email: jwtEmail(t.id_token) || jwtEmail(json.id_token),
+  };
+}

package/companion/state-lock.mjs

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const pause = () => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+
+const TRANSIENT = ['EPERM', 'EBUSY', 'EACCES'];
+
+/** Atomic replace that survives Windows sharing violations. Replacing a file
+ *  another process currently has open for reading fails there with EPERM or
+ *  EBUSY; readers poll state and progress files every few hundred ms, so
+ *  retry briefly before giving up. POSIX never takes the retry path. */
+export function replaceFile(tmp, file) {
+  for (let attempt = 0; ; attempt++) {
+    try { fs.renameSync(tmp, file); return; } catch (error) {
+      if (!TRANSIENT.includes(error.code) || attempt >= 50) throw error;
+      pause();
+    }
+  }
+}
+
+/** Read a file that a concurrent writer may be replacing right now. ENOENT is
+ *  returned to the caller; transient Windows sharing errors are retried. */
+export function readTextRetry(file) {
+  for (let attempt = 0; ; attempt++) {
+    try { return fs.readFileSync(file, 'utf8'); } catch (error) {
+      if (!TRANSIENT.includes(error.code) || attempt >= 50) throw error;
+      pause();
+    }
+  }
+}
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (error) { return error.code === 'EPERM'; } };
+
+// Publish a nonempty directory atomically. Reapers remove only the unique
+// marker they inspected, then rmdir (never recursively delete a successor).
+export function withStateLock(lock, change) {
+  const owner = `owner-${process.pid}-${randomUUID()}`;
+  const candidate = `${lock}.${owner}`;
+  fs.mkdirSync(candidate);
+  fs.writeFileSync(path.join(candidate, owner), '');
+  const start = Date.now();
+  let acquired = false;
+  let lastError = null;
+  try {
+    for (;;) {
+      try { fs.renameSync(candidate, lock); acquired = true; break; } catch (error) {
+        // Windows reports EPERM (not EEXIST/ENOTEMPTY) when renaming a
+        // non-empty directory onto an existing one, and EBUSY while a
+        // scanner holds it. Both are transient here: the holder releases
+        // the lock momentarily, so retry instead of failing the job.
+        if (!['EEXIST', 'ENOTEMPTY', 'EPERM', 'EBUSY', 'EACCES'].includes(error.code)) throw error;
+        lastError = error;
+      }
+      let entries = [];
+      // Windows also reports EPERM/EBUSY/EACCES while another process is renaming
+      // or removing the lock directory; treat those like a busy lock and retry.
+      try { entries = fs.readdirSync(lock); } catch (error) {
+        if (!['ENOENT', 'ENOTDIR', 'EPERM', 'EBUSY', 'EACCES'].includes(error.code)) throw error;
+        if (error.code !== 'ENOENT') lastError = error;
+      }
+      if (entries.length === 1) {
+        const match = /^owner-(\d+)-[a-f0-9-]+$/.exec(entries[0]);
+        if (match && Number(match[1]) > 1 && !alive(Number(match[1]))) {
+          try {
+            fs.unlinkSync(path.join(lock, entries[0]));
+            fs.rmdirSync(lock);
+          } catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST', 'EPERM', 'EBUSY', 'EACCES'].includes(error.code)) throw error; }
+        }
+      }
+      if (Date.now() - start > 10000) {
+        const detail = lastError?.code ? ` (last error: ${lastError.code})` : '';
+        throw new Error(`Timed out acquiring job state lock${detail}: ${lock}. If no companion process is running, inspect and remove the stale lock.`);
+      }
+      pause();
+    }
+    return change();
+  } finally {
+    if (acquired) {
+      const marker = path.join(lock, owner);
+      // A concurrent reaper may already have removed our marker (it judges the
+      // holder dead once the dispatch process exits, resulting in ENOENT).
+      // On Windows, open handles or scanners can cause transient EPERM/EBUSY/EACCES;
+      // retry briefly before giving up, and only ignore if the marker no longer exists.
+      for (let attempt = 0; attempt < 5; attempt++) {
+        try {
+          fs.unlinkSync(marker);
+          break;
+        } catch (error) {
+          if (error.code === 'ENOENT') break;
+          if (['EPERM', 'EBUSY', 'EACCES'].includes(error.code)) {
+            if (attempt < 4) {
+              pause();
+              continue;
+            }
+            if (!fs.existsSync(marker)) break;
+          }
+          throw error;
+        }
+      }
+      try { fs.rmdirSync(lock); } catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST', 'EPERM', 'EBUSY', 'EACCES'].includes(error.code)) throw error; }
+    } else fs.rmSync(candidate, { recursive: true, force: true });
+  }
+}