mixdog 1.2.1 → 1.2.3

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/bounded-file-read.mjs

@@ -156,6 +156,19 @@ export function readBoundedFile(
   }
 }
 
+/**
+ * A file's state for the turn review of a tool write: null when absent, its
+ * bytes (binary included) up to PATCH_EDIT_MAX_BYTES and within `budget`,
+ * otherwise an omitted marker — counted as changed, never diffed or restored.
+ * Throws ENOTREGULAR for anything but a regular file.
+ */
+export function reviewFileContent(path, { budget = null } = {}) {
+  const read = readBoundedFile(path, { maxBytes: PATCH_EDIT_MAX_BYTES, budget, detectBinary: false });
+  if (read.state === 'absent') return null;
+  if (read.state === 'omitted') return { omitted: true, size: read.size, reason: read.reason };
+  return read.content;
+}
+
 /** Human phrase for an omitted read: "binary (N bytes)", "larger than 8 MiB (N bytes)". */
 export function describeOmittedFile({ reason, size, limit } = {}) {
   const bytes = `${Number(size) || 0} bytes`;

package/src/runtime/shared/bounded-line-diff.mjs

@@ -0,0 +1,182 @@
+// In-process line diffs for the turn-change paths, bounded the way codex
+// bounds its own: every file gets a short timeout, every operation (one tool
+// call, one review or seal pass) a total budget. A file over the size limits,
+// past its timeout or past the spent budget gets one replacement hunk between
+// its common line prefix and suffix instead — still an exact patch that
+// applies, only not a minimal one. Results are cached by content, so the same
+// pair is not diffed again across calls and reviews.
+import { createHash } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { formatPatch, structuredPatch } from 'diff';
+
+/** Longest a single file's Myers diff may run (codex's per-file value). */
+export const LINE_DIFF_FILE_TIMEOUT_MS = 100;
+/** Total Myers diff time one operation may spend across its files. */
+// Kept well under the lag target: an operation also renders, hashes and
+// bounds its patches outside the diff itself.
+export const LINE_DIFF_OPERATION_BUDGET_MS = 150;
+// A side over either limit is never Myers-diffed.
+const LINE_DIFF_MAX_CHARS = 1024 * 1024;
+const LINE_DIFF_MAX_LINES = 20_000;
+const CONTEXT_LINES = 3;
+const CACHE_MAX_ENTRIES = 512;
+// Cached hunks reference their texts: bound the cache by their length.
+const CACHE_MAX_CHARS = 32 * 1024 * 1024;
+
+/** One operation's diff budget; pass it to every lineDiffHunks call of it. */
+export function createLineDiffBudget(totalMs = LINE_DIFF_OPERATION_BUDGET_MS) {
+  return { remainingMs: totalMs };
+}
+
+const _cache = new Map();
+let _cachedChars = 0;
+const _hashByBytes = new WeakMap();
+
+const sha1 = (value) => createHash('sha1').update(value).digest('hex');
+
+/** Content hash of one side: a byte array is hashed once per object. A text
+ *  hashes to the same id as its UTF-8 bytes; one that has no exact UTF-8 form
+ *  (a lone surrogate) gets no id. */
+function sideHash(source, text) {
+  if (source && typeof source === 'object') {
+    let hash = _hashByBytes.get(source);
+    if (!hash) {
+      hash = sha1(source);
+      _hashByBytes.set(source, hash);
+    }
+    return hash;
+  }
+  return text.isWellFormed() ? sha1(text) : null;
+}
+
+function cacheKey(sources, oldText, newText) {
+  const before = sideHash(sources[0], oldText);
+  const after = before && sideHash(sources[1], newText);
+  return after ? `${before}:${after}` : null;
+}
+
+function cacheGet(key) {
+  const entry = _cache.get(key);
+  if (!entry) return null;
+  _cache.delete(key);
+  _cache.set(key, entry);
+  return entry.result;
+}
+
+function cacheSet(key, result, chars) {
+  if (chars > CACHE_MAX_CHARS) return;
+  _cachedChars -= _cache.get(key)?.chars || 0;
+  _cache.delete(key);
+  _cache.set(key, { result, chars });
+  _cachedChars += chars;
+  while (_cache.size > CACHE_MAX_ENTRIES || _cachedChars > CACHE_MAX_CHARS) {
+    const [oldest, entry] = _cache.entries().next().value;
+    _cache.delete(oldest);
+    _cachedChars -= entry.chars;
+  }
+}
+
+function overLimits(text) {
+  if (text.length > LINE_DIFF_MAX_CHARS) return true;
+  let lines = 0;
+  for (let index = text.indexOf('\n'); index >= 0; index = text.indexOf('\n', index + 1)) {
+    lines += 1;
+    if (lines > LINE_DIFF_MAX_LINES) return true;
+  }
+  return false;
+}
+
+/** Lines with their `\n` (the last one may lack it), as jsdiff tokenizes. */
+function lineTokens(text) {
+  if (!text) return [];
+  const lines = text.split('\n');
+  const tokens = lines.map((line, index) => (index < lines.length - 1 ? `${line}\n` : line));
+  if (tokens.at(-1) === '') tokens.pop();
+  return tokens;
+}
+
+/** The one hunk replacing everything between the texts' common line prefix
+ *  and suffix, with up to three context lines each side, in jsdiff's hunk
+ *  shape (`` included). */
+function replacementHunks(oldText, newText) {
+  const before = lineTokens(oldText);
+  const after = lineTokens(newText);
+  const shortest = Math.min(before.length, after.length);
+  let start = 0;
+  while (start < shortest && before[start] === after[start]) start += 1;
+  let end = 0;
+  while (end < shortest - start && before[before.length - 1 - end] === after[after.length - 1 - end]) end += 1;
+  const lead = Math.min(CONTEXT_LINES, start);
+  const trail = Math.min(CONTEXT_LINES, end);
+  const lines = [];
+  const push = (mark, tokens) => {
+    for (const token of tokens) {
+      if (token.endsWith('\n')) lines.push(mark + token.slice(0, -1));
+      else lines.push(mark + token, '\');
+    }
+  };
+  push(' ', before.slice(start - lead, start));
+  push('-', before.slice(start, before.length - end));
+  push('+', after.slice(start, after.length - end));
+  push(' ', before.slice(before.length - end, before.length - end + trail));
+  const first = start - lead;
+  return [
+    {
+      oldStart: first + 1,
+      oldLines: before.length - end + trail - first,
+      newStart: first + 1,
+      newLines: after.length - end + trail - first,
+      lines,
+    },
+  ];
+}
+
+/**
+ * Hunks (context 3, jsdiff's structuredPatch shape) turning `oldText` into
+ * `newText`: jsdiff's own when its diff finishes within the file timeout and
+ * what is left of `budget` (`exact`), else the replacement hunk. `sources`
+ * are the raw sides the texts came from (bytes or the texts), used only as
+ * the cache key. The returned value is shared: never mutate it.
+ */
+export function lineDiffHunks(oldText, newText, budget, sources = [oldText, newText]) {
+  if (oldText === newText) return { hunks: [], exact: true };
+  const key = cacheKey(sources, oldText, newText);
+  const cached = key ? cacheGet(key) || budget.fallbacks?.get(key) : null;
+  if (cached) return cached;
+  let result = null;
+  // A fallback forced by the operation's spent budget is not this pair's own
+  // outcome: it is not cached, so a later operation can still diff it.
+  let repeatable = true;
+  if (!overLimits(oldText) && !overLimits(newText)) {
+    if (budget.remainingMs > 0) {
+      const timeout = Math.min(LINE_DIFF_FILE_TIMEOUT_MS, budget.remainingMs);
+      const startedAt = performance.now();
+      const patch = structuredPatch('', '', oldText, newText, '', '', { context: CONTEXT_LINES, timeout });
+      budget.remainingMs -= performance.now() - startedAt;
+      if (patch) result = { hunks: patch.hunks, exact: true };
+      else repeatable = timeout >= LINE_DIFF_FILE_TIMEOUT_MS;
+    } else {
+      repeatable = false;
+    }
+  }
+  result ||= { hunks: replacementHunks(oldText, newText), exact: false };
+  if (key && repeatable) cacheSet(key, result, oldText.length + newText.length);
+  // Within its own operation it is final: the budget never grows back.
+  else if (key) (budget.fallbacks ||= new Map()).set(key, result);
+  return result;
+}
+
+/** The `--- `/`+++ ` headers and hunks of `hunks`, as jsdiff formats them,
+ *  ending in exactly one newline. */
+export function unifiedHunksBody(oldHeader, newHeader, hunks) {
+  const generated = formatPatch({ oldFileName: oldHeader, newFileName: newHeader, oldHeader: '', newHeader: '', hunks });
+  let end = generated.length;
+  // Linear trim: a /\n*$/ regex rescans from every position of a large patch.
+  while (end > 0 && generated.charCodeAt(end - 1) === 10) end -= 1;
+  return `${generated.slice(generated.search(/^--- /m), end)}\n`;
+}
+
+export function _resetLineDiffCacheForTest() {
+  _cache.clear();
+  _cachedChars = 0;
+}

package/src/runtime/shared/buffered-appender.mjs

@@ -175,6 +175,24 @@ export function appendBuffered(path, text) {
   }
 }
 
+/**
+ * Drop every not-yet-written chunk for `path` (its file is being deleted, so a
+ * later flush must not recreate it). A write already handed to the OS cannot
+ * be recalled; callers unlink after this and it lands before or is removed.
+ */
+export function discardBuffered(path) {
+  const q = queues.get(path);
+  if (!q) return;
+  if (q.timer) {
+    clearTimeout(q.timer);
+    q.timer = null;
+  }
+  q.chunks = [];
+  q.bytes = 0;
+  q.failCount = 0;
+  deleteIfIdle(path, q);
+}
+
 /** Observable overflow counters for buffered append queues. */
 export function getBufferedAppenderStats(path) {
   const q = queues.get(path);

package/src/runtime/shared/config.mjs

@@ -18,8 +18,10 @@ import {
   backupUserData,
   backupUserDataAsync,
   markUserDataInitialized,
+  ensureUserDataInitialized,
   loadLatestMixdogConfigFromBackup,
-  hasUserDataInitMarker,
+  isUserDataRecoveryExpected,
+  findLegacyUserDataEvidence,
 } from './user-data-guard.mjs';
 import { AGENT_PROVIDER_ENV, AGENT_PROVIDER_ENV_ALIASES, getAgentApiKey } from './provider-api-key.mjs';
 
@@ -236,7 +238,7 @@ function readConfigFile() {
   }
 }
 
-function writeConfigFile(data) {
+function writeConfigFile(data, postBackupReason = 'post-config-write') {
   // R4 data-at-rest: mixdog-config.json holds provider apiKeys; clamp to
   // owner-only on POSIX via 0o600/0o700 mode bits, AND fail-closed on
   // Windows where those bits are advisory — `secret: true` makes the
@@ -261,29 +263,76 @@ function writeConfigFile(data) {
     markUserDataInitialized(resolvePluginData());
   } catch {}
   try {
-    backupUserData(resolvePluginData(), 'post-config-write');
+    backupUserData(resolvePluginData(), postBackupReason);
   } catch {}
 }
 
+// Config paths whose restore could not be persisted: the in-memory restore is
+// still served, but the failure is logged (and the write retried) only once
+// per process instead of on every read.
+const _restorePersistFailed = new Set();
+
+/**
+ * Write a config restored on a plain read back to disk through the normal save
+ * path (atomic write + backups), so later reads hit the file instead of
+ * restoring again. Try-once lock: a contended lock means a writer (possibly
+ * this process's own outer RMW) is about to persist, so the next read retries.
+ */
+function persistRestoredConfig(restored) {
+  const path = configPath();
+  if (_restorePersistFailed.has(path)) return;
+  try {
+    const wrote = withFileLockSync(
+      `${path}.lock`,
+      () => {
+        if (existsSync(path)) return false;
+        writeAll(restored, 'post-restore');
+        return true;
+      },
+      { timeoutMs: 0 }
+    );
+    if (wrote) {
+      process.stderr.write(
+        '[config] read: restored mixdog-config.json from latest user-data backup (missing after init) and saved it\n'
+      );
+    }
+  } catch (err) {
+    if (err?.code === 'ELOCKCONTENDED') return;
+    _restorePersistFailed.add(path);
+    process.stderr.write(
+      `[config] read: restored mixdog-config.json from latest user-data backup (missing after init); saving it failed, serving it from memory: ${err?.message || err}\n`
+    );
+  }
+}
+
 function readAll() {
   const parsed = readConfigFile();
-  if (parsed != null) return canonicalizeUnifiedConfig(parsed);
+  if (parsed != null) {
+    // A data dir from before the in-dir init marker gets one (plus a first
+    // scoped snapshot) once per process, so its config stays recoverable.
+    try {
+      ensureUserDataInitialized(resolvePluginData());
+    } catch {}
+    return canonicalizeUnifiedConfig(parsed);
+  }
   // Symmetric with readAllForRmW(): a missing/unreadable config on a data
   // dir that was previously initialized means the file was LOST (deleted,
-  // failed write), not a fresh install. Self-heal from the newest
+  // failed write), not a fresh install. A recreated data dir has no marker
+  // and starts fresh. Self-heal from this data dir's newest
   // structurally-complete backup instead of silently collapsing to {} —
   // which callers (readSection/getCapabilities) merge with in-memory
-  // defaults, dropping the user's presets/agent routes/sections. In-memory only:
-  // readAll() runs OUTSIDE the config lock (unlike the RMW path), so we do
-  // not write here to avoid an unlocked-write race; the next updateSection
-  // re-persists the file under the lock.
-  if (hasUserDataInitMarker(resolvePluginData())) {
+  // defaults, dropping the user's presets/agent routes/sections. The restore
+  // is persisted under the config lock (only if the file is still missing) so
+  // later reads hit the file instead of restoring and logging again.
+  // An upgraded data dir (legacy marker / matching legacy backup, no in-dir
+  // marker yet) is a recovery case too; without a verifiable backup reads stay
+  // empty and RMW writes refuse (see readAllForRmW).
+  if (isUserDataRecoveryExpected(resolvePluginData())) {
     const restored = loadLatestMixdogConfigFromBackup(resolvePluginData());
     if (restored && isPlainObject(restored)) {
-      process.stderr.write(
-        '[config] read: restored mixdog-config.json from latest user-data backup (missing after init)\n'
-      );
-      return canonicalizeUnifiedConfig(restored);
+      const config = canonicalizeUnifiedConfig(restored);
+      persistRestoredConfig(config);
+      return config;
     }
   }
   return {};
@@ -300,11 +349,22 @@ function quarantineMalformedConfig(parseErr) {
 }
 
 function restoreAllForRmWOrThrow(reason) {
-  const restored = loadLatestMixdogConfigFromBackup(resolvePluginData());
+  const restored = loadLatestMixdogConfigFromBackup(resolvePluginData(), { fresh: true });
   if (restored && isPlainObject(restored)) {
     process.stderr.write(`[config] RMW read: restored mixdog-config.json from latest user-data backup (${reason})\n`);
     return restored;
   }
+  const legacy = findLegacyUserDataEvidence(resolvePluginData(), { fresh: true });
+  if (legacy) {
+    const err = new Error(
+      `[config] mixdog-config.json is missing but this data dir (${resolvePluginData()}) was initialized by an older ` +
+        `Mixdog build and no backup verified to belong to it was found; refusing to write a fresh config over a ` +
+        `recoverable state. Restore mixdog-config.json from a backup under ${legacy.roots.join(' or ')}, or delete ` +
+        `the legacy marker(s) to start fresh: ${legacy.markers.join(', ') || '(none; matching legacy backups are incomplete)'}`
+    );
+    err.code = 'EUSERDATARECOVERY';
+    throw err;
+  }
   throw new Error(
     `[config] mixdog-config.json is unreadable and no valid backup was found (${reason}); refusing section write that would wipe other sections`
   );
@@ -321,7 +381,7 @@ function readAllForRmW() {
     raw = readFileSync(configPath(), 'utf8');
   } catch (err) {
     if (err.code === 'ENOENT') {
-      if (hasUserDataInitMarker(resolvePluginData())) {
+      if (isUserDataRecoveryExpected(resolvePluginData(), { fresh: true })) {
         return restoreAllForRmWOrThrow('config file missing after user-data was initialized');
       }
       return {};
@@ -402,8 +462,8 @@ export function subscribeConfigChange(listener) {
   };
 }
 
-function writeAll(data) {
-  writeConfigFile(canonicalizeUnifiedConfig(data));
+function writeAll(data, postBackupReason) {
+  writeConfigFile(canonicalizeUnifiedConfig(data), postBackupReason);
   notifyConfigChanged();
 }
 

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;
@@ -190,6 +215,12 @@ export function presentErrorText(error, options = {}) {
   const name = error && typeof error === 'object' ? String(error.name || '') : '';
   const code = error && typeof error === 'object' ? String(error.code || '') : '';
   const status = errorHttpStatus(error);
+  // The fixed request overhead error is actionable as written (sizes,
+  // contributors, remedy): keep its lines instead of a generic "Context too
+  // large." that would suggest compacting.
+  if (code === 'TOOL_SURFACE_EXCEEDS_CONTEXT' || /\(TOOL_SURFACE_EXCEEDS_CONTEXT\)/.test(text)) {
+    return stripErrorPrefix(text);
+  }
   const jsonError = extractJsonError(text);
   if (jsonError) text = jsonError;
   const embeddedError = extractEmbeddedError(text);