agy-crew 0.9.3 → 0.9.4

package/README.md

@@ -244,7 +244,7 @@ agy-crew accounts list              # shows work1 as ready
 
 From then on, runs pick an account automatically (`--account auto` is the default): an idle account first, then the one with the most known quota left. Repeat `login` with another name for more accounts. Your own agy login (**live**) is never pooled: `auto` never uses it and it never lends credentials. It is used only with `--account live`, or when the pool has no enabled account, so an empty pool changes nothing.
 
-When an account hits a quota limit, the companion records a cooldown for that account and model family (until the reset time agy reports, or 60 minutes if none). A run that had not started a conversation fails over to another account. A run in the middle of a conversation stays bound to its account, because the history lives there; if that account is cooling, an idle account lends its credential for the rest of the run and the token files are restored afterwards, including after a crash. If nothing can continue, the job ends with `quota_exhausted` and a `retry_at`, and you decide when to `continue`. `agy-crew accounts quota --refresh` asks Google's Cloud Code service for current quota; that is the only command that uses the network.
+When an account hits a quota limit, the companion records a cooldown for that account and model family (until the reset time agy reports, or 60 minutes if none). A run that had not started a conversation fails over to another account. A run in the middle of a conversation stays bound to its account, because the history lives there; if that account is cooling, an idle account lends its credential for the rest of the run and the token files are restored afterwards, including after a crash. If nothing can continue, the job ends with `quota_exhausted` and a `retry_at`, and you decide when to `continue`. An upstream 503 (`No capacity available for model ...`) parks the account for 3 minutes so the next run uses another one, and a task that had changed nothing is rerun from its original prompt as a new conversation rather than continued; if it still ends with `upstream_unavailable` before agy did anything, start the task again instead of using `continue`. `agy-crew accounts quota --refresh` asks Google's Cloud Code service for current quota; that is the only command that uses the network.
 
 Already have accounts? `agy-crew accounts import work2 --home <dir>` copies the token from an existing HOME-shaped directory, such as an agy-cli-manager account directory (`~/.agy-cli-manager/accounts/<name>`). agy-cli-manager is not needed otherwise; import is just a file copy plus the usual email and duplicate checks. Other subcommands: `enable`, `disable`, `cooldown clear`, `remove --yes`. Full details in the [reference](docs/REFERENCE.md#accounts).
 

package/README.zh-CN.md

@@ -205,7 +205,7 @@ agy-crew accounts list              # work1 显示为 ready
 
 之后每次运行都会自动选择账号（默认就是 `--account auto`）：优先选空闲账号，其次选已知剩余配额最多的。想要更多账号，换个名字再执行一次 `login` 即可。你自己的 agy 登录（**live**）永远不属于账号池：`auto` 不会用它，它也不会借出凭据。只有显式传入 `--account live`，或账号池里没有任何启用的账号时才会用到它，所以账号池为空时一切照旧。
 
-账号触及配额上限时，companion 会为该账号和模型家族记录冷却，直到 agy 报告的重置时间，没有报告则为 60 分钟。尚未开始会话的任务会转到另一个账号；已经在会话中的任务仍绑定原账号，因为会话历史保存在那里。如果该账号正在冷却，就由一个空闲账号在本次运行中出借凭据，结束后令牌文件会还原，崩溃后也会恢复。所有账号都无法继续时，任务以 `quota_exhausted` 结束并给出 `retry_at`，由你决定何时 `continue`。`agy-crew accounts quota --refresh` 会向 Google 的 Cloud Code 服务查询当前配额，这是唯一会联网的命令。
+账号触及配额上限时，companion 会为该账号和模型家族记录冷却，直到 agy 报告的重置时间，没有报告则为 60 分钟。尚未开始会话的任务会转到另一个账号；已经在会话中的任务仍绑定原账号，因为会话历史保存在那里。如果该账号正在冷却，就由一个空闲账号在本次运行中出借凭据，结束后令牌文件会还原，崩溃后也会恢复。所有账号都无法继续时，任务以 `quota_exhausted` 结束并给出 `retry_at`，由你决定何时 `continue`。上游 503（`No capacity available for model ...`）会让该账号冷却 3 分钟，下一次运行改用其他账号；没有改动过工作区的任务会用原始提示词开新会话重跑，而不是继续旧会话。如果任务仍以 `upstream_unavailable` 结束且 agy 还什么都没做，请重新开始任务，不要用 `continue`。`agy-crew accounts quota --refresh` 会向 Google 的 Cloud Code 服务查询当前配额，这是唯一会联网的命令。
 
 已经有账号了？`agy-crew accounts import work2 --home <dir>` 会从现有的 HOME 形态目录复制令牌，例如 agy-cli-manager 的账号目录（`~/.agy-cli-manager/accounts/<name>`）。agy-crew 并不依赖 agy-cli-manager，导入只是复制文件，再做与登录相同的邮箱和重复检查。其他子命令：`enable`、`disable`、`cooldown clear`、`remove --yes`。完整说明见[参考手册](docs/REFERENCE.zh-CN.md#账号池)。
 

package/companion/agy-companion.mjs

@@ -111,7 +111,7 @@ import { atomicJSON, runStreaming, processIdentity } from './stream-worker.mjs';
 import { withStateLock, replaceFile, readTextRetry } from './state-lock.mjs';
 import { cmdAccounts, poolSettingsFiles } from './accounts.mjs';
 import { acquireRun, boundAccount, preflight, recordCooldown, markAuthError } from './pool/lease.mjs';
-import { classifyFailureText, modelFamily } from './pool/results.mjs';
+import { classifyFailureText, isCooldownReason, modelFamily } from './pool/results.mjs';
 import { loadPool, updatePool, poolExists } from './pool/state.mjs';
 
 const SELF = fileURLToPath(import.meta.url);
@@ -1165,6 +1165,9 @@ function treeDeltaReport(mode, before, after) {
 // ---------------------------------------------------------------------------
 
 const MAX_POOL_RETRIES = 3;
+// agy already retries a 503 about eight times (a couple of minutes) before it
+// gives up, so each extra attempt on another account is expensive.
+const MAX_UNAVAILABLE_RETRIES = 2;
 const QUOTA_CONTINUE_PROMPT = 'Your previous turn stopped because the account hit a quota limit. ' +
   'Continue the same task from where you stopped; do not repeat finished steps.';
 
@@ -1207,15 +1210,20 @@ async function invokeOnce(invoke, execution) {
   return { result, failure: resultFailure(result) };
 }
 
-function quotaFailure(resolved, opts, { message, retry_at, conversation }) {
-  const when = retry_at || 'the account quota resets';
-  const recovery = conversation
-    ? `continue ${opts.jobId ? `--job ${opts.jobId}` : `--conversation ${conversation}`} after ${when}; ` +
-      'when another pool account is idle, a credential loan is used automatically'
-    : `start a new run after ${when}, pass --account live, or choose another model family`;
+function quotaFailure(resolved, opts, { message, retry_at, conversation, reason = 'quota_exhausted' }) {
+  const unavailable = reason === 'upstream_unavailable';
+  const when = retry_at || (unavailable ? 'the upstream recovers' : 'the account quota resets');
+  const target = opts.jobId ? `--job ${opts.jobId}` : `--conversation ${conversation}`;
+  const recovery = unavailable
+    ? 'the upstream model had no capacity (503). If agy had not done anything yet, start the task again as a new run with a rewritten prompt' +
+      `${opts.jobId ? ` (restart ${opts.jobId})` : ''} and do not use continue. ` +
+      (conversation ? `Only if agy already changed the workspace, inspect it and continue ${target} after ${when}.` : `Start a new run after ${when}, or choose another model family.`)
+    : conversation
+      ? `continue ${target} after ${when}; when another pool account is idle, a credential loan is used automatically`
+      : `start a new run after ${when}, pass --account live, or choose another model family`;
   const text = `${message}\n${recovery}`;
-  if (resolved.background) throw Object.assign(new Error(text), { reason: 'quota_exhausted', retry_at: retry_at || null, recovery });
-  die(`${text}\n${JSON.stringify({ status: conversation ? 'attention' : 'error', reason: 'quota_exhausted',
+  if (resolved.background) throw Object.assign(new Error(text), { reason, retry_at: retry_at || null, recovery });
+  die(`${text}\n${JSON.stringify({ status: conversation ? 'attention' : 'error', reason,
     retry_at: retry_at || null, conversation_id: conversation || null, recovery }, null, 2)}`, conversation ? 5 : 1);
 }
 
@@ -1223,15 +1231,20 @@ function latestConversation(jobId) {
   return jobId ? loadState().jobs?.find((j) => j.id === jobId)?.conversation_id || null : null;
 }
 
-/** Run agy on a pool account chosen under a lease. A quota failure records a
- *  cooldown and then either fails over to another account (nothing started
- *  yet) or continues the bound conversation on a borrowed credential. */
-async function runWithPool(resolved, invoke, opts, execution) {
+/** Run agy on a pool account chosen under a lease. A quota or upstream-503
+ *  failure records a cooldown and then either fails over to another account
+ *  (nothing started yet) or continues the bound conversation on a borrowed
+ *  credential. A 503 on a task that began as a new conversation and left the
+ *  workspace untouched is not continued: the original prompt runs again in a
+ *  fresh conversation on another account. `untouched` tells whether agy has
+ *  changed nothing so far. */
+async function runWithPool(resolved, invoke, opts, execution, untouched = () => false) {
   const family = modelFamily(resolved.model);
+  const original = { prompt: invoke.prompt, conversation: invoke.conversation };
   for (let retries = 0; ; retries++) {
     const got = acquireRun({ requested: resolved.account_request, family, conversation: invoke.conversation, jobId: opts.jobId });
     if (got.error) {
-      if (got.error.reason !== 'quota_exhausted') die(got.error.message);
+      if (!isCooldownReason(got.error.reason)) die(got.error.message);
       quotaFailure(resolved, opts, { ...got.error, conversation: invoke.conversation });
     }
     const held = got.held;
@@ -1258,18 +1271,27 @@ async function runWithPool(resolved, invoke, opts, execution) {
       if (error) rethrow(error);
       return { result, held }; // triage reports it with its usual message
     }
-    const cooldown = recordCooldown(credit, family, failure.text, opts.jobId);
+    const unavailable = failure.kind === 'upstream_unavailable';
+    const cooldown = recordCooldown(credit, family, failure.text, opts.jobId, failure.kind);
     const conversation = result?.payload?.conversation_id || latestConversation(opts.jobId) || invoke.conversation;
-    if (retries < MAX_POOL_RETRIES) {
+    if (retries < (unavailable ? MAX_UNAVAILABLE_RETRIES : MAX_POOL_RETRIES)) {
       if (!conversation && held.auto) continue; // nothing started: just pick another account
+      if (unavailable && held.auto && !original.conversation && untouched()) {
+        // agy did nothing: rewrite the task from its original prompt instead of continuing it
+        invoke.prompt = original.prompt;
+        invoke.conversation = null;
+        continue;
+      }
       if (conversation && boundAccount(loadPool(), conversation) !== 'live') {
         invoke.conversation = conversation; // the next acquire finds the account cooling and borrows a credential
         invoke.prompt = QUOTA_CONTINUE_PROMPT;
         continue;
       }
     }
-    quotaFailure(resolved, opts, { conversation, retry_at: cooldown.retry_at,
-      message: `agy account "${credit}" hit a ${family} quota limit (quota_exhausted).` });
+    quotaFailure(resolved, opts, { conversation, retry_at: cooldown.retry_at, reason: failure.kind,
+      message: unavailable
+        ? `agy account "${credit}" got ${family} unavailable upstream (503, upstream_unavailable).`
+        : `agy account "${credit}" hit a ${family} quota limit (quota_exhausted).` });
   }
 }
 
@@ -1289,7 +1311,12 @@ async function executeRun(resolved, prompt, opts, execution = null) {
   };
   let result, response, held;
   try {
-    ({ result, held } = await runWithPool(resolved, invoke, opts, execution));
+    const untouched = () => {
+      if (resolved.mode === 'ask') return true;
+      const after = porcelainSnapshot();
+      return !!workspaceBefore && !!after && porcelainDelta(workspaceBefore, after).length === 0;
+    };
+    ({ result, held } = await runWithPool(resolved, invoke, opts, execution, untouched));
     response = triageResult(result, resolved.mode, resolved.profile, resolved.profileSource, resolved.model);
   } catch (error) {
     error.workspace = {
@@ -1348,7 +1375,7 @@ function cmdRun(mode, opts) {
  *  another account. Quota problems are left to the run itself. */
 function preflightAccount(resolved) {
   const problem = preflight({ requested: resolved.account_request, family: modelFamily(resolved.model), conversation: resolved.conversation });
-  if (problem && problem.reason !== 'quota_exhausted') die(problem.message);
+  if (problem && !isCooldownReason(problem.reason)) die(problem.message);
 }
 
 async function dispatch(resolved, prompt, opts) {
@@ -1471,7 +1498,7 @@ async function workerMain(jobId) {
     if (!job) throw error;
     const reason = job.cancel_requested_at ? 'canceled' : error.reason || 'agy_error';
     const status = job.status === 'canceled' || reason === 'canceled' ? 'canceled'
-      : (isTimeoutReason(reason) || reason === 'quota_exhausted') && job.conversation_id ? 'attention' : 'error';
+      : (isTimeoutReason(reason) || isCooldownReason(reason)) && job.conversation_id ? 'attention' : 'error';
     job = finishJob(jobId, (completed) => {
       const report = { ...diagnosticPacket(completed), result_exists: true, reason: completed.reason,
         workspace: error.workspace, last_snapshot: readObservation(completed) };
@@ -1650,6 +1677,17 @@ function quotaRecovery(job) {
       : `No conversation was started. Restart after ${when}, pass --account live, or choose another model family.` };
 }
 
+/** Recovery for a job that stopped because the upstream model had no capacity (503). */
+function unavailableRecovery(job) {
+  return { retry_at: job.retry_at || null, spec_file: job.spec_file || null,
+    inspect: 'git status --short; git diff',
+    restart: `restart ${job.id}`,
+    continue: job.conversation_id ? `continue --job ${job.id} --prompt "Continue after inspecting partial workspace changes"` : null,
+    note: 'The upstream model had no capacity (503). If agy had not done anything yet (clean `git status`, no partial result), start the task again ' +
+      `(restart ${job.id}, or a new run with a rewritten prompt) and do not use continue: a continuation stays bound to the same account and conversation. ` +
+      'Use continue only when agy already changed the workspace, after inspecting it. Never retry in a loop.' };
+}
+
 function diagnosticPacket(job) {
   let logBytes = null;
   try { logBytes = fs.statSync(job.log_file).size; } catch {}
@@ -1660,8 +1698,8 @@ function diagnosticPacket(job) {
     result_exists: fs.existsSync(job.result_file), log_file: job.log_file, events_file: job.events_file || null,
     conversation_id: job.conversation_id || null, model: job.model || null, profile: job.profile || null,
     ...(job.account ? { account: job.account } : {}),
-    ...(job.reason === 'quota_exhausted' ? { retry_at: job.retry_at || null } : {}),
-    recovery: isTimeoutReason(job.reason) ? timeoutRecovery(job) : job.reason === 'quota_exhausted' ? quotaRecovery(job) : { inspect: 'git status --short; git diff', spec_file: job.spec_file || null,
+    ...(isCooldownReason(job.reason) ? { retry_at: job.retry_at || null } : {}),
+    recovery: isTimeoutReason(job.reason) ? timeoutRecovery(job) : job.reason === 'quota_exhausted' ? quotaRecovery(job) : job.reason === 'upstream_unavailable' ? unavailableRecovery(job) : { inspect: 'git status --short; git diff', spec_file: job.spec_file || null,
       continue: job.conversation_id ? `continue --job ${job.id} --prompt "Continue after inspecting partial workspace changes"` : null,
       restart: `restart ${job.id}`, note: 'Inspect partial workspace changes first. Recovery creates a linked new job with a fresh budget; nothing is retried automatically.' },
   };

package/companion/pool/lease.mjs

@@ -41,8 +41,9 @@ export function acquireRun(req) {
     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 why = pick.reason === 'upstream_unavailable' ? 'is unavailable upstream (503)' : 'has no quota';
+        return { error: { reason: pick.reason, retry_at: pick.retry_at,
+          message: `account ${pick.account} ${why} for ${req.family} 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 } };
@@ -67,17 +68,26 @@ export function acquireRun(req) {
 }
 
 const DEFAULT_COOLDOWN_MS = 60 * 60_000;
+const UNAVAILABLE_COOLDOWN_MS = 3 * 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) {
+/** Record a cooldown for the account whose credential made the request.
+ *  A quota failure lasts until the reported reset (one hour when agy did not
+ *  say); an upstream_unavailable (503) one is a few minutes, just long enough
+ *  that the next run picks another account, and never shortens a quota
+ *  cooldown that is still running. Returns the cooldown now in force. */
+export function recordCooldown(name, family, text, jobId, kind = 'quota_exhausted') {
   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,
+  const wait = kind === 'upstream_unavailable' ? UNAVAILABLE_COOLDOWN_MS : (parseResetsIn(text) ?? DEFAULT_COOLDOWN_MS);
+  const cooldown = { retry_at: new Date(now + wait).toISOString(),
+    reason: kind, 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;
+  return updatePool((pool) => {
+    const key = `${name}|${family}`;
+    const current = pool.cooldowns[key];
+    if (kind === 'upstream_unavailable' && current && Date.parse(current.retry_at) > Date.parse(cooldown.retry_at)) return current;
+    pool.cooldowns[key] = cooldown;
+    return cooldown;
+  });
 }
 
 /** An authentication failure parks the account until `accounts login`. */

package/companion/pool/results.mjs

@@ -23,10 +23,22 @@ export function isAuthFailed(text) {
     ['auth', 'credential', 'login', 'token'].some((b) => t.includes(b));
 }
 
-/** 'quota_exhausted' | 'authentication_failed' | null */
+/** The model has no capacity right now ("UNAVAILABLE (code 503): No capacity
+ *  available for model X on the server"). agy has already retried internally. */
+export function isUpstreamUnavailable(text) {
+  const t = String(text || '').toLowerCase();
+  return (t.includes('unavailable') && t.includes('503')) || t.includes('no capacity available');
+}
+
+/** Failures that park an account for a model family: out of quota, or the
+ *  upstream has no capacity. */
+export const isCooldownReason = (reason) => reason === 'quota_exhausted' || reason === 'upstream_unavailable';
+
+/** 'quota_exhausted' | 'authentication_failed' | 'upstream_unavailable' | null */
 export function classifyFailureText(text) {
   if (isQuotaExhausted(text)) return 'quota_exhausted';
   if (isAuthFailed(text)) return 'authentication_failed';
+  if (isUpstreamUnavailable(text)) return 'upstream_unavailable';
   return null;
 }
 

package/companion/pool/select.mjs

@@ -34,6 +34,11 @@ function usable(pool, a, family, now, hasToken) {
     !activeCooldown(pool, a.name, family, now) && !exhaustedSnapshot(pool, a.name, family, now);
 }
 
+// Remaining quota counts in 5% steps: accounts that are about equally full
+// rotate by least recent use instead of the fullest one winning every time.
+const QUOTA_STEPS = 20;
+const quotaBucket = (remaining) => (remaining === null ? -1 : Math.round(remaining * QUOTA_STEPS));
+
 // 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) => {
@@ -41,8 +46,8 @@ function rank(pool, family, 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;
+    const ra = quotaBucket(knownRemaining(pool, a.name, family));
+    const rb = quotaBucket(knownRemaining(pool, b.name, family));
     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;
@@ -50,15 +55,22 @@ function rank(pool, family, withLeases) {
   };
 }
 
-function coolingError(pool, accounts, family, now, intro) {
+const unavailableCooldown = (c) => c?.reason === 'upstream_unavailable';
+
+function coolingError(pool, accounts, family, now) {
   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 };
+    return { name: a.name, at: c?.retry_at || s?.reset_at || null, capacity: unavailableCooldown(c) && !s };
   });
   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,
+  const capacity = rows.every((r) => r.capacity);
+  const reason = capacity ? 'upstream_unavailable' : 'quota_exhausted';
+  const intro = capacity
+    ? `every pool account recently got ${family} unavailable upstream (503, upstream_unavailable).`
+    : `every pool account is out of ${family} quota (quota_exhausted).`;
+  return { error: { reason, retry_at: times[0] || null,
     message: `${intro}\n${detail}\nUse \`--account live\` (your own agy login) or another model family.` } };
 }
 
@@ -76,7 +88,7 @@ export function chooseAccount(pool, { requested = 'auto', family, conversation =
     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 };
+    if (c) return { account: a.name, needsLoan: true, retry_at: c.retry_at, reason: c.reason || 'quota_exhausted' };
     return { account: a.name };
   }
   if (requested === 'live') return { account: 'live' };
@@ -87,8 +99,9 @@ export function chooseAccount(pool, { requested = 'auto', family, conversation =
     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.` } };
+      const why = unavailableCooldown(c) ? `was unavailable upstream (503) for ${family}; retry after` : `has no ${family} quota until`;
+      return { error: { reason: c.reason || 'quota_exhausted', retry_at: c.retry_at,
+        message: `account ${a.name} ${why} ${c.retry_at}. Use \`--account auto\`, another account, or another model family.` } };
     }
     return { account: a.name };
   }
@@ -97,7 +110,7 @@ export function chooseAccount(pool, { requested = 'auto', family, conversation =
   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).`);
+    if (cooling.length) return coolingError(pool, cooling, family, now);
     return { error: { message: 'no pool account is ready: each enabled account needs login (see `accounts list`)' } };
   }
   candidates.sort(rank(pool, family, true));

package/docs/REFERENCE.md

@@ -237,11 +237,11 @@ Every agy process for a pool account runs with its own HOME (and `USERPROFILE` o
 **Selection ranking for `auto`.** A candidate is an enabled account with a token file, no authentication error, no active cooldown for the model family, and no cached Cloud Code snapshot reporting zero remaining quota for the family's quota pool with a reset time in the future. Candidates are ranked by:
 
 1. fewest active leases (an idle account beats a busy one);
-2. highest known remaining quota fraction (the lower of the short and weekly windows; unknown ranks after any known value above zero);
+2. highest known remaining quota fraction (the lower of the short and weekly windows, compared in 5% steps so that accounts that are about equally full rotate by least recent use; unknown ranks after any known value above zero);
 3. oldest `last_used_at`;
 4. insertion order.
 
-If there is no candidate, the run fails with reason `quota_exhausted`, listing each account's earliest `retry_at` and suggesting `--account live` or another model. Concurrent runs share one account only when it is named explicitly, or when `auto` finds no idle candidate (the least-loaded account wins).
+If there is no candidate, the run fails with reason `quota_exhausted` (or `upstream_unavailable` when every account is cooling only because of 503s), listing each account's earliest `retry_at` and suggesting `--account live` or another model. Concurrent runs share one account only when it is named explicitly, or when `auto` finds no idle candidate (the least-loaded account wins).
 
 Selection and the lease that marks the account busy are taken in one locked update, and released when the agy process ends. A lease whose process died is dropped automatically.
 
@@ -259,6 +259,12 @@ The run then recovers, with at most three extra attempts:
 - **A conversation id is known and the conversation is bound to a pool account**: a credential loan is attempted (below). If a lender exists, the run continues with the prompt "Your previous turn stopped because the account hit a quota limit. Continue the same task from where you stopped; do not repeat finished steps."
 - **Otherwise the run fails** with reason `quota_exhausted`. A background job gets status `attention` when a conversation id exists and `error` when none does; its result includes `retry_at` and recovery text (`continue --job <id> after <retry_at>`; a credential loan is used automatically once another pool account is idle). A foreground run dies with the same information, exit 5 when a conversation id exists, otherwise 1. Further continuation is the caller's decision; the companion does not loop.
 
+**Upstream 503 (`upstream_unavailable`).** When agy gives up with `UNAVAILABLE (code 503)` or `No capacity available for model ...` (it has already retried about eight times, roughly two minutes), the companion records a short cooldown for that account and family, **3 minutes** and with reason `upstream_unavailable`, so the next selection, in this run or a separate one, picks another account. A 503 cooldown never shortens a quota cooldown that is still running. Recovery makes at most two extra attempts:
+
+- **No conversation id yet, or the task began as a new conversation and the workspace is unchanged** (always true for `ask`; otherwise `git status` shows nothing new) and the account was chosen by `auto`: the original prompt runs again in a new conversation on another account. It is a rewrite, never a continuation.
+- **Workspace already changed, with a conversation bound to a pool account**: the same credential-loan continuation as for quota.
+- **Otherwise the run fails** with reason `upstream_unavailable`, exit 5 or status `attention` when a conversation id exists, otherwise 1. The recovery text tells the caller to start the task again (`restart <job>`) when agy had not done anything yet, and to use `continue` only when the workspace was already changed. An explicit `--account` is never moved to another account.
+
 An **authentication failure** on a pool account (`401`, `403` or `unauthenticated` together with auth, credential, login or token wording) sets the account's auth error. Selection skips it, `list` shows `needs login`, and `accounts login <name>` clears it. Authentication failures are never retried.
 
 ### Credential loans
@@ -315,6 +321,7 @@ A refreshed snapshot with remaining quota above zero for a pool clears that acco
 | Situation | Reason / output | Exit |
 |---|---|---|
 | No `auto` candidate, or quota hit mid-run with no lender | `quota_exhausted`, with `retry_at` (per account when no candidate) | 5 when a conversation id exists, otherwise 1; a background job ends `attention` or `error` accordingly |
+| 503 / no capacity from the model, no account or lender could continue | `upstream_unavailable`, with `retry_at` (3 minutes after the last 503) | 5 when a conversation id exists, otherwise 1; a background job ends `attention` or `error` accordingly |
 | Authentication failure on a pool account | account marked `needs login`; never retried | follows the normal error path |
 | Explicit `--account <name>` that is unknown, disabled, cooling or needs login | error before launch naming the reason | 1 |
 | `--account` conflicting with a bound conversation | `conversation <id> belongs to account <x>` | 1 |
@@ -324,7 +331,7 @@ A refreshed snapshot with remaining quota above zero for a pool clears that acco
 ## Troubleshooting
 
 - **"agy reported an error (status ERROR)"** — the companion relays agy's own error verbatim, and appends a cause hint only when the error text actually matches one (invalid model id → run `agy models`; expired auth → run `agy` interactively once to re-login; exhausted quota). If agy reported an error but still returned response text, the companion delivers the response anyway — exit 0, response on stdout, warning on stderr (`done_with_warnings`); a deadline with no response but a known conversation instead signals attention (exit 5).
-- **Quota error or `needs login` on a pool account** — see [Accounts](#accounts). A quota failure records a cooldown and is recovered inside the run when another account or an idle lender exists; otherwise the job ends with `quota_exhausted` and a `retry_at`. An authentication failure is never retried: run `agy-crew accounts login <name>` in your own terminal.
+- **Quota error or `needs login` on a pool account** — see [Accounts](#accounts). A quota failure records a cooldown and is recovered inside the run when another account or an idle lender exists; otherwise the job ends with `quota_exhausted` and a `retry_at`. A 503 (`upstream_unavailable`) parks the account for 3 minutes and reruns an untouched task on another account; if the job still ends with `upstream_unavailable` and agy had not done anything, start it again with `restart <job>` or a rewritten prompt rather than `continue`. An authentication failure is never retried: run `agy-crew accounts login <name>` in your own terminal.
 - **`operation not permitted` on `~/.gemini/...` / `bind: operation not permitted` / sudden "authentication failed" while `agy` works in your terminal** — check whether a harness command sandbox is blocking access. AGY needs its OAuth credentials and a localhost port for its internal language server; allowing workspace writes alone may not provide that access. Where those restrictions apply, use the host's authorization mechanism to run the companion in a context that supports AGY. Use the same permission context to start and manage a job.
 - **False crash report on `wait`/`status` ("finished with status crashed and no stored result")** — the background job was started in one permission or sandbox context (e.g. unsandboxed) and collected from another (e.g. inside a command sandbox). The collector cannot see the worker PID across the sandbox boundary and misclassifies the running job as crashed. Run management commands (`wait`, `status`, `result`) in the same unsandboxed permission context as the job start; rerunning from the unsandboxed context resumes waiting or reporting normal status.
 - **Empty response, "status SUCCESS"** — a restricted run may report success even when its tool calls were denied. Check whether the profile came from a flag, repository policy or an earlier conversation. Use `setup` to configure allowed commands, or pass `--unrestricted` explicitly if authorized; dropping `--restricted` alone does not override an inherited profile. Some native tools remain unavailable in restricted headless runs even with allow-rules. An empty response from unrestricted mode or tool-free ask needs a separate diagnosis; retain the diagnostics and report it.
@@ -471,7 +478,7 @@ To get upstream back later, run `agy-crew uninstall --all` first.
 
 ## Upgrading
 
-Claude Code and Codex cache the plugin under a per-**version** directory (e.g. `cache/agy-crew/agy-crew/0.9.3`) and key "is it current?" on that version string, not on the commit. Bump their manifests and `package.json` together when preparing a release. Pi's Git source instead follows the configured ref; local sources read the checkout directly.
+Claude Code and Codex cache the plugin under a per-**version** directory (e.g. `cache/agy-crew/agy-crew/0.9.4`) and key "is it current?" on that version string, not on the commit. Bump their manifests and `package.json` together when preparing a release. Pi's Git source instead follows the configured ref; local sources read the checkout directly.
 
 - **Terminal command (`agy-crew install`)** — for an npm install, run `npm install -g agy-crew@latest`, then `agy-crew install` to render a fresh bundle and re-link; restart the harness. For a checkout, `git pull` is live at once for the source, and `agy-crew install` refreshes the bundle. See [Install command](#install-command).
 - **Claude Code** — `claude plugin marketplace update agy-crew` refreshes the marketplace clone, then `claude plugin update agy-crew@agy-crew` re-copies it into the cache. `install` is **not** the upgrade command: on an already-installed plugin it answers "already installed" and does nothing, whatever the version. And `update` only moves if the version string changed — on an unchanged version it answers "already at the latest version" and leaves the old commit in place. Force the current commit in with `claude plugin uninstall agy-crew@agy-crew && claude plugin install agy-crew@agy-crew`. Restart Claude Code afterwards either way — skills are registered at session start.

package/docs/REFERENCE.zh-CN.md

@@ -286,7 +286,7 @@ review --prompt "Review the patch at /tmp/change.patch"
 **`auto` 的选择规则。** 候选账号必须已启用、有令牌文件、没有认证错误、在该模型家族上没有生效的冷却，并且缓存的 Cloud Code 快照没有显示该家族所属配额池剩余为 0 且重置时间尚未到来。候选账号依次按以下条件排序：
 
 1. 当前租约最少（空闲账号优先于忙碌账号）；
-2. 已知的剩余配额比例最高（取短窗口和每周窗口中较小的一个；未知的排在所有已知且大于 0 的值之后）；
+2. 已知的剩余配额比例最高（取短窗口和每周窗口中较小的一个，按 5% 一档比较，额度相近的账号按最久未使用轮换；未知的排在所有已知且大于 0 的值之后）；
 3. `last_used_at` 最早；
 4. 添加顺序。
 
@@ -308,6 +308,12 @@ review --prompt "Review the patch at /tmp/change.patch"
 - **已有会话 ID，且会话绑定在某个池账号上**：尝试凭据借用（见下文）。找到出借方时，任务带着这段提示继续："Your previous turn stopped because the account hit a quota limit. Continue the same task from where you stopped; do not repeat finished steps."
 - **其他情况任务失败**，原因为 `quota_exhausted`。后台任务在已有会话 ID 时状态为 `attention`，没有时为 `error`；结果中包含 `retry_at` 和恢复说明（`continue --job <id>`，在 `<retry_at>` 之后；其他池账号空闲时会自动借用凭据）。前台任务以相同信息退出：有会话 ID 时退出码为 5，否则为 1。是否继续由调用方决定，companion 不会循环重试。
 
+**上游 503（`upstream_unavailable`）。** agy 以 `UNAVAILABLE (code 503)` 或 `No capacity available for model ...` 放弃时（它自己已经重试约八次，大约两分钟），companion 会为该账号和模型家族记录一条 **3 分钟**的短冷却，原因为 `upstream_unavailable`，这样无论是本次运行还是之后单独的运行，下一次选择都会换一个账号。503 冷却不会缩短仍在生效的额度冷却。最多额外尝试 2 次：
+
+- **还没有会话 ID，或者任务从新会话开始且工作区没有变化**（`ask` 恒为如此，其他模式要求 `git status` 没有新增内容），并且账号由 `auto` 选出：用原始提示词在另一个账号上开一个新会话重跑。这是重写任务，不是继续任务。
+- **工作区已有改动，且会话绑定在某个池账号上**：与额度失败相同，走凭据借用继续。
+- **其他情况任务失败**，原因为 `upstream_unavailable`，已有会话 ID 时退出码为 5（后台任务为 `attention`），否则为 1。恢复说明会告诉调用方：agy 还什么都没做时重新开始任务（`restart <job>`），只有工作区已经有改动时才用 `continue`。显式指定的 `--account` 不会被换到其他账号。
+
 池账号上的**认证失败**（`401`、`403` 或 `unauthenticated`，并带有 auth、credential、login 或 token 字样）会记录该账号的认证错误。之后选择时会跳过它，`list` 显示 `needs login`，运行 `accounts login <name>` 后恢复。认证失败从不重试。
 
 ### 凭据借用
@@ -364,6 +370,7 @@ review --prompt "Review the patch at /tmp/change.patch"
 | 情况 | 原因与输出 | 退出码 |
 | --- | --- | --- |
 | `auto` 没有候选账号，或运行中遇到配额错误且没有可借用的出借方 | `quota_exhausted`，附 `retry_at`（没有候选时按账号分别列出） | 已有会话 ID 时为 5，否则为 1；后台任务相应地以 `attention` 或 `error` 结束 |
+| 模型返回 503 / 没有容量，且没有账号或出借方可以继续 | `upstream_unavailable`，附 `retry_at`（最后一次 503 之后 3 分钟） | 已有会话 ID 时为 5，否则为 1；后台任务相应地以 `attention` 或 `error` 结束 |
 | 池账号认证失败 | 账号标记为 `needs login`，不重试 | 按普通错误处理 |
 | 显式指定的 `--account <name>` 不存在、已停用、处于冷却或需要登录 | 启动前报错并说明原因 | 1 |
 | `--account` 与已绑定的会话冲突 | `conversation <id> belongs to account <x>` | 1 |
@@ -400,7 +407,7 @@ review --prompt "Review the patch at /tmp/change.patch"
 
 ### 池账号配额用尽或需要登录
 
-池账号遇到配额错误时，companion 会记录冷却；如果还有其他账号，或有空闲账号可以出借凭据，任务会在运行内部恢复。否则任务以 `quota_exhausted` 结束，并附上 `retry_at`。认证失败不会重试：请在自己的终端里运行 `agy-crew accounts login <name>`。详见[账号池](#账号池)。
+池账号遇到配额错误时，companion 会记录冷却；如果还有其他账号，或有空闲账号可以出借凭据，任务会在运行内部恢复。否则任务以 `quota_exhausted` 结束，并附上 `retry_at`。遇到 503（`upstream_unavailable`）时账号冷却 3 分钟，没有改动过工作区的任务会换账号重跑；如果任务仍以 `upstream_unavailable` 结束且 agy 还什么都没做，请用 `restart <job>` 或改写提示词重新开始，不要 `continue`。认证失败不会重试：请在自己的终端里运行 `agy-crew accounts login <name>`。详见[账号池](#账号池)。
 
 ### 参数和任务被放进了同一个字符串
 
@@ -562,7 +569,7 @@ agy-crew 与上游 [agy-staff](https://github.com/keli-wen/agy-staff) 不能安
 
 ## 升级
 
-Claude Code 和 Codex 按版本号缓存插件，例如 `cache/agy-crew/agy-crew/0.9.3`。缓存是否需要更新取决于版本号，而不是仓库的最新提交。因此，准备发布时需要同步更新两个插件 manifest 和 `package.json` 中的版本。
+Claude Code 和 Codex 按版本号缓存插件，例如 `cache/agy-crew/agy-crew/0.9.4`。缓存是否需要更新取决于版本号，而不是仓库的最新提交。因此，准备发布时需要同步更新两个插件 manifest 和 `package.json` 中的版本。
 
 ### 终端命令（`agy-crew install`）
 

package/opencode-skills/agy-crew-jobs/SKILL.md

@@ -79,6 +79,7 @@ Include relevant decisions made in the host conversation, what changed, and what
 With a pool configured, the companion handles quota inside the run: it records a cooldown for that account and model family, and either fails over to another account (when no conversation existed yet) or borrows an idle account's credential to continue the same conversation. Nothing for you to do when the job still finishes `done`.
 
 - **`quota_exhausted`** (status `attention`, exit 5, when a conversation exists; otherwise `error`) means no account could continue. The result and `observe` include `retry_at`. Report it, keep the job id, and offer `continue --job <id> --prompt "..."` after `retry_at`, or sooner once `accounts list` shows another account idle (a credential loan is then used automatically). Ask before continuing, as with a timeout. Never loop retries and never clear a cooldown yourself. Without a conversation, a new run with `--account auto`, `--account live` or another model family is the alternative; propose it to the user.
+- **`upstream_unavailable`** (agy's `UNAVAILABLE (code 503): No capacity available for model ...`; status `attention` when a conversation exists, otherwise `error`) means the model itself had no capacity. agy has already retried internally, and the companion has already parked that account briefly and tried another one, so do not loop. **If agy had not done anything yet** (clean `git status`, no partial result in the job output), **rewrite the task and start it as a new run (`restart <job id>`, or a fresh dispatch with the prompt rewritten). Do not use `continue`**: a continuation stays bound to the original account and conversation, and the 503 gave it nothing to continue from. Use `continue --job <id>` only when agy had already changed the workspace; inspect `git status` and `git diff` first, and say what was left unfinished in the prompt. Offer a retry after `retry_at` (a few minutes), or another model family when the outage persists; ask the user before retrying a second time.
 - **`needs login`** (an authentication failure on a pool account) is not retried. Tell the user to run `agy-crew accounts login <name>` in their own terminal; it opens a browser, so you must not run it.
 - An unknown, disabled or cooling explicit `--account <name>` fails before launch with the reason; use `auto` or another account.
 

package/opencode-skills/agy-crew-jobs/references/troubleshooting.md

@@ -26,6 +26,14 @@ When agy reports an error but response text came back, the companion delivers th
 
 `reason=quota_exhausted` with a `retry_at` means the account (and any idle account that could lend a credential) hit its quota for that model family. Failover and credential loans have already been tried inside the run, so do not retry in a loop. Offer `continue --job <id>` after `retry_at`, or when `accounts list` shows an idle account; with no conversation, offer a new run with another `--account` or model family. `accounts quota --refresh` shows current numbers when the user wants them.
 
+## upstream_unavailable (503, no capacity)
+
+`reason=upstream_unavailable` means agy got `UNAVAILABLE (code 503): No capacity available for model ...` from the server, after its own internal retries (roughly two minutes each time). The companion has parked that account for the model family for a few minutes and tried other accounts where it could, so another account or a loan is not worth trying by hand; do not retry in a loop.
+
+- **agy had not done anything yet** (clean `git status`, no partial result): rewrite the task and run it again as a new run, with `restart <job id>` or a new dispatch with an updated prompt. **Do not use `continue`.** A continuation is bound to the original account and conversation, which holds nothing useful, and it only repeats the failing request.
+- **agy had already changed the workspace**: inspect `git status` and `git diff`, then `continue --job <id>` with a prompt that says what is done and what is left. Ask the user first, as with a timeout.
+- The outage may be model-wide. After `retry_at` try once more, or offer another model family; ask before a second retry.
+
 An authentication failure on a pool account marks it `needs login` and is never retried. The user must run `agy-crew accounts login <name>` in their own terminal (browser sign-in); do not run it yourself. Live authentication failures still mean running `agy` interactively once.
 
 ## Retry rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agy-crew",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Delegate work to Google's Antigravity CLI (agy) across a pool of accounts. A fork of agy-staff.",
   "bin": {
     "agy-crew": "companion/agy-companion.mjs"

package/pi-skills/agy-crew-jobs/SKILL.md

@@ -79,6 +79,7 @@ Include relevant decisions made in the host conversation, what changed, and what
 With a pool configured, the companion handles quota inside the run: it records a cooldown for that account and model family, and either fails over to another account (when no conversation existed yet) or borrows an idle account's credential to continue the same conversation. Nothing for you to do when the job still finishes `done`.
 
 - **`quota_exhausted`** (status `attention`, exit 5, when a conversation exists; otherwise `error`) means no account could continue. The result and `observe` include `retry_at`. Report it, keep the job id, and offer `continue --job <id> --prompt "..."` after `retry_at`, or sooner once `accounts list` shows another account idle (a credential loan is then used automatically). Ask before continuing, as with a timeout. Never loop retries and never clear a cooldown yourself. Without a conversation, a new run with `--account auto`, `--account live` or another model family is the alternative; propose it to the user.
+- **`upstream_unavailable`** (agy's `UNAVAILABLE (code 503): No capacity available for model ...`; status `attention` when a conversation exists, otherwise `error`) means the model itself had no capacity. agy has already retried internally, and the companion has already parked that account briefly and tried another one, so do not loop. **If agy had not done anything yet** (clean `git status`, no partial result in the job output), **rewrite the task and start it as a new run (`restart <job id>`, or a fresh dispatch with the prompt rewritten). Do not use `continue`**: a continuation stays bound to the original account and conversation, and the 503 gave it nothing to continue from. Use `continue --job <id>` only when agy had already changed the workspace; inspect `git status` and `git diff` first, and say what was left unfinished in the prompt. Offer a retry after `retry_at` (a few minutes), or another model family when the outage persists; ask the user before retrying a second time.
 - **`needs login`** (an authentication failure on a pool account) is not retried. Tell the user to run `agy-crew accounts login <name>` in their own terminal; it opens a browser, so you must not run it.
 - An unknown, disabled or cooling explicit `--account <name>` fails before launch with the reason; use `auto` or another account.
 

package/pi-skills/agy-crew-jobs/references/troubleshooting.md

@@ -26,6 +26,14 @@ When agy reports an error but response text came back, the companion delivers th
 
 `reason=quota_exhausted` with a `retry_at` means the account (and any idle account that could lend a credential) hit its quota for that model family. Failover and credential loans have already been tried inside the run, so do not retry in a loop. Offer `continue --job <id>` after `retry_at`, or when `accounts list` shows an idle account; with no conversation, offer a new run with another `--account` or model family. `accounts quota --refresh` shows current numbers when the user wants them.
 
+## upstream_unavailable (503, no capacity)
+
+`reason=upstream_unavailable` means agy got `UNAVAILABLE (code 503): No capacity available for model ...` from the server, after its own internal retries (roughly two minutes each time). The companion has parked that account for the model family for a few minutes and tried other accounts where it could, so another account or a loan is not worth trying by hand; do not retry in a loop.
+
+- **agy had not done anything yet** (clean `git status`, no partial result): rewrite the task and run it again as a new run, with `restart <job id>` or a new dispatch with an updated prompt. **Do not use `continue`.** A continuation is bound to the original account and conversation, which holds nothing useful, and it only repeats the failing request.
+- **agy had already changed the workspace**: inspect `git status` and `git diff`, then `continue --job <id>` with a prompt that says what is done and what is left. Ask the user first, as with a timeout.
+- The outage may be model-wide. After `retry_at` try once more, or offer another model family; ask before a second retry.
+
 An authentication failure on a pool account marks it `needs login` and is never retried. The user must run `agy-crew accounts login <name>` in their own terminal (browser sign-in); do not run it yourself. Live authentication failures still mean running `agy` interactively once.
 
 ## Retry rules

package/skills/jobs/SKILL.md

@@ -79,6 +79,7 @@ Include relevant decisions made in the host conversation, what changed, and what
 With a pool configured, the companion handles quota inside the run: it records a cooldown for that account and model family, and either fails over to another account (when no conversation existed yet) or borrows an idle account's credential to continue the same conversation. Nothing for you to do when the job still finishes `done`.
 
 - **`quota_exhausted`** (status `attention`, exit 5, when a conversation exists; otherwise `error`) means no account could continue. The result and `observe` include `retry_at`. Report it, keep the job id, and offer `continue --job <id> --prompt "..."` after `retry_at`, or sooner once `accounts list` shows another account idle (a credential loan is then used automatically). Ask before continuing, as with a timeout. Never loop retries and never clear a cooldown yourself. Without a conversation, a new run with `--account auto`, `--account live` or another model family is the alternative; propose it to the user.
+- **`upstream_unavailable`** (agy's `UNAVAILABLE (code 503): No capacity available for model ...`; status `attention` when a conversation exists, otherwise `error`) means the model itself had no capacity. agy has already retried internally, and the companion has already parked that account briefly and tried another one, so do not loop. **If agy had not done anything yet** (clean `git status`, no partial result in the job output), **rewrite the task and start it as a new run (`restart <job id>`, or a fresh dispatch with the prompt rewritten). Do not use `continue`**: a continuation stays bound to the original account and conversation, and the 503 gave it nothing to continue from. Use `continue --job <id>` only when agy had already changed the workspace; inspect `git status` and `git diff` first, and say what was left unfinished in the prompt. Offer a retry after `retry_at` (a few minutes), or another model family when the outage persists; ask the user before retrying a second time.
 - **`needs login`** (an authentication failure on a pool account) is not retried. Tell the user to run `agy-crew accounts login <name>` in their own terminal; it opens a browser, so you must not run it.
 - An unknown, disabled or cooling explicit `--account <name>` fails before launch with the reason; use `auto` or another account.
 

package/skills/jobs/references/troubleshooting.md

@@ -24,6 +24,14 @@ When agy reports an error but response text came back, the companion delivers th
 
 `reason=quota_exhausted` with a `retry_at` means the account (and any idle account that could lend a credential) hit its quota for that model family. Failover and credential loans have already been tried inside the run, so do not retry in a loop. Offer `continue --job <id>` after `retry_at`, or when `accounts list` shows an idle account; with no conversation, offer a new run with another `--account` or model family. `accounts quota --refresh` shows current numbers when the user wants them.
 
+## upstream_unavailable (503, no capacity)
+
+`reason=upstream_unavailable` means agy got `UNAVAILABLE (code 503): No capacity available for model ...` from the server, after its own internal retries (roughly two minutes each time). The companion has parked that account for the model family for a few minutes and tried other accounts where it could, so another account or a loan is not worth trying by hand; do not retry in a loop.
+
+- **agy had not done anything yet** (clean `git status`, no partial result): rewrite the task and run it again as a new run, with `restart <job id>` or a new dispatch with an updated prompt. **Do not use `continue`.** A continuation is bound to the original account and conversation, which holds nothing useful, and it only repeats the failing request.
+- **agy had already changed the workspace**: inspect `git status` and `git diff`, then `continue --job <id>` with a prompt that says what is done and what is left. Ask the user first, as with a timeout.
+- The outage may be model-wide. After `retry_at` try once more, or offer another model family; ask before a second retry.
+
 An authentication failure on a pool account marks it `needs login` and is never retried. The user must run `agy-crew accounts login <name>` in their own terminal (browser sign-in); do not run it yourself. Live authentication failures still mean running `agy` interactively once.
 
 ## Retry rules