pi-goal-list-loop-audit 0.35.4 → 0.35.13

package/extensions/goal-recovery.ts

@@ -22,7 +22,22 @@ import { state } from "./goal-state.js";
 import { appendLedger, claimRecoveryNotice, nowIso, piGlaDir, isForbiddenModel, isStaleApiError, nextHourlyProbeMs, providerErrorFingerprint, providerErrorPresentation, sanitizeProviderDisplayText, writeGoalMd, type Goal, type MainModelRecovery, type PendingCompletion } from "./goal-loop-core.js";
 import { persistStateLine } from "./goal-state.js";
 import { cancelDetachedGoalCompletionAuditor } from "./goal-loop-auditor-process.js";
-import { classifyMainModelFailure, isContextOverflowError, isMainModelFallbackFailure, mainModelAutoRetryUntil, mainModelFailureDelayMs, mainModelRetryDelayMs, MAIN_MODEL_AUTO_RETRY_HORIZON_MS, modelRef, normalizeMainModelFallbackRefs, requiresMainModelRecovery, splitModelRef, type MainModelFailure } from "./main-model-recovery.js";
+import {
+  classifyMainModelFailure,
+  isContextOverflowError,
+  isMainModelFailbackAuto,
+  isMainModelFallbackFailure,
+  mainModelAutoRetryUntil,
+  mainModelFailureDelayMs,
+  mainModelPrimaryProbeDelayMs,
+  mainModelRetryDelayMs,
+  MAIN_MODEL_AUTO_RETRY_HORIZON_MS,
+  modelRef,
+  normalizeMainModelFallbackRefs,
+  requiresMainModelRecovery,
+  splitModelRef,
+  type MainModelFailure,
+} from "./main-model-recovery.js";
 import { ModelSelector, type ModelScope } from "./model-selector.js";
 import { loadGlobalSettings, loadSettings } from "./goal-settings.js";
 import { clearLoopTimer, scheduleLoopTick } from "./goal-loop.js";
@@ -361,6 +376,27 @@ export function mainModelFallbackRefs(ctx: ExtensionContext): string[] {
   try { return normalizeMainModelFallbackRefs(loadGlobalSettings().mainModelFallbacks); } catch { return []; }
 }
 
+function mainModelFailbackEnabled(): boolean {
+  try { return isMainModelFailbackAuto(loadGlobalSettings().mainModelFailback); } catch { return true; }
+}
+
+function mainModelPrimaryProbeDelay(): number {
+  try { return mainModelPrimaryProbeDelayMs(loadGlobalSettings().mainModelPrimaryProbeMinutes); } catch { return mainModelPrimaryProbeDelayMs(); }
+}
+
+function sameModelRef(left: string | undefined, right: string | undefined): boolean {
+  return !!left && !!right && left.toLowerCase() === right.toLowerCase();
+}
+
+function scheduleSupervisedPrimaryProbe(ctx: ExtensionContext, recovery: MainModelRecovery): void {
+  flags.continuationDispatchStoodDown = false;
+  if (recovery.kind === "goal" && state.goal?.status === "active") {
+    scheduleContinuation(ctx, true, 1_000);
+  } else if (recovery.kind === "loop" && state.loop?.active) {
+    scheduleLoopTick(ctx);
+  }
+}
+
 export function holdMainModelRecovery(ctx: ExtensionContext, recovery: MainModelRecovery, why: string): void {
   const normalizedBase = withMainModelRecoveryWindow(recovery);
   const diagnostic = normalizedBase.providerErrorDiagnostic ?? normalizedBase.reason;
@@ -376,7 +412,13 @@ export function holdMainModelRecovery(ctx: ExtensionContext, recovery: MainModel
   clearContinuationTimer();
   clearLoopTimer();
   flags.continuationDispatchStoodDown = true;
-  state.mainModelRecovery = { ...normalized, retryAt: undefined, manualResumeRequired: true };
+  state.mainModelRecovery = {
+    ...normalized,
+    retryAt: undefined,
+    primaryProbeAt: undefined,
+    primaryProbeInFlight: undefined,
+    manualResumeRequired: true,
+  };
   const resumeCmd = recoverySurfaceCommand(normalized.kind, "resume");
   const pauseReason = `main model recovery — automatic probes stopped (${sanitizeProviderDisplayText(why)})`;
   const action = `No automatic provider probes remain. Switch /model if desired, then ${resumeCmd} to start a fresh recovery window; ${activeGoalSurfaceCommand("cancel")} stops it.`;
@@ -503,6 +545,11 @@ export async function tryMainModelFallback(ctx: ExtensionContext, failure: MainM
   const failureCopy = providerErrorPresentation(failure.raw, "main");
   const recovery: MainModelRecovery = {
     ...baseRecovery,
+    // A provider failure while serving a fallback returns to the normal
+    // ordered recovery walk; the next successful fallback turn will arm a
+    // fresh preferred-primary probe.
+    primaryProbeAt: undefined,
+    primaryProbeInFlight: undefined,
     reason: mainModelRecoveryReason(failure),
     providerErrorDiagnostic: failureCopy.diagnostic,
     recoveryEpisodeKey: baseRecovery.recoveryEpisodeKey ?? `${baseRecovery.firstFailureAt ?? nowIso()}:${failureCopy.fingerprint}`,
@@ -543,6 +590,8 @@ export async function tryMainModelFallback(ctx: ExtensionContext, failure: MainM
         active: current,
         reason: mainModelRecoveryReason(failure),
         providerErrorDiagnostic: failureCopy.diagnostic,
+        primaryProbeAt: undefined,
+        primaryProbeInFlight: undefined,
         skipped: recovery.skipped,
       };
       persistState(ctx);
@@ -593,7 +642,7 @@ export async function tryMainModelFallback(ctx: ExtensionContext, failure: MainM
       state.mainModelRecovery = nextRecovery;
       persistState(ctx);
       appendLedger(ctx.cwd, "main_model_failover", { from: current, to: candidateRef, backupIndex, backupCount: refs.length, reason: failure.kind });
-      ctx.ui.notify(`Main session model failover: ${current} → backup ${backupIndex}/${refs.length} ${candidateRef}. The next supervised turn tests it; a successful turn clears recovery.`, "warning");
+      ctx.ui.notify(`Main session model failover: ${current} → backup ${backupIndex}/${refs.length} ${candidateRef}. The next supervised turn tests it; a healthy fallback schedules a preferred-primary failback probe.`, "warning");
       return true;
     } catch (err) {
       // A user cancellation or host replacement may have cleared/replaced the
@@ -640,6 +689,8 @@ export function setMainModelRecoveryPause(ctx: ExtensionContext, recovery: MainM
   state.mainModelRecovery = {
     ...normalized,
     retryAt,
+    primaryProbeAt: undefined,
+    primaryProbeInFlight: undefined,
     manualResumeRequired: undefined,
     reason: sanitizeProviderDisplayText(normalized.reason),
   };
@@ -703,6 +754,43 @@ export function scheduleMainModelRecoveryTimer(ctx: ExtensionContext, delayMs: n
   scheduleHourlyProbe(ctx);
 }
 
+/** Keep the preferred-primary probe separate from the parked-recovery wait.
+ * `retryAt` means the goal/loop is paused; `primaryProbeAt` means the
+ * fallback is serving successfully and work may continue normally. */
+export function scheduleMainModelPrimaryProbe(ctx: ExtensionContext, delayMs?: number): void {
+  const recovery = state.mainModelRecovery;
+  if (!recovery || recovery.manualResumeRequired === true || !mainModelFailbackEnabled()) return;
+  if (recovery.primaryProbeInFlight) return;
+  const configuredAt = recovery.primaryProbeAt ? Date.parse(recovery.primaryProbeAt) : Number.NaN;
+  const requestedDelay = delayMs === undefined
+    ? Number.isFinite(configuredAt) ? Math.max(0, configuredAt - Date.now()) : mainModelPrimaryProbeDelay()
+    : Math.max(0, delayMs);
+  const probeAt = Number.isFinite(configuredAt) && delayMs === undefined
+    ? recovery.primaryProbeAt
+    : new Date(Date.now() + requestedDelay).toISOString();
+  const changed = recovery.primaryProbeAt !== probeAt
+    || recovery.retryAt !== undefined
+    || recovery.pendingModelSwitch !== undefined;
+  if (changed) {
+    state.mainModelRecovery = {
+      ...recovery,
+      primaryProbeAt: probeAt,
+      primaryProbeInFlight: undefined,
+      retryAt: undefined,
+      pendingModelSwitch: undefined,
+      resumeCurrent: undefined,
+    };
+    persistState(ctx);
+    appendLedger(ctx.cwd, "main_model_failback_scheduled", {
+      primary: recovery.primary,
+      active: recovery.active,
+      probeAt,
+      delayMs: requestedDelay,
+    });
+  }
+  scheduleMainModelRecoveryTimer(ctx, requestedDelay);
+}
+
 // =================================================================
 // v0.34.142: hourly retry ticker — optional (default ON) extra retry at :00:30
 // every hour while main-model recovery is parked. This is a blind retry slot:
@@ -815,6 +903,8 @@ export function manuallyResumeMainModelRecovery(ctx: ExtensionContext): boolean
     firstFailureAt: new Date(now).toISOString(),
     autoRetryUntil: mainModelAutoRetryUntil(now, MAIN_MODEL_AUTO_RETRY_HORIZON_MS),
     retryAt: undefined,
+    primaryProbeAt: undefined,
+    primaryProbeInFlight: undefined,
     manualResumeRequired: undefined,
     resumeCurrent: undefined,
     providerErrorDiagnostic: undefined,
@@ -863,6 +953,153 @@ export async function probeMainModelRecovery(ctx: ExtensionContext): Promise<voi
   }
 }
 
+async function probePreferredPrimary(ctx: ExtensionContext, recovery: MainModelRecovery): Promise<void> {
+  if (!mainModelFailbackEnabled()) {
+    clearMainModelRecoveryTimer();
+    state.mainModelRecovery = undefined;
+    persistState(ctx);
+    appendLedger(ctx.cwd, "main_model_failback_cancelled", { reason: "sticky policy" });
+    return;
+  }
+  const generation = flags.sessionGeneration;
+  const primary = recovery.primary;
+  const current = modelRef(ctx.model);
+
+  // A host/session replacement may have committed the switch before the
+  // replacement process rehydrated its durable marker. Treat that as the
+  // same in-flight probe and wait for one real supervised turn before
+  // declaring the primary healthy.
+  if (recovery.primaryProbeInFlight && sameModelRef(current, primary)) {
+    const reconciled = {
+      ...recovery,
+      active: current,
+      attempted: [primary],
+      primaryProbeAt: undefined,
+      primaryProbeInFlight: true,
+      pendingModelSwitch: undefined,
+      retryAt: undefined,
+    };
+    state.mainModelRecovery = reconciled;
+    persistState(ctx);
+    appendLedger(ctx.cwd, "main_model_failback_reconciled", { primary, generation });
+    scheduleSupervisedPrimaryProbe(ctx, reconciled);
+    return;
+  }
+
+  // The timer can fire after the host has already selected the primary (for
+  // example, a restore event races the timer). Still require a supervised
+  // turn; setModel alone is not a provider health check.
+  if (!recovery.primaryProbeInFlight && sameModelRef(current, primary)) {
+    const inFlight = {
+      ...recovery,
+      active: current,
+      attempted: [primary],
+      primaryProbeAt: undefined,
+      primaryProbeInFlight: true,
+      pendingModelSwitch: undefined,
+      retryAt: undefined,
+    };
+    state.mainModelRecovery = inFlight;
+    persistState(ctx);
+    appendLedger(ctx.cwd, "main_model_failback_probe", { from: current, to: primary, mode: "already-selected" });
+    scheduleSupervisedPrimaryProbe(ctx, inFlight);
+    return;
+  }
+
+  if (isForbiddenModel(primary, loadGlobalSettings().forbiddenModels)) {
+    clearMainModelRecoveryTimer();
+    state.mainModelRecovery = undefined;
+    persistState(ctx);
+    appendLedger(ctx.cwd, "main_model_failback_cancelled", { primary, reason: "forbidden" });
+    ctx.ui.notify(`Main-model failback skipped ${primary} because forbiddenModels excludes it; the current fallback remains selected.`, "warning");
+    return;
+  }
+  const candidate = resolveMainModel(ctx, primary);
+  if (!candidate) {
+    const delay = mainModelPrimaryProbeDelay();
+    state.mainModelRecovery = {
+      ...recovery,
+      active: current ?? recovery.active,
+      primaryProbeAt: new Date(Date.now() + delay).toISOString(),
+      primaryProbeInFlight: undefined,
+      pendingModelSwitch: undefined,
+      retryAt: undefined,
+    };
+    persistState(ctx);
+    appendLedger(ctx.cwd, "main_model_failback_unavailable", { primary, reason: "primary not in registry" });
+    scheduleMainModelPrimaryProbe(ctx, delay);
+    return;
+  }
+
+  if (flags.mainModelSwitchInFlight && modelSwitchOperationGeneration !== generation) {
+    flags.mainModelSwitchInFlight = false;
+    activeModelSwitchToken = 0;
+    modelSwitchOperationGeneration = null;
+  }
+  if (flags.mainModelSwitchInFlight) return;
+  const operationToken = ++modelSwitchOperationToken;
+  activeModelSwitchToken = operationToken;
+  modelSwitchOperationGeneration = generation;
+  const pending = {
+    ...recovery,
+    active: current ?? recovery.active,
+    attempted: current ? [current] : recovery.attempted,
+    primaryProbeAt: undefined,
+    primaryProbeInFlight: true,
+    pendingModelSwitch: primary,
+    retryAt: new Date(Date.now() + 1_000).toISOString(),
+  };
+  state.mainModelRecovery = pending;
+  persistState(ctx);
+  flags.mainModelSwitchInFlight = true;
+  try {
+    if (generation !== flags.sessionGeneration || !freshCtxForGeneration(generation)) return;
+    const accepted = await flags.extensionApi?.setModel(candidate);
+    if (generation !== flags.sessionGeneration || !freshCtxForGeneration(generation)) return;
+    if (state.mainModelRecovery?.pendingModelSwitch?.toLowerCase() !== primary.toLowerCase()) return;
+    if (!accepted) throw new Error("no configured auth for preferred primary");
+    const switched = {
+      ...state.mainModelRecovery!,
+      active: primary,
+      attempted: [primary],
+      primaryProbeAt: undefined,
+      primaryProbeInFlight: true,
+      pendingModelSwitch: undefined,
+      retryAt: undefined,
+    };
+    state.mainModelRecovery = switched;
+    persistState(ctx);
+    appendLedger(ctx.cwd, "main_model_failback", { from: current, to: primary });
+    ctx.ui.notify(`Main session model failed back to ${primary} from ${current ?? "the fallback"}; the next supervised turn tests the primary.`, "info");
+    scheduleSupervisedPrimaryProbe(ctx, switched);
+  } catch (err) {
+    if (generation !== flags.sessionGeneration || state.mainModelRecovery?.pendingModelSwitch?.toLowerCase() !== primary.toLowerCase()) return;
+    const delay = mainModelPrimaryProbeDelay();
+    const next = {
+      ...state.mainModelRecovery!,
+      active: current ?? recovery.active,
+      primaryProbeAt: new Date(Date.now() + delay).toISOString(),
+      primaryProbeInFlight: undefined,
+      pendingModelSwitch: undefined,
+      retryAt: undefined,
+    };
+    state.mainModelRecovery = next;
+    persistState(ctx);
+    appendLedger(ctx.cwd, "main_model_failback_failed", {
+      primary,
+      error: err instanceof Error ? err.message : String(err),
+      nextProbeAt: next.primaryProbeAt,
+    });
+    scheduleMainModelPrimaryProbe(ctx, delay);
+  } finally {
+    if (activeModelSwitchToken === operationToken) {
+      activeModelSwitchToken = 0;
+      modelSwitchOperationGeneration = null;
+      flags.mainModelSwitchInFlight = false;
+    }
+  }
+}
+
 async function probeMainModelRecoveryImpl(ctx: ExtensionContext): Promise<void> {
   const generation = flags.sessionGeneration;
   const recovery = state.mainModelRecovery;
@@ -877,8 +1114,22 @@ async function probeMainModelRecoveryImpl(ctx: ExtensionContext): Promise<void>
     state.mainModelRecovery = { ...recovery, active: current, pendingModelSwitch: undefined, retryAt: undefined };
     persistState(ctx);
   }
+  const preferredPrimaryRecovery = state.mainModelRecovery;
+  if (preferredPrimaryRecovery?.primaryProbeAt || preferredPrimaryRecovery?.primaryProbeInFlight) {
+    await probePreferredPrimary(ctx, preferredPrimaryRecovery);
+    return;
+  }
   if (recovery.resumeCurrent && current) {
-    state.mainModelRecovery = { ...recovery, active: current, attempted: [current], retryAt: undefined, resumeCurrent: undefined, pendingModelSwitch: undefined };
+    state.mainModelRecovery = {
+      ...recovery,
+      active: current,
+      attempted: [current],
+      primaryProbeAt: undefined,
+      primaryProbeInFlight: undefined,
+      retryAt: undefined,
+      resumeCurrent: undefined,
+      pendingModelSwitch: undefined,
+    };
     flags.continuationDispatchStoodDown = false;
     if (recovery.kind === "goal" && state.goal?.status === "paused" && (state.goal.pauseReason ?? "").startsWith("main model recovery")) {
       updateGoal({ status: "active", pauseKind: undefined, pauseResumeAt: undefined, pauseReason: undefined, pauseSuggestedAction: undefined, providerErrorDiagnostic: undefined, recoveryEpisodeKey: undefined, recoveryNoticeKeys: undefined }, ctx);
@@ -1038,7 +1289,15 @@ async function probeMainModelRecoveryImpl(ctx: ExtensionContext): Promise<void>
     if (generation !== flags.sessionGeneration || !freshCtxForGeneration(generation)) return;
     if (state.mainModelRecovery?.pendingModelSwitch?.toLowerCase() !== target.toLowerCase()) return;
     if (!accepted) throw new Error(`no configured auth for ${target}`);
-    state.mainModelRecovery = { ...state.mainModelRecovery!, active: target, attempted, pendingModelSwitch: undefined, retryAt: undefined };
+    state.mainModelRecovery = {
+      ...state.mainModelRecovery!,
+      active: target,
+      attempted,
+      primaryProbeAt: undefined,
+      primaryProbeInFlight: undefined,
+      pendingModelSwitch: undefined,
+      retryAt: undefined,
+    };
     persistState(ctx);
     appendLedger(ctx.cwd, "main_model_probe", { from: current, to: target, tryLabel: targetTryLabel, attempts: recovery.attempts });
     flags.continuationDispatchStoodDown = false;
@@ -1147,6 +1406,57 @@ export async function recoverMainModelFromSendStorm(ctx: ExtensionContext, kind:
 export function mainModelRecoverySucceeded(ctx: ExtensionContext): void {
   const recovery = state.mainModelRecovery;
   if (!recovery) return;
+  const current = modelRef(ctx.model);
+  const preferredPrimary = recovery.primary;
+  const servingFallback = !!current && !sameModelRef(current, preferredPrimary);
+
+  // A successful fallback turn proves only that the backup works. Keep the
+  // original primary durable and schedule a reverse probe instead of settling
+  // the episode permanently on the fallback.
+  if (servingFallback && mainModelFailbackEnabled()) {
+    const existingProbeAt = recovery.primaryProbeAt;
+    const existingProbeMs = existingProbeAt ? Date.parse(existingProbeAt) : Number.NaN;
+    const alreadyScheduled = Number.isFinite(existingProbeMs) && !recovery.primaryProbeInFlight;
+    clearMainModelRecoveryTimer();
+    cancelHourlyProbe();
+    flags.lastMainModelFailure = null;
+    flags.mainModelAbortForRecovery = false;
+    flags.continuationDispatchStoodDown = false;
+    flags.lastMainModelRecoveryResumeAt = Date.now();
+
+    const probeAt = alreadyScheduled
+      ? existingProbeAt!
+      : new Date(Date.now() + mainModelPrimaryProbeDelay()).toISOString();
+    const nextRecovery: MainModelRecovery = {
+      ...recovery,
+      active: current,
+      primaryProbeAt: probeAt,
+      primaryProbeInFlight: undefined,
+      retryAt: undefined,
+      pendingModelSwitch: undefined,
+      resumeCurrent: undefined,
+    };
+    state.mainModelRecovery = nextRecovery;
+    const auditRetryStarted = recovery.kind === "goal"
+      && state.goal?.status === "paused"
+      && !!state.goal.pendingCompletion
+      && typeof maybeAutoRetryParkedCompletionAudit === "function"
+      && maybeAutoRetryParkedCompletionAudit("main-model-recovery");
+    persistState(ctx);
+    if (!alreadyScheduled) {
+      appendLedger(ctx.cwd, "main_model_fallback_healthy", {
+        model: current,
+        primary: preferredPrimary,
+        primaryProbeAt: probeAt,
+        attempts: recovery.attempts,
+      });
+      ctx.ui.notify(`Main session fallback ${current} is healthy; the preferred primary ${preferredPrimary} will be probed automatically.`, "info");
+    }
+    if (auditRetryStarted) ctx.ui.notify("The stored completion audit is retrying after the healthy main-model fallback.", "info");
+    scheduleMainModelRecoveryTimer(ctx, Math.max(0, Date.parse(probeAt) - Date.now()));
+    return;
+  }
+
   clearMainModelRecoveryTimer();
   cancelHourlyProbe(); // recovery settled — ticker stops
   state.mainModelRecovery = undefined;
@@ -1169,7 +1479,7 @@ export function mainModelRecoverySucceeded(ctx: ExtensionContext): void {
     : recovery.kind === "loop" && recoveryLoop
       ? "loop"
       : undefined;
-  appendLedger(ctx.cwd, "main_model_recovered", { model: modelRef(ctx.model), attempts: recovery.attempts, resumed });
+  appendLedger(ctx.cwd, "main_model_recovered", { model: current, attempts: recovery.attempts, resumed });
   // A successful bounded provider recovery is also a healthy recovery event
   // for a parked detached-auditor claim. The auditor hook owns the durable
   // one-shot marker and generation/context fence; this call never bypasses
@@ -1195,7 +1505,7 @@ export function mainModelRecoverySucceeded(ctx: ExtensionContext): void {
   } else {
     persistState(ctx);
   }
-  ctx.ui.notify(`Main session model recovered on ${modelRef(ctx.model) ?? "the active model"}; automatic recovery is cleared${resumed ? ` and the ${resumed} is resuming` : auditRetryStarted ? " and the stored completion audit is retrying" : ""}.`, "info");
+  ctx.ui.notify(`Main session model recovered on ${current ?? "the active model"}; automatic recovery is cleared${resumed ? ` and the ${resumed} is resuming` : auditRetryStarted ? " and the stored completion audit is retrying" : ""}.`, "info");
 }
 
 /** Handle a provider error before loop/goal bookkeeping can mistake it for

package/extensions/goal-settings.ts

@@ -5,6 +5,13 @@
 // without importing the whole extension. Two-tier config (v0.7.0): GLOBAL
 // is the normal home, PROJECT the rare local override. Resolution:
 // project > global > defaults (per key).
+//
+// v0.35.6: this module owns the typed boundary for the long-term
+// preferences policy (audit/LONG-TERM-PREFERENCES-POLICY-2026-08-19.md).
+// The Settings interface is the ONLY schema accepted by saveSettings;
+// natural-language conversation / completion / auditor / Explore
+// transcripts are NEVER written here. A regression in
+// tests/long-term-preferences-boundary.test.ts pins this boundary.
 
 import * as fs from "node:fs";
 import * as os from "node:os";
@@ -17,7 +24,10 @@ import {
   piGlaDir,
 } from "./goal-loop-core.ts";
 import type { SubagentModelStrategy } from "./goal-loop-subagents.js";
-import { normalizeMainModelFallbackRefs } from "./main-model-recovery.js";
+import {
+  DEFAULT_MAIN_MODEL_PRIMARY_PROBE_MINUTES,
+  normalizeMainModelFallbackRefs,
+} from "./main-model-recovery.js";
 
 export interface Settings {
   /** v0.34.57: model refs/ids that must never be selected — the policy
@@ -56,6 +66,12 @@ export interface Settings {
   subagentFallbacks?: Record<string, string[]>;
   /** Global-only base minutes before main-session recovery; doubles per attempt, caps at 5h, and the automatic window ends at 24h. */
   mainModelRetryMinutes?: number;
+  /** Global-only: after a fallback succeeds, automatically test the preferred
+   * primary again, or keep the fallback for the rest of the session. */
+  mainModelFailback?: "auto" | "sticky";
+  /** Global-only minutes between preferred-primary health probes while a
+   * fallback is serving successfully. */
+  mainModelPrimaryProbeMinutes?: number;
   /** "provider/model-id" or bare "model-id". Unset → session model. */
   auditorModel?: string;
   /** v0.31.3/v0.34.25: next detached auditor candidate when the primary
@@ -181,6 +197,8 @@ export interface Settings {
 const GLOBAL_MAIN_RECOVERY_KEYS: ReadonlySet<keyof Settings> = new Set([
   "mainModelFallbacks",
   "mainModelRetryMinutes",
+  "mainModelFailback",
+  "mainModelPrimaryProbeMinutes",
   "hourlyRetryProbe",
   "drafterModel",
   "drafterThinkingLevel",
@@ -201,6 +219,8 @@ export const DEFAULT_SETTINGS: Settings = {
   // vision CLI job, never a reason to switch models (note.md 2026-08-07).
   visionAssist: true,
   mainModelRetryMinutes: 15,
+  mainModelFailback: "auto",
+  mainModelPrimaryProbeMinutes: DEFAULT_MAIN_MODEL_PRIMARY_PROBE_MINUTES,
   // Unset = inherit the session thinking level while the temporary drafter
   // agent is active; the original session level is restored afterward.
   drafterThinkingLevel: undefined,
@@ -260,6 +280,14 @@ function normalizeLoadedSettings(settings: Settings): Settings {
   // all see the same bounded value.
   settings.mainModelFallbacks = normalizeMainModelFallbackRefs(settings.mainModelFallbacks);
   settings.drafterModelFallbacks = normalizeMainModelFallbackRefs(settings.drafterModelFallbacks);
+  if (settings.mainModelFailback !== "auto" && settings.mainModelFailback !== "sticky") {
+    settings.mainModelFailback = "auto";
+  }
+  if (typeof settings.mainModelPrimaryProbeMinutes !== "number"
+      || !Number.isFinite(settings.mainModelPrimaryProbeMinutes)
+      || settings.mainModelPrimaryProbeMinutes <= 0) {
+    settings.mainModelPrimaryProbeMinutes = DEFAULT_MAIN_MODEL_PRIMARY_PROBE_MINUTES;
+  }
   // v0.34.142: these old policy knobs no longer control recovery. Drop
   // them from the effective object so stale files cannot resurrect the old
   // behavior or make the settings UI imply that quota inspection exists.
@@ -317,6 +345,8 @@ export const SETTINGS_KEYS: Array<keyof Settings> = [
   "drafterThinkingLevel",
   "drafterModelFallbacks",
   "mainModelRetryMinutes",
+  "mainModelFailback",
+  "mainModelPrimaryProbeMinutes",
   "forbiddenModels",
   "blockForbiddenModelSwitches",
   "visionAssist",