mixdog 1.2.1 → 1.2.2

package/src/runtime/memory/lib/pg/process.mjs

@@ -12,17 +12,16 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
-  readdirSync,
   readFileSync,
   rmdirSync,
   rmSync,
-  statSync,
   symlinkSync,
   unlinkSync,
   writeFileSync,
 } from 'node:fs';
+import { readdir, readFile, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { spawn, spawnSync } from 'node:child_process';
+import { execFile, spawn, spawnSync } from 'node:child_process';
 import { createConnection, createServer } from 'node:net';
 import { isPidAlive } from '../../../shared/pid-liveness.mjs';
 
@@ -607,22 +606,36 @@ export function classifyOrphanTempPostmaster({
   return Number(uptimeSec) >= Math.max(60, Number(minUptimeSec) || ORPHAN_TEMP_PG_MIN_UPTIME_SEC);
 }
 
-function tempPostmasterOwnerAlive(args) {
+async function tempPostmasterOwnerAlive(args) {
   const rawDataDir = pgDataDirFromArgs(args);
   if (!rawDataDir) return false;
   const dataRoot = join(rawDataDir, '..');
   for (const name of ['memory-runtime-owner.json', 'daemon-owner.json']) {
     try {
-      const owner = JSON.parse(readFileSync(join(dataRoot, name), 'utf8'));
+      const owner = JSON.parse(await readFile(join(dataRoot, name), 'utf8'));
       if (Number(owner?.pid) > 0 && isPidAlive(Number(owner.pid))) return true;
     } catch {}
   }
   return false;
 }
 
-function listPostmasterRows() {
+// Async child run: stdout on exit 0, null on any failure/timeout (the old
+// spawnSync `status !== 0` contract). Never blocks the event loop.
+function execFileText(file, args, options) {
+  return new Promise((resolve) => {
+    try {
+      execFile(file, args, { encoding: 'utf8', ...options }, (error, stdout) => {
+        resolve(error ? null : String(stdout || ''));
+      });
+    } catch {
+      resolve(null);
+    }
+  });
+}
+
+async function listPostmasterRows() {
   if (process.platform === 'win32') {
-    const result = spawnSync(
+    const stdout = await execFileText(
       'powershell',
       [
         '-NoProfile',
@@ -632,10 +645,10 @@ function listPostmasterRows() {
           'started = [int](New-TimeSpan -Start $_.CreationDate -End (Get-Date)).TotalSeconds; ' +
           'args = $_.CommandLine } }',
       ],
-      { encoding: 'utf8', timeout: 15_000, windowsHide: true }
+      { timeout: 15_000, windowsHide: true }
     );
-    if (result.status !== 0) return [];
-    return String(result.stdout || '')
+    if (stdout === null) return [];
+    return stdout
       .split(/\r?\n/)
       .filter(Boolean)
       .flatMap((line) => {
@@ -647,12 +660,9 @@ function listPostmasterRows() {
         }
       });
   }
-  const result = spawnSync('ps', ['-eo', 'pid=,etimes=,args='], {
-    encoding: 'utf8',
-    timeout: 15_000,
-  });
-  if (result.status !== 0) return [];
-  return String(result.stdout || '')
+  const stdout = await execFileText('ps', ['-eo', 'pid=,etimes=,args='], { timeout: 15_000 });
+  if (stdout === null) return [];
+  return stdout
     .split(/\r?\n/)
     .flatMap((line) => {
       const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.*postgres.*)$/);
@@ -679,11 +689,11 @@ function pristineRootForArgs(args, tempRoot) {
 // (observed: 87 roots, 6.1GB, alongside 57 live postmasters). Roots a live
 // postmaster still owns are kept, and the same uptime margin that protects a
 // running harness from the process sweep protects its directory here.
-function sweepAbandonedPristineRoots(tempRoot, liveRoots, minAgeMs) {
+async function sweepAbandonedPristineRoots(tempRoot, liveRoots, minAgeMs) {
   let removed = 0;
   let entries;
   try {
-    entries = readdirSync(tempRoot, { withFileTypes: true });
+    entries = await readdir(tempRoot, { withFileTypes: true });
   } catch {
     return 0;
   }
@@ -693,12 +703,12 @@ function sweepAbandonedPristineRoots(tempRoot, liveRoots, minAgeMs) {
     const full = join(tempRoot, entry.name);
     if (liveRoots.has(normalizePathForMatch(full))) continue;
     try {
-      if (statSync(full).mtimeMs > cutoff) continue;
+      if ((await stat(full)).mtimeMs > cutoff) continue;
     } catch {
       continue;
     }
     try {
-      rmSync(full, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+      await rm(full, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
       removed += 1;
     } catch {
       /* a process this sweep did not reap still holds it */
@@ -709,18 +719,18 @@ function sweepAbandonedPristineRoots(tempRoot, liveRoots, minAgeMs) {
 
 /** Best-effort machine hygiene: reap orphan temp postmasters, then drop the
  *  throwaway roots no live postmaster owns. Runs periodically, not once. */
-export function sweepOrphanTempPostmasters({ tempRoot, minUptimeSec } = {}) {
+export async function sweepOrphanTempPostmasters({ tempRoot, minUptimeSec } = {}) {
   let reaped = 0;
   try {
     const root = tempRoot || process.env.TMPDIR || process.env.TEMP || process.env.TMP || '/tmp';
     const liveRoots = new Set();
-    for (const row of listPostmasterRows()) {
+    for (const row of await listPostmasterRows()) {
       if (!row.pid || row.pid === process.pid) continue;
       if (
         !classifyOrphanTempPostmaster({
           ...row,
           tempRoot: root,
-          ownerAlive: tempPostmasterOwnerAlive(row.args),
+          ownerAlive: await tempPostmasterOwnerAlive(row.args),
           minUptimeSec,
         })
       ) {
@@ -737,7 +747,7 @@ export function sweepOrphanTempPostmasters({ tempRoot, minUptimeSec } = {}) {
       }
     }
     const minAgeMs = Math.max(60, Number(minUptimeSec) || ORPHAN_TEMP_PG_MIN_UPTIME_SEC) * 1000;
-    const removed = sweepAbandonedPristineRoots(root, liveRoots, minAgeMs);
+    const removed = await sweepAbandonedPristineRoots(root, liveRoots, minAgeMs);
     if (removed > 0) __mixdogMemoryLog(`[pg-process] removed ${removed} abandoned pristine root(s)\n`);
   } catch {
     /* hygiene is best-effort */

package/src/runtime/memory/lib/pg/supervisor.mjs

@@ -372,6 +372,16 @@ function readPostmasterInfo(pgdata) {
   }
 }
 
+// Async child run (never blocks the daemon loop): stdout on exit 0, else null.
+async function _execFileText(file, args) {
+  const { execFile } = await import('node:child_process');
+  return new Promise((resolveText) => {
+    execFile(file, args, { encoding: 'utf8', windowsHide: true, timeout: 15_000 }, (error, stdout) => {
+      resolveText(error ? null : String(stdout || ''));
+    });
+  });
+}
+
 /**
  * Best-effort process-name check: confirms the pid's comm name contains 'postgres'.
  * Falls back to true (alive) when the name cannot be determined.
@@ -383,19 +393,12 @@ async function isPostgresPid(pid) {
       return comm.includes('postgres');
     }
     if (process.platform === 'darwin') {
-      const { spawnSync } = await import('node:child_process');
-      const r = spawnSync('ps', ['-o', 'comm=', '-p', String(pid)], { encoding: 'utf8', windowsHide: true });
-      if (r.status === 0) return (r.stdout || '').trim().includes('postgres');
-      return true;
+      const out = await _execFileText('ps', ['-o', 'comm=', '-p', String(pid)]);
+      return out === null ? true : out.trim().includes('postgres');
     }
     if (process.platform === 'win32') {
-      const { spawnSync } = await import('node:child_process');
-      const r = spawnSync('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], {
-        encoding: 'utf8',
-        windowsHide: true,
-      });
-      if (r.status === 0) return (r.stdout || '').toLowerCase().includes('postgres');
-      return true;
+      const out = await _execFileText('tasklist', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH']);
+      return out === null ? true : out.toLowerCase().includes('postgres');
     }
   } catch {
     /* cannot read — fall back to alive */
@@ -463,8 +466,8 @@ function scheduleOrphanTempPostmasterSweep() {
   _orphanSweepStarted = true;
   const runSweep = () => {
     void _getPgProc()
-      .then(({ sweepOrphanTempPostmasters }) => {
-        const reaped = sweepOrphanTempPostmasters?.() || 0;
+      .then(async ({ sweepOrphanTempPostmasters }) => {
+        const reaped = (await sweepOrphanTempPostmasters?.()) || 0;
         if (reaped > 0) __mixdogMemoryLog(`[supervisor-pg] orphan sweep reaped ${reaped} temp postmaster(s)\n`);
       })
       .catch(() => {

package/src/runtime/office/README.md

@@ -17,7 +17,7 @@ Microsoft Office installed.
 | `design/` | Design tokens, content model, composition, creative direction for the Word and Excel composers (`compose_document`, `compose_sheet`); `design-discipline.mjs` owns the safe typeface list, palette repair (tinted dark fields, WCAG contrast, paired accent tints), and the brief rules; `docx/`, `xlsx/` format compilers; `library/` template library with the bundled `templates/`. Decks are never composed here — a slide is authored by the model as a script (`authoring/`), and `compose_slide` is refused with that route. |
 | `quality/` | Reviews and gates: `assurance-*.mjs` (trust, structure, rendered pages, checklist), aesthetics, design review, scoring, visual diff. |
 | `bench/` | Benchmarks behind `npm run bench:office*`; `bench-support.mjs` holds the shared tool-call helpers. |
-| `shared/` | Tiny helpers used across folders: `values.mjs` (`plainObject`, `clone`, `stableValue`, `sha256`, `clamp`, `compact`, `imageBuffer`), `page-sizes.mjs` (the paper sizes PDF create and Word `set_page` share), `column-widths.mjs` (the widths a Word or PDF table given none takes from its text), and `asar-path.mjs`. |
+| `shared/` | Tiny helpers used across folders: `values.mjs` (`plainObject`, `clone`, `stableValue`, `sha256`, `clamp`, `compact`), `page-sizes.mjs` (the paper sizes PDF create and Word `set_page` share), `column-widths.mjs` (the widths a Word or PDF table given none takes from its text), and `asar-path.mjs`. |
 
 ## Dependency direction
 

package/src/runtime/office/shared/values.mjs

@@ -32,8 +32,3 @@ export function compact(value, maximum = 120) {
     .replace(/\s+/g, ' ')
     .slice(0, maximum);
 }
-
-export function imageBuffer(image) {
-  if (Buffer.isBuffer(image?.data)) return image.data;
-  return Buffer.from(String(image?.data || ''), 'base64');
-}

package/src/runtime/shared/background-tasks.mjs

@@ -18,6 +18,10 @@ export { TOOL_ASYNC_EXECUTION_CONTRACT, TOOL_MANUAL_CONTROL_CONTRACT, TOOL_SYNC_
 const TASK_TTL_MS = 30 * 60_000;
 const MAX_TASKS = 300;
 const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+// A `notifyOnCancel` task reports its cancellation to the owner once, after its
+// run settles, so the notification can carry what the run produced before it
+// stopped. A run that never settles still reports, header-only, after this grace.
+const CANCEL_NOTIFY_GRACE_MS = 10_000;
 const tasks = new Map();
 let seq = 0;
 
@@ -151,6 +155,7 @@ export function registerBackgroundTask({
   resultType,
   renderResult,
   cancel,
+  notifyOnCancel = false,
 } = {}) {
   pruneTasks();
   const explicitId = clean(taskId);
@@ -189,6 +194,7 @@ export function registerBackgroundTask({
     resultType: clean(resultType) || null,
     renderResult: typeof renderResult === 'function' ? renderResult : null,
     cancel: typeof cancel === 'function' ? cancel : null,
+    notifyOnCancel: notifyOnCancel === true,
   };
   tasks.set(id, task);
   return task;
@@ -200,10 +206,14 @@ export function startBackgroundTask(options = {}) {
     .then(() => options.run?.())
     .then((result) => {
       completeBackgroundTask(task.taskId, { status: 'completed', result, terminalReason: 'run-resolved' });
+      deliverCancelledNotification(task);
       return result;
     })
     .catch((error) => {
-      if (task.status === 'cancelled') return null;
+      if (task.status === 'cancelled') {
+        deliverCancelledNotification(task);
+        return null;
+      }
       completeBackgroundTask(task.taskId, {
         status: 'failed',
         error,
@@ -258,15 +268,62 @@ export function cleanupBackgroundTasks(options = {}) {
   return { removed: before - after, tasks: after };
 }
 
-export function cancelBackgroundTask(taskId, reason = 'cancelled') {
+// `notify`: true notifies immediately, false never notifies (owner teardown).
+// Left unset, a `notifyOnCancel` task defers its single `cancelled`
+// notification until its run settles (see settleCancelledBackgroundTask); any
+// other task stays silent.
+function cancelRunningTask(task, reason, notify) {
+  try {
+    task.cancel?.();
+  } catch {}
+  completeBackgroundTask(task.taskId, { status: 'cancelled', error: reason, notify: notify === true });
+  if (task.notifyOnCancel !== true || notify === true || task.status !== 'cancelled' || task.cancelNotify) return;
+  if (notify === false) {
+    task.cancelNotify = 'silent';
+    return;
+  }
+  task.cancelNotify = 'pending';
+  task.cancelNotifyTimer = setTimeout(() => deliverCancelledNotification(task), CANCEL_NOTIFY_GRACE_MS);
+  task.cancelNotifyTimer.unref?.();
+}
+
+// Owner teardown/delete (`notify: false`) also silences a cancellation that is
+// still waiting for its run to settle.
+function resolvePendingCancelNotify(task, next) {
+  if (task.cancelNotify !== 'pending') return false;
+  clearTimeout(task.cancelNotifyTimer);
+  task.cancelNotifyTimer = null;
+  task.cancelNotify = next;
+  return true;
+}
+
+function silenceCancelledNotification(task) {
+  resolvePendingCancelNotify(task, 'silent');
+}
+
+function deliverCancelledNotification(task) {
+  if (!resolvePendingCancelNotify(task, 'delivered')) return false;
+  if (tasks.get(task.taskId) !== task) return false;
+  task.meta = sanitizeTaskMeta(task.meta);
+  return notifyTaskCompletion(task, task.notificationInstruction);
+}
+
+export function cancelBackgroundTask(taskId, reason = 'cancelled', { notify } = {}) {
   const task = getBackgroundTask(taskId);
   if (!task) return null;
-  if (!TERMINAL_STATUSES.has(task.status)) {
-    try {
-      task.cancel?.();
-    } catch {}
-    completeBackgroundTask(task.taskId, { status: 'cancelled', error: reason, notify: false });
-  }
+  if (!TERMINAL_STATUSES.has(task.status)) cancelRunningTask(task, reason, notify);
+  else if (notify === false) silenceCancelledNotification(task);
+  return task;
+}
+
+/** The cancelled run has stopped: attach what it produced before stopping (if
+ *  any) and deliver the task's single deferred `cancelled` notification. A
+ *  no-op unless that notification is still pending. */
+export function settleCancelledBackgroundTask(taskId, { result } = {}) {
+  const task = getBackgroundTask(taskId);
+  if (task?.status !== 'cancelled' || task.cancelNotify !== 'pending') return null;
+  if (result !== undefined) task.result = result;
+  deliverCancelledNotification(task);
   return task;
 }
 
@@ -280,11 +337,11 @@ export function cancelBackgroundTasks(options = {}) {
     // visible/recoverable, but may not be claimed by whichever session happens
     // to close first.
     if (!taskMatchesScope(task, options, { includeUnattributed: false })) continue;
-    if (TERMINAL_STATUSES.has(task.status)) continue;
-    try {
-      task.cancel?.();
-    } catch {}
-    completeBackgroundTask(task.taskId, { status: 'cancelled', error: reason, notify: options.notify === true });
+    if (TERMINAL_STATUSES.has(task.status)) {
+      if (options.notify === false) silenceCancelledNotification(task);
+      continue;
+    }
+    cancelRunningTask(task, reason, options.notify);
     cancelled += 1;
   }
   return { cancelled };
@@ -358,10 +415,26 @@ export function completeBackgroundTask(
   return task;
 }
 
+// Surfaces whose later reads consume the structured result object itself:
+// shell `task read` re-reads output via result paths and renders exit_code /
+// timed_out / signal; agent job views return `job.result`. They keep it for the
+// TTL; every other surface keeps only resultText + metadata once delivered.
+const RESULT_KEPT_SURFACES = new Set(['shell', 'agent']);
+
+function releaseDeliveredResult(task, body) {
+  if (task.result === undefined || RESULT_KEPT_SURFACES.has(task.surface)) return;
+  // Pin the rendered body first so re-renders and retries stay identical.
+  if (!task.resultText) task.resultText = body;
+  task.result = undefined;
+}
+
 export function notifyTaskCompletion(task, instruction) {
   if (!task) return false;
   if (!TERMINAL_STATUSES.has(task.status)) return false;
   if (task.completionAcknowledged === true) return false;
+  // A deferred cancellation is delivered only by deliverCancelledNotification;
+  // a silent (owner-teardown) cancellation never notifies.
+  if (task.cancelNotify === 'pending' || task.cancelNotify === 'silent') return false;
   // `notified` tracks whether *any* completion notification was sent (e.g. an
   // early header-only preview from the agent surface). A later call that can
   // finally include the result body must still fire once, otherwise the owner
@@ -396,7 +469,10 @@ export function notifyTaskCompletion(task, instruction) {
   });
   if (sent) {
     task.notified = true;
-    if (hasBody) task.notifiedWithBody = true;
+    if (hasBody) {
+      task.notifiedWithBody = true;
+      releaseDeliveredResult(task, body);
+    }
   }
   return sent;
 }
@@ -457,6 +533,8 @@ export function renderBackgroundTaskNotification(task) {
     status: task.status,
     result,
     error: task.error,
+    // A cancelled Agent's header names the cancel reason.
+    detail: task.surface === 'agent' && task.status === 'cancelled' ? task.error : null,
   });
 }
 

package/src/runtime/shared/err-text.mjs

@@ -180,9 +180,34 @@ export function isCancelLikeError(error) {
   );
 }
 
+// One-line reason per provider kind. Fixed sentences (optionally with a
+// parenthesised value) are the renderer's translation keys.
+const KIND_LINES = {
+  overloaded: 'Provider is busy at capacity.',
+  rate_limited: ({ retryAfterMs }) =>
+    retryAfterMs ? `Provider is rate-limited (retry in ${formatDurationMs(retryAfterMs)}).` : 'Provider is rate-limited.',
+  quota_exhausted: 'Provider usage limit reached.',
+  entitlement: 'Not included in your plan.',
+  billing: 'Out of credits or at spend limit.',
+  permission: 'Access denied by the provider.',
+  policy: 'Refused by the provider safety policy.',
+  auth: 'Provider authentication failed.',
+};
+
+// Typed evidence: a persisted descriptor or structured status/code fields.
+// A bare message carries none, so its wording keeps the legacy text path.
+function hasTypedEvidence(error) {
+  if (!error || typeof error !== 'object') return false;
+  return Boolean(error.errorKind?.kind) || errorHttpStatus(error) > 0 || Boolean(error.code) || Boolean(error.retryAfterMs);
+}
+
 export function presentErrorText(error, options = {}) {
   const presentation = describeError(error);
   if (['image-size', 'payload-size', 'request'].includes(presentation.kind)) return presentation.summary;
+  const kindLine = hasTypedEvidence(error) ? KIND_LINES[presentation.providerKind] : null;
+  if (kindLine && presentation.kind !== 'unknown') {
+    return typeof kindLine === 'function' ? kindLine(presentation) : kindLine;
+  }
   const surface = options.surface || options.tool || '';
   const subject = subjectForSurface(surface);
   const max = options.max ?? 240;

package/src/runtime/shared/error-presentation.mjs

@@ -1,3 +1,4 @@
+import { PROVIDER_ERROR_KINDS, providerErrorKind } from '../agent/orchestrator/providers/provider-error-kind.mjs';
 import { transportErrorText } from './transport-error-text.mjs';
 
 const DETAILS_LIMIT = 12_000;
@@ -72,34 +73,167 @@ export function isRejected429(value) {
   return /\bAPI 429 request rejected\b/.test(messageOf(value));
 }
 
+// Provider kind → presentation. Summaries are also the persisted form of a
+// failure, so each maps back to its kind when only the text survives.
+const KIND_COPY = {
+  overloaded: ['overloaded', 'The provider is busy right now.', 'Try again later or choose another model.'],
+  rate_limited: ['rate-limit', 'The provider is temporarily rate-limiting requests.', 'Try again shortly.'],
+  quota_exhausted: [
+    'quota',
+    'The provider usage limit was reached.',
+    'Wait for the limit to reset or choose another account.',
+  ],
+  entitlement: [
+    'entitlement',
+    "This model isn't included in your plan.",
+    'Upgrade your plan, or choose another model or provider.',
+  ],
+  billing: [
+    'billing',
+    'The provider account is out of credits or at its spend limit.',
+    'Check your billing with the provider, then try again.',
+  ],
+  permission: [
+    'permission',
+    "You don't have access to this resource.",
+    'Check your account permissions, or choose another model.',
+  ],
+  context_overflow: [
+    'context-overflow',
+    'The conversation is too long for this model.',
+    'Compact the conversation or start a new one.',
+  ],
+  request_too_large: [
+    'payload-size',
+    'The request exceeds the size limit.',
+    'Reduce the attachments or request size, then try again.',
+  ],
+  policy: [
+    'policy',
+    'The provider refused this request under its safety policy.',
+    'Rephrase the request or choose another model.',
+  ],
+  service_tier_unavailable: [
+    'service-tier',
+    'The requested service tier is unavailable right now.',
+    'Switch to the standard tier or try again later.',
+  ],
+};
+const SUMMARY_KINDS = new Map(Object.entries(KIND_COPY).map(([providerKind, [, summary]]) => [summary, providerKind]));
+
+function waitLabel(ms) {
+  const seconds = Math.max(1, Math.ceil(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.ceil(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return minutes % 60 ? `${hours}h ${minutes % 60}m` : `${hours}h`;
+}
+
+/** Local HH:mm, prefixed with month/day when the reset is not today. */
+function resetLabel(resetAt) {
+  const reset = new Date(resetAt);
+  const pad = (n) => String(n).padStart(2, '0');
+  const time = `${pad(reset.getHours())}:${pad(reset.getMinutes())}`;
+  return reset.toDateString() === new Date().toDateString() ? time : `${reset.getMonth() + 1}/${reset.getDate()} ${time}`;
+}
+
+// Only legacy items (no persisted descriptor) and untyped strings reach this.
+const LEGACY_TEXT_KINDS = [
+  [/The provider usage limit was reached|quota.*(?:hit|exceed)|usage limit/i, 'quota_exhausted'],
+  [/rate[_ -]?limit|too many requests/i, 'rate_limited'],
+];
+
+/**
+ * The provider kind descriptor: the persisted one, else typed evidence, else
+ * wording. `typed` is true when the kind came from a persisted descriptor or a
+ * typed error: wording heuristics must then never override it.
+ */
+function classify(value, raw, clean, status, code) {
+  const persisted = value?.errorKind;
+  if (persisted && PROVIDER_ERROR_KINDS.includes(persisted.kind)) {
+    return { descriptor: persisted, typed: persisted.kind !== 'unknown' };
+  }
+  const hasTypedFields =
+    value &&
+    typeof value === 'object' &&
+    Boolean(value.status || value.httpStatus || value.response?.status || value.code || value.retryAfterMs);
+  if (!hasTypedFields) {
+    // Legacy persisted strings: their wording (and wait) is the only evidence.
+    const legacy = SUMMARY_KINDS.get(clean) ?? LEGACY_TEXT_KINDS.find(([re]) => re.test(clean))?.[1];
+    if (legacy) {
+      const wait = /retryAfter=(\d+)(ms|s|m)\b/i.exec(raw);
+      const retryAfterMs = wait ? Number(wait[1]) * { ms: 1, s: 1000, m: 60_000 }[wait[2].toLowerCase()] : undefined;
+      return { descriptor: { kind: legacy, ...(retryAfterMs ? { retryAfterMs } : {}) }, typed: false };
+    }
+  }
+  let descriptor = value && typeof value === 'object' ? providerErrorKind(value) : null;
+  const typed = Boolean(descriptor) && descriptor.kind !== 'unknown';
+  if (!descriptor || descriptor.kind === 'unknown') {
+    descriptor = providerErrorKind(
+      Object.assign(new Error(raw), { ...(status ? { status } : {}), ...(code ? { code } : {}) })
+    );
+  }
+  if (descriptor.kind === 'unknown') {
+    const known = SUMMARY_KINDS.get(clean);
+    const legacy = known ?? LEGACY_TEXT_KINDS.find(([re]) => re.test(clean))?.[1];
+    if (legacy) return { descriptor: { ...descriptor, kind: legacy }, typed: false };
+  }
+  return { descriptor, typed };
+}
+
 /** Presentation only: never changes retry policy or the underlying failure. */
 export function describeError(value) {
-  const { raw, message, status, code } = unwrap(value);
-  const rejected429 = isRejected429(value);
+  const { raw, message, status: textStatus, code: textCode } = unwrap(value);
   const details = safeErrorDetails(raw);
   const clean = safeErrorDetails(message)
     .replace(/^(?:Error invoking remote method ['"][^'"]+['"]:\s*)?(?:Error:\s*)?/i, '')
     .trim();
+  const { descriptor, typed } = classify(value, raw, clean, textStatus, textCode);
+  // A typed or persisted kind owns the verdict: its own status and code stand
+  // in for the text-derived ones, and wording below may only refine it.
+  const status = typed ? Number(descriptor.status) || 0 : textStatus;
+  const code = typed ? String(descriptor.code || '') : textCode;
+  // A 429 refusal without quota headers refines a rate limit, nothing else.
+  const rejected429 = isRejected429(value) && (!typed || descriptor.kind === 'rate_limited');
+  const copy = KIND_COPY[descriptor.kind];
+  const retryAfterMs = Number(descriptor.retryAfterMs) > 0 ? Number(descriptor.retryAfterMs) : null;
+  const resetAt = Number(descriptor.resetAt) > 0 ? Number(descriptor.resetAt) : null;
   let kind = 'unknown';
   let summary = '';
   let recovery = '';
-  const transport = transportErrorText(value) || transportErrorText(raw);
+  // Localization hook: a recovery that carries a value is given as a template.
+  let recoveryTemplate = '';
+  let params = null;
+  // A persisted descriptor keeps the status and errno code, not the cause
+  // chain: rebuild the transport evidence from them. Wording only reads for
+  // untyped failures and transient ones (a bare "fetch failed" is that evidence).
+  const transport =
+    transportErrorText(value) ||
+    (typed && transportErrorText({ code: code.toUpperCase(), status })) ||
+    (!typed || descriptor.kind === 'transient' ? transportErrorText(raw) : null);
   if (
     value?.reauthRequired === true ||
-    /invalid_grant|refresh token (?:expired|revoked|not available)|sign in again|sign-in expired|Reauth Required/i.test(raw)
+    (!typed &&
+      /invalid_grant|refresh token (?:expired|revoked|not available)|sign in again|sign-in expired|Reauth Required/i.test(raw))
   ) {
     kind = 'reauth';
     summary = 'Sign-in expired.';
     recovery = 'Sign in again from Providers.';
   } else if (
-    status === 401 ||
-    status === 403 ||
-    /\b(?:invalid|expired)\s+(?:api[ _-]?key|access token|credentials?)\b|Provider authentication failed/i.test(clean)
+    descriptor.kind === 'auth' ||
+    (descriptor.kind === 'unknown' &&
+      /\b(?:invalid|expired)\s+(?:api[ _-]?key|access token|credentials?)\b|Provider authentication failed/i.test(clean))
   ) {
     kind = 'authentication';
     summary = 'Provider authentication failed';
     recovery = 'Check your sign-in or API key, then try again.';
+  } else if (rejected429) {
+    kind = 'request';
+    summary = 'The provider rejected this request.';
+    recovery = 'Review the request details before trying again.';
   } else if (
+    ['invalid_request', 'unknown', 'request_too_large'].includes(descriptor.kind) &&
     /image.*dimensions.*exceed|image.*(?:too large|maximum.*(?:size|dimension))|many-image requests|An attached image exceeds the provider limit/i.test(
       clean
     )
@@ -108,20 +242,21 @@ export function describeError(value) {
     summary = 'An attached image exceeds the provider limit.';
     recovery = 'Reduce the image dimensions or number of images, then try again.';
   } else if (
-    status === 413 ||
+    descriptor.kind === 'unknown' &&
     /payload too large|request (?:body )?too large|The request exceeds the size limit/i.test(clean)
   ) {
-    kind = 'payload-size';
-    summary = 'The request exceeds the size limit.';
-    recovery = 'Reduce the attachments or request size, then try again.';
-  } else if (
-    !rejected429 &&
-    (status === 429 ||
-      /rate[_ -]?limit|quota.*(?:hit|exceed)|too many requests|The provider usage limit was reached/i.test(clean))
-  ) {
-    kind = 'rate-limit';
-    summary = 'The provider usage limit was reached.';
-    recovery = 'Wait for the limit to reset or choose another account.';
+    [kind, summary, recovery] = KIND_COPY.request_too_large;
+  } else if (copy) {
+    [kind, summary, recovery] = copy;
+    if (descriptor.kind === 'rate_limited' && retryAfterMs) {
+      recovery = `Try again in ${waitLabel(retryAfterMs)}.`;
+      recoveryTemplate = 'Try again in {{wait}}.';
+      params = { wait: waitLabel(retryAfterMs) };
+    } else if (descriptor.kind === 'quota_exhausted' && resetAt) {
+      recovery = `It resets at ${resetLabel(resetAt)}. Switch accounts or providers to continue now.`;
+      recoveryTemplate = 'It resets at {{time}}. Switch accounts or providers to continue now.';
+      params = { time: resetLabel(resetAt) };
+    }
   } else if (transport) {
     kind = 'connection';
     summary = transport.replace(/\.$/, '');
@@ -150,6 +285,11 @@ export function describeError(value) {
     kind,
     summary,
     recovery,
+    recoveryTemplate,
+    params,
+    providerKind: descriptor.kind,
+    resetAt,
+    retryAfterMs,
     details,
     // Known structured failures ignore volatile indexes; unknown failures
     // retain their diagnostic identity rather than merging unrelated work.