mixdog 1.3.5 → 1.4.0

package/src/runtime/agent/orchestrator/providers/provider-error-kind.mjs

@@ -5,6 +5,7 @@
 // to the older fields (httpStatus, responseFailed, providerError, SDK error
 // bodies, RPC status strings). Message text is consulted only for untyped
 // errors and only for unambiguous wordings.
+import { TIMEOUT_PHASE, isFirstByteTimeout } from '../../../shared/provider-timeout-phase.mjs';
 
 export const PROVIDER_ERROR_KINDS = Object.freeze([
   'overloaded',
@@ -391,6 +392,13 @@ const CODE_KINDS = new Map(
   }).flatMap(([kind, codes]) => codes.map((code) => [code, kind]))
 );
 const RESOURCE_EXHAUSTED = 'resource_exhausted';
+
+/** True when `code` is one of the provider error codes this module classifies
+ *  (rate/usage limits, quota, overload, server/transient, context length,
+ *  model not found, auth, policy, …): a known vocabulary word, never free text. */
+function isKnownProviderErrorCode(code) {
+  return typeof code === 'string' && (CODE_KINDS.has(code) || code === RESOURCE_EXHAUSTED);
+}
 // When several typed codes are present (an envelope type plus a specific
 // code), the most specific verdict wins.
 const KIND_RANK = [
@@ -435,7 +443,7 @@ const GATEWAY_ERROR_TYPE_CODES = Object.freeze({
 });
 
 /** The typed code a gateway `error_type` names, or null for an absent/unmapped one. */
-export function gatewayErrorTypeCode(errorType) {
+function gatewayErrorTypeCode(errorType) {
   const key = typeof errorType === 'string' ? errorType.trim().toLowerCase() : '';
   return key && Object.hasOwn(GATEWAY_ERROR_TYPE_CODES, key) ? GATEWAY_ERROR_TYPE_CODES[key] : null;
 }
@@ -718,6 +726,62 @@ export function providerErrorKind(err, options = {}) {
   return describe(kind, code || undefined);
 }
 
+// ── Retry reason, without server text ───────────────────────────────────────
+// A server error's free text can echo request content (prompt, tokens,
+// account ids), so neither the retry trace nor the reconnect status carries
+// it: only a fixed reason class derived from typed status/code, and a code
+// only when it is a known provider error code (an identifier-shaped value can
+// still be private, e.g. an account id in a `code` field).
+const SERVER_ERROR_CODES = new Set([
+  'server_error',
+  'api_error',
+  'internal',
+  'internal_error',
+  'unavailable',
+  'service_unavailable',
+]);
+// Responses failure codes the WS retry classifier acts on beyond the shared
+// provider vocabulary.
+const WS_RETRY_ERROR_CODES = new Set(['auth_context_expired', 'auth_expired']);
+
+/** The typed error code when it is a known provider error code; null otherwise. */
+export function safeRetryErrorCode(err) {
+  const code = providerErrorKind(err).code;
+  return isKnownProviderErrorCode(code) || WS_RETRY_ERROR_CODES.has(code) ? code : null;
+}
+
+const STALL_ERROR_NAMES = new Set(['StreamStalledError', 'StreamStalledAbortError']);
+
+/**
+ * One of rate_limited / overloaded / server_error / auth / first_response_timeout /
+ * stalled / other. The timeout classes read our own typed timeout stamps
+ * (name, code, timeoutPhase), never message text.
+ */
+export function retryReasonClass(err) {
+  const { kind, status } = providerErrorKind(err);
+  const code = safeRetryErrorCode(err);
+  if (kind === 'rate_limited' || kind === 'quota_exhausted' || status === 429) return 'rate_limited';
+  if (kind === 'overloaded' || status === 529) return 'overloaded';
+  if (kind === 'auth' || kind === 'permission' || status === 401 || status === 403) return 'auth';
+  // A token-refresh timeout is a sign-in problem, not a slow model.
+  if (err?.timeoutPhase === TIMEOUT_PHASE.AUTH) return 'auth';
+  if ((status >= 500 && status < 600) || (code && SERVER_ERROR_CODES.has(code))) return 'server_error';
+  if (err?.timeoutPhase === TIMEOUT_PHASE.IDLE || STALL_ERROR_NAMES.has(err?.name) || err?.code === 'ESTREAMSTALL') {
+    return 'stalled';
+  }
+  // `firstByteTimeout` is the stamp the Anthropic first-message and OpenAI
+  // WS/HTTP first-event watchdogs put on their errors.
+  if (
+    isFirstByteTimeout(err) ||
+    err?.firstByteTimeout === true ||
+    err?.name === 'ProviderTimeoutError' ||
+    err?.code === 'EPROVIDERTIMEOUT'
+  ) {
+    return 'first_response_timeout';
+  }
+  return 'other';
+}
+
 /** Kinds whose refusal no wait or replay can change: quota, plan and billing. */
 export const QUOTA_KINDS = new Set(['quota_exhausted', 'entitlement', 'billing']);
 /** Kinds that are deterministic refusals of this request (never replayed as-is). */

package/src/runtime/agent/orchestrator/providers/quota-reading.mjs

@@ -13,6 +13,8 @@ import {
 } from '../../../shared/provider-accounts.mjs';
 import { fetchOAuthUsageSnapshot } from './oauth-usage.mjs';
 import { getProvider } from './registry.mjs';
+import { modelProxyClientMode } from '../../../shared/model-proxy-mode.mjs';
+import { getModelProxyChannel } from './model-proxy-channel.mjs';
 
 const forcedReading = (routeInfo, providerObj) =>
   fetchOAuthUsageSnapshot(routeInfo, providerObj, () => {}, { force: true }).catch(() => null);
@@ -40,15 +42,15 @@ function readingServesModel(reading, model, useCredits) {
   return measured.length > 0 && measured.every((window) => window.usedPct < 100);
 }
 
-export async function providerQuotaUsable(providerName, model = '', { provider = getProvider(providerName) } = {}) {
+/** The model-independent, account-wide measurement: one forced usage reading
+ *  per roster account (or the single credential). Null for a provider that
+ *  reports no exhausted quota. */
+export async function measureProviderQuota(providerName, { provider } = {}) {
   // Only an account-pooled provider reports exhausted quota at all.
-  if (!ACCOUNT_PROVIDERS.includes(providerName)) return true;
+  if (!ACCOUNT_PROVIDERS.includes(providerName)) return null;
+  if (provider === undefined) provider = getProvider(providerName);
   const pool = readProviderAccountPool(providerName);
   const useCredits = pool.useCredits === true;
-  // Only this reading counts as evidence: an account whose forced reading
-  // failed or measured nothing for this model stays exhausted however its
-  // older record reads; the pool's own choice (selection, blocks) decides
-  // among the rest.
   if (pool.accounts.length > 0) {
     const readings = await Promise.all(
       pool.accounts.map((row) =>
@@ -58,13 +60,37 @@ export async function providerQuotaUsable(providerName, model = '', { provider =
         )
       )
     );
-    const unproven = new Set(
-      pool.accounts.filter((_, index) => !readingServesModel(readings[index], model, useCredits)).map((row) => row.id)
-    );
-    if (unproven.size === pool.accounts.length) return false;
-    return chooseProviderAccount(readProviderAccountPool(providerName), unproven, Date.now(), model) !== null;
+    return {
+      providerName,
+      useCredits,
+      accounts: pool.accounts.map((row, index) => ({ id: row.id, reading: readings[index] })),
+    };
   }
   // No roster: the single credential's fresh meter decides.
   const reading = await forcedReading({ provider: providerName, model: '' }, provider);
-  return readingServesModel(reading, model, useCredits);
+  return { providerName, useCredits, accounts: null, reading };
+}
+
+/** Whether `model` can be served per `measurement` (from measureProviderQuota).
+ *  Only the measurement counts as evidence: an account whose forced reading
+ *  failed or measured nothing for this model stays exhausted however its
+ *  older record reads; the pool's own choice (selection, blocks) decides
+ *  among the rest. */
+export function quotaMeasurementServesModel(measurement, model = '') {
+  if (!measurement) return true;
+  const { providerName, useCredits, accounts } = measurement;
+  if (!accounts) return readingServesModel(measurement.reading, model, useCredits);
+  const unproven = new Set(
+    accounts.filter((row) => !readingServesModel(row.reading, model, useCredits)).map((row) => row.id)
+  );
+  if (unproven.size === accounts.length) return false;
+  return chooseProviderAccount(readProviderAccountPool(providerName), unproven, Date.now(), model) !== null;
+}
+
+export async function providerQuotaUsable(providerName, model = '', { provider } = {}) {
+  // The PC owns the accounts in proxy mode; do not resolve a server provider.
+  if (modelProxyClientMode()) {
+    return (await getModelProxyChannel().request({ provider: providerName, method: 'quotaUsable', model })) === true;
+  }
+  return quotaMeasurementServesModel(await measureProviderQuota(providerName, { provider }), model);
 }

package/src/runtime/agent/orchestrator/providers/registry.mjs

@@ -70,6 +70,17 @@ let _initChain = Promise.resolve();
 let _inFlightPromise = null;
 let _inFlightSig = null;
 let _lastAppliedSig = null;
+// Settles when an initialization by the owning runtime first applies.
+let _markProvidersInitialized;
+const _providersInitialized = new Promise((resolve) => {
+  _markProvidersInitialized = resolve;
+});
+
+/** Read-only readiness: resolves once the owning runtime's provider
+ *  initialization has applied a config (never starts one). */
+export function providersInitialized() {
+  return _providersInitialized;
+}
 // Provider instances are process-global inside the daemon. Catalog
 // readers use this revision to share one raw model snapshot while still
 // rebuilding their cheap route/config projection after auth/config changes.
@@ -223,7 +234,14 @@ async function instantiateProvider(name, Ctor, cfg, proxyChannel = null) {
   return createAccountPoolProvider(name, () => wrapProviderAdmission(new Ctor(cfg), name));
 }
 
+let _initProvidersCalls = 0;
+/** Test seam: how many times initProviders was called in this process. */
+export function _initProvidersCallCountForTest() {
+  return _initProvidersCalls;
+}
+
 export async function initProviders(config, { signal = null } = {}) {
+  _initProvidersCalls += 1;
   throwIfAborted(signal);
   // Remote mode: provider availability and config are the PC's, never this
   // server's credential probes. No connected client fails here, clearly.
@@ -263,6 +281,7 @@ export async function initProviders(config, { signal = null } = {}) {
       if (_lastAppliedSig !== sig) _providerCatalogRevision += 1;
       _lastAppliedSig = sig;
       settle();
+      _markProvidersInitialized();
       return v;
     },
     (err) => {
@@ -452,6 +471,13 @@ function _scheduleOAuthSelfHeal(name) {
 // by its replacement account. When that account is not connected the lookup
 // misses like any other unconnected provider.
 const RETIRED_PROVIDER_ALIASES = Object.freeze({ 'opencode-go': 'opencode-go-oauth' });
+
+/** The instance registered under `name` right now, or null — a read-only
+ *  lookup (no lazy registration, unlike getProvider). */
+export function registeredProvider(name) {
+  return providers.get(name) || null;
+}
+
 export function getProvider(requestedName) {
   const name = Object.hasOwn(RETIRED_PROVIDER_ALIASES, requestedName)
     ? RETIRED_PROVIDER_ALIASES[requestedName]

package/src/runtime/agent/orchestrator/providers/retry-executor.mjs

@@ -4,7 +4,7 @@ import { PROVIDER_RETRY_JITTER_RATIO, createTimeoutSignal } from '../stall-polic
 import { readStreamOutcome } from './lib/stream-outcome.mjs';
 import { recycleLlmDispatcher } from '../../../shared/llm/http-agent.mjs';
 import { noteErrorUsage } from './lib/note-error-usage.mjs';
-import { retryReasonText, retryStatusLine } from '../../../shared/err-text.mjs';
+import { retryStatusLine, retryTimeoutText } from '../../../shared/err-text.mjs';
 import {
   TERMINAL_EDGE_STATUSES,
   boundedCauseChain,
@@ -13,7 +13,14 @@ import {
   isToolInputCut,
   retryAfterMsFromError,
 } from './retry-classification.mjs';
-import { DETERMINISTIC_KINDS, QUOTA_KINDS, errorHeaderValue, providerErrorKind } from './provider-error-kind.mjs';
+import {
+  DETERMINISTIC_KINDS,
+  QUOTA_KINDS,
+  errorHeaderValue,
+  providerErrorKind,
+  retryReasonClass,
+  safeRetryErrorCode,
+} from './provider-error-kind.mjs';
 import { adviceGatedRetry } from './retry-midstream.mjs';
 import {
   ModelFallbackTriggeredError,
@@ -35,7 +42,9 @@ export function createStreamSafetyStamps() {
       try {
         e.liveTextEmitted = true;
         e.unsafeToRetry = true;
-      } catch {}
+      } catch {
+        // the error object may be frozen; the live-text stamp is advisory
+      }
     }
     return e;
   };
@@ -44,7 +53,9 @@ export function createStreamSafetyStamps() {
       try {
         e.emittedToolCall = true;
         e.unsafeToRetry = true;
-      } catch {}
+      } catch {
+        // the error object may be frozen; the tool-call stamp is advisory
+      }
     }
     return e;
   };
@@ -313,6 +324,19 @@ function retryWaitMs(
   return retryAfterJitterRatio > 0 ? jitterDelayMs(wait, retryAfterJitterRatio, 'positive') : wait;
 }
 
+/** Fixed status phrases for a caller-classified retry reason. */
+const RETRY_REASON_TEXT = Object.freeze({
+  rate_limited: 'Rate limited by the provider',
+  overloaded: 'Provider overloaded',
+  server_error: 'Provider server error',
+  auth: 'Provider rejected the sign-in',
+  other: 'Connection interrupted',
+});
+
+// Timeout classes read our own typed timeout stamps (retryTimeoutText), so
+// their phrases carry the wait window.
+const TIMEOUT_REASON_CLASSES = new Set(['first_response_timeout', 'stalled']);
+
 /**
  * Display-only 'reconnecting' stage for one retry wait, so it reads as a
  * reconnect instead of a silent spinner. `attempt` is the attempt about to run
@@ -321,20 +345,28 @@ function retryWaitMs(
  */
 export function emitProviderRetryStage(
   onStageChange,
-  { attempt, maxAttempts, lastErr, delayMs, classifier = null, extra = null }
+  { attempt, maxAttempts, lastErr, delayMs, classifier = null, extra = null, reasonClass = null, providerLabel = null }
 ) {
   if (typeof onStageChange !== 'function') return;
   try {
-    const reason = retryReasonText(lastErr);
+    // The reason is a fixed phrase for a class (the caller's, else derived from
+    // the error's typed status/code), never the error's own text; an
+    // unrecognized class reads as `other`.
+    const cls = reasonClass == null ? retryReasonClass(lastErr) : reasonClass;
+    const fixedClass = Object.hasOwn(RETRY_REASON_TEXT, cls) || TIMEOUT_REASON_CLASSES.has(cls) ? cls : 'other';
+    const reason = TIMEOUT_REASON_CLASSES.has(fixedClass)
+      ? retryTimeoutText(lastErr, fixedClass, providerLabel)
+      : RETRY_REASON_TEXT[fixedClass];
     const waitMs = Math.max(0, Number(delayMs) || 0);
     onStageChange('reconnecting', {
       ...extra,
+      reasonClass: fixedClass,
       attempt,
       max: maxAttempts,
       waitMs,
       retryAt: Date.now() + waitMs,
       reason,
-      classifier: classifier || lastErr?.retryClassifier || lastErr?.code || null,
+      classifier: classifier || lastErr?.retryClassifier || safeRetryErrorCode(lastErr),
       message: retryStatusLine({ reason, attempt, maxAttempts, delayMs: waitMs }),
     });
   } catch {

package/src/runtime/agent/orchestrator/providers/statusline-route-meta.mjs

@@ -34,6 +34,12 @@ export function recordGatewayUsageEvent(summary) {
   return requireRouteMeta().recordGatewayUsageEvent(summary);
 }
 
+/** Resolves once every recorded usage event has been written; nothing was
+ *  recorded while the module is not loaded. */
+export function settleGatewayUsageWrites() {
+  return routeMeta ? routeMeta.settleGatewayUsageWrites() : Promise.resolve();
+}
+
 export function summarizeGatewayUsage(routeInfo, providerOut, compact = null, durationMs = null) {
   return requireRouteMeta().summarizeGatewayUsage(routeInfo, providerOut, compact, durationMs);
 }

package/src/runtime/agent/orchestrator/runtime-core/ask-user-tool-defs.mjs

@@ -8,9 +8,9 @@ export const ASK_USER_TOOL_DEFS = Object.freeze([
     name: 'ask_user',
     title: 'Ask User',
     trigger:
-      'Ask the user 1–4 multiple-choice questions and wait; when a plan needs the user to pick between clear options, instead of listing them in chat.',
+      'Ask the user 1–4 multiple-choice questions and wait; when a plan needs the user to pick between clear options, instead of listing them in chat. Also hands the user a page or app step (CAPTCHA, sign-in, 2FA, a secret).',
     description:
-      'Ask the user multiple-choice questions and wait. Only for a decision only the user can make, with clear options; never for minor choices or approval of requested work, and open questions go in chat. Do not repeat the options in your message.',
+      'Ask the user multiple-choice questions and wait. Only for a decision only the user can make, with clear options; never for minor choices or approval of requested work, and open questions go in chat. Do not repeat the options in your message. A step only the user can do on a page or app (CAPTCHA, human check, sign-in, 2FA, a password) is a handoff here, never a request in plain chat.',
     annotations: {
       title: 'Ask User',
       readOnlyHint: true,
@@ -55,7 +55,7 @@ export const ASK_USER_TOOL_DEFS = Object.freeze([
         handoff: {
           type: 'object',
           description:
-            'Instead of questions: secret = the user types a password/token into the focused field (you never see it; result provided/skipped/timeout); takeover = the user does a step (sign-in, CAPTCHA, 2FA) and says done.',
+            'Instead of questions: secret = the user types a password, sign-in, new password or one-time code into that field of the page (you never see it; result entered/user_skipped/no_field/page_changed/blocked/expired); takeover = the user does a step (sign-in, CAPTCHA, 2FA) and says done.',
           properties: {
             kind: { type: 'string', enum: ['secret', 'takeover'] },
             surface: { type: 'string', enum: ['browser', 'computer'] },
@@ -74,8 +74,9 @@ export const ASK_USER_TOOL_DEFS = Object.freeze([
               description: 'browser takeover: login = sign-in window on url.',
             },
             url: { type: 'string', maxLength: 2048, description: 'login: sign-in page (https).' },
-            tab: { type: 'string', maxLength: 64, description: 'browser takeover: page ID from list_tabs.' },
-            window_id: { type: 'string', maxLength: 128, description: 'computer takeover: exact window id.' },
+            tab: { type: 'string', maxLength: 64, description: 'browser: page ID from list_tabs.' },
+            window_id: { type: 'string', maxLength: 128, description: 'computer: exact window id (secret: required).' },
+            ref: { type: 'string', maxLength: 64, description: 'computer secret: field ref (required).' },
             app: { type: 'string', maxLength: 120, description: 'computer takeover: app name.' },
           },
           required: ['kind', 'surface'],
@@ -106,13 +107,16 @@ export function validateAskUserHandoff(args) {
   const login = handoffLogin(handoff);
   let need = login ? 'sign_in' : 'action';
   if (['sign_in', 'action', 'confirmation'].includes(handoff.need)) need = handoff.need;
+  const loginField = login ? { login } : {};
   return {
     kind: handoff.kind,
     surface: handoff.surface,
     target: text('target', 200),
     field: text('field', 80),
     instructions: text('instructions', 2000),
-    ...(handoff.kind === 'takeover' ? { need, identity: handoffIdentity(handoff), ...(login ? { login } : {}) } : {}),
+    // A secret is bound to its page (browser tab) or window and field (computer).
+    identity: handoffIdentity(handoff),
+    ...(handoff.kind === 'takeover' ? { need, ...loginField } : {}),
   };
 }
 
@@ -149,7 +153,8 @@ function handoffIdentity(handoff) {
           .trim()
           .slice(0, 120)
       : '';
-  return { ...(windowId ? { windowId } : {}), ...(app ? { app } : {}) };
+  const ref = handoff.kind === 'secret' ? token('ref', 64) : '';
+  return { ...(windowId ? { windowId } : {}), ...(app ? { app } : {}), ...(ref ? { ref } : {}) };
 }
 
 /** Throws a clear error when the questions are malformed; returns the list. */

package/src/runtime/agent/orchestrator/runtime-core/compaction-config-keys.mjs

@@ -0,0 +1,62 @@
+// The fields of `session.compaction` that the saved global config owns, as
+// opposed to the per-session state (archive, thresholds, outcome telemetry)
+// the session owns. Shared by the config sync and by the compaction commit, so
+// a commit that finishes after a reload never writes back a stale config value.
+import { RETIRED_COMPACTION_FIELDS } from '../config-storage.mjs';
+import { normalizeCompactionConfig } from './config-helpers.mjs';
+
+// Every spelling of the main-context buffer budget; a new representation
+// replaces the previous one.
+export const MAIN_BUFFER_KEYS = [
+  'mainBufferTokens',
+  'mainBuffer',
+  'mainBufferPercent',
+  'mainBufferPct',
+  'mainBufferRatio',
+  'mainBufferFraction',
+];
+
+// Everything the normalizer emits for an empty config, the retired aliases it
+// folds away, and every setting a session record is seeded from the config
+// (session-record.mjs initialCompactionConfig). A field the config no longer
+// sets is cleared so the session falls back to the default.
+export const COMPACTION_CONFIG_KEYS = Object.freeze([
+  ...Object.keys(normalizeCompactionConfig({})),
+  ...RETIRED_COMPACTION_FIELDS,
+  'enabled',
+  'useMaintainer',
+  'model',
+  'summaryModel',
+  'timeoutMs',
+  'memoryTimeoutMs',
+  'buffer',
+  'bufferTokens',
+  'reservedTokens',
+  'bufferPercent',
+  'bufferPct',
+  'bufferRatio',
+  'bufferFraction',
+  ...MAIN_BUFFER_KEYS,
+]);
+
+// The resolved buffer is the plan's own measurement, recorded on every compact
+// pass, so for the writers below it is telemetry and not a setting.
+const RESOLVED_BUFFER_KEYS = new Set(['bufferTokens', 'bufferRatio']);
+
+/**
+ * The `session.compaction` record a compaction writer produces: the live record
+ * plus its own outcome telemetry. Config-owned fields always come from the
+ * live record, never from the policy or the plan the writer started with: a
+ * reload that landed while the compaction was running (auto turned off, a
+ * model removed) must not be undone by the write that follows it.
+ */
+export function withLiveCompactionConfig(live, telemetry) {
+  const record = { ...live, auto: live.auto !== false, ...telemetry };
+  for (const key of COMPACTION_CONFIG_KEYS) {
+    if (key === 'auto' || RESOLVED_BUFFER_KEYS.has(key)) continue;
+    if (Object.hasOwn(live, key)) record[key] = live[key];
+    else delete record[key];
+  }
+  record.auto = live.auto !== false;
+  return record;
+}

package/src/runtime/agent/orchestrator/runtime-core/config-helpers.mjs

@@ -78,6 +78,14 @@ function resolveAutoEffort({ autoEffort, saved, preset = null }) {
   return preset?.autoEffort !== false;
 }
 
+/** The route's context percent: an explicit request, else the saved choice
+ *  (read lazily) unless an exact token selection replaced it. */
+function resolveContextPercent({ hasExplicitContextPercent, contextPercent, keepsSavedPercent, savedPercent }) {
+  if (hasExplicitContextPercent) return cleanContextPercent(contextPercent);
+  if (keepsSavedPercent) return cleanContextPercent(savedPercent());
+  return undefined;
+}
+
 export function makeResolveRoute(resolveDefaultProvider) {
   return function resolveRoute(
     config,
@@ -119,11 +127,12 @@ export function makeResolveRoute(resolveDefaultProvider) {
             modelParameters: hasExplicitModelParameters
               ? cleanModelParameters(modelParameters)
               : cleanModelParameters(saved.modelParameters ?? preset.modelParameters),
-            contextPercent: hasExplicitContextPercent
-              ? cleanContextPercent(contextPercent)
-              : keepsSavedPercent
-                ? cleanContextPercent(saved.contextPercent ?? preset.contextPercent)
-                : undefined,
+            contextPercent: resolveContextPercent({
+              hasExplicitContextPercent,
+              contextPercent,
+              keepsSavedPercent,
+              savedPercent: () => saved.contextPercent ?? preset.contextPercent,
+            }),
             ...(tokens ? { contextTokens: tokens } : {}),
           };
         }
@@ -144,11 +153,12 @@ export function makeResolveRoute(resolveDefaultProvider) {
       modelParameters: hasExplicitModelParameters
         ? cleanModelParameters(modelParameters)
         : cleanModelParameters(saved.modelParameters),
-      contextPercent: hasExplicitContextPercent
-        ? cleanContextPercent(contextPercent)
-        : keepsSavedPercent
-          ? cleanContextPercent(saved.contextPercent)
-          : undefined,
+      contextPercent: resolveContextPercent({
+        hasExplicitContextPercent,
+        contextPercent,
+        keepsSavedPercent,
+        savedPercent: () => saved.contextPercent,
+      }),
       ...(tokens ? { contextTokens: tokens } : {}),
     };
   };
@@ -231,7 +241,7 @@ const AGENT_TERMINAL_REAP_MS = Object.freeze({ 'openai-oauth': 60 * 60 * 1000 })
 
 /** A stored/requested idle value: AUTO_CLEAR_UNLIMITED, a window ≥ 1 min, or
  *  null when absent or invalid. */
-export function normalizeAutoClearIdleValue(value) {
+function normalizeAutoClearIdleValue(value) {
   if (value === null || value === undefined || typeof value === 'boolean') return null;
   if (typeof value === 'string') {
     const text = value.trim().toLowerCase();
@@ -290,11 +300,11 @@ export function autoClearProviderDefaults(providerIdleMs = null, extraProviders
     const builtIn = Object.hasOwn(AUTO_CLEAR_PROVIDER_IDLE_MS, provider)
       ? AUTO_CLEAR_PROVIDER_IDLE_MS[provider]
       : AUTO_CLEAR_PROVIDER_IDLE_MS.default;
-    const idleMs = Object.hasOwn(overrides, provider)
-      ? resolvedIdleMs(overrides[provider])
-      : provider === 'default' || Object.hasOwn(AUTO_CLEAR_PROVIDER_IDLE_MS, provider)
-        ? resolvedIdleMs(builtIn)
-        : autoClearIdleMsForProvider(provider, overrides);
+    let idleMs;
+    if (Object.hasOwn(overrides, provider)) idleMs = resolvedIdleMs(overrides[provider]);
+    else if (provider === 'default' || Object.hasOwn(AUTO_CLEAR_PROVIDER_IDLE_MS, provider)) {
+      idleMs = resolvedIdleMs(builtIn);
+    } else idleMs = autoClearIdleMsForProvider(provider, overrides);
     return {
       provider,
       idleMs,
@@ -338,6 +348,17 @@ export function resolveAutoClearIdleMs(config, provider) {
   return autoClearIdleMsForProvider(provider, raw.providerIdleMs);
 }
 
+/** The idle auto-clear gate's settings for a thread on `provider`
+ *  (idle-auto-clear-gate.mjs): `{ enabled, idleMs, minContextPercent }`. */
+function autoClearGateSettings(config, provider) {
+  const normalized = normalizeAutoClearConfig(config?.autoClear);
+  return {
+    enabled: normalized.enabled,
+    idleMs: resolveAutoClearIdleMs(config, provider),
+    minContextPercent: normalized.minContextPercent,
+  };
+}
+
 export function normalizeSystemShellConfig(value = {}) {
   const raw = value && typeof value === 'object' ? value : {};
   const command = clean(raw.command);