mixdog 1.3.0 → 1.3.2

package/src/runtime/shared/connector-triggers.mjs

@@ -6,6 +6,8 @@
 export const CONNECTOR_TRIGGER_MAX_CHARS = 100;
 
 export const CONNECTOR_TRIGGERS = Object.freeze({
+  // Not a catalog connector (Mixdog uses the signed-in GitHub CLI), but a
+  // user-added `github` MCP server still gets this line.
   github: 'GitHub repos, issues, pull requests, Actions and code search; not local Git history or diffs.',
   notion: 'Notion pages, databases and workspace search; create or update team docs and notes.',
   linear: 'Linear issues, projects, cycles and comments; create, triage or update tickets.',

package/src/runtime/shared/defaults-separation.mjs

@@ -11,9 +11,10 @@
  * Left untouched on purpose: `desktop`, credentials, onboarding, detection and
  * install flags, caches, and keys that are only ever hand-edited.
  */
-import { constants, copyFileSync, existsSync, mkdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
+import { writeFileAtomicSync } from './atomic-file.mjs';
 import { packDefinitionFromDir } from './shipped-definitions.mjs';
 import { resolvePluginData } from './plugin-paths.mjs';
 import { hasOwn, isPlainObject } from './object.mjs';
@@ -231,7 +232,10 @@ export function backupConfigBeforeDefaultsSeparation({ dataDir = resolvePluginDa
       throw err;
     }
     const target = join(dir, 'mixdog-config.json');
-    copyFileSync(source, target, constants.COPYFILE_EXCL);
+    // Written through an fsynced handle (a plain copy can leave this backup NUL
+    // exactly when a crash makes it needed); the folder was claimed above, so
+    // nothing can exist at `target`.
+    writeFileAtomicSync(target, readFileSync(source), { mode: statSync(source).mode & 0o777 });
     return target;
   }
 }

package/src/runtime/shared/delegated-approval-host.mjs

@@ -0,0 +1,74 @@
+// Delegated approvals: a sub-agent's approval request (tui/session/tool-approval.mjs)
+// is also shown in the top-level conversation the user watches — the root bot's
+// home chat, or the coding Lead's session (human-gate/gate.mjs approvalSurface).
+// It stays ONE request: the sub-agent's queue owns it and its waiter; the
+// top-level session's queue holds a copy whose answer is forwarded to that
+// owner, and the copy is withdrawn as soon as the owner settles (answered in
+// either place, timed out, its turn ended). Like held-request-host.mjs this
+// registry is process-wide and dependency-free.
+
+const KEY = Symbol.for('mixdog.delegatedApprovalHost.v1');
+
+function registry() {
+  globalThis[KEY] ??= { queues: new Set(), pending: new Map(), opener: null };
+  return globalThis[KEY];
+}
+
+/** `queue`: `{ sessionId() → string, disposed() → boolean, offer(delegated),
+ *  withdraw(id, result) }` — one session runtime's approval queue. */
+export function registerApprovalQueue(queue) {
+  registry().queues.add(queue);
+  return () => registry().queues.delete(queue);
+}
+
+/** `open(sessionId) → Promise`: brings a session's runtime up (the daemon's
+ *  session service), so a top-level chat that is not loaded can show the copy. */
+export function registerDelegatedApprovalOpener(open) {
+  registry().opener = open;
+  return () => {
+    if (registry().opener === open) registry().opener = null;
+  };
+}
+
+function liveQueuesOf(sessionId) {
+  const { queues } = registry();
+  const live = [];
+  for (const queue of queues) {
+    if (queue.disposed()) queues.delete(queue);
+    else if (queue.sessionId() === sessionId) live.push(queue);
+  }
+  return live;
+}
+
+function offerTo(sessionId, delegated) {
+  const live = liveQueuesOf(sessionId);
+  for (const queue of live) queue.offer(delegated);
+  return live.length > 0;
+}
+
+/** Show `delegated` (`{ id, sessionId, request, answer(...finishArgs) → boolean }`,
+ *  `sessionId` being the top-level conversation) there, now or once it loads. */
+export function delegateApproval(delegated) {
+  const { pending, opener } = registry();
+  pending.set(delegated.id, delegated);
+  if (offerTo(delegated.sessionId, delegated) || typeof opener !== 'function') return;
+  void Promise.resolve()
+    .then(() => opener(delegated.sessionId))
+    .then(() => {
+      if (pending.get(delegated.id) === delegated) offerTo(delegated.sessionId, delegated);
+    })
+    .catch(() => {});
+}
+
+/** The owner settled `id`: every copy goes away. `result` (`{ approved, device }`)
+ *  lets the copy say who answered. */
+export function withdrawDelegatedApproval(id, result = null) {
+  const { pending, queues } = registry();
+  if (!pending.delete(id)) return;
+  for (const queue of queues) queue.withdraw(id, result);
+}
+
+/** The pending delegated approvals a top-level session should show. */
+export function delegatedApprovalsFor(sessionId) {
+  return [...registry().pending.values()].filter((delegated) => delegated.sessionId === sessionId);
+}

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

@@ -237,7 +237,9 @@ function typedStreamFailureText(error, text) {
 
 export function presentErrorText(error, options = {}) {
   const presentation = describeError(error);
-  if (['image-size', 'payload-size', 'request'].includes(presentation.kind)) return presentation.summary;
+  if (['image-size', 'payload-size', 'request', 'model-unavailable', 'tool-schema'].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;
@@ -255,6 +257,10 @@ export function presentErrorText(error, options = {}) {
   if (code === 'TOOL_SURFACE_EXCEEDS_CONTEXT' || /\(TOOL_SURFACE_EXCEEDS_CONTEXT\)/.test(text)) {
     return stripErrorPrefix(text);
   }
+  // Likewise a latest message that cannot fit names its size and what would
+  // help; a wrapper's prefix ("agent compact failed (...): ") is dropped.
+  const latestTurn = /The latest message cannot fit this model \(LATEST_TURN_EXCEEDS_CONTEXT\)[\s\S]*$/.exec(text);
+  if (latestTurn) return latestTurn[0].replace(' (LATEST_TURN_EXCEEDS_CONTEXT)', '');
   const jsonError = extractJsonError(text);
   if (jsonError) text = jsonError;
   const embeddedError = extractEmbeddedError(text);

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

@@ -3,10 +3,14 @@ import { transportErrorText } from './transport-error-text.mjs';
 
 const DETAILS_LIMIT = 12_000;
 const SUMMARY_LIMIT = 180;
+// "<wrapper>: The latest message cannot fit this model (CODE): <sizes>. <cause and remedy>"
+const LATEST_TURN_RE =
+  /The latest message cannot fit this model \(LATEST_TURN_EXCEEDS_CONTEXT\)(: it needs about [\d,]+ tokens, but the [^.]* window leaves [\d,]+ for it\.)([\s\S]*)$/;
 
 /** Diagnostic text must be safe before it reaches a view, copy button or log. */
 export function safeErrorDetails(value) {
   let text = String(value ?? '')
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: strips ANSI escape sequences (ESC) from diagnostic text
     .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
     .replace(/\r\n?/g, '\n')
     .replace(/\b((?:https?|ssh):\/\/)[^/\s@]+@/gi, '$1[redacted]@')
@@ -135,7 +139,80 @@ 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}`;
+  return reset.toDateString() === new Date().toDateString()
+    ? time
+    : `${reset.getMonth() + 1}/${reset.getDate()} ${time}`;
+}
+
+// A refused request that names its model as unknown, retired or not offered
+// to this account. Read only for request-refusal kinds, so a typed overload,
+// quota or auth failure never reads as a missing model.
+const MODEL_REFUSAL_KINDS = new Set(['invalid_request', 'permission', 'unknown']);
+const MODEL_UNAVAILABLE_CODES = new Set(['model_not_found', 'model_not_supported']);
+// The model must be the subject of the refusal, at the start of a line or
+// sentence ("The model `x` does not exist", "models/x is not found", Ollama's
+// `model "x" not found`), or the refusal names it ("Unknown model", "… is not
+// a valid model ID", Anthropic's bare "model: x"). A model merely mentioned
+// beside some other missing thing ("For model x, tool lookup: route not
+// found") does not count.
+const MODEL_REFUSAL_PREDICATE =
+  "(?:(?:is|was|has been)\\s+)?(?:not found|does not exist|doesn'?t exist|not (?:supported|available)|(?:currently\\s+)?unavailable|no longer (?:available|supported)|deprecated|retired|removed)\\b";
+const SENTENCE_START = '(?:^|[.:;!]\\s+)';
+const MODEL_UNAVAILABLE_RE = new RegExp(
+  [
+    // "The model `x` does not exist", "models/x is not found", Vertex
+    // "Publisher Model `…` was not found", Ollama `model "x" not found`.
+    `${SENTENCE_START}(?:(?:the|this|that|requested|selected|publisher)\\s+)*models?(?:\\/\\S+|\\s+[\`'"]?[\\w./:@-]+[\`'"]?)?\\s+${MODEL_REFUSAL_PREDICATE}`,
+    // OpenAI "The 'gpt-x' model is not supported when using Codex …".
+    `${SENTENCE_START}(?:the\\s+)?[\`'"][^\`'"\\n]+[\`'"]\\s+model\\s+${MODEL_REFUSAL_PREDICATE}`,
+    `${SENTENCE_START}(?:unknown|invalid|unsupported) model\\b`,
+    // OpenRouter: no provider serves this model id.
+    `${SENTENCE_START}no endpoints found for [\\w.-]+\\/[\\w.:-]+`,
+    '\\bis not a valid model\\b',
+    '^model: \\S+$',
+  ].join('|'),
+  'im'
+);
+
+/**
+ * True when `error` (or its text) says the requested model is unknown,
+ * retired or not offered to this account: a typed model code, or provider
+ * wording with the model as the subject of the refusal.
+ */
+export function namesUnavailableModel(error) {
+  if (!error) return false;
+  if (typeof error === 'string') return MODEL_UNAVAILABLE_RE.test(error);
+  const codes = [error.code, error.providerErrorCode, error.error?.code, error.providerError?.code];
+  if (codes.some((code) => MODEL_UNAVAILABLE_CODES.has(String(code || '').toLowerCase()))) return true;
+  return [error.message, error.error?.message, error.providerError?.message, error.detail]
+    .filter((text) => typeof text === 'string' && text)
+    .some((text) => MODEL_UNAVAILABLE_RE.test(text));
+}
+const MODEL_UNAVAILABLE_COPY = [
+  'model-unavailable',
+  "This model isn't available for this account.",
+  'Choose another model, or check the model and endpoint in Providers.',
+];
+const NOT_FOUND_SUMMARY = "The provider couldn't find the requested model or endpoint.";
+// A tool definition the provider's schema validator refused (an MCP or custom
+// tool schema), named by the field path or wording each API uses.
+const TOOL_SCHEMA_RE =
+  /invalid schema for (?:function|tool)\b|\btools\.\d+\.(?:custom\.)?input_schema\b|\bfunction_declarations\[\d+\]\.parameters\b|\btools\[\d+\]\.function\.parameters\b|\binvalid (?:tool|function) (?:schema|parameters|definition)\b/i;
+const TOOL_SCHEMA_COPY = [
+  'tool-schema',
+  'The provider rejected a tool definition.',
+  'Disable the tool or MCP server named in the details, then try again.',
+];
+
+// The first line of a provider message worth showing as-is; '' for a stack
+// frame, a markup page or a raw JSON body.
+function firstReadableLine(clean) {
+  const lines = clean
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+  const first = lines.find((line) => !/^at\s|^\{|^<!doctype|^<html/i.test(line)) || '';
+  return first && !/^[{[]|^<|(?:API|HTTP)\s+[45]\d\d.*[<{]/i.test(first) ? first : '';
 }
 
 // Only legacy items (no persisted descriptor) and untyped strings reach this.
@@ -215,7 +292,9 @@ export function describeError(value) {
   if (
     value?.reauthRequired === true ||
     (!typed &&
-      /invalid_grant|refresh token (?:expired|revoked|not available)|sign in again|sign-in expired|Reauth Required/i.test(raw))
+      /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.';
@@ -223,7 +302,9 @@ export function describeError(value) {
   } else if (
     descriptor.kind === 'auth' ||
     (descriptor.kind === 'unknown' &&
-      /\b(?:invalid|expired)\s+(?:api[ _-]?key|access token|credentials?)\b|Provider authentication failed/i.test(clean))
+      /\b(?:invalid|expired)\s+(?:api[ _-]?key|access token|credentials?)\b|Provider authentication failed/i.test(
+        clean
+      ))
   ) {
     kind = 'authentication';
     summary = 'Provider authentication failed';
@@ -241,6 +322,32 @@ export function describeError(value) {
     kind = 'image-size';
     summary = 'An attached image exceeds the provider limit.';
     recovery = 'Reduce the image dimensions or number of images, then try again.';
+  } else if (
+    clean === MODEL_UNAVAILABLE_COPY[1] ||
+    (MODEL_REFUSAL_KINDS.has(descriptor.kind) &&
+      (MODEL_UNAVAILABLE_CODES.has(code) || MODEL_UNAVAILABLE_RE.test(clean)))
+  ) {
+    [kind, summary, recovery] = MODEL_UNAVAILABLE_COPY;
+  } else if (
+    clean === TOOL_SCHEMA_COPY[1] ||
+    (['invalid_request', 'unknown'].includes(descriptor.kind) && TOOL_SCHEMA_RE.test(clean))
+  ) {
+    [kind, summary, recovery] = TOOL_SCHEMA_COPY;
+  } else if (
+    clean === NOT_FOUND_SUMMARY ||
+    (MODEL_REFUSAL_KINDS.has(descriptor.kind) && (status === 404 || status === 410))
+  ) {
+    // The provider's own words name what is missing; the next step is the same.
+    kind = 'not-found';
+    summary = firstReadableLine(clean) || NOT_FOUND_SUMMARY;
+    recovery = MODEL_UNAVAILABLE_COPY[2];
+  } else if (LATEST_TURN_RE.test(clean)) {
+    // The latest message cannot fit the window (compact/runner.mjs): the
+    // sizes are the headline, the cause and remedy the next step.
+    const [, headline, rest] = LATEST_TURN_RE.exec(clean);
+    kind = 'latest-turn-size';
+    summary = `The latest message cannot fit this model${headline}`;
+    recovery = rest.trim();
   } else if (
     descriptor.kind === 'unknown' &&
     /payload too large|request (?:body )?too large|The request exceeds the size limit/i.test(clean)
@@ -272,15 +379,11 @@ export function describeError(value) {
     summary = 'The provider rejected this request.';
     recovery = 'Review the request details before trying again.';
   } else {
-    const lines = clean
-      .split('\n')
-      .map((line) => line.trim())
-      .filter(Boolean);
-    const first = lines.find((line) => !/^at\s|^\{|^<!doctype|^<html/i.test(line)) || '';
-    summary = first && !/^[{[]|^<|(?:API|HTTP)\s+[45]\d\d.*[<{]/i.test(first) ? first : 'Something went wrong.';
+    summary = firstReadableLine(clean) || 'Something went wrong.';
   }
   summary = summary.replace(/\s+/g, ' ').trim() || 'Something went wrong.';
   if (summary.length > SUMMARY_LIMIT) summary = `${summary.slice(0, SUMMARY_LIMIT - 1).trimEnd()}…`;
+  const fingerprintStatus = kind === 'reauth' ? '' : status || '';
   return {
     kind,
     summary,
@@ -293,6 +396,6 @@ export function describeError(value) {
     details,
     // Known structured failures ignore volatile indexes; unknown failures
     // retain their diagnostic identity rather than merging unrelated work.
-    fingerprint: kind === 'unknown' ? details : `${kind}:${kind === 'reauth' ? '' : status || ''}`,
+    fingerprint: kind === 'unknown' ? details : `${kind}:${fingerprintStatus}`,
   };
 }

package/src/runtime/shared/file-has-data.mjs

@@ -0,0 +1,28 @@
+import { closeSync, openSync, readSync } from 'node:fs';
+import { holdsNoData } from './atomic-file.mjs';
+
+const PROBE_BYTES = 4096;
+
+/**
+ * Install check for a downloaded binary or model: false when `path` is absent
+ * or its first bytes hold no data (empty, or NUL-filled by a crash that
+ * committed the size but not the bytes). Cheaper than hashing a multi-GB file
+ * on every use. A file that exists but cannot be opened right now (locked by a
+ * scanner or by the process running it) still counts as present.
+ */
+export function fileHasData(path) {
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const head = Buffer.alloc(PROBE_BYTES);
+    return !holdsNoData(head.subarray(0, readSync(fd, head, 0, PROBE_BYTES, 0)));
+  } catch (err) {
+    return err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR';
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {}
+    }
+  }
+}

package/src/runtime/shared/handoff-artifacts.d.mts

@@ -0,0 +1,20 @@
+export interface HandoffFile {
+  name: string;
+  path: string;
+  kind: 'image' | 'file' | 'text';
+  mimeType: string;
+  size: number;
+  /** Attachment-store reference when the file was stored. */
+  id?: string;
+}
+export function normalizeHandoffFiles(files: unknown): HandoffFile[];
+export function artifactLines(files: unknown, omitted?: number, options?: { ids?: boolean }): string[];
+export interface HandoffRecord {
+  id: string;
+  attachmentRef: string;
+  kind: 'image' | 'file' | 'text';
+  name: string;
+  mimeType: string;
+  size: number;
+}
+export function artifactRecords(files: unknown): HandoffRecord[];

package/src/runtime/shared/handoff-artifacts.mjs

@@ -0,0 +1,61 @@
+// The files a bot's or agent's turn handed back (session-runtime/
+// handoff-attachments.mjs collectTurnArtifacts) as the rows that carry them
+// show them: one model-facing line per file — the attachment id that forwards
+// it, or its path when it is too large or of a type no prompt carries — and
+// the message attachment records of the stored ones. Only those records
+// authorize forwarding by id; the lines are information for the model.
+import { escapeHarnessTags } from './shell-output-summary.mjs';
+import { normalizeMessageAttachments } from './transcript-metadata.mjs';
+
+const sizeLabel = (size) => {
+  const bytes = Number(size) || 0;
+  if (bytes >= 1_048_576) return `${(bytes / 1_048_576).toFixed(1)} MB`;
+  return bytes >= 1024 ? `${Math.round(bytes / 1024)} KB` : `${bytes} B`;
+};
+
+const oneLine = (value) => escapeHarnessTags(String(value ?? '').replace(/[\r\n]+/g, ' '));
+
+/** `files` ({ name, mimeType, size, path, id? }) normalized: bounded strings,
+ *  ids only of the attachment-store shape. */
+export function normalizeHandoffFiles(files) {
+  return (Array.isArray(files) ? files : [])
+    .filter((file) => file && typeof file === 'object' && typeof file.path === 'string' && file.path)
+    .slice(0, 8)
+    .map((file) => ({
+      name: String(file.name || 'file').slice(0, 200),
+      path: file.path.slice(0, 1024),
+      kind: ['image', 'file', 'text'].includes(file.kind) ? file.kind : 'file',
+      mimeType: String(file.mimeType || 'application/octet-stream').slice(0, 100),
+      size: Number(file.size) >= 0 ? Number(file.size) : 0,
+      ...(/^[a-f0-9]{64}$/.test(String(file.id ?? '')) ? { id: file.id } : {}),
+    }));
+}
+
+/** The model-facing list of `files`, empty when there are none. `ids`: the
+ *  row also records the stored files as its attachments (a task report), so
+ *  their ids can be forwarded; a plain-text handoff (an agent completion)
+ *  lists paths only — an id named in text is never trusted. */
+export function artifactLines(files, omitted = 0, { ids = true } = {}) {
+  const list = normalizeHandoffFiles(files);
+  if (!list.length) return [];
+  const attachable = (file) => (ids ? ` [attachment:${file.id}]` : ' (attachable: forward it by path)');
+  return [
+    `Files from this turn (forward one with attachments: [${ids ? 'id or path' : 'path'}]; link a path to show it):`,
+    ...list.map(
+      (file) =>
+        `- ${oneLine(file.name)} (${oneLine(file.mimeType)}, ${sizeLabel(file.size)}) — ${oneLine(file.path)}${
+          file.id ? attachable(file) : ' (too large or unsupported to attach; link the path)'
+        }`
+    ),
+    ...(omitted > 0 ? [`- …and ${omitted} more file(s)`] : []),
+  ];
+}
+
+/** The message attachment records of `files` (the stored ones). */
+export function artifactRecords(files) {
+  return normalizeMessageAttachments(
+    normalizeHandoffFiles(files)
+      .filter((file) => file.id)
+      .map((file) => ({ ...file, attachmentRef: file.id }))
+  );
+}

package/src/runtime/shared/llm/provider-model-identities.mjs

@@ -28,7 +28,12 @@ export const ANTIGRAVITY_MODELS = Object.freeze([
     low: 'gemini-3.1-pro-low',
     high: 'gemini-3.1-pro-high',
   }),
-  fallbackModel('gemini-4-argon', 'Gemini 4 Argon', 'gemini-pro', 1048576, 'gemini-4-argon', ['low', 'medium', 'high']),
+  // The gateway serves Argon only through per-tier ids; bare `gemini-4-argon` is a 404.
+  fallbackModel('gemini-4-argon', 'Gemini 4 Argon', 'gemini-pro', 1048576, {
+    low: 'gemini-4-argon-low',
+    medium: 'gemini-4-argon-medium',
+    high: 'gemini-4-argon-high',
+  }),
   fallbackModel('claude-opus-4-6-thinking', 'Claude Opus 4.6 (Thinking)', null, 250000, 'claude-opus-4-6-thinking', [
     'low',
     'medium',

package/src/runtime/shared/llm/usage-accounting.mjs

@@ -63,6 +63,12 @@ export async function accountProviderSend(provider, instance, send, model, opts
     if (!ledger) return;
     recorded.add(owner);
     const usage = result.usage || UNMEASURED_USAGE;
+    const durationMs = timed ? Date.now() - startedAt : 0;
+    // The one measured request time: the loop's speed figures read it, so
+    // the composer and the ledger show the same span.
+    if (timed && result && typeof result === 'object') {
+      Object.defineProperty(result, 'usageDurationMs', { value: durationMs, configurable: true, writable: true });
+    }
     const row = makeUsageRecord({
       id: result.responseId ? undefined : id,
       ts: Date.now(),
@@ -88,7 +94,7 @@ export async function accountProviderSend(provider, instance, send, model, opts
       // The account this send is bound to, so quota history can tell one
       // connected subscription's records from another's.
       account: ACCOUNT_PROVIDERS.includes(provider) ? currentProviderAccountId(provider) : '',
-      durationMs: timed ? Date.now() - startedAt : 0,
+      durationMs,
     });
     // Committed by the ledger worker (batched with concurrent sends); the
     // send still settles only once its row is durable, as before, but the

package/src/runtime/shared/llm/usage-ledger-import.mjs

@@ -114,7 +114,7 @@ export async function importUsageHistory(ledger, dataDir, { now = Date.now(), re
   // send's diagnostic copy cannot also enter as historical usage.
   const until = Number(ledger.get('liveSince')) || now;
   if (Number(ledger.get('importedThrough')) >= until) return { skipped: true };
-  const result = { inserted: 0, sourceRows: 0, unrecordableRows: 0, files: [], traceRows: 0 };
+  const result = { inserted: 0, sourceRows: 0, unrecordableRows: 0, tornTraceLines: 0, files: [], traceRows: 0 };
   const accept = (rows) => {
     const normalized = [];
     for (const raw of rows) {
@@ -140,15 +140,23 @@ export async function importUsageHistory(ledger, dataDir, { now = Date.now(), re
     const original = await readFile(path, 'utf8');
     const lines = original.split(/\r?\n/);
     const rows = [];
+    let torn = 0;
     for (let i = 0; i < lines.length; i++) {
       if (!lines[i].trim()) continue;
       let row;
       try {
         row = JSON.parse(lines[i]);
       } catch {
-        throw new Error(`Incomplete or invalid trace record: ${path}:${i + 1}`);
+        // An append a crash tore (cut short, or NUL-filled) is no record: skip
+        // it, like the gateway store below, instead of failing every import.
+        torn += 1;
+        continue;
       }
-      if (row.kind === 'usage_raw' || row.kind === 'usage') rows.push(row);
+      if (row?.kind === 'usage_raw' || row?.kind === 'usage') rows.push(row);
+    }
+    if (torn > 0) {
+      process.stderr.write(`[usage-ledger] warning: ${path} has ${torn} torn trace line(s); skipped\n`);
+      result.tornTraceLines += torn;
     }
     accept(rows);
     result.files.push({ path, sha256: createHash('sha256').update(original).digest('hex'), rows: rows.length });
@@ -160,29 +168,40 @@ export async function importUsageHistory(ledger, dataDir, { now = Date.now(), re
   // The JSONL store supersedes the legacy JSON file (it is migrated from it).
   const gatewayJsonl = await optionalFile(join(dataDir, 'gateway-usage.local.jsonl'));
   const gateway = gatewayJsonl === null ? await optionalFile(join(dataDir, 'gateway-usage.local.json')) : null;
-  if (gatewayJsonl !== null || gateway)
+  // A missing file is absence. Empty, unparsable, or wrong-shaped JSON is not:
+  // skip only that legacy import and leave importedThrough unset so a repair
+  // is retried instead of short-circuiting forever.
+  let legacyReady = true;
+  let gatewayEvents = null;
+  if (gatewayJsonl !== null) {
+    gatewayEvents = gatewayJsonl.split('\n').flatMap((line) => {
+      try {
+        return line.trim() ? [JSON.parse(line)] : [];
+      } catch {
+        return []; // torn append
+      }
+    });
+  } else if (gateway !== null) {
+    try {
+      const events = JSON.parse(gateway)?.events;
+      gatewayEvents = Array.isArray(events) ? events : [];
+    } catch (error) {
+      legacyReady = false;
+      process.stderr.write(
+        `[usage-ledger] warning: legacy gateway usage file gateway-usage.local.json is empty or corrupt (${error.message}); skipping its import\n`
+      );
+    }
+  }
+  if (gatewayEvents)
     accept(
-      (gatewayJsonl !== null
-        ? gatewayJsonl.split('\n').flatMap((line) => {
-            try {
-              return line.trim() ? [JSON.parse(line)] : [];
-            } catch {
-              return []; // torn append
-            }
-          })
-        : JSON.parse(gateway).events || []
-      ).map((event) => ({
+      gatewayEvents.map((event) => ({
         ...event,
         kind: 'usage',
         session_id: event.sessionId,
       }))
     );
-  // A missing file is absence. Empty, unparsable, or wrong-shaped JSON is not:
-  // skip only this legacy import and leave importedThrough unset so a repair
-  // is retried instead of short-circuiting forever.
   const legacyPath = join(dataDir, 'usage-rollup.local.json');
   const legacy = await optionalFile(legacyPath);
-  let legacyReady = true;
   if (legacy !== null) {
     let days;
     try {

package/src/runtime/shared/model-route-fallback.mjs

@@ -1,10 +1,84 @@
-import { providerErrorKind } from '../agent/orchestrator/providers/provider-error-kind.mjs';
+import {
+  boundedCauseChain,
+  providerErrorKind,
+  typedCodeKind,
+} from '../agent/orchestrator/providers/provider-error-kind.mjs';
 import { readStreamOutcome } from '../agent/orchestrator/providers/lib/stream-outcome.mjs';
+import { namesUnavailableModel } from './error-presentation.mjs';
 
-const ELIGIBLE = new Set(['rate_limited', 'quota_exhausted', 'overloaded', 'transient']);
+// When a route's model fails, does the next model in its fallback chain get
+// the request? Only for a refusal scoped to THIS provider, account or model —
+// another provider may serve the identical request:
+//   quota_exhausted / entitlement / billing — the plan or account is spent;
+//   rate_limited / overloaded / service_tier_unavailable — this provider is
+//     saturated once its own retries are spent;
+//   auth / permission — the provider's own sign-in refresh already failed, or
+//     the account, region or tier is refused;
+//   transient — only when the server answered (a typed status or code): its
+//     retry ladder is spent. A bare network failure would fail on every
+//     provider, so it stays with the transport recovery;
+//   invalid_request on 404/410, a typed model code, or provider wording with
+//     the model as the refused subject (namesUnavailableModel) — the model is
+//     unknown, retired or not offered to this account.
+// A request that fails the same way on any model never hops: request too
+// large, a refused tool schema or other invalid request, a policy refusal,
+// a cancel, a stall and any untyped failure. A context overflow hops only to
+// a model with a larger window (`contextGrows`); compaction runs first.
+// Whatever the kind, nothing may have been produced: no visible or buffered
+// output, no tool call started or dispatched.
+const PROVIDER_SCOPED_KINDS = new Set([
+  'quota_exhausted',
+  'entitlement',
+  'billing',
+  'rate_limited',
+  'overloaded',
+  'service_tier_unavailable',
+  'auth',
+  'permission',
+]);
+const MODEL_UNAVAILABLE_CODES = new Set(['model_not_found', 'model_not_supported']);
 
-export function canFallbackRoute(error, { signal, outcome = readStreamOutcome(error), committed = false } = {}) {
-  if (signal?.aborted || committed || outcome.userAbort || outcome.stallObserved) return false;
+/** 'hop', 'context' (a context overflow: hop only to a larger window) or 'stay'. */
+// A recovery layer may wrap the provider failure (a context overflow it could
+// not compact away): what the original request exposed lives on the cause.
+// Every node of the chain counts, so a wrapper never launders exposure.
+function chainOutcome(error) {
+  return readStreamOutcome(...(error && typeof error === 'object' ? boundedCauseChain(error) : [error]));
+}
+
+export function routeFallbackVerdict(error, { signal, outcome = chainOutcome(error), committed = false } = {}) {
+  if (signal?.aborted || committed || outcome.userAbort || outcome.stallObserved) return 'stay';
+  if (!outcome.replaySafe || outcome.observedOutput || outcome.toolCallsStarted || outcome.pendingToolInput) {
+    return 'stay';
+  }
+  const { kind, status, code } = providerErrorKind(error);
+  if (PROVIDER_SCOPED_KINDS.has(kind)) return 'hop';
+  if (kind === 'transient') return status >= 408 || typedCodeKind(error) === 'transient' ? 'hop' : 'stay';
+  if (kind === 'invalid_request') {
+    return status === 404 || status === 410 || MODEL_UNAVAILABLE_CODES.has(code) || namesUnavailableModel(error)
+      ? 'hop'
+      : 'stay';
+  }
+  return kind === 'context_overflow' ? 'context' : 'stay';
+}
+
+export function canFallbackRoute(error, { contextGrows = false, ...options } = {}) {
+  const verdict = routeFallbackVerdict(error, options);
+  return verdict === 'hop' || (verdict === 'context' && contextGrows === true);
+}
+
+const CAPACITY_KINDS = new Set(['rate_limited', 'quota_exhausted', 'overloaded', 'transient']);
+
+/**
+ * The narrower rule a stateless tool route (native web search) keeps: only a
+ * capacity refusal the server stated (429 / 503, or an account-pool quota
+ * refusal) moves to the next provider; a denied or failed credential
+ * surfaces so the user fixes that route.
+ */
+// It also keeps its stricter stream guards: any started or terminal stream
+// stays on its route, since a tool call cannot prove nothing was generated.
+export function canFallbackCapacityRoute(error, { signal, outcome = readStreamOutcome(error) } = {}) {
+  if (signal?.aborted || outcome.userAbort || outcome.stallObserved) return false;
   if (
     !outcome.replaySafe ||
     outcome.observedOutput ||
@@ -15,8 +89,6 @@ export function canFallbackRoute(error, { signal, outcome = readStreamOutcome(er
   )
     return false;
   const { kind, status } = providerErrorKind(error);
-  if (!ELIGIBLE.has(kind)) return false;
-  // A rejected HTTP request or a provider account-pool refusal proves no
-  // generation started. A transport disconnect alone does not.
+  if (!CAPACITY_KINDS.has(kind)) return false;
   return status === 429 || status === 503 || (kind === 'quota_exhausted' && error?.quotaExhausted != null);
 }