mixdog 1.2.2 → 1.2.4

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

@@ -1,6 +1,7 @@
 import { transportErrorText } from './transport-error-text.mjs';
 import { describeError, safeErrorDetails } from './error-presentation.mjs';
 import { oneLine } from './clean.mjs';
+import { TIMEOUT_PHASE, isFirstByteTimeout } from './provider-timeout-phase.mjs';
 
 // HTTP status carried by a provider/transport error, or 0 when absent.
 export function errorHttpStatus(err) {
@@ -185,7 +186,9 @@ export function isCancelLikeError(error) {
 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.',
+    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.',
@@ -198,7 +201,38 @@ const KIND_LINES = {
 // 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);
+  return (
+    Boolean(error.errorKind?.kind) || errorHttpStatus(error) > 0 || Boolean(error.code) || Boolean(error.retryAfterMs)
+  );
+}
+
+// The window a provider timeout names (providerTimeoutError's message), or 0.
+const timedOutMs = (text) => Number(/timed out after (\d+)ms/i.exec(text)?.[1]) || 0;
+
+// A provider timeout before the model produced anything (isFirstByteTimeout):
+// the model is slow, not the connection.
+function stillThinkingText(error, text) {
+  const ms = Number(error.waitedMs) || timedOutMs(text);
+  const provider =
+    typeof error.providerLabel === 'string' && error.providerLabel ? error.providerLabel : 'the provider';
+  const attempts = Number(error.attempts) > 0 ? `; attempts: ${Math.floor(Number(error.attempts))}` : '';
+  return `Model still thinking: no output in ${formatDurationMs(ms)}; ${provider} sent nothing yet${attempts}.`;
+}
+
+// Stamped provider timeout phases and stream cuts. Null when the error names
+// neither, so the text rules below decide.
+function typedStreamFailureText(error, text) {
+  if (!error || typeof error !== 'object') return null;
+  if (isFirstByteTimeout(error)) return stillThinkingText(error, text);
+  if (error.timeoutPhase === TIMEOUT_PHASE.IDLE) {
+    const ms = timedOutMs(text);
+    return ms > 0 ? `No progress ${formatDurationMs(ms)}.` : 'No progress.';
+  }
+  // A stream that ended before its finish marker lost its connection.
+  if (error.code === 'TRUNCATED_STREAM' && error.streamCorruption !== true) {
+    return 'Connection to the provider was lost (TRUNCATED_STREAM).';
+  }
+  return null;
 }
 
 export function presentErrorText(error, options = {}) {
@@ -215,12 +249,20 @@ 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);
   if (embeddedError) text = embeddedError;
   text = oneLine(stripErrorPrefix(text));
   if (!text) return 'Unknown error';
+  const streamFailure = typedStreamFailureText(error, text);
+  if (streamFailure) return streamFailure;
 
   if (code === 'PROVIDER_PREFIX_MUTATION' || name === 'ProviderPrefixMutationError') {
     return 'Session state changed unexpectedly.';
@@ -276,9 +318,10 @@ export function presentErrorText(error, options = {}) {
     return Number.isFinite(ms) && ms > 0 ? `No first response ${formatDurationMs(ms)}.` : 'No first response.';
   }
 
+  // The agent's own watchdog, worded apart from any provider timeout.
   const firstTransport = /first (?:transport|semantic response) stale\s*\((\d+)ms\)/i.exec(text);
   if (firstTransport) {
-    return `No first response ${formatDurationMs(firstTransport[1])}.`;
+    return `Agent watchdog stopped the run: no model response in ${formatDurationMs(firstTransport[1])}.`;
   }
 
   const firstResponse = /(?:agent\s+)?first response stale\s*\((\d+)ms\)/i.exec(text);
@@ -357,7 +400,8 @@ export function backgroundTaskFailureStatusLabel(status, error, options = {}) {
     /^timeout$/i.test(statusNorm) ||
     watchdog?.kind === 'timeout' ||
     /first response stale/i.test(raw) ||
-    /no first response from/i.test(presented)
+    /no first response from/i.test(presented) ||
+    /^(?:Model still thinking|Agent watchdog stopped the run):/.test(presented)
   )
     head = 'Timeout';
   else if (

package/src/runtime/shared/file-lock.mjs

@@ -278,12 +278,13 @@ function* releaseReclaimGuard(reclaim) {
 
 // A lock is reclaimable when its recorded owner is dead, or when it names no
 // owner at all and has outlived the stale window.
-function lockReclaimable(owner, stat, staleMs) {
+function lockReclaimable(owner, stat, staleMs, strictOwner = false) {
   if (owner.pid !== null) return !ownerIsLive(owner);
+  if (strictOwner) return false;
   return Date.now() - (Number(stat.mtimeMs) || 0) >= Math.max(0, staleMs);
 }
 
-function* tryReclaimStaleLock(lockPath, staleMs) {
+function* tryReclaimStaleLock(lockPath, staleMs, strictOwner = false) {
   let initial;
   try {
     initial = yield ['stat', lockPath];
@@ -291,7 +292,7 @@ function* tryReclaimStaleLock(lockPath, staleMs) {
     return false;
   }
   const owner = yield* readLockOwner(lockPath);
-  if (!lockReclaimable(owner, initial, staleMs)) return false;
+  if (!lockReclaimable(owner, initial, staleMs, strictOwner)) return false;
   const reclaim = yield* tryAcquireReclaimGuard(lockPath);
   if (reclaim === null) return false;
   try {
@@ -303,7 +304,7 @@ function* tryReclaimStaleLock(lockPath, staleMs) {
     }
     const currentOwner = yield* readLockOwner(lockPath);
     if (currentOwner.pid !== owner.pid || currentOwner.token !== owner.token) return false;
-    if (lockReclaimable(currentOwner, current, staleMs)) {
+    if (lockReclaimable(currentOwner, current, staleMs, strictOwner)) {
       try {
         yield ['unlink', lockPath];
         return true;
@@ -429,7 +430,7 @@ function* acquireLock(lockPath, opts, mode, markHeld, timing = null) {
       // The reclaim runs synchronously in both modes: it is a few metadata
       // calls, and an await inside it would let a process exit strand its guard.
       try {
-        if (runSync(tryReclaimStaleLock(lockPath, staleMs))) continue;
+        if (runSync(tryReclaimStaleLock(lockPath, staleMs, opts.strictOwner === true))) continue;
       } catch {}
       if (timeoutMs <= 0) throw contentionError(lockPath, error, yield* describeLockHolder(lockPath));
       if (Date.now() >= deadline) break;

package/src/runtime/shared/file-permissions.d.mts

@@ -1,3 +1,8 @@
 export function enforceOwnerOnlyAclWin32(targetPath: string, options?: { fresh?: boolean }): void;
 
-export function enforceOwnerOnlyAclWin32Async(targetPath: string, options?: { fresh?: boolean }): Promise<void>;
+export function enforceOwnerOnlyAclWin32Async(
+  targetPath: string,
+  options?: { fresh?: boolean }
+): Promise<void>;
+
+export function enforceOwnerOnlyDirectoryWin32Async(targetPath: string): Promise<void>;

package/src/runtime/shared/file-permissions.mjs

@@ -73,6 +73,16 @@ function icaclsPath() {
   return path;
 }
 
+const quoteForPowerShell = (value) => `'${String(value).replaceAll("'", "''")}'`;
+
+function powerShellCommand(icacls, script) {
+  return {
+    executable: join(dirname(icacls), 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+    label: 'Windows ACL update',
+    args: ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')],
+  };
+}
+
 function ownerOnlyAclCommand(targetPath, sid, fresh, icacls) {
   if (fresh) {
     return {
@@ -84,7 +94,7 @@ function ownerOnlyAclCommand(targetPath, sid, fresh, icacls) {
   // Never /reset a published secret: that temporarily restores broad parent
   // grants, and a later failure leaves them in place. Build the protected DACL
   // in memory and publish it in one native ACL update instead.
-  const quote = (value) => `'${String(value).replaceAll("'", "''")}'`;
+  const quote = quoteForPowerShell;
   const script = [
     "$ErrorActionPreference = 'Stop';",
     `$path = ${quote(targetPath)};`,
@@ -100,11 +110,37 @@ function ownerOnlyAclCommand(targetPath, sid, fresh, icacls) {
     'if ($directory) { [System.IO.Directory]::SetAccessControl($path, $acl) }',
     'else { [System.IO.File]::SetAccessControl($path, $acl) };',
   ].join(' ');
-  return {
-    executable: join(dirname(icacls), 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
-    label: 'Windows ACL update',
-    args: ['-NoProfile', '-NonInteractive', '-EncodedCommand', Buffer.from(script, 'utf16le').toString('base64')],
-  };
+  return powerShellCommand(icacls, script);
+}
+
+// Replaces a directory's whole DACL (explicit grants to anyone else included)
+// with one protected, inheritable owner-only grant, in one native update, so
+// files created inside need no ACL call of their own. Files already inside
+// that carry an explicit grant or any other principal's grant are reset to
+// inherit only that owner grant.
+function ownerOnlyDirectoryCommand(targetPath, sid, icacls) {
+  const script = [
+    "$ErrorActionPreference = 'Stop';",
+    `$path = ${quoteForPowerShell(targetPath)};`,
+    `$sid = [System.Security.Principal.SecurityIdentifier]::new(${quoteForPowerShell(sid)});`,
+    '$acl = [System.Security.AccessControl.DirectorySecurity]::new();',
+    '$acl.SetAccessRuleProtection($true, $false);',
+    '$acl.AddAccessRule([System.Security.AccessControl.FileSystemAccessRule]::new(',
+    '$sid, [System.Security.AccessControl.FileSystemRights]::FullControl,',
+    "[System.Security.AccessControl.InheritanceFlags]'ContainerInherit, ObjectInherit',",
+    '[System.Security.AccessControl.PropagationFlags]::None,',
+    '[System.Security.AccessControl.AccessControlType]::Allow));',
+    '[System.IO.Directory]::SetAccessControl($path, $acl);',
+    'foreach ($file in [System.IO.Directory]::GetFiles($path)) {',
+    '$current = [System.IO.File]::GetAccessControl($file);',
+    '$rules = @($current.GetAccessRules($true, $true, [System.Security.Principal.SecurityIdentifier]));',
+    '$foreign = @($rules | Where-Object { -not $_.IsInherited -or $_.IdentityReference -ne $sid });',
+    'if ($current.AreAccessRulesProtected -or $foreign.Count -gt 0) {',
+    '$reset = [System.Security.AccessControl.FileSecurity]::new();',
+    '$reset.SetAccessRuleProtection($false, $false);',
+    '[System.IO.File]::SetAccessControl($file, $reset) } };',
+  ].join(' ');
+  return powerShellCommand(icacls, script);
 }
 
 function aclFailure(targetPath, cause, label = 'icacls') {
@@ -143,3 +179,15 @@ export async function enforceOwnerOnlyAclWin32Async(targetPath, { fresh = false
     throw aclFailure(targetPath, error, command.label);
   }
 }
+
+export async function enforceOwnerOnlyDirectoryWin32Async(targetPath) {
+  if (process.platform !== 'win32') return;
+  const icacls = icaclsPath();
+  if (cachedUserSid === null) cachedUserSid = await resolveCurrentUserPrincipalAsync();
+  const command = ownerOnlyDirectoryCommand(targetPath, cachedUserSid, icacls);
+  try {
+    await execFileAsync(command.executable, command.args, { windowsHide: true, timeout: 15_000 });
+  } catch (error) {
+    throw aclFailure(targetPath, error, command.label);
+  }
+}

package/src/runtime/shared/llm/anthropic-betas.mjs

@@ -2,7 +2,6 @@ import { EFFORT_BETA_HEADER } from './anthropic-effort.mjs';
 import { normalizeClaudeModelId } from './anthropic-thinking-contract.mjs';
 import { getModelMetadataSync } from './model-catalog.mjs';
 
-const EXTENDED_CACHE_TTL_BETA_HEADER = 'extended-cache-ttl-2025-04-11';
 const INTERLEAVED_THINKING_BETA_HEADER = 'interleaved-thinking-2025-05-14';
 const FAST_MODE_BETA_HEADER = 'fast-mode-2026-02-01';
 const TOOL_SEARCH_BETA_HEADER = 'advanced-tool-use-2025-11-20';
@@ -23,7 +22,7 @@ export function supportsAnthropicFastMode(model) {
 }
 
 export function buildAnthropicBetaHeaders({
-  base = `${INTERLEAVED_THINKING_BETA_HEADER},${EXTENDED_CACHE_TTL_BETA_HEADER}`,
+  base = INTERLEAVED_THINKING_BETA_HEADER,
   fastMode = false,
   toolSearch = false,
   effort = false,

package/src/runtime/shared/llm/anthropic-effort.mjs

@@ -291,6 +291,12 @@ export function applyAnthropicEffortToBody(
 ) {
   if (!body || typeof body !== 'object') return;
 
+  // A gateway that declares its own effort contract (DeepSeek ignores
+  // budget_tokens) projects effort itself; returning true skips the Claude rules.
+  if (typeof opts.messagesEffortProjection === 'function') {
+    if (opts.messagesEffortProjection(body, { model, effort: opts.effort }) === true) return;
+  }
+
   const thinkingBudgetTokens = Number(opts.thinkingBudgetTokens);
   if (Number.isFinite(thinkingBudgetTokens) && thinkingBudgetTokens > 0) {
     assertAnthropicManualBudgetSupported(model);

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

@@ -28,6 +28,7 @@ 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']),
   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

@@ -8,6 +8,7 @@ import { currentProviderAccountId } from '../provider-auth-binding.mjs';
 // fallback, catalog retry) runs its own accounting and its result or error
 // then returns through the enclosing send, which must not write it again.
 const recorded = new WeakSet();
+const UNMEASURED_USAGE = Object.freeze({ inputTokens: null, inputTokensKnown: false });
 const hasTokens = (usage) =>
   ['inputTokens', 'outputTokens', 'cachedTokens', 'cacheWriteTokens'].some((key) => Number(usage?.[key]) > 0);
 // One rule for every reported usage object: tokens, or a provider-reported
@@ -51,7 +52,9 @@ export async function accountProviderSend(provider, instance, send, model, opts
   // abandoned attempt or a failure shares that clock with the final attempt,
   // so timing it too would count the same seconds twice and understate speed.
   const record = async (result, id, owner, timed) => {
-    if (!result?.usage) return;
+    // A completed call that reported no usage is still a call: it is recorded
+    // as unmeasured (unknown input, unpriced) instead of vanishing from totals.
+    if (!result?.usage && !(timed && result && typeof result === 'object')) return;
     // A nested send (e.g. a fallback model re-send) already stamped its own
     // final attempt's tier; the outer context only saw the abandoned attempt.
     result.requestServiceTier ??= identity.requestServiceTier || '';
@@ -59,7 +62,7 @@ export async function accountProviderSend(provider, instance, send, model, opts
     if (openingError) throw openingError;
     if (!ledger) return;
     recorded.add(owner);
-    const usage = result.usage;
+    const usage = result.usage || UNMEASURED_USAGE;
     const row = makeUsageRecord({
       id: result.responseId ? undefined : id,
       ts: Date.now(),

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

@@ -61,6 +61,8 @@ const add = (target, row) => {
     costBilled: row.cost_source === 'provider' ? row.cost_usd : 0,
     costEstimated: row.cost_source === 'provider' ? 0 : row.cost_usd,
   });
+  // A call recorded without provider usage is unmeasured whatever its provider.
+  if (row.unmeasured && !usage.unmeasuredTurns) usage.unmeasuredTurns = usage.turns || 0;
   for (const field of [
     'turns',
     'input',
@@ -311,6 +313,7 @@ export function readSessionUsage(db, sessionIds) {
                     json_extract(r.signature,'$[1]') AS model,
                     json_extract(r.signature,'$[4]') AS cost_source,
                     json_extract(r.signature,'$[7]') AS rank,
+                    COALESCE(json_extract(json_extract(r.signature,'$[5]'),'$.inputTokensKnown'),1)=0 AS unmeasured,
                     m.turns,m.input,m.output,m.cache_read,m.cache_write,m.cost_usd,m.duration_ms,
                     m.speed_output,m.speed_ms
                 FROM mine m JOIN usage_routes r ON r.id=m.route

package/src/runtime/shared/loopback-listener.mjs

@@ -9,6 +9,15 @@ export function createLoopbackListener({
   let current = null;
   let closing = null;
 
+  // close() drops only the keep-alive sockets idle at that moment; one whose
+  // in-flight response ends later would hold the close for the server's whole
+  // keepAliveTimeout (~5 s). Drop each as its response settles while stopping.
+  server.on('request', (_req, res) => {
+    res.once('close', () => {
+      if (closing) server.closeIdleConnections();
+    });
+  });
+
   function start() {
     if (closing) return Promise.reject(new Error('HTTP listener is stopping'));
     if (current) return current.promise;

package/src/runtime/shared/model-route-chain.d.mts

@@ -0,0 +1,8 @@
+export function canonicalRouteProvider(value: unknown): string;
+export function routeChain(route: Record<string, unknown>): Record<string, unknown>[];
+export function validateRouteChainProviders(routes: Record<string, unknown>[]): void;
+export function normalizeRouteChain(
+  route: Record<string, unknown>,
+  normalizeLeaf: (route: Record<string, unknown>, fallback: Record<string, unknown>) => Record<string, unknown> | null,
+  fallback?: Record<string, unknown>
+): Record<string, unknown> | null;

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

@@ -0,0 +1,48 @@
+const PROVIDER_ALIASES = Object.freeze({
+  'openai-api': 'openai',
+  'xai-api': 'xai',
+  'gemini-api': 'gemini',
+  'anthropic-api': 'anthropic',
+});
+
+export function canonicalRouteProvider(value) {
+  const id = String(value || '').trim();
+  return PROVIDER_ALIASES[id] || id;
+}
+
+export function routeChain(route) {
+  if (!route || typeof route !== 'object' || Array.isArray(route)) return [];
+  const { fallbacks = [], ...primary } = route;
+  if (!Array.isArray(fallbacks)) throw new Error('route.fallbacks must be an array');
+  for (const entry of fallbacks) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || Object.hasOwn(entry, 'fallbacks')) {
+      throw new Error('fallback routes must be leaf route objects');
+    }
+  }
+  return [primary, ...fallbacks];
+}
+
+export function validateRouteChainProviders(routes) {
+  const providers = new Set();
+  for (const route of routes) {
+    const provider = canonicalRouteProvider(route.provider);
+    if (!provider || !String(route.model || '').trim()) throw new Error('route requires provider and model');
+    if (providers.has(provider)) throw new Error(`duplicate route provider "${provider}"`);
+    if (providers.size && provider === 'default') throw new Error('follow Main is only allowed as the primary route');
+    providers.add(provider);
+  }
+}
+
+export function normalizeRouteChain(route, normalizeLeaf, fallback = {}) {
+  const raw = routeChain({ ...fallback, ...route });
+  const primary = normalizeLeaf(route, fallback);
+  if (!primary) return null;
+  const routes = raw.map((entry, index) => {
+    const normalized = index === 0 ? primary : normalizeLeaf(entry, {});
+    if (!normalized) throw new Error('fallback route requires provider and model');
+    return { ...normalized, provider: canonicalRouteProvider(normalized.provider) };
+  });
+  validateRouteChainProviders(routes);
+  const [first, ...rest] = routes;
+  return rest.length ? { ...first, fallbacks: rest } : first;
+}

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

@@ -0,0 +1,22 @@
+import { providerErrorKind } from '../agent/orchestrator/providers/provider-error-kind.mjs';
+import { readStreamOutcome } from '../agent/orchestrator/providers/lib/stream-outcome.mjs';
+
+const ELIGIBLE = new Set(['rate_limited', 'quota_exhausted', 'overloaded', 'transient']);
+
+export function canFallbackRoute(error, { signal, outcome = readStreamOutcome(error), committed = false } = {}) {
+  if (signal?.aborted || committed || outcome.userAbort || outcome.stallObserved) return false;
+  if (
+    !outcome.replaySafe ||
+    outcome.observedOutput ||
+    outcome.toolCallsStarted ||
+    outcome.pendingToolInput ||
+    outcome.continuation ||
+    outcome.terminalObserved
+  )
+    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.
+  return status === 429 || status === 503 || (kind === 'quota_exhausted' && error?.quotaExhausted != null);
+}

package/src/runtime/shared/pid-liveness.mjs

@@ -25,3 +25,15 @@ export function isPidAlive(value) {
     return error?.code === 'EPERM';
   }
 }
+
+/** Destructive operations require proof of death, not merely a failed probe. */
+export function isPidAliveOrUnknown(value) {
+  const pid = parsePid(value);
+  if (!pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== 'ESRCH';
+  }
+}

package/src/runtime/shared/provider-api-key.mjs

@@ -72,12 +72,20 @@ export function getAgentApiKey(provider) {
 /** The one API-key resolver for key-based providers: an explicit config key
  *  wins, otherwise the environment/keychain (getAgentApiKey). */
 export function resolveProviderApiKey(provider, config) {
+  if (config?.apiKeyEnv) return process.env[config.apiKeyEnv] || '';
   return config?.apiKey || getAgentApiKey(provider) || '';
 }
 
+/** Presence twin of resolveProviderApiKey, same precedence, no key value read. */
+export function hasProviderApiKey(provider, config) {
+  if (config?.apiKeyEnv) return Boolean(process.env[config.apiKeyEnv]);
+  return Boolean(config?.apiKey) || hasAgentApiKey(provider);
+}
+
 /** Auth-error reload: the stored/environment key is re-read first so a
  *  rotated key beats the stale one captured in config. */
 export function reloadProviderApiKey(provider, config) {
+  if (config?.apiKeyEnv) return process.env[config.apiKeyEnv] || '';
   return getAgentApiKey(provider) || config?.apiKey || '';
 }