switchroom 0.18.9 → 0.18.11

package/dist/agent-scheduler/index.js

@@ -11646,6 +11646,7 @@ var SwitchroomConfigSchema = exports_external.object({
       uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
       mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here — in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) — swallowed when CAP_CHOWN is absent.")
     })).optional().describe("Non-agent peers that hold a broker socket (RFC H §4.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),
+    proactive_failover_pct: exports_external.number().min(1).max(99).optional().describe("Soft-avoid threshold (percent) for proactive auth failover (#3031). " + "When set (e.g. 95), an account whose fresh 7-day utilization is at/" + "above this value — or whose 5h utilization is at/above min(pct+3, " + "98) — enters the SOFT-AVOID preference tier: the broker prefers a " + "fully-eligible fallback account on the serving path, without ever " + "blocking the account (the hard wall stays 99.5). Enter/exit uses " + "hysteresis (exit below pct-5 or on window reset) so the preference " + "does not flap between probe ticks. Accounts serving past the wall " + "via `allow_overage_accounts` are never soft-avoided. UNSET (the " + "default) disables the tier entirely — behavior is identical to a " + "fleet without this field."),
     allow_overage_accounts: exports_external.array(exports_external.string().min(1)).optional().describe("Opt-in list of account labels (bare strings matching `auth.active` / " + "`auth.fallback_order` entries) that may be served PAST the weekly " + "utilization wall when Anthropic overage billing is available for the " + "account (`overageStatus === 'allowed'`). Overage is REAL MONEY — " + "default is empty (no account gets this). An account in this list is " + "only kept eligible when its fresh quota snapshot reports " + "`overageStatus: 'allowed'` AND `overageDisabledReason` is NOT " + "'out_of_credits' (i.e. the overage credit has not been exhausted). " + "As soon as `overageDisabledReason` becomes 'out_of_credits', the " + "account is blocked immediately regardless of this flag. Overage lifts " + "ONLY the utilization wall — it cannot lift an active exhaustion mark " + "written by a real 429 (`mark-exhausted`).")
   }).optional().describe("Switchroom-auth-broker configuration (RFC H). Fleet-wide active account, " + "fallback order, admin-agent ACL, and ephemeral-consumer surface. " + "Required from the v0.8+ schema onwards; pre-v0.8 fleets are migrated " + "in-place by `switchroom apply` (see src/auth/migrate-schema.ts)."),
   drive: GoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Optional Google " + "Workspace onboarding configuration. When set, supplies Google OAuth " + "client credentials, the approver allowlist for `switchroom drive " + "connect`, and the optional tier knob. Env vars " + "(SWITCHROOM_GOOGLE_CLIENT_ID, SWITCHROOM_GOOGLE_CLIENT_SECRET, " + "SWITCHROOM_APPROVER_USER_ID) take precedence over this block when " + "set, preserving back-compat with the env-only flow shipped in #766."),

package/dist/auth-broker/index.js

@@ -17275,6 +17275,7 @@ var SwitchroomConfigSchema = exports_external.object({
       uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
       mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here — in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) — swallowed when CAP_CHOWN is absent.")
     })).optional().describe("Non-agent peers that hold a broker socket (RFC H §4.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),
+    proactive_failover_pct: exports_external.number().min(1).max(99).optional().describe("Soft-avoid threshold (percent) for proactive auth failover (#3031). " + "When set (e.g. 95), an account whose fresh 7-day utilization is at/" + "above this value — or whose 5h utilization is at/above min(pct+3, " + "98) — enters the SOFT-AVOID preference tier: the broker prefers a " + "fully-eligible fallback account on the serving path, without ever " + "blocking the account (the hard wall stays 99.5). Enter/exit uses " + "hysteresis (exit below pct-5 or on window reset) so the preference " + "does not flap between probe ticks. Accounts serving past the wall " + "via `allow_overage_accounts` are never soft-avoided. UNSET (the " + "default) disables the tier entirely — behavior is identical to a " + "fleet without this field."),
     allow_overage_accounts: exports_external.array(exports_external.string().min(1)).optional().describe("Opt-in list of account labels (bare strings matching `auth.active` / " + "`auth.fallback_order` entries) that may be served PAST the weekly " + "utilization wall when Anthropic overage billing is available for the " + "account (`overageStatus === 'allowed'`). Overage is REAL MONEY — " + "default is empty (no account gets this). An account in this list is " + "only kept eligible when its fresh quota snapshot reports " + "`overageStatus: 'allowed'` AND `overageDisabledReason` is NOT " + "'out_of_credits' (i.e. the overage credit has not been exhausted). " + "As soon as `overageDisabledReason` becomes 'out_of_credits', the " + "account is blocked immediately regardless of this flag. Overage lifts " + "ONLY the utilization wall — it cannot lift an active exhaustion mark " + "written by a real 429 (`mark-exhausted`).")
   }).optional().describe("Switchroom-auth-broker configuration (RFC H). Fleet-wide active account, " + "fallback order, admin-agent ACL, and ephemeral-consumer surface. " + "Required from the v0.8+ schema onwards; pre-v0.8 fleets are migrated " + "in-place by `switchroom apply` (see src/auth/migrate-schema.ts)."),
   drive: GoogleWorkspaceConfigSchema.describe("RFC D legacy key — use `google_workspace:` instead. Optional Google " + "Workspace onboarding configuration. When set, supplies Google OAuth " + "client credentials, the approver allowlist for `switchroom drive " + "connect`, and the optional tier knob. Env vars " + "(SWITCHROOM_GOOGLE_CLIENT_ID, SWITCHROOM_GOOGLE_CLIENT_SECRET, " + "SWITCHROOM_APPROVER_USER_ID) take precedence over this block when " + "set, preserving back-compat with the env-only flow shipped in #766."),
@@ -18135,7 +18136,7 @@ import_handlebars.default.registerHelper("isNumber", (value) => {
   return typeof value === "number" && Number.isFinite(value);
 });
 var SHARED_FRAGMENTS_DIR = resolve4(PROFILES_ROOT, "_shared");
-var SHARED_FRAGMENTS = ["vault-protocol", "agent-self-service", "execution-discipline", "reply-discipline"];
+var SHARED_FRAGMENTS = ["vault-protocol", "agent-self-service", "execution-discipline", "reply-discipline", "dev-protocol"];
 for (const name of SHARED_FRAGMENTS) {
   const fragPath = join2(SHARED_FRAGMENTS_DIR, `${name}.md.hbs`);
   if (existsSync4(fragPath)) {
@@ -18754,6 +18755,51 @@ function clampMarkExpiry(opts) {
   const liveContradictsWeeklyWall = snapshotFresh(snapshot, now) && snapshot.sevenDayUtilizationPct < WALL_PCT;
   return liveContradictsWeeklyWall ? shortCeil : proposedUntil;
 }
+var SOFT_AVOID_FIVE_HOUR_CAP = 98;
+var SOFT_AVOID_EXIT_MARGIN = 5;
+function softAvoidThresholds(pct) {
+  return { sevenDay: pct, fiveHour: Math.min(pct + 3, SOFT_AVOID_FIVE_HOUR_CAP) };
+}
+function evaluateSoftAvoid(opts) {
+  const { snapshot, now, pct, overageLifted = false, prev } = opts;
+  if (pct === undefined)
+    return { softAvoided: false };
+  if (overageLifted)
+    return { softAvoided: false };
+  if (!snapshotFresh(snapshot, now)) {
+    return prev ?? { softAvoided: false };
+  }
+  const s = snapshot;
+  const thresholds = softAvoidThresholds(pct);
+  const fiveRefilled = s.fiveHourResetAtMs != null && s.fiveHourResetAtMs <= now;
+  const sevenRefilled = s.sevenDayResetAtMs != null && s.sevenDayResetAtMs <= now;
+  const five = fiveRefilled ? 0 : s.fiveHourUtilizationPct;
+  const seven = sevenRefilled ? 0 : s.sevenDayUtilizationPct;
+  const nextState = (softAvoided, triggeredBy) => ({
+    softAvoided,
+    ...softAvoided && triggeredBy ? { triggeredBy } : {},
+    fiveHourResetAt: s.fiveHourResetAtMs ?? prev?.fiveHourResetAt ?? null,
+    sevenDayResetAt: s.sevenDayResetAtMs ?? prev?.sevenDayResetAt ?? null
+  });
+  const fiveTriggered = five >= thresholds.fiveHour;
+  const sevenTriggered = seven >= thresholds.sevenDay;
+  if (fiveTriggered || sevenTriggered) {
+    const prevTrig = prev?.softAvoided ? prev.triggeredBy ?? { fiveHour: true, sevenDay: true } : undefined;
+    return nextState(true, {
+      fiveHour: fiveTriggered || (prevTrig?.fiveHour ?? false),
+      sevenDay: sevenTriggered || (prevTrig?.sevenDay ?? false)
+    });
+  }
+  if (prev?.softAvoided) {
+    const trig = prev.triggeredBy ?? { fiveHour: true, sevenDay: true };
+    const fiveReleased = !trig.fiveHour || fiveRefilled || prev.fiveHourResetAt != null && s.fiveHourResetAtMs != null && s.fiveHourResetAtMs > prev.fiveHourResetAt || five < thresholds.fiveHour - SOFT_AVOID_EXIT_MARGIN;
+    const sevenReleased = !trig.sevenDay || sevenRefilled || prev.sevenDayResetAt != null && s.sevenDayResetAtMs != null && s.sevenDayResetAtMs > prev.sevenDayResetAt || seven < thresholds.sevenDay - SOFT_AVOID_EXIT_MARGIN;
+    if (fiveReleased && sevenReleased)
+      return nextState(false);
+    return nextState(true, trig);
+  }
+  return nextState(false);
+}
 
 // src/auth/broker/consumer-quota-sensor.ts
 var EXHAUSTION_PCT = 99.5;
@@ -20017,6 +20063,7 @@ class AuthBroker {
   shaIndex = {};
   thresholdViolations = {};
   notificationClaims = {};
+  lastFleetRoll = null;
   lastWrittenExpiresAt = new Map;
   refreshInFlight = new Set;
   consumerLastSeen = {};
@@ -20473,6 +20520,41 @@ class AuthBroker {
       allowOverage: this.isOverageAllowed(account)
     });
   }
+  softAvoidState = {};
+  softAvoidRolledTo = {};
+  softAvoidSnapshotOf(account) {
+    const s = this.lastQuotaCache[account];
+    if (!s)
+      return;
+    return {
+      ...s,
+      fiveHourResetAtMs: s.fiveHourResetAt ? Date.parse(s.fiveHourResetAt) : null,
+      sevenDayResetAtMs: s.sevenDayResetAt ? Date.parse(s.sevenDayResetAt) : null
+    };
+  }
+  isAccountSoftAvoided(account) {
+    const pct = this.config.auth?.proactive_failover_pct;
+    if (pct === undefined)
+      return false;
+    const now = this.now();
+    const snapshot = this.softAvoidSnapshotOf(account);
+    const overageLifted = !!snapshot && snapshotFresh(snapshot, now) && overageLiftsWall(snapshot, this.isOverageAllowed(account));
+    const state = evaluateSoftAvoid({
+      snapshot,
+      now,
+      pct,
+      overageLifted,
+      prev: this.softAvoidState[account]
+    });
+    this.softAvoidState[account] = state;
+    return state.softAvoided;
+  }
+  softAvoidUtilScore(account) {
+    const s = this.lastQuotaCache[account];
+    if (!s || !snapshotFresh(s, this.now()))
+      return Number.POSITIVE_INFINITY;
+    return Math.max(s.fiveHourUtilizationPct, s.sevenDayUtilizationPct);
+  }
   isActiveOverageServing(account) {
     if (!account)
       return false;
@@ -20519,8 +20601,9 @@ class AuthBroker {
   }
   async nextHealthyAccountLive(current, order) {
     const cached = this.nextHealthyAccount(current, order);
-    if (cached && this.accountEligibilityOf(cached) === "eligible")
+    if (cached && this.accountEligibilityOf(cached) === "eligible" && !this.isAccountSoftAvoided(cached)) {
       return cached;
+    }
     const start = order.indexOf(current);
     const ring = start === -1 ? [...order] : order.map((_, i) => order[(start + 1 + i) % order.length]).filter((x) => !!x);
     const unknowns = ring.filter((cand) => cand && cand !== current && accountExists(cand, this.home) && this.accountEligibilityOf(cand) === "unknown");
@@ -20536,14 +20619,46 @@ class AuthBroker {
     return null;
   }
   accountWithFailover(account) {
-    if (!account || !this.isAccountExhausted(account))
-      return account ?? null;
+    if (!account)
+      return null;
+    const exhausted = this.isAccountExhausted(account);
+    if (!exhausted && !this.isAccountSoftAvoided(account))
+      return account;
+    let softAvoidExcludedAny = false;
     for (const cand of this.config.auth?.fallback_order ?? []) {
       if (cand === account || this.isAccountExhausted(cand))
         continue;
+      if (this.isAccountSoftAvoided(cand)) {
+        softAvoidExcludedAny = true;
+        continue;
+      }
       if (readAccountCredentials(cand, this.home))
         return cand;
     }
+    if (!exhausted) {
+      let best = account;
+      let bestScore = this.softAvoidUtilScore(account);
+      for (const cand of this.config.auth?.fallback_order ?? []) {
+        if (cand === account || this.isAccountExhausted(cand))
+          continue;
+        if (!readAccountCredentials(cand, this.home))
+          continue;
+        const score = this.softAvoidUtilScore(cand);
+        if (score < bestScore) {
+          best = cand;
+          bestScore = score;
+        }
+      }
+      return best;
+    }
+    if (softAvoidExcludedAny) {
+      for (const cand of this.config.auth?.fallback_order ?? []) {
+        if (cand === account || this.isAccountExhausted(cand))
+          continue;
+        if (readAccountCredentials(cand, this.home))
+          return cand;
+      }
+    }
     const active = this.config.auth?.active;
     if (active && active !== account && !this.isAccountExhausted(active) && readAccountCredentials(active, this.home)) {
       return active;
@@ -20603,7 +20718,8 @@ class AuthBroker {
       accounts,
       agents,
       consumers,
-      active_overage_serving
+      active_overage_serving,
+      last_fleet_roll: this.lastFleetRoll
     }));
   }
   async opListGoogleAccounts(socket, id, identity) {
@@ -20698,6 +20814,7 @@ class AuthBroker {
     }
   }
   async fleetQuotaProbeTick() {
+    const probed = [];
     for (const label of listAccounts(this.home)) {
       const creds = readAccountCredentials(label, this.home);
       const token = creds?.claudeAiOauth?.accessToken;
@@ -20711,16 +20828,65 @@ class AuthBroker {
         continue;
       }
       this.cacheQuotaSnapshot(label, result);
+      probed.push({ label, result });
+    }
+    for (const { label, result } of probed) {
       const active = this.config.auth?.active;
-      if (label !== active)
+      const isPinnedAgentAccount = this.pinnedAgentAccounts().has(label);
+      if (label !== active && !isPinnedAgentAccount)
         continue;
       const decision = quotaIndicatesExhaustion(result, this.isOverageAllowed(label));
-      if (!decision.exhausted)
+      if (decision.exhausted) {
+        process.stdout.write(`auth-broker: fleet-quota-probe shows ${label === active ? "ACTIVE" : "PINNED"} ${label} exhausted — proactive failover
+`);
+        this.audit({ op: "mark-exhausted", identity: { kind: "operator" }, account: label, accountKind: "claude", ok: true, reason: "hard-exhaustion" });
+        const { rolledTo } = await this.markExhaustedAndRoll(label, decision.until ?? undefined, { kind: "operator" });
+        if (rolledTo && label === active) {
+          this.recordFleetRoll(label, rolledTo, "hard-exhaustion", decision.until ?? undefined);
+        }
         continue;
-      process.stdout.write(`auth-broker: fleet-quota-probe shows ACTIVE ${label} exhausted — proactive failover
+      }
+      this.softAvoidProbeRoll(label);
+    }
+  }
+  recordFleetRoll(from, to, reason, exhaustedUntil) {
+    const s = this.lastQuotaCache[from];
+    this.lastFleetRoll = {
+      from,
+      to,
+      at: this.now(),
+      reason,
+      ...exhaustedUntil != null ? { exhausted_until: exhaustedUntil } : {},
+      ...s ? {
+        window: s.fiveHourUtilizationPct >= s.sevenDayUtilizationPct ? "5h" : "7d",
+        pct: Math.max(s.fiveHourUtilizationPct, s.sevenDayUtilizationPct)
+      } : {}
+    };
+    this.persistLastFleetRoll();
+  }
+  pinnedAgentAccounts() {
+    return new Set(Object.values(this.config.agents ?? {}).map((a) => a.auth?.override).filter((x) => typeof x === "string" && x.length > 0));
+  }
+  softAvoidProbeRoll(label) {
+    if (!this.isAccountSoftAvoided(label)) {
+      delete this.softAvoidRolledTo[label];
+      return;
+    }
+    const target = this.accountWithFailover(label);
+    if (!target || target === label || this.isAccountSoftAvoided(target)) {
+      delete this.softAvoidRolledTo[label];
+      return;
+    }
+    if (this.softAvoidRolledTo[label] === target)
+      return;
+    this.softAvoidRolledTo[label] = target;
+    process.stdout.write(`auth-broker: fleet-quota-probe shows ${label} soft-avoided (≥ auth.proactive_failover_pct) — serving-preference roll → ${target}
 `);
-      this.audit({ op: "mark-exhausted", identity: { kind: "operator" }, account: label, accountKind: "claude", ok: true });
-      await this.markExhaustedAndRoll(label, decision.until ?? undefined, { kind: "operator" });
+    this.audit({ op: "proactive-roll", identity: { kind: "operator" }, account: label, accountKind: "claude", ok: true, reason: "soft-avoid" });
+    this.fanoutFailoverTo(label, target);
+    this.fanoutToAffectedConsumers(label);
+    if (label === this.config.auth?.active) {
+      this.recordFleetRoll(label, target, "soft-avoid");
     }
   }
   async consumerQuotaProbeTick() {
@@ -20893,6 +21059,8 @@ class AuthBroker {
       socket.write(encodeError(id, "INTERNAL", err.message));
       return;
     }
+    delete this.softAvoidState[label];
+    delete this.softAvoidRolledTo[label];
     this.chownAccountFilesIfRoot(label);
     const contents = readFileSync7(accountCredentialsPath(label, this.home), "utf-8");
     this.shaIndex[label] = sha256Hex(contents);
@@ -20934,6 +21102,8 @@ class AuthBroker {
     delete this.thresholdViolations[label];
     this.lastWrittenExpiresAt.delete(label);
     delete this.lastQuotaCache[label];
+    delete this.softAvoidState[label];
+    delete this.softAvoidRolledTo[label];
     this.persistShaIndex();
     this.persistQuota();
     this.persistThresholdViolations();
@@ -21415,14 +21585,23 @@ class AuthBroker {
     const start = order.indexOf(current);
     if (start === -1)
       return order[0] ?? null;
+    let bestSoftAvoided = null;
+    let bestScore = Number.POSITIVE_INFINITY;
     for (let i = 1;i <= order.length; i++) {
       const cand = order[(start + i) % order.length];
       if (!cand)
         continue;
-      if (!this.isAccountExhausted(cand) && accountExists(cand, this.home))
+      if (this.isAccountExhausted(cand) || !accountExists(cand, this.home))
+        continue;
+      if (!this.isAccountSoftAvoided(cand))
         return cand;
+      const score = this.softAvoidUtilScore(cand);
+      if (bestSoftAvoided === null || score < bestScore) {
+        bestSoftAvoided = cand;
+        bestScore = score;
+      }
     }
-    return null;
+    return bestSoftAvoided;
   }
   fanoutForAgent(name) {
     const auth = this.config.auth ?? {};
@@ -21515,6 +21694,7 @@ class AuthBroker {
     this.shaIndex = this.readJson("sha-index.json") ?? {};
     this.thresholdViolations = this.readJson("threshold-violations.json") ?? {};
     this.notificationClaims = this.readJson("notification-claims.json") ?? {};
+    this.lastFleetRoll = this.readJson("last-fleet-roll.json") ?? null;
     this.lastQuotaCache = this.readJson("last-quota.json") ?? {};
     this.applyActiveOverride();
   }
@@ -21572,6 +21752,10 @@ class AuthBroker {
   persistNotificationClaims() {
     atomicWriteJsonSync(join8(this.stateDir, "notification-claims.json"), this.notificationClaims, 384);
   }
+  persistLastFleetRoll() {
+    if (this.lastFleetRoll)
+      atomicWriteJsonSync(join8(this.stateDir, "last-fleet-roll.json"), this.lastFleetRoll, 384);
+  }
   persistShaIndex() {
     atomicWriteJsonSync(join8(this.stateDir, "sha-index.json"), this.shaIndex, 384);
   }
@@ -21608,7 +21792,8 @@ class AuthBroker {
       accountKind: entry.accountKind,
       ok: entry.ok,
       error: entry.error,
-      replace: entry.replace
+      replace: entry.replace,
+      reason: entry.reason
     });
     const auditPath = join8(this.stateDir, "audit.jsonl");
     try {

package/dist/cli/notion-write-pretool.mjs

@@ -12395,6 +12395,7 @@ var SwitchroomConfigSchema = exports_external.object({
       uid: exports_external.number().int().nonnegative().optional().describe("Optional UID to chown the consumer socket to (defaults to 0 = root, " + "suitable for sibling containers running as root)."),
       mirror_dir: exports_external.string().optional().describe("Optional host-side directory path. When set, the broker actively " + "writes the consumer's effective-account `.credentials.json` mirror " + "here \u2014 in addition to serving creds on demand via `get-credentials`. " + "Use this to eliminate the pull-latency gap: without a mirror the " + "consumer only gets failover creds at its next scheduled re-fetch " + "(up to 30 min). With a mirror the broker pushes failover creds " + "immediately when it detects exhaustion (consumer-quota-sensor tick, " + "or a mark-exhausted RPC on the pinned account). The directory must " + "be accessible to the broker container (bind-mounted from the host) " + "and to the consumer container; the broker writes " + "`<mirror_dir>/.credentials.json` atomically. Chown is attempted to " + "`uid` (default 0) \u2014 swallowed when CAP_CHOWN is absent.")
     })).optional().describe("Non-agent peers that hold a broker socket (RFC H \u00a74.8). Each gets " + "its own `/run/switchroom/auth-broker/<name>/sock` chowned to its UID. " + "Consumers cannot be admins; a consumer name that collides with an " + "agent (whether that agent has `admin: true` or not) is a config " + "error caught at schema validation."),
+    proactive_failover_pct: exports_external.number().min(1).max(99).optional().describe("Soft-avoid threshold (percent) for proactive auth failover (#3031). " + "When set (e.g. 95), an account whose fresh 7-day utilization is at/" + "above this value \u2014 or whose 5h utilization is at/above min(pct+3, " + "98) \u2014 enters the SOFT-AVOID preference tier: the broker prefers a " + "fully-eligible fallback account on the serving path, without ever " + "blocking the account (the hard wall stays 99.5). Enter/exit uses " + "hysteresis (exit below pct-5 or on window reset) so the preference " + "does not flap between probe ticks. Accounts serving past the wall " + "via `allow_overage_accounts` are never soft-avoided. UNSET (the " + "default) disables the tier entirely \u2014 behavior is identical to a " + "fleet without this field."),
     allow_overage_accounts: exports_external.array(exports_external.string().min(1)).optional().describe("Opt-in list of account labels (bare strings matching `auth.active` / " + "`auth.fallback_order` entries) that may be served PAST the weekly " + "utilization wall when Anthropic overage billing is available for the " + "account (`overageStatus === 'allowed'`). Overage is REAL MONEY \u2014 " + "default is empty (no account gets this). An account in this list is " + "only kept eligible when its fresh quota snapshot reports " + "`overageStatus: 'allowed'` AND `overageDisabledReason` is NOT " + "'out_of_credits' (i.e. the overage credit has not been exhausted). " + "As soon as `overageDisabledReason` becomes 'out_of_credits', the " + "account is blocked immediately regardless of this flag. Overage lifts " + "ONLY the utilization wall \u2014 it cannot lift an active exhaustion mark " + "written by a real 429 (`mark-exhausted`).")
   }).optional().describe("Switchroom-auth-broker configuration (RFC H). Fleet-wide active account, " + "fallback order, admin-agent ACL, and ephemeral-consumer surface. " + "Required from the v0.8+ schema onwards; pre-v0.8 fleets are migrated " + "in-place by `switchroom apply` (see src/auth/migrate-schema.ts)."),
   drive: GoogleWorkspaceConfigSchema.describe("RFC D legacy key \u2014 use `google_workspace:` instead. Optional Google " + "Workspace onboarding configuration. When set, supplies Google OAuth " + "client credentials, the approver allowlist for `switchroom drive " + "connect`, and the optional tier knob. Env vars " + "(SWITCHROOM_GOOGLE_CLIENT_ID, SWITCHROOM_GOOGLE_CLIENT_SECRET, " + "SWITCHROOM_APPROVER_USER_ID) take precedence over this block when " + "set, preserving back-compat with the env-only flow shipped in #766."),