@oddessentials/agent-guild 0.31.0 → 0.33.0

package/src/manager/main.mjs

@@ -21,11 +21,13 @@ import { resolveBaseEnv, pathReader } from './shell-env.mjs';
 import { writeReportShims } from './report-shims.mjs';
 import { SessionHooks } from './session-hooks.mjs';
 import { launcherPath, spawnManager } from './launch.mjs';
+import { createAutostart } from './autostart.mjs';
 import {
   DEFAULT_HOST,
   PACKAGE_FILE,
   PACKAGE_NAME,
   VERSION,
+  dataDir,
   ensureDataDir,
   loadOrCreateToken,
   multiplexerStore,
@@ -40,8 +42,8 @@ const rootDir = path.resolve(here, '../..');
 
 const VERSION_REFRESH_MS = 60 * 60 * 1000;
 
-/** `version`, `packageFile` and `github` (GitHub's URLs and client id) stand in for the real ones in tests. */
-export async function startManager({ port = resolvePort(), host = DEFAULT_HOST, sessionDefaults, version = VERSION, packageFile = PACKAGE_FILE, github: githubOptions = {}, remoteAccess: remoteOptions = {} } = {}) {
+/** `version`, `packageFile`, `github` (GitHub's URLs and client id) and `autostart` stand in for the real ones in tests. */
+export async function startManager({ port = resolvePort(), host = DEFAULT_HOST, sessionDefaults, version = VERSION, packageFile = PACKAGE_FILE, github: githubOptions = {}, remoteAccess: remoteOptions = {}, autostart = null } = {}) {
   // Validate before creating files, processes or timers, so a typo fails startup cleanly.
   const remoteSettings = loadRemoteAccess(paths.remoteAccess);
   ensureDataDir();
@@ -82,6 +84,15 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   const modelStats = new ModelStats({ registry });
   const news = new NewsFeed({ registry });
   const changelog = new Changelog({ latest: () => selfUpdate.latest });
+  // A sign-in entry starts a manager with the default data folder, so one
+  // kept elsewhere (as tests do) cannot be given one.
+  autostart ??= createAutostart({
+    script: path.join(rootDir, 'bin', 'agent-guild.mjs'),
+    dataDir: dataDir(),
+    log: paths.log,
+    getPort: () => api.port,
+    unavailable: process.env.AGENT_GUILD_HOME ? 'Not available while AGENT_GUILD_HOME sets the data folder.' : null,
+  });
   let closing = null;
 
   const refreshVersions = () => {
@@ -143,6 +154,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
     extraHosts: remoteSettings.config.access.hosts,
     extraOrigins: remoteSettings.config.access.origins,
     remoteAccess,
+    autostart,
     notes: createNotesStore(paths.notes),
     launcher: launcherPath(),
     onShutdownRequest: ({ restart = false } = {}) => shutdown('requested via API', { restart }).then(() => process.exit(0)),
@@ -173,6 +185,7 @@ export async function startManager({ port = resolvePort(), host = DEFAULT_HOST,
   });
   console.log(`[manager] Agent Guild ${version} listening on ${api.url} (pid ${process.pid})`);
   refreshVersions();
+  autostart.refresh().catch((err) => console.warn(`[manager] could not update the sign-in entry: ${err.message}`));
   return { api, manager, registry, token, shutdown, remoteAccess };
 }
 

package/src/manager/server.mjs

@@ -115,6 +115,8 @@ export function createManagerServer({
   extraHosts = [],
   extraOrigins = [],
   remoteAccess = null,
+  /** Starting the manager at sign-in, or null where it is not offered. */
+  autostart = null,
   /** In-memory when omitted, so a test server never reads the user's notes file. */
   notes = createNotesStore(),
   folderOpener = createFolderOpener({ resolveCwd: (cwd) => manager.resolveCwd(cwd) }),
@@ -276,6 +278,15 @@ export function createManagerServer({
       return sendJson(res, 202, { remoteAccess: operation });
     }
 
+    if (autostart && route === '/autostart' && method === 'GET') {
+      return sendJson(res, 200, { autostart: await autostart.describe() });
+    }
+    if (autostart && route === '/autostart' && method === 'PUT') {
+      const { enabled } = await readJsonBody(req);
+      if (typeof enabled !== 'boolean') throw new HttpError(400, 'enabled must be true or false', 'bad_request');
+      return sendJson(res, 200, { autostart: await autostart.set(enabled) });
+    }
+
     if (route === '/info' && method === 'GET') {
       selfUpdate?.refresh().catch(() => {});
       return sendJson(res, 200, {
@@ -458,7 +469,7 @@ export function createManagerServer({
       const folder = manager.resolveCwd(url.searchParams.get('cwd'));
       return sendJson(res, 200, { folder, repo: folderOrigin(folder) });
     }
-    const view = route.match(/^\/github\/accounts\/([^/]+)\/repos\/([^/]+)\/([^/]+)\/(issues|actions|pulls)(?:\/([^/]+))?$/);
+    const view = route.match(/^\/github\/accounts\/([^/]+)\/repos\/([^/]+)\/([^/]+)\/(issues|actions|pulls|branches)(?:\/([^/]+))?$/);
     if (view) {
       let parts;
       try { parts = view.map((part) => (part === undefined ? part : decodeURIComponent(part))); } catch { throw new HttpError(400, 'repo must be a GitHub repository written as owner/name', 'bad_repo'); }
@@ -472,6 +483,7 @@ export function createManagerServer({
       if (kind === 'issues' && number !== undefined && method === 'PATCH') {
         return sendJson(res, 200, { issue: await views.updateIssue(id, owner, name, number, await readJsonBody(req)) });
       }
+      if (kind === 'branches' && number === undefined && method === 'GET') return sendJson(res, 200, await views.branches(id, owner, name, { page: url.searchParams.get('page') ?? '1' }));
       if (kind === 'actions' && number === undefined && method === 'GET') return sendJson(res, 200, await views.actions(id, owner, name));
       if (kind === 'pulls' && number === undefined && method === 'GET') return sendJson(res, 200, await views.pulls(id, owner, name));
     }

package/src/manager/session.mjs

@@ -23,6 +23,10 @@ const REPORTING_STATES = new Set(['pending', 'active', 'unavailable', 'setup_req
 const SHELL_EVENTS = new Set(['start', 'waiting', 'asked', 'background', 'end', 'running', 'reset']);
 const MAX_SHELLS = 256;
 const MAX_ENDED_TASKS = 256;
+// Keys and reports a terminal sends as escape sequences: X10 mouse reports (three raw bytes after ESC [ M), other CSI
+// and SS3 sequences, OSC and DCS strings (to their end, or the next ESC, so a large paste is scanned once), and ESC
+// with one character (Alt+key). Bracketed paste markers are CSI, so pasted text is kept.
+const ESCAPE_SEQUENCE = /\x1b\[M[\s\S]{3}|\x1b\[[0-?]*[ -/]*[@-~]|\x1bO[\s\S]|\x1b[\]P][^\x07\x1b]*(?:\x07|\x1b\\)?|\x1b[\s\S]?/g;
 
 /**
  * Colours reported to programs that query them (OSC 10/11/12), matching the
@@ -91,6 +95,7 @@ export class Session extends EventEmitter {
     this.reportingTimeoutMs = opts.reportingTimeoutMs ?? 30000;
     this.reporting = REPORTING_STATES.has(opts.reporting?.state) ? { state: opts.reporting.state, reason: opts.reporting.reason ?? null } : null;
     this._reportingTimer = null;
+    this._typedSinceEnter = false;
     this.shellDisplayDelayMs = opts.shellDisplayDelayMs ?? 600;
     this.shells = new Map();
     this._shellSeq = 0;
@@ -309,12 +314,12 @@ export class Session extends EventEmitter {
 
   input(data) {
     this.write(data);
-    if (this.reporting?.state === 'pending' && !this._reportingTimer && typeof data === 'string' && /[\r\n]/.test(data)) {
+    if (this.reporting?.state === 'pending' && !this._reportingTimer && typeof data === 'string' && this._sendsTypedLine(data)) {
       this._reportingTimer = setTimeout(() => {
         if (this.reporting?.state !== 'pending' || this.status !== 'running') return;
         this.reporting = {
           state: 'unavailable',
-          reason: `${this.provider.tool} has not run Agent Guild's reporting hooks yet. That is expected while it signs in or sets up; otherwise its hooks may be turned off, restricted by an administrator, or not trusted for this folder.`,
+          reason: `No report from ${this.provider.tool}'s hooks yet. They report once a prompt is sent; that can wait while ${this.provider.tool} signs in or sets up. If a prompt was sent and this stays, its hooks may be turned off, restricted by an administrator, or not trusted for this folder.`,
         };
         this._changed();
       }, this.reportingTimeoutMs);
@@ -322,6 +327,26 @@ export class Session extends EventEmitter {
     }
   }
 
+  /**
+   * Whether this input sends a line with something typed on it, the way a
+   * prompt is sent. An Enter on an empty line, or after only keys that send
+   * escape sequences (arrows in a menu, focus and mouse reports), is not a
+   * prompt; nor is one after Ctrl+C or Ctrl+U, which clear the line. Text
+   * may arrive one key at a time, so what was typed carries over.
+   */
+  _sendsTypedLine(data) {
+    const keys = data.replace(ESCAPE_SEQUENCE, '');
+    let sent = false;
+    for (const ch of keys) {
+      if (ch === '\r' || ch === '\n') {
+        sent ||= this._typedSinceEnter;
+        this._typedSinceEnter = false;
+      } else if (ch === '\x03' || ch === '\x15') this._typedSinceEnter = false;
+      else if (ch >= ' ' && ch !== '\x7f') this._typedSinceEnter = true;
+    }
+    return sent;
+  }
+
   _reply(data) {
     this.write(data);
   }

package/src/manager/shell-env.mjs

@@ -1,10 +1,16 @@
-// Recover the user's real PATH on macOS and Linux.
+// Recover the user's real PATH and locale on macOS and Linux.
 //
 // An app started from Finder, the Dock, or a login item does not inherit the
 // PATH that the user's shell profile builds (Homebrew, nvm, ~/.local/bin, ...),
 // which is exactly where CLI coding tools usually live. Like VS Code, we ask
 // the user's login shell for its PATH and merge it in.
+//
+// launchd starts a sign-in manager with no locale at all, where Terminal.app
+// would set LANG to the region's UTF-8 locale. Without one, tmux writes
+// non-ASCII characters as underscores, so a macOS manager with no locale
+// takes Terminal.app's, and there a locale the login shell exports wins.
 
+import fs from 'node:fs';
 import { execFile, spawn, spawnSync } from 'node:child_process';
 import path from 'node:path';
 
@@ -24,17 +30,31 @@ export function mergePathLists(primary, secondary, delimiter = path.delimiter) {
   return out.join(delimiter);
 }
 
-/** Pull PATH out of `env` output captured between the two markers. */
-export function parsePathFromEnvOutput(stdout) {
+/** The variables that choose a locale, in the order they take effect. */
+export const LOCALE_VARS = ['LC_ALL', 'LC_CTYPE', 'LANG'];
+
+/** The non-empty `names` in `env` output captured between the two markers, or null without the markers. */
+export function parseEnvOutput(stdout, names) {
   if (typeof stdout !== 'string') return null;
   const start = stdout.indexOf(START);
   const end = stdout.indexOf(END, start);
   if (start === -1 || end === -1) return null;
-  const line = stdout.slice(start + START.length, end).split(/\r?\n/).find((l) => l.startsWith('PATH='));
-  return line ? line.slice('PATH='.length) : null;
+  const found = {};
+  for (const line of stdout.slice(start + START.length, end).split(/\r?\n/)) {
+    const eq = line.indexOf('=');
+    const name = line.slice(0, eq);
+    if (eq > 0 && names.includes(name) && line.length > eq + 1 && !(name in found)) found[name] = line.slice(eq + 1);
+  }
+  return found;
 }
 
-export function loginShellPath({ shell = process.env.SHELL, timeoutMs = 8000 } = {}) {
+/** Pull PATH out of `env` output captured between the two markers. */
+export function parsePathFromEnvOutput(stdout) {
+  return parseEnvOutput(stdout, ['PATH'])?.PATH ?? null;
+}
+
+/** PATH and the locale variables the user's login shell exports, or null. */
+export function loginShellEnv({ shell, env = process.env, timeoutMs = 8000 } = {}) {
   if (process.platform === 'win32' || !shell) return null;
   // Read the exported PATH from `env` rather than expanding $PATH: fish, for
   // one, expands "$PATH" to a space-separated list.
@@ -42,10 +62,26 @@ export function loginShellPath({ shell = process.env.SHELL, timeoutMs = 8000 } =
     encoding: 'utf8',
     timeout: timeoutMs,
     stdio: ['ignore', 'pipe', 'ignore'],
-    env: { ...process.env, AGENT_GUILD_RESOLVING_ENV: '1' },
+    env: { ...env, AGENT_GUILD_RESOLVING_ENV: '1' },
   });
   if (result.error) return null;
-  return parsePathFromEnvOutput(result.stdout);
+  return parseEnvOutput(result.stdout, ['PATH', ...LOCALE_VARS]);
+}
+
+function readAppleLocale() {
+  const result = spawnSync('/usr/bin/defaults', ['read', '-g', 'AppleLocale'], { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] });
+  return result.error ? null : result.stdout;
+}
+
+/**
+ * The locale Terminal.app gives its shells: the system region's UTF-8 locale,
+ * or en_US.UTF-8 when macOS has none for it. `AppleLocale` may carry a script
+ * (`zh-Hans_CN`) and options (`en_US@rg=gbzzzz`), which locale names do not.
+ */
+export function macLocale({ read = readAppleLocale, exists = (name) => fs.existsSync(path.join('/usr/share/locale', name)) } = {}) {
+  const region = String(read() || '').trim().split('@')[0].replace(/-[A-Za-z]+(?=_)/, '');
+  const name = `${region}.UTF-8`;
+  return /^[A-Za-z]+_[A-Za-z]+$/.test(region) && exists(name) ? name : 'en_US.UTF-8';
 }
 
 /**
@@ -59,11 +95,15 @@ export function trimPathExt(env, platform = process.platform) {
   return env;
 }
 
-export function resolveBaseEnv() {
-  const env = trimPathExt({ ...process.env });
-  if (process.env.AGENT_GUILD_SKIP_SHELL_ENV === '1') return env;
-  const shellPath = loginShellPath();
-  if (shellPath) env.PATH = mergePathLists(shellPath, env.PATH);
+/** `platform`, `env`, `shellEnv` and `locale` are replaceable in tests. */
+export function resolveBaseEnv({ platform = process.platform, env: source = process.env, shellEnv = loginShellEnv, locale = macLocale } = {}) {
+  const env = trimPathExt({ ...source }, platform);
+  // Set before asking the shell, so macOS's /etc/zprofile keeps it rather than putting its C.UTF-8 in its place.
+  if (platform === 'darwin' && !LOCALE_VARS.some((name) => env[name])) env.LANG = locale();
+  if (env.AGENT_GUILD_SKIP_SHELL_ENV === '1') return env;
+  const shell = shellEnv({ shell: env.SHELL, env }) || {};
+  if (shell.PATH) env.PATH = mergePathLists(shell.PATH, env.PATH);
+  if (platform === 'darwin') for (const name of LOCALE_VARS) if (shell[name]) env[name] = shell[name];
   return env;
 }
 

package/src/manager/uninstall.mjs

@@ -68,8 +68,11 @@ function launchChain(launcher) {
   return chain;
 }
 
-function removeFile(file) {
-  fs.rmSync(file, { recursive: true, force: true, maxRetries: 3 });
+/** Deletes a file or folder, and a link as the link itself even when its target is already gone. */
+export function removeFile(file) {
+  // Some Node releases (24.13.0 among them) silently keep a dangling link that rmSync is asked to force.
+  if (fs.lstatSync(file, { throwIfNoEntry: false })?.isSymbolicLink()) fs.unlinkSync(file);
+  else fs.rmSync(file, { recursive: true, force: true, maxRetries: 3 });
 }
 
 export function runPlan(
@@ -111,6 +114,8 @@ export function runPlan(
     } catch (err) {
       throw Object.assign(err, { file });
     }
+    // Never report a removal that did not happen.
+    if (exists(file)) throw Object.assign(new Error('it is still there'), { file });
   };
   const prune = (dir) => {
     for (const name of fs.readdirSync(dir)) {

package/src/manager/usage.mjs

@@ -139,7 +139,7 @@ export async function fetchClaudeUsage({ accessToken, plan = null, version = nul
     },
     signal: AbortSignal.timeout(10000),
   });
-  if (!res.ok) throw httpUsageError(res.status, 'sign in again in Claude Code');
+  if (!res.ok) throw await httpUsageError(res, 'sign in again in Claude Code');
   const body = await res.json();
   const windows = [];
   for (const [key, label] of [['five_hour', '5-hour'], ['seven_day', '7-day'], ['seven_day_opus', '7-day Opus'], ['seven_day_sonnet', '7-day Sonnet']]) {
@@ -210,7 +210,7 @@ export async function fetchCodexUsage({ accessToken, accountId = null, fetchImpl
   const headers = { Authorization: `Bearer ${accessToken}`, Accept: 'application/json', 'User-Agent': 'agent-guild' };
   if (accountId) headers['ChatGPT-Account-Id'] = accountId;
   const res = await fetchImpl(CODEX_USAGE_URL, { headers, signal: AbortSignal.timeout(10000) });
-  if (!res.ok) throw httpUsageError(res.status, 'sign in again in Codex CLI');
+  if (!res.ok) throw await httpUsageError(res, 'sign in again in Codex CLI');
   const body = await res.json();
   const windows = codexWindows(body?.rate_limit ?? body?.rateLimit);
   // Limits metered apart from the plan's main windows, one entry per
@@ -279,10 +279,94 @@ export async function commandUsage({ command, args = [] }, env, platform = proce
   return { plan: body.plan ? String(body.plan).slice(0, 40) : null, windows };
 }
 
-function httpUsageError(status, signInHint) {
-  if (status === 401 || status === 403) return new UsageError(`usage endpoint refused the sign-in (HTTP ${status}); ${signInHint}`);
-  if (status === 429) return Object.assign(new UsageError('usage endpoint is rate limiting requests; retrying later'), { rateLimited: true });
-  return new UsageError(`usage endpoint answered HTTP ${status}`);
+// JWTs, API keys, bearer credentials and other long opaque strings never reach a message or the log.
+const SECRET_LIKE = /\beyJ[\w-]+\.[\w-]+(?:\.[\w-]*)?|\b(?:sk|rk|pk)-[\w-]{8,}|\bBearer\s+\S+|[\w+/=-]{40,}/gi;
+
+/** One line of at most `max` characters from a response body, without markup or anything credential-like. */
+export function excerpt(text, max = 200) {
+  if (typeof text !== 'string') return '';
+  return text
+    .replace(/<(script|style)\b[\s\S]*?<\/\1\s*>/gi, ' ')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(SECRET_LIKE, '[redacted]')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+/** The error message a JSON body carries, in the shapes the vendors use, else null. */
+function jsonMessage(text) {
+  let body;
+  try { body = JSON.parse(text); } catch { return null; }
+  const error = body?.error;
+  const message = firstText(error?.message, typeof error === 'string' ? error : null, body?.error_description, body?.detail, body?.message);
+  return message ? excerpt(message, 120) || null : null;
+}
+
+/** How much of a failed reply is read: enough for any error message or the start of a challenge page. */
+export const ERROR_BODY_LIMIT = 16 * 1024;
+
+/**
+ * The start of a reply's body as text, at most about `limit` bytes, the rest
+ * left unread. A reply-like object without a body stream is read with text().
+ */
+export async function readStart(res, limit = ERROR_BODY_LIMIT) {
+  const reader = res.body?.getReader?.();
+  if (!reader) return typeof res.text === 'function' ? res.text() : '';
+  const decoder = new TextDecoder();
+  let text = '';
+  let size = 0;
+  try {
+    while (size < limit) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      text += decoder.decode(value, { stream: true });
+    }
+  } finally {
+    // Ends the download of whatever is left; the result does not matter.
+    reader.cancel().catch(() => {});
+  }
+  return (text + decoder.decode()).slice(0, limit);
+}
+
+/**
+ * The error for a failed usage request. A 401 means the token was refused;
+ * a 403 that Cloudflare answered means the request was blocked before the
+ * token was looked at, usually because of the network it came from, so it
+ * gets no sign-in advice. `detail` is what the manager log records.
+ */
+async function httpUsageError(res, signInHint) {
+  const { status } = res;
+  const header = (name) => { try { return res.headers?.get?.(name) ?? null; } catch { return null; } };
+  let text = '';
+  try { text = await readStart(res); } catch { /* the body is optional */ }
+  const server = header('server');
+  const detail = { status, server: excerpt(server, 80) || null, ray: excerpt(header('cf-ray'), 80) || null, body: excerpt(text) };
+  const error = (message, extra = {}) => Object.assign(new UsageError(message), { detail }, extra);
+  if (status === 401) return error(`usage endpoint refused the sign-in (HTTP 401); ${signInHint}`);
+  if (status === 403) {
+    const blocked = header('cf-mitigated') !== null || (/cloudflare/i.test(server ?? '') && /html/i.test(header('content-type') ?? ''));
+    if (blocked) return error('usage endpoint blocked this network (HTTP 403), not a sign-in problem; usually a VPN, proxy or exit node, and it clears by itself');
+    const message = jsonMessage(text);
+    return error(`usage endpoint refused access (HTTP 403${message ? `: ${message}` : ''}); if this continues, ${signInHint}`);
+  }
+  if (status === 429) return error('usage endpoint is rate limiting requests; retrying later', { rateLimited: true });
+  return error(`usage endpoint answered HTTP ${status}`);
+}
+
+/**
+ * What the manager log adds to a failed lookup's message, which already
+ * names the HTTP status: the reply's headers and body for a vendor failure,
+ * '' when there is nothing more to say, and null for a failure that needs
+ * no log entry, such as no sign-in.
+ */
+function failureDetail(err) {
+  if (err.detail) {
+    const { server, ray, body } = err.detail;
+    return [server && `server=${server}`, ray && `cf-ray=${ray}`, body && `body="${body}"`].filter(Boolean).join(' ');
+  }
+  return err instanceof UsageError || err.notSignedIn ? null : '';
 }
 
 // ---- monitor ----------------------------------------------------------------
@@ -295,15 +379,19 @@ export class UsageMonitor {
    * @param {Function} [opts.fetchImpl]
    * @param {number} [opts.ttlMs]
    * @param {object} [opts.readers]  credential readers, replaceable in tests
+   * @param {(line: string) => void} [opts.log]  where vendor and network failures are recorded
    */
-  constructor({ registry, env = process.env, platform = process.platform, fetchImpl = fetch, ttlMs = USAGE_TTL_MS, readers = {} } = {}) {
+  constructor({ registry, env = process.env, platform = process.platform, fetchImpl = fetch, ttlMs = USAGE_TTL_MS, readers = {}, log = console.warn } = {}) {
     this.registry = registry;
     this.env = env;
     this.platform = platform;
     this.fetchImpl = fetchImpl;
     this.ttlMs = ttlMs;
     this.readers = { claude: readClaudeCredentials, codex: readCodexCredentials, ...readers };
+    this.log = log;
     this.cache = new Map();
+    /** Account key → the failure last logged for it, so a failure that persists is logged once and its end once. */
+    this.logged = new Map();
   }
 
   /** Snapshots for every account of every provider that has a usage source. */
@@ -322,7 +410,8 @@ export class UsageMonitor {
     const now = Date.now();
     if (entry?.inflight) return entry.inflight;
     if (entry && now - entry.at < entry.ttl) return Promise.resolve(entry.snapshot);
-    const inflight = this._fetch(provider, account).then((snapshot) => {
+    const inflight = this._fetch(provider, account).then(({ snapshot, failure }) => {
+      this._record(`${provider.id}/${account.id}`, snapshot.error, failure);
       const ttl = snapshot.rateLimited ? RATE_LIMITED_TTL_MS : this.ttlMs;
       this.cache.set(key, { snapshot, at: Date.now(), ttl });
       return snapshot;
@@ -331,6 +420,20 @@ export class UsageMonitor {
     return inflight;
   }
 
+  /** Log a vendor or network failure when it starts or changes, and once when lookups succeed again. */
+  _record(key, error, failure) {
+    const previous = this.logged.get(key);
+    if (failure !== null) {
+      if (previous === error) return;
+      this.logged.set(key, error);
+      this.log(`[usage] ${key}: ${error}${failure ? ` (${failure})` : ''}`);
+    } else if (previous !== undefined) {
+      this.logged.delete(key);
+      if (!error) this.log(`[usage] ${key}: usage lookups work again`);
+    }
+  }
+
+  /** Resolves to `{ snapshot, failure }`: the snapshot for clients and, for a vendor or network failure, its log detail (else null). */
   async _fetch(provider, account) {
     const base = { providerId: provider.id, accountId: account.id, plan: null, windows: [], credits: null, signedIn: null, fetchedAt: new Date().toISOString(), error: null };
     const env = { ...this.env, ...provider.env, ...account.env };
@@ -352,10 +455,13 @@ export class UsageMonitor {
       } else {
         result = await commandUsage(provider.usage, env, this.platform);
       }
-      return { ...base, signedIn, ...result };
+      return { snapshot: { ...base, signedIn, ...result }, failure: null };
     } catch (err) {
       const message = err instanceof UsageError ? err.message : `usage check failed: ${err.name === 'TimeoutError' ? 'timed out' : err.message}`;
-      return { ...base, signedIn: err.notSignedIn ? false : signedIn, error: message, ...(err.rateLimited ? { rateLimited: true } : {}) };
+      return {
+        snapshot: { ...base, signedIn: err.notSignedIn ? false : signedIn, error: message, ...(err.rateLimited ? { rateLimited: true } : {}) },
+        failure: failureDetail(err),
+      };
     }
   }
 }