takomi 2.1.29 → 2.1.30

package/.pi/agents/coder.md

@@ -42,6 +42,12 @@ If scope is unclear, ask a focused question instead of guessing.
 - handle errors and edge cases deliberately
 - avoid broad refactors unless requested or required
 
+## Tool-Use Safety
+- Keep `bash` commands short; use them for filesystem operations, running scripts, inspections, and verification.
+- Do not embed large generated files or long scripts directly in `bash` heredocs.
+- Use `write` for large files, or `write` a small generator script to disk and then run it.
+- If a command fails with `ENAMETOOLONG`, stop using the oversized inline command and switch to file-based writes or a written script.
+
 ## Phase 4: Verification
 After edits, run the strongest practical checks for the repo.
 For TypeScript/TSX work, prefer `npx tsc --noEmit` or the project equivalent.

package/.pi/agents/orchestrator.md

@@ -90,6 +90,22 @@ Task packets should be self-contained enough for a subagent to execute without g
 
 Keep human-readable markdown meaningful; keep JSON as tracking/continuity metadata.
 
+### Tool-Use Safety for Authored Plans
+- Do not pack large markdown plans, task packets, or generator scripts into one oversized `bash` command.
+- Prefer direct markdown authorship through the appropriate file-writing path, then register the same content with `takomi_board`.
+- If repeated files are needed, write a small generator script to disk first and run it with a short shell command.
+- If `ENAMETOOLONG` occurs, switch immediately to file-based writes or a written generator script instead of retrying the inline command.
+
+### Stage Expansion Quality Gate
+Before calling `takomi_board expand_stage`:
+- Write or provide full `taskMarkdown` for every expanded task.
+- Ensure each task has real Scope, Definition of Done, Expected Artifacts, Dependencies, and Verification/Review checkpoint.
+- Include exact prime-agent context paths and relevant FR/mockup/design docs.
+- For Build, decompose by implementation slice and FR coverage, not just broad labels like “school workflows.”
+- If a detailed subagent prompt is needed, the task packet should contain the same level of detail before launch.
+- Do not leave generated task files with `Scope: None specified`, `Definition Of Done: None specified`, or `Expected Artifacts: None specified`.
+- If `takomi_board` produced generic task packets, immediately repair them with detailed markdown before dispatching more work.
+
 ## Phase 4: Delegation
 When delegating:
 - send self-contained task instructions

package/.pi/extensions/oauth-router/README.md

@@ -27,6 +27,8 @@ Pi extension that auto-loads and registers an `oauth-router` provider with multi
   - weighted round robin
   - 429 cooldowns
   - transient failure penalties
+  - client/network transport failure tracking without default account cooldown
+  - 5 router-level client/network retries by default before pre-output failover, starting at 5s and doubling
   - auth failure quarantine
   - safe pre-output failover
 
@@ -45,7 +47,7 @@ The extension ships with two default upstream profiles:
    - api: `openai-responses`
    - default models: `gpt-4o`, `gpt-4.1`, `o4-mini`
 
-Edit `~/.pi/agent/oauth-router/config.json` to add more upstreams, swap endpoints, or change model catalogs.
+Edit `~/.pi/agent/oauth-router/config.json` to add more upstreams, swap endpoints, change model catalogs, or tune retry behavior. By default client-side transport failures such as `Codex SSE response headers timed out after 10000ms` retry the same account 5 times with exponential backoff (`5s`, `10s`, `20s`, `40s`, then capped at `60s`) before router failover. These failures are recorded but do not cool down an account unless `clientNetworkPenaltyMs` is set above `0`.
 
 ## Setup
 
@@ -98,7 +100,7 @@ Health and local usage state live separately in:
 
 - `~/.pi/agent/oauth-router/state.json`
 
-The router records successful request usage per account for rolling local 5-hour and weekly windows. These are router-observed counters only. `/router-refresh-usage [id|all]` now also probes configured authenticated provider endpoints for ChatGPT/Codex quota windows, then falls back to safe token claims such as account id, token expiry, issuer, subject, and available claim keys. `/router-usage` shows a compact visual quota view; `/router-usage-raw [id]` shows detailed/raw provider data. Provider-side quota counters depend on undocumented upstream endpoints and may change; they are not normally present in the OAuth token itself.
+The router records successful request usage per account for rolling local 5-hour and weekly windows. These are router-observed counters only. `/router-refresh-usage [id|all]` probes ChatGPT/Codex provider quota from `/backend-api/wham/usage` first and treats `rate_limit.primary_window.used_percent` as the 5-hour window and `rate_limit.secondary_window.used_percent` as the weekly window. It then falls back to safe token claims such as account id, token expiry, issuer, subject, and available claim keys. `/router-usage` shows a compact visual quota view; `/router-usage-raw [id]` shows detailed/raw provider data. Provider-side quota counters depend on undocumented upstream endpoints and may change; they are not normally present in the OAuth token itself.
 
 Most account commands accept an optional account ID. When run in the Pi UI without an ID, the extension opens an account picker instead of dumping the same account list repeatedly.
 

package/.pi/extensions/oauth-router/commands.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { createAccountFromUpstream } from "./oauth-flow.ts";
 import type { RouterStatusRow, RouterUsageSummary, RouterUsageWindowSummary, RoutingPolicyName, StoredRouterAccount } from "./types.ts";
 import { RouterRuntime } from "./provider.ts";
@@ -98,7 +98,8 @@ export function formatStatusReport(runtime: RouterRuntime): string {
             `  upstream=${row.upstream} enabled=${row.enabled} weight=${row.weight} state=${health}`,
             `  lastUsed=${formatLastUsedSummary(row.lastUsedAt)} | lastStatus=${row.lastStatus ?? "-"} | expires=${formatWhen(row.expires)}`,
             `  successes=${row.successCount} failures=${row.failures} 429s=${row.rateLimitCount} authFailures=${row.authFailureCount}`,
-          ].join("\n");
+            row.lastError ? `  lastError=${row.lastError}` : undefined,
+          ].filter((line): line is string => Boolean(line)).join("\n");
         })
     : ["- No accounts configured yet. Use /router-login add."];
 
@@ -118,7 +119,18 @@ export function formatStatusReport(runtime: RouterRuntime): string {
   ].join("\n");
 }
 
-export function formatAccountsReport(runtime: RouterRuntime): string {
+export async function refreshUsageAfterCredentialChange(runtime: RouterRuntime, accountId: string): Promise<string> {
+  try {
+    const snapshot = await runtime.refreshUsageSnapshot(accountId);
+    const windows = [snapshot.fiveHour ? "5h" : undefined, snapshot.weekly ? "weekly" : undefined].filter(Boolean).join("/");
+    return ` Provider usage refreshed (${snapshot.source}${windows ? `, ${windows}` : ""}).`;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return ` Provider usage refresh failed: ${message}`;
+  }
+}
+
+function formatAccountsReport(runtime: RouterRuntime): string {
   const rows = runtime.getStatusRows();
   const accounts = rows.length
     ? [...rows]
@@ -404,13 +416,15 @@ async function handleRouterLogin(pi: ExtensionAPI, runtime: RouterRuntime, args:
           updatedAt: Date.now(),
         });
         runtime.clearAccountHealth(duplicate.id);
+        const usageMessage = await refreshUsageAfterCredentialChange(runtime, duplicate.id);
         setFooterStatus(ctx, runtime);
-        emitReport(pi, `Updated existing account ${duplicate.id} (${duplicate.label}) with fresh credentials instead of adding a duplicate. Run /router-refresh-usage ${duplicate.id} to refresh provider quota metadata.`);
+        emitReport(pi, `Updated existing account ${duplicate.id} (${duplicate.label}) with fresh credentials instead of adding a duplicate.${usageMessage}`);
         return;
       }
       runtime.addAccount(account);
+      const usageMessage = await refreshUsageAfterCredentialChange(runtime, account.id);
       setFooterStatus(ctx, runtime);
-      emitReport(pi, `Added account ${account.id} (${account.label}) for upstream ${upstream.id}. Run /router-refresh-usage ${account.id} to refresh provider quota metadata.`);
+      emitReport(pi, `Added account ${account.id} (${account.label}) for upstream ${upstream.id}.${usageMessage}`);
       ctx.ui.notify(`Added ${account.id}`, "info");
       return;
     }
@@ -459,15 +473,17 @@ async function handleRouterLogin(pi: ExtensionAPI, runtime: RouterRuntime, args:
         updatedAt: Date.now(),
       });
       runtime.clearAccountHealth(existing.id);
+      const usageMessage = await refreshUsageAfterCredentialChange(runtime, existing.id);
       setFooterStatus(ctx, runtime);
-      emitReport(pi, `Re-logged account ${existing.id} (${existing.label}) and cleared auth state. Run /router-refresh-usage ${existing.id} to refresh provider quota metadata.`);
+      emitReport(pi, `Re-logged account ${existing.id} (${existing.label}) and cleared auth state.${usageMessage}`);
       return;
     }
     case "refresh": {
       const account = await pickAccount(runtime, ctx, first, "Choose account to refresh");
       const refreshed = await runtime.refreshAccount(account.id);
+      const usageMessage = await refreshUsageAfterCredentialChange(runtime, refreshed.id);
       setFooterStatus(ctx, runtime);
-      emitReport(pi, `Refreshed account ${refreshed.id} (${refreshed.label}). Run /router-refresh-usage ${refreshed.id} to refresh provider quota metadata.`);
+      emitReport(pi, `Refreshed account ${refreshed.id} (${refreshed.label}).${usageMessage}`);
       return;
     }
     case "help":
@@ -555,8 +571,20 @@ export function registerRouterCommands(pi: ExtensionAPI, runtime: RouterRuntime)
       const [requestedId] = parseArgs(args || "");
       const target = await pickUsageTarget(runtime, ctx, requestedId);
       const ids = target === "all" ? runtime.listAccounts().map((account) => account.id) : [target];
-      for (const accountId of ids) await runtime.refreshUsageSnapshot(accountId);
-      emitReport(pi, formatUsageReport(runtime, target === "all" ? undefined : target));
+      const failures: string[] = [];
+
+      for (const accountId of ids) {
+        try {
+          await runtime.refreshUsageSnapshot(accountId);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          failures.push(`- ${accountId}: ${message}`);
+        }
+      }
+
+      const report = formatUsageReport(runtime, target === "all" ? undefined : target);
+      emitReport(pi, failures.length ? [report, "", "## Refresh failures", ...failures].join("\n") : report);
+      if (failures.length) ctx.ui.notify(`oauth-router usage refreshed with ${failures.length} failure(s)`, "error");
       setFooterStatus(ctx, runtime);
     },
   });

package/.pi/extensions/oauth-router/config.ts

@@ -98,7 +98,7 @@ const DEFAULT_UPSTREAMS: RouterUpstreamConfig[] = [
     modelIds: ["gpt-5.1", "gpt-5.4", "gpt-5.4-mini", "gpt-5.5"],
     usageProbe: {
       enabled: true,
-      timeoutMs: 2_500,
+      timeoutMs: 8_000,
       endpoints: [
         "/wham/usage",
         "/codex/usage",
@@ -117,6 +117,12 @@ export const DEFAULT_CONFIG: RouterConfig = {
   tokenRefreshSkewMs: 60_000,
   rateLimitCooldownMs: 120_000,
   transientPenaltyMs: 30_000,
+  upstreamMaxRetries: 0,
+  upstreamMaxRetryDelayMs: 60_000,
+  clientNetworkMaxRetries: 5,
+  clientNetworkRetryBaseDelayMs: 5_000,
+  clientNetworkMaxRetryDelayMs: 60_000,
+  clientNetworkPenaltyMs: 0,
   models: DEFAULT_MODELS,
   upstreams: DEFAULT_UPSTREAMS,
 };

package/.pi/extensions/oauth-router/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerRouterCommands, formatStatusReport } from "./commands.ts";
 import { registerRouterProvider, RouterRuntime } from "./provider.ts";
 

package/.pi/extensions/oauth-router/oauth-flow.ts

@@ -3,7 +3,7 @@ import { Buffer } from "node:buffer";
 import { randomUUID } from "node:crypto";
 import type { OAuthCredentials, OAuthSelectPrompt } from "@earendil-works/pi-ai/oauth";
 import { getOAuthProvider } from "@earendil-works/pi-ai/oauth";
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { RouterProviderQuotaWindow, RouterProviderUsageSnapshot, RouterUpstreamConfig, StoredRouterAccount } from "./types.ts";
 
 function now() {
@@ -197,7 +197,8 @@ export function inspectAccountToken(account: StoredRouterAccount): RouterProvide
     getStringClaim(claims, "account_id");
   const planType =
     (typeof account.meta?.planType === "string" ? account.meta.planType : undefined) ??
-    (openaiAuth && (getStringClaim(openaiAuth, "plan_type") ?? getStringClaim(openaiAuth, "planType"))) ??
+    (openaiAuth && (getStringClaim(openaiAuth, "chatgpt_plan_type") ?? getStringClaim(openaiAuth, "plan_type") ?? getStringClaim(openaiAuth, "planType"))) ??
+    getStringClaim(claims, "chatgpt_plan_type") ??
     getStringClaim(claims, "plan_type") ??
     getStringClaim(claims, "planType");
 
@@ -254,12 +255,16 @@ function normalizeResetAt(record: Record<string, unknown>): number | undefined {
   return raw < 10_000_000_000 ? raw * 1000 : raw;
 }
 
+function clampPercent(value: number): number {
+  return Math.max(0, Math.min(100, value));
+}
+
 function quotaFromRecord(label: string, record: Record<string, unknown>): RouterProviderQuotaWindow | undefined {
   const limit = firstNumber(record.limit, record.cap, record.total, record.max, record.quota);
   const remaining = firstNumber(record.remaining, record.available, record.left, record.remaining_messages, record.remainingMessages);
   const used = firstNumber(record.used, record.consumed, record.current, record.used_messages, record.usedMessages);
   const usedPercent = firstNumber(record.used_percent, record.usedPercent);
-  const percentRemaining = firstNumber(record.percent_remaining, record.percentRemaining, record.remaining_percent, record.remainingPercent) ?? (usedPercent !== undefined ? 100 - Math.max(0, Math.min(100, usedPercent)) : undefined);
+  const percentRemaining = firstNumber(record.percent_remaining, record.percentRemaining, record.remaining_percent, record.remainingPercent) ?? (usedPercent !== undefined ? 100 - clampPercent(usedPercent) : undefined);
   const resetAt = normalizeResetAt(record);
 
   if (limit === undefined && remaining === undefined && used === undefined && percentRemaining === undefined && resetAt === undefined) {
@@ -271,7 +276,24 @@ function quotaFromRecord(label: string, record: Record<string, unknown>): Router
     used,
     limit,
     remaining,
-    percentRemaining: percentRemaining !== undefined ? percentRemaining : limit && remaining !== undefined ? (remaining / limit) * 100 : undefined,
+    percentRemaining: percentRemaining !== undefined ? clampPercent(percentRemaining) : limit && remaining !== undefined ? clampPercent((remaining / limit) * 100) : undefined,
+    resetAt,
+  };
+}
+
+function quotaFromWhamWindow(label: string, window: Record<string, unknown> | undefined, limitReached?: boolean): RouterProviderQuotaWindow | undefined {
+  if (!window) return undefined;
+
+  const usedPercent = firstNumber(window.used_percent, window.usedPercent);
+  const explicitRemainingPercent = firstNumber(window.percent_remaining, window.percentRemaining, window.remaining_percent, window.remainingPercent);
+  const percentRemaining = explicitRemainingPercent ?? (usedPercent !== undefined ? 100 - clampPercent(usedPercent) : limitReached ? 0 : undefined);
+  const resetAt = normalizeResetAt(window);
+
+  if (percentRemaining === undefined && resetAt === undefined) return undefined;
+
+  return {
+    label,
+    percentRemaining: percentRemaining !== undefined ? clampPercent(percentRemaining) : undefined,
     resetAt,
   };
 }
@@ -282,20 +304,43 @@ function mergeQuota(previous: RouterProviderQuotaWindow | undefined, next: Route
   return { ...previous, ...next };
 }
 
+function pickWindow(record: Record<string, unknown>, snakeKey: string, camelKey: string): Record<string, unknown> | undefined {
+  const snake = record[snakeKey];
+  if (isRecord(snake)) return snake;
+  const camel = record[camelKey];
+  return isRecord(camel) ? camel : undefined;
+}
+
+function extractWhamUsage(json: unknown): Pick<RouterProviderUsageSnapshot, "planType" | "fiveHour" | "weekly"> {
+  if (!isRecord(json)) return {};
+
+  const planType = firstString(json.plan_type, json.planType, json.plan, json.subscription_plan, json.subscriptionPlan);
+  const rateLimit = isRecord(json.rate_limit) ? json.rate_limit : isRecord(json.rateLimit) ? json.rateLimit : undefined;
+  if (!rateLimit) return { planType };
+
+  const limitReached = Boolean(rateLimit.limit_reached ?? rateLimit.limitReached);
+  return {
+    planType,
+    fiveHour: quotaFromWhamWindow("5h", pickWindow(rateLimit, "primary_window", "primaryWindow"), limitReached),
+    weekly: quotaFromWhamWindow("weekly", pickWindow(rateLimit, "secondary_window", "secondaryWindow"), limitReached),
+  };
+}
+
 function extractProviderUsage(json: unknown): Pick<RouterProviderUsageSnapshot, "planType" | "fiveHour" | "weekly"> {
-  let planType: string | undefined;
-  let fiveHour: RouterProviderQuotaWindow | undefined;
-  let weekly: RouterProviderQuotaWindow | undefined;
+  const wham = extractWhamUsage(json);
+  let planType = wham.planType;
+  let fiveHour = wham.fiveHour;
+  let weekly = wham.weekly;
+
+  if (fiveHour || weekly) return { planType, fiveHour, weekly };
 
   walkRecords(json, (record) => {
     planType ??= firstString(record.plan_type, record.planType, record.plan, record.subscription_plan, record.subscriptionPlan, record.account_plan, record.accountPlan);
 
-    const rateLimit = isRecord(record.rate_limit) ? record.rate_limit : undefined;
+    const rateLimit = isRecord(record.rate_limit) ? record.rate_limit : isRecord(record.rateLimit) ? record.rateLimit : undefined;
     if (rateLimit) {
-      const primary = isRecord(rateLimit.primary_window) ? rateLimit.primary_window : isRecord(rateLimit.primaryWindow) ? rateLimit.primaryWindow : undefined;
-      const secondary = isRecord(rateLimit.secondary_window) ? rateLimit.secondary_window : isRecord(rateLimit.secondaryWindow) ? rateLimit.secondaryWindow : undefined;
-      fiveHour = mergeQuota(fiveHour, primary ? quotaFromRecord("5h", primary) : undefined);
-      weekly = mergeQuota(weekly, secondary ? quotaFromRecord("weekly", secondary) : undefined);
+      fiveHour = mergeQuota(fiveHour, quotaFromWhamWindow("5h", pickWindow(rateLimit, "primary_window", "primaryWindow"), Boolean(rateLimit.limit_reached ?? rateLimit.limitReached)));
+      weekly = mergeQuota(weekly, quotaFromWhamWindow("weekly", pickWindow(rateLimit, "secondary_window", "secondaryWindow"), Boolean(rateLimit.limit_reached ?? rateLimit.limitReached)));
     }
 
     const name = [record.name, record.label, record.bucket, record.window, record.period, record.type, record.key, record.id]
@@ -361,7 +406,7 @@ export async function refreshProviderUsageSnapshot(account: StoredRouterAccount,
 
   const accountId = base.accountId;
   const endpoints = Array.from(new Set(["/wham/usage", ...(upstream.usageProbe?.endpoints ?? [])]));
-  if (!accountId || endpoints.length === 0) {
+  if (endpoints.length === 0) {
     return { ...base, message: `${base.message ?? "Token inspected."} No provider usage probe endpoints are configured.` };
   }
 
@@ -382,17 +427,21 @@ export async function refreshProviderUsageSnapshot(account: StoredRouterAccount,
     const url = resolveProbeUrl(upstream.baseUrl, endpoint);
     lastEndpoint = url;
     try {
+      const headers: Record<string, string> = {
+        Authorization: `Bearer ${account.access}`,
+        Originator: "codex_cli_rs",
+        originator: "codex_cli_rs",
+        "User-Agent": "codex_cli_rs/0.133.0 (Windows; x86_64) pi/oauth-router",
+        accept: "application/json",
+      };
+      if (accountId) {
+        headers["ChatGPT-Account-Id"] = accountId;
+        headers["chatgpt-account-id"] = accountId;
+      }
+
       const { response, text } = await fetchJsonWithTimeout(url, {
         method: "GET",
-        headers: {
-          Authorization: `Bearer ${account.access}`,
-          "ChatGPT-Account-Id": accountId,
-          "chatgpt-account-id": accountId,
-          Originator: "codex_cli_rs",
-          originator: "codex_cli_rs",
-          "User-Agent": "codex_cli_rs/0.133.0 (Windows; x86_64) pi/oauth-router",
-          accept: "application/json",
-        },
+        headers,
       }, Math.max(1, remainingMs));
       lastStatus = response.status;
       lastHeaders = collectRateLimitHeaders(response.headers);

package/.pi/extensions/oauth-router/provider.ts

@@ -10,8 +10,8 @@ import {
   streamSimpleOpenAICodexResponses,
   streamSimpleOpenAICompletions,
   streamSimpleOpenAIResponses,
-} from "@mariozechner/pi-ai";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+} from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadRouterConfig } from "./config.ts";
 import { refreshAccountCredentials, getApiKeyForAccount, refreshProviderUsageSnapshot } from "./oauth-flow.ts";
 import { RouterAccountStore } from "./oauth-store.ts";
@@ -43,6 +43,21 @@ function parseRetryAfterMs(value: string | undefined): number | undefined {
   return undefined;
 }
 
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("Request was aborted"));
+      return;
+    }
+
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timeout);
+      reject(new Error("Request was aborted"));
+    }, { once: true });
+  });
+}
+
 function isMeaningfulEvent(event: AssistantMessageEvent): boolean {
   switch (event.type) {
     case "text_delta":
@@ -88,6 +103,25 @@ function isAbortLike(message?: string, signal?: AbortSignal, stopReason?: string
   return lower.includes("abort") || lower.includes("cancelled") || lower.includes("canceled");
 }
 
+function isClientNetworkFailure(lower: string): boolean {
+  return [
+    "codex sse response headers timed out",
+    "response headers timed out",
+    "headers timeout",
+    "headers timed out",
+    "fetch failed",
+    "network",
+    "econnreset",
+    "etimedout",
+    "enotfound",
+    "eai_again",
+    "socket hang up",
+    "connection reset",
+    "connection terminated",
+    "und_err_headers_timeout",
+  ].some((token) => lower.includes(token));
+}
+
 function classifyFailure(
   status: number | undefined,
   headers: Record<string, string>,
@@ -105,13 +139,15 @@ function classifyFailure(
     return { kind: "auth", status: status ?? 401, message };
   }
 
-  if (
-    (status !== undefined && status >= 500) ||
-    lower.includes("network") ||
-    lower.includes("fetch failed") ||
-    lower.includes("connection") ||
-    lower.includes("timeout")
-  ) {
+  if (isClientNetworkFailure(lower)) {
+    return { kind: "client-network", status, message };
+  }
+
+  if (status !== undefined && status >= 500) {
+    return { kind: "transient", status, message };
+  }
+
+  if (lower.includes("timeout") || lower.includes("service unavailable") || lower.includes("overloaded")) {
     return { kind: "transient", status: status ?? 500, message };
   }
 
@@ -218,11 +254,35 @@ export class RouterRuntime {
 
   async refreshUsageSnapshot(id: string) {
     this.reloadConfig();
-    const account = this.accounts.get(id);
+    let account = this.accounts.get(id);
     if (!account) throw new Error(`Unknown account: ${id}`);
     const upstream = this.getUpstream(account.upstreamId);
     if (!upstream) throw new Error(`Unknown upstream for account ${id}: ${account.upstreamId}`);
-    const snapshot = await refreshProviderUsageSnapshot(account, upstream);
+
+    const refreshIfPossible = async (reason: string): Promise<boolean> => {
+      if (!account || account.provider === "api-key") return false;
+      try {
+        account = await refreshAccountCredentials(account);
+        this.accounts.update(account);
+        this.state.clearHealth(id);
+        return true;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.state.markAuthFailure(id, 401, `Unable to refresh OAuth credentials for usage probe (${reason}): ${message}`);
+        throw error;
+      }
+    };
+
+    if (account.provider !== "api-key" && account.expires - this.config.tokenRefreshSkewMs <= now()) {
+      await refreshIfPossible("expired access token");
+    }
+
+    let snapshot = await refreshProviderUsageSnapshot(account, upstream);
+    if (account.provider !== "api-key" && (snapshot.status === 401 || snapshot.status === 403)) {
+      const refreshed = await refreshIfPossible(`provider quota probe returned HTTP ${snapshot.status}`);
+      if (refreshed) snapshot = await refreshProviderUsageSnapshot(account, upstream);
+    }
+
     this.state.setProviderUsage(id, snapshot);
     return snapshot;
   }
@@ -283,6 +343,7 @@ export class RouterRuntime {
         rateLimitCount: state.rateLimitCount,
         authFailureCount: state.authFailureCount,
         successCount: state.successCount,
+        lastError: state.lastError,
         expires: account.expires,
       };
     });
@@ -378,12 +439,49 @@ export class RouterRuntime {
           failure.message,
         );
         break;
+      case "client-network":
+        if (this.config.clientNetworkPenaltyMs > 0) {
+          this.state.markTransientFailure(accountId, this.config.clientNetworkPenaltyMs, failure.status ?? 500, failure.message);
+        } else {
+          this.state.recordClientNetworkFailure(accountId, failure.status, failure.message);
+        }
+        break;
       case "fatal":
         this.state.markTransientFailure(accountId, this.config.transientPenaltyMs, failure.status ?? 500, failure.message);
         break;
     }
   }
 
+  private getClientNetworkRetryDelayMs(retryIndex: number): number {
+    const baseDelayMs = Math.max(0, this.config.clientNetworkRetryBaseDelayMs);
+    const uncappedDelayMs = baseDelayMs * 2 ** retryIndex;
+    const maxDelayMs = this.config.clientNetworkMaxRetryDelayMs;
+    return maxDelayMs > 0 ? Math.min(uncappedDelayMs, maxDelayMs) : uncappedDelayMs;
+  }
+
+  private async tryAccountWithClientNetworkRetries(
+    selection: DelegateSelection,
+    outerStream: ReturnType<typeof createAssistantMessageEventStream>,
+    context: Context,
+    modelId: string,
+    options?: SimpleStreamOptions,
+  ): Promise<{ completed: boolean; emittedMeaningfulOutput: boolean; failure?: FailureClassification }> {
+    for (let retryIndex = 0; ; retryIndex += 1) {
+      const result = await this.trySingleAccount(selection, outerStream, context, options);
+      const canRetry =
+        !result.completed &&
+        !result.emittedMeaningfulOutput &&
+        result.failure?.kind === "client-network" &&
+        retryIndex < this.config.clientNetworkMaxRetries;
+
+      if (!canRetry) return result;
+
+      const delayMs = this.getClientNetworkRetryDelayMs(retryIndex);
+      await sleep(delayMs, options?.signal);
+      this.state.markAttempt(selection.account.id, modelId);
+    }
+  }
+
   private async trySingleAccount(
     selection: DelegateSelection,
     outerStream: ReturnType<typeof createAssistantMessageEventStream>,
@@ -402,6 +500,8 @@ export class RouterRuntime {
         ...(options?.headers ?? {}),
         ...selection.headers,
       },
+      maxRetries: options?.maxRetries ?? this.config.upstreamMaxRetries,
+      maxRetryDelayMs: options?.maxRetryDelayMs ?? this.config.upstreamMaxRetryDelayMs,
       onResponse: async (response, responseModel) => {
         responseStatus = response.status;
         responseHeaders = response.headers;
@@ -520,7 +620,7 @@ export class RouterRuntime {
             continue;
           }
 
-          const result = await this.trySingleAccount(selection, outer, context, options);
+          const result = await this.tryAccountWithClientNetworkRetries(selection, outer, context, model.id, options);
           if (result.completed) {
             outer.end();
             return;

package/.pi/extensions/oauth-router/state.ts

@@ -9,7 +9,7 @@ import type {
   RouterUsageWindowSummary,
   RoutingPolicyName,
 } from "./types.ts";
-import type { AssistantMessage } from "@mariozechner/pi-ai";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
 
 const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
@@ -335,6 +335,17 @@ export class RouterStateStore {
     });
   }
 
+  recordClientNetworkFailure(accountId: string, status: number | undefined, message = "Client/network transport failure") {
+    this.mutate(() => {
+      const account = this.ensureAccountInMemory(accountId);
+      account.lastStatus = status;
+      account.lastError = message;
+      account.failures += 1;
+      account.penaltyUntil = undefined;
+      account.cooldownUntil = undefined;
+    });
+  }
+
   clearHealth(accountId: string) {
     this.mutate(() => {
       const account = this.ensureAccountInMemory(accountId);

package/.pi/extensions/oauth-router/types.ts

@@ -1,4 +1,4 @@
-import type { Api, AssistantMessage, Context, Model, SimpleStreamOptions } from "@mariozechner/pi-ai";
+import type { Api, AssistantMessage, Context, Model, SimpleStreamOptions } from "@earendil-works/pi-ai";
 
 export type RouterUpstreamApi = "openai-completions" | "openai-responses" | "openai-codex-responses";
 export type RouterAuthMode = "oauth" | "api-key";
@@ -52,6 +52,18 @@ export interface RouterConfig {
   tokenRefreshSkewMs: number;
   rateLimitCooldownMs: number;
   transientPenaltyMs: number;
+  /** Default retry attempts passed to upstream providers when the caller does not specify one. */
+  upstreamMaxRetries: number;
+  /** Maximum provider-request retry delay when supported by the upstream provider. */
+  upstreamMaxRetryDelayMs: number;
+  /** Router-level same-account retries for local/client transport failures before account failover. */
+  clientNetworkMaxRetries: number;
+  /** First router-level retry delay for local/client transport failures. Later retries double this delay. */
+  clientNetworkRetryBaseDelayMs: number;
+  /** Maximum router-level retry delay for local/client transport failures. */
+  clientNetworkMaxRetryDelayMs: number;
+  /** Penalty for local/client transport failures. Zero records the failure without cooling down the account. */
+  clientNetworkPenaltyMs: number;
   models: RouterModelConfig[];
   upstreams: RouterUpstreamConfig[];
 }
@@ -180,6 +192,7 @@ export interface RouterStatusRow {
   rateLimitCount: number;
   authFailureCount: number;
   successCount: number;
+  lastError?: string;
   expires: number;
 }
 
@@ -200,7 +213,7 @@ export interface DelegateSelection {
 }
 
 export interface FailureClassification {
-  kind: "rate-limit" | "auth" | "transient" | "fatal";
+  kind: "rate-limit" | "auth" | "transient" | "client-network" | "fatal";
   status?: number;
   retryAfterMs?: number;
   message: string;