dsh-llm-fallbacks 0.3.4 → 0.4.0-alpha.1

package/dist/index.js

@@ -1,5 +1,4 @@
 import { createRequire } from "node:module";
-import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import z from "@deepseek-ai/schemastery";
 import { LlmAdapter, LlmError, createUserMessage } from "@deepseek-ai/dsh-llm";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
@@ -259,6 +258,65 @@ function resolveSlotState(config, now, tz) {
 		label: "all-day"
 	};
 }
+const ESCALATION_CAP_MS = 36e5;
+function escalatedCooldownMs(ms, n) {
+	return Math.max(ms, Math.min(ESCALATION_CAP_MS, ms * 2 ** (n - 1)));
+}
+var RecoveryStore = class {
+	entries = new Map();
+	recordFailure(key) {
+		const entry = this.entries.get(key);
+		if (entry === void 0) {
+			this.entries.set(key, {
+				consecutiveFailures: 1,
+				halfOpen: false,
+				probeLogged: false
+			});
+			return 1;
+		}
+		entry.consecutiveFailures += 1;
+		entry.halfOpen = false;
+		entry.probeLogged = false;
+		return entry.consecutiveFailures;
+	}
+	markHalfOpen(key, until) {
+		const entry = this.entries.get(key);
+		if (entry === void 0) {
+			this.entries.set(key, {
+				consecutiveFailures: 0,
+				halfOpen: true,
+				probeLogged: false,
+				expiredUntil: until
+			});
+			return;
+		}
+		entry.halfOpen = true;
+		entry.probeLogged = false;
+		entry.expiredUntil = until;
+	}
+	tryMarkProbeLogged(key) {
+		const entry = this.entries.get(key);
+		if (entry === void 0 || !entry.halfOpen || entry.probeLogged) return false;
+		entry.probeLogged = true;
+		return true;
+	}
+	isHalfOpen(key) {
+		return this.entries.get(key)?.halfOpen === true;
+	}
+	close(key) {
+		const entry = this.entries.get(key);
+		if (entry === void 0 || !entry.halfOpen) return;
+		this.entries.delete(key);
+	}
+	halfOpenEntries() {
+		const out = [];
+		for (const [key, entry] of this.entries) if (entry.halfOpen && entry.expiredUntil !== void 0) out.push({
+			key,
+			untilEpochMs: entry.expiredUntil
+		});
+		return out;
+	}
+};
 //#endregion
 //#region .build/host/config.js
 const defaultFallbacksConfig = {
@@ -280,7 +338,8 @@ const defaultFallbacksConfig = {
 	presets: "bundled",
 	roleAutoMatch: true,
 	timeSlots: [],
-	tz: "Asia/Shanghai"
+	tz: "Asia/Shanghai",
+	recovery: "timer"
 };
 const INHERIT_ROLE_ID = "inherit";
 const ROLE_ID_PATTERN = /^[a-z0-9-]{1,32}$/;
@@ -325,6 +384,7 @@ function validateFallbacksConfig(config, logger) {
 			if (row.start !== void 0 || row.end !== void 0 || row.days !== void 0 && row.days.length > 0) logger.warn(`llm-fallbacks: preset "${preset}" carries its own window/day fields — preset windows are fixed code constants; the row is ignored`);
 		}
 	}
+	if ((config.recovery ?? "timer") === "half-open" && config.cooldownMs >= 36e5) logger.warn(`llm-fallbacks: recovery "half-open" escalation is inert — cooldownMs (${config.cooldownMs} ms) is at or above the 1-hour escalation cap (${ESCALATION_CAP_MS} ms), so every suppression stays flat at cooldownMs`);
 }
 function detectLegacyKeys(source) {
 	const keys = [];
@@ -394,7 +454,8 @@ const Config = z.object({
 		days: z.array(z.number()),
 		chain: z.array(z.string())
 	})).default([]),
-	tz: z.string().default("Asia/Shanghai")
+	tz: z.string().default("Asia/Shanghai"),
+	recovery: z.union([z.const("timer"), z.const("half-open")]).default("timer")
 });
 function buildAutomatchPrompt(roles, agent) {
 	const lines = [
@@ -633,6 +694,98 @@ function firstExactCandidate(all, wildcard) {
 	for (let index = 0; index < all.length; index += 1) if (!wildcard[index]) return all[index];
 }
 //#endregion
+//#region .build/host/authorized-route.js
+function completeRoute(source) {
+	if (typeof source !== "object" || source === null || typeof source.provider !== "string" || source.provider.length === 0 || typeof source.model !== "string" || source.model.length === 0) return;
+	return {
+		provider: source.provider,
+		model: source.model
+	};
+}
+function lastModelSelection(entries) {
+	if (entries === void 0) return void 0;
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const candidate = entries[index];
+		if (candidate?.type !== "model/selection") continue;
+		const route = completeRoute(candidate.data);
+		if (route !== void 0) return route;
+	}
+}
+function detectAuthorizedRoute(session) {
+	const { events, requestHeader, options, inherited } = session;
+	const selected = lastModelSelection(events);
+	if (selected !== void 0) return selected;
+	const route = completeRoute(requestHeader) ?? completeRoute(options);
+	if (route === void 0) return void 0;
+	const baseline = completeRoute(inherited);
+	if (baseline !== void 0 && route.provider === baseline.provider && route.model === baseline.model) return;
+	return route;
+}
+//#endregion
+//#region .build/host/route-allowlist.js
+function resolvedRoutes(candidates) {
+	const routes = [];
+	for (const candidate of candidates) {
+		if (candidate.model === void 0) continue;
+		routes.push({
+			provider: candidate.provider,
+			model: candidate.model
+		});
+	}
+	return routes;
+}
+function routeOnAllowlist(route, allowedModels) {
+	return allowedModels.some((allowed) => allowed.provider === route.provider && allowed.model === route.model);
+}
+function firstAllowedCandidate(resolved, allowedModels) {
+	return resolved.find((route) => routeOnAllowlist(route, allowedModels));
+}
+//#endregion
+//#region .build/host/subagent-policy.js
+function parseRoutes(value) {
+	if (!Array.isArray(value)) return void 0;
+	const routes = [];
+	for (const candidate of value) {
+		if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate) || !("provider" in candidate) || typeof candidate.provider !== "string" || candidate.provider.length === 0 || !("model" in candidate) || typeof candidate.model !== "string" || candidate.model.length === 0) return;
+		routes.push({
+			provider: candidate.provider,
+			model: candidate.model
+		});
+	}
+	return routes;
+}
+function readSessionPolicyEvent(events) {
+	const event = events.find((candidate) => candidate.type === "subagent/model-selection-policy");
+	if (event === void 0) return {
+		ok: false,
+		present: false
+	};
+	const data = event.data;
+	const routes = parseRoutes(typeof data === "object" && data !== null && "allowedModels" in data ? data.allowedModels : void 0);
+	if (routes === void 0 || routes.length === 0) return {
+		ok: false,
+		present: true
+	};
+	return {
+		ok: true,
+		allowedModels: routes
+	};
+}
+function effectivePolicy(event, settings) {
+	if (event.ok) return {
+		state: "enabled",
+		allowedModels: event.allowedModels
+	};
+	if (event.present) return { state: "unprovable" };
+	if (settings === void 0 || settings.enabled !== true) return { state: "disabled" };
+	const routes = parseRoutes(settings.allowedModels);
+	if (routes === void 0 || routes.length === 0) return { state: "unprovable" };
+	return {
+		state: "enabled",
+		allowedModels: routes
+	};
+}
+//#endregion
 //#region .build/host/cooldown.js
 var CooldownStore = class {
 	entries = new Map();
@@ -651,6 +804,12 @@ var CooldownStore = class {
 		}
 		return true;
 	}
+	peek(key) {
+		return this.entries.get(key);
+	}
+	keys() {
+		return this.entries.keys();
+	}
 	snapshot(now = Date.now()) {
 		const active = [];
 		for (const [key, until] of this.entries) {
@@ -701,7 +860,8 @@ var FallbackStateStore = class {
 					failed: new StepFailureSet(),
 					switchCount: 0
 				},
-				cooldown: new CooldownStore()
+				cooldown: new CooldownStore(),
+				recovery: new RecoveryStore()
 			};
 			this.states.set(agentId, state);
 		}
@@ -752,13 +912,47 @@ var FallbackStateStore = class {
 	suppress(state, key, untilEpochMs) {
 		state.cooldown.suppress(key, untilEpochMs);
 	}
-	isSuppressed(state, key, now = Date.now()) {
-		return state.cooldown.isSuppressed(key, now);
+	isSuppressed(state, key, now = Date.now(), recovery = "timer") {
+		if (recovery !== "half-open") return state.cooldown.isSuppressed(key, now);
+		const until = state.cooldown.peek(key);
+		if (until === void 0) return false;
+		if (until > now) return true;
+		state.cooldown.isSuppressed(key, now);
+		state.recovery.markHalfOpen(key, until);
+		return false;
+	}
+	syncRecovery(state, now, mode) {
+		if (mode !== "half-open") return;
+		for (const key of state.cooldown.keys()) this.isSuppressed(state, key, now, mode);
+	}
+	observeSuccess(state, key) {
+		state.recovery.close(key);
 	}
 };
 //#endregion
+//#region .build/host/override.js
+function overrideConfigWithRouteRule(seed, to, explicitEffort) {
+	if (explicitEffort !== void 0) return {
+		...seed,
+		reasoningEffort: explicitEffort,
+		provider: to.provider,
+		model: to.model
+	};
+	if (!(to.provider !== seed.provider || to.model !== seed.model)) return {
+		...seed,
+		provider: to.provider,
+		model: to.model
+	};
+	const { reasoningEffort: _routeOwned, ...withoutRouteOwnedEffort } = seed;
+	return {
+		...withoutRouteOwnedEffort,
+		provider: to.provider,
+		model: to.model
+	};
+}
+//#endregion
 //#region .build/host/gateway.js
-const FALLBACKS_SETTINGS_NAMESPACE = settingsNamespace("fallbacks");
+const FALLBACKS_SETTINGS_NAMESPACE = "fallbacks";
 const CONFIG_KEYS = {
 	enabled: true,
 	triggerCodes: true,
@@ -771,7 +965,8 @@ const CONFIG_KEYS = {
 	presets: true,
 	roleAutoMatch: true,
 	timeSlots: true,
-	tz: true
+	tz: true,
+	recovery: true
 };
 const ROLES_KEYS = {
 	list: true,
@@ -791,10 +986,12 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 	bridge;
 	seeds;
 	settings;
-	constructor(ctx, bridge, seeds) {
+	subagentPolicy;
+	constructor(ctx, bridge, seeds, subagentPolicy) {
 		super(ctx, "fallbacks");
 		this.bridge = bridge;
 		this.seeds = seeds;
+		this.subagentPolicy = subagentPolicy;
 		ctx.inject(["settings"], (sctx) => {
 			this.settings = sctx.settings;
 			return () => {
@@ -840,11 +1037,14 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 	}
 	readResult() {
 		const source = this.bridge.source();
-		return {
+		const result = {
 			config: this.readConfig(source),
 			legacyKeys: detectLegacyKeys(source),
 			seeds: this.seeds.wireStatus(this.seedsIo())
 		};
+		const projected = projectSubagentPolicy(this.subagentPolicy);
+		if (projected !== void 0) result.subagentPolicy = projected;
+		return result;
 	}
 	seedsIo() {
 		const settings = this.settings;
@@ -857,6 +1057,41 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 		};
 	}
 };
+function projectSubagentPolicy(snapshot) {
+	if (snapshot === void 0) return void 0;
+	let captured;
+	try {
+		captured = snapshot();
+	} catch {
+		return { state: "unprovable" };
+	}
+	const { policy, head, blockedAttempt } = captured;
+	if (policy.state === "disabled") return { state: "disabled" };
+	if (policy.state === "unprovable") return { state: "unprovable" };
+	const wire = {
+		state: "enabled",
+		allowedModels: policy.allowedModels.map((route) => ({
+			provider: route.provider,
+			model: route.model
+		}))
+	};
+	if (head !== void 0) wire.head = {
+		route: {
+			provider: head.route.provider,
+			model: head.route.model
+		},
+		source: head.source
+	};
+	if (blockedAttempt !== void 0) wire.blockedAttempt = {
+		at: blockedAttempt.at,
+		route: {
+			provider: blockedAttempt.route.provider,
+			model: blockedAttempt.route.model
+		},
+		reason: blockedAttempt.reason
+	};
+	return wire;
+}
 function normalizeRoles(value) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
 	const roles = {};
@@ -1005,6 +1240,7 @@ const FALLBACKS_COMMAND_LOCALES = {
 		cooldownNone: "无活跃冷却",
 		cooldownLine: "{key} 冷却至 {time}",
 		cooldownNever: "{key} 会话内不再回主",
+		cooldownHalfOpen: "{key} half-open（等待恢复探针）",
 		reason: {
 			"trigger-code": "触发码",
 			"always-cap": "always 上限"
@@ -1059,6 +1295,7 @@ const FALLBACKS_COMMAND_LOCALES = {
 		cooldownNone: "none active",
 		cooldownLine: "{key} suppressed until {time}",
 		cooldownNever: "{key} not reverting this session",
+		cooldownHalfOpen: "{key} half-open (awaiting recovery probe)",
 		reason: {
 			"trigger-code": "trigger-code",
 			"always-cap": "always-cap"
@@ -1151,6 +1388,7 @@ function formatSwitch(entry, t) {
 	return t.switchLine.replace("{from}", from).replace("{to}", to).replace("{role}", entry.role).replace("{reason}", t.reason[entry.reason] ?? entry.reason);
 }
 function formatCooldown(entry, t) {
+	if (entry.halfOpen === true) return t.cooldownHalfOpen.replace("{key}", entry.key);
 	if (!Number.isFinite(entry.untilEpochMs)) return t.cooldownNever.replace("{key}", entry.key);
 	return t.cooldownLine.replace("{key}", entry.key).replace("{time}", new Date(entry.untilEpochMs).toISOString());
 }
@@ -1954,6 +2192,15 @@ var FallbacksChainAdapter = class extends LlmAdapter {
 			name: model
 		};
 	}
+	imageRequestPricing(_provider, _model) {
+		try {
+			const head = effectiveHeadOf(this.readConfig(), new Date());
+			if (head === void 0 || head.provider === "FallbacksChain") return void 0;
+			return this.getLlm()?.imageRequestPricing(head.provider, head.model);
+		} catch {
+			return;
+		}
+	}
 	stream(options) {
 		const config = this.readConfig();
 		const now = new Date();
@@ -2015,6 +2262,19 @@ const stateStores = new WeakMap();
 function stateStore(ctx) {
 	return stateStores.get(ctx);
 }
+const blockedAttemptStores = new WeakMap();
+function blockedAttempts(ctx) {
+	return blockedAttemptStores.get(ctx);
+}
+const chainHeadStores = new WeakMap();
+function chainHeads(ctx) {
+	return chainHeadStores.get(ctx);
+}
+function latestByAt(map) {
+	let latest;
+	for (const value of map.values()) if (latest === void 0 || value.at >= latest.at) latest = value;
+	return latest;
+}
 async function makeModelExists(ctx, providers) {
 	const llm = ctx.get("llm");
 	if (llm === void 0 || typeof llm.listModels !== "function") return () => true;
@@ -2051,12 +2311,49 @@ function slotWinnerKey(winner) {
 	if (winner === "all-day") return "all-day";
 	return winner.kind === "preset" ? `preset:${winner.preset}` : `custom:${winner.start}-${winner.end}`;
 }
-function overrideConfig(seed, to) {
-	const { reasoningEffort: _inherited, ...withoutInheritedEffort } = seed;
+function overrideConfig(seed, to, explicitEffort) {
+	return overrideConfigWithRouteRule(seed, to, explicitEffort);
+}
+function readSubagentSettings(ctx) {
+	const service = ctx.get("subagentModelSelection");
+	return service === void 0 ? void 0 : service.current();
+}
+function readGuardedPolicySettings(ctx, agentId, lastKnown, warn) {
+	try {
+		const service = ctx.get("subagentModelSelection");
+		if (service === void 0) return {
+			ok: true,
+			settings: lastKnown.get(agentId)
+		};
+		const settings = service.current();
+		lastKnown.set(agentId, settings);
+		return {
+			ok: true,
+			settings
+		};
+	} catch (error) {
+		warn("llm-fallbacks: agent \"%s\" subagent model-selection settings read failed — %s", agentId, error?.message ?? String(error));
+		const known = lastKnown.get(agentId);
+		return known === void 0 ? { ok: false } : {
+			ok: true,
+			settings: known
+		};
+	}
+}
+function authorizedRouteView(ctx, agent) {
+	const header = agent.session?.header;
+	const parentId = header?.origin === "subagent" ? header.parentSession : void 0;
+	const parent = parentId === void 0 ? void 0 : ctx.get("agents")?.get(parentId);
+	const parentHeader = parent?.session.requestHeader()?.config;
+	const parentOptions = parent?.options;
 	return {
-		...withoutInheritedEffort,
-		provider: to.provider,
-		model: to.model
+		requestHeader: agent.session?.requestHeader()?.config,
+		events: agent.session?.events,
+		options: agent.options,
+		inherited: parentHeader ?? (typeof parentOptions?.provider === "string" && typeof parentOptions?.model === "string" ? {
+			provider: parentOptions.provider,
+			model: parentOptions.model
+		} : void 0)
 	};
 }
 function apply(ctx, config = defaultFallbacksConfig) {
@@ -2105,21 +2402,40 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	if (legacyKeys.length > 0) logger.warn("llm-fallbacks: legacy config keys detected (chains/roles.default/undeclared role refs); see docs/configuration.md migration table — %o", legacyKeys);
 	let roleIds = new Map(entry.roles.list.map((role) => [role.id.trim(), role.id]));
 	let hasChains = entry.rootChain.length > 0 || entry.roles.list.some((role) => (role.chain?.length ?? 0) > 0);
-	installSettingsSection(ctx, FALLBACKS_SETTINGS_NAMESPACE, Config, entry, {
-		setSource: (current) => {
-			source = current;
-		},
-		onChange: () => {
-			const current = source();
-			roleIds = new Map(current.roles.list.map((role) => [role.id.trim(), role.id]));
-			hasChains = current.rootChain.length > 0 || current.roles.list.some((role) => (role.chain?.length ?? 0) > 0);
-			reconcileFallbacksAdapter();
-			slotWinners.clear();
-		}
+	ctx.inject(["settings"], (sctx) => {
+		sctx.settings.installSection(ctx, FALLBACKS_SETTINGS_NAMESPACE, Config, entry, {
+			setSource: (current) => {
+				source = current;
+			},
+			onChange: () => {
+				const current = source();
+				roleIds = new Map(current.roles.list.map((role) => [role.id.trim(), role.id]));
+				hasChains = current.rootChain.length > 0 || current.roles.list.some((role) => (role.chain?.length ?? 0) > 0);
+				reconcileFallbacksAdapter();
+				slotWinners.clear();
+			}
+		});
 	});
 	const bridge = { source: () => source() };
+	const chainHeadMap = new Map();
+	chainHeadStores.set(ctx, chainHeadMap);
+	const blockedAttemptMap = new Map();
+	blockedAttemptStores.set(ctx, blockedAttemptMap);
 	try {
-		new FallbacksConfigGateway(ctx, bridge, seeds);
+		new FallbacksConfigGateway(ctx, bridge, seeds, () => {
+			try {
+				return {
+					policy: effectivePolicy({
+						ok: false,
+						present: false
+					}, readSubagentSettings(ctx)),
+					head: latestByAt(chainHeadMap),
+					blockedAttempt: latestByAt(blockedAttemptMap)
+				};
+			} catch {
+				return { policy: { state: "unprovable" } };
+			}
+		});
 	} catch (error) {
 		if (!(error instanceof Error) || !error.message.includes("has been registered")) throw error;
 		ctx.logger("llm-fallbacks").debug("fallbacks gateway already registered — no gateway on this fiber (multi-fiber dedupe)");
@@ -2137,6 +2453,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	stateStores.set(ctx, states);
 	const dispatchInjected = new Set();
 	const slotWinners = new Map();
+	const lastKnownPolicySettings = new Map();
 	async function decide(agent, turn, step, current, reason, state) {
 		const config = source();
 		if (state !== void 0) {
@@ -2148,15 +2465,48 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		const { all, wildcard } = resolveChainViews(config.roles.list, rootTail, role, current.provider, current.model, logger.warn);
 		if (all.length === 0) return null;
 		const modelExists = hasWildcardEntry(config.roles.list, rootTail, role) ? await makeModelExists(ctx, [...new Set(all.map((candidate) => candidate.provider))]) : void 0;
-		const cooldown = { isSuppressed: (key) => state !== void 0 && states.isSuppressed(state, key) };
+		const cooldown = { isSuppressed: (key) => state !== void 0 && states.isSuppressed(state, key, Date.now(), source().recovery ?? "timer") };
 		const failed = { has: (key) => state !== void 0 && state.stepFailures.failed.has(key) };
 		const surviving = selectCandidates(all, wildcard, createCandidateFilter({
 			current,
 			cooldown,
 			failed
 		}), modelExists);
-		const target = surviving[0];
-		if (target === void 0 || target.model === void 0) return null;
+		const first = surviving[0];
+		let target;
+		if (first !== void 0 && first.model !== void 0) target = {
+			provider: first.provider,
+			model: first.model
+		};
+		if (agent.session?.header?.origin === "subagent" && target !== void 0) {
+			const settingsRead = readGuardedPolicySettings(ctx, agent.id, lastKnownPolicySettings, logger.warn);
+			const policy = settingsRead.ok ? effectivePolicy(readSessionPolicyEvent(agent.session.events), settingsRead.settings) : { state: "unprovable" };
+			if (policy.state === "unprovable") {
+				logger.warn("llm-fallbacks: agent \"%s\" subagent model-selection policy is on but unreadable — skipping fallback switch", agent.id);
+				return null;
+			}
+			if (policy.state === "enabled") {
+				const allowed = firstAllowedCandidate(resolvedRoutes(surviving), policy.allowedModels);
+				if (allowed === void 0) {
+					logger.warn("llm-fallbacks: agent \"%s\" fallback switch %s/%s blocked: resolved candidates are all outside the subagent allowlist — no switch", agent.id, target.provider, target.model);
+					blockedAttemptMap.set(agent.id, {
+						at: Date.now(),
+						route: {
+							provider: target.provider,
+							model: target.model
+						},
+						reason
+					});
+					return null;
+				}
+				target = {
+					provider: allowed.provider,
+					model: allowed.model
+				};
+			}
+		}
+		if (target === void 0) return null;
+		if ((source().recovery ?? "timer") === "half-open" && state !== void 0 && state.recovery.tryMarkProbeLogged(selectorKey(target.provider, target.model))) logger.info("llm-fallbacks: agent \"%s\" half-open probe %s/%s (role=%s, reason=%s)", agent.id, target.provider, target.model, role, reason);
 		logger.info("llm-fallbacks: agent \"%s\" fallback switch (降级切换) %s/%s -> %s/%s (role=%s, reason=%s, candidates=%o)", agent.id, current.provider, current.model, target.provider, target.model, role, reason, annotateCandidates(all, surviving, {
 			current,
 			cooldown,
@@ -2178,13 +2528,22 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	function commit(state, pending, turn, step) {
 		const config = source();
 		const fromKey = selectorKey(pending.from.provider, pending.from.model);
-		const until = config.revertPolicy === "never" ? Number.POSITIVE_INFINITY : Date.now() + config.cooldownMs;
+		const until = config.revertPolicy === "never" ? Number.POSITIVE_INFINITY : config.recovery === "half-open" ? Date.now() + escalatedCooldownMs(config.cooldownMs, state.recovery.recordFailure(fromKey)) : Date.now() + config.cooldownMs;
 		states.syncStep(state, turn, step);
 		states.writePending(state, pending);
 		states.suppress(state, fromKey, until);
 		states.recordFailure(state, fromKey);
 		states.recordSwitch(state);
 	}
+	function failHalfOpenProbe(agentId, current) {
+		const key = selectorKey(current.provider, current.model);
+		if ((source().recovery ?? "timer") !== "half-open") return;
+		if (source().revertPolicy === "never") return;
+		if (states.peek(agentId)?.recovery.isHalfOpen(key) !== true) return;
+		const state = states.get(agentId);
+		const n = state.recovery.recordFailure(key);
+		states.suppress(state, key, Date.now() + escalatedCooldownMs(source().cooldownMs, n));
+	}
 	ctx.on("agent/request-error", async ({ agent, turn, step, provider, failure }, next) => {
 		const config = source();
 		if (!config.enabled || !config.triggerCodes.includes(failure.code)) return next();
@@ -2192,7 +2551,10 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		if (!current.model) return next();
 		try {
 			const pending = await decide(agent, turn, step, current, "trigger-code", states.peek(agent.id));
-			if (pending === null) return next();
+			if (pending === null) {
+				failHalfOpenProbe(agent.id, current);
+				return next();
+			}
 			commit(states.get(agent.id), pending, turn, step);
 			return { kind: "retry" };
 		} catch (error) {
@@ -2230,21 +2592,54 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		if (config.enabled && hasChains && agent.session?.header?.origin === "subagent" && !dispatchInjected.has(agent.id)) {
 			dispatchInjected.add(agent.id);
 			try {
-				const role = await resolveRoleAtDispatch(agent, config.roles.rules, roleIds, {
-					automatchEnabled: config.roleAutoMatch ?? true,
-					automatch: (agent) => pickRoleByLlm(ctx, config.roles, agent, { warn: logger.warn }),
-					warn: logger.warn
-				});
-				if (role !== "inherit") {
-					const { all, wildcard } = resolveChainViews(config.roles.list, config.rootChain, role, seed.provider, seed.model, logger.warn);
-					const head = firstExactCandidate(all, wildcard);
-					if (head !== void 0 && head.model !== void 0 && !(head.provider === seed.provider && head.model === seed.model)) {
-						const to = {
-							provider: head.provider,
-							model: head.model
-						};
-						logger.info("llm-fallbacks: agent \"%s\" role-inject role=%s model=%s/%s", agent.id, role, head.provider, head.model);
-						return overrideConfig(seed, to);
+				const settingsRead = readGuardedPolicySettings(ctx, agent.id, lastKnownPolicySettings, logger.warn);
+				const policy = settingsRead.ok ? effectivePolicy(readSessionPolicyEvent(agent.session.events), settingsRead.settings) : { state: "unprovable" };
+				if (policy.state === "unprovable") logger.warn("llm-fallbacks: agent \"%s\" subagent model-selection policy is on but unreadable — skipping role-inject", agent.id);
+				else {
+					const authorized = policy.state === "enabled" ? detectAuthorizedRoute(authorizedRouteView(ctx, agent)) : void 0;
+					if (authorized !== void 0) {
+						chainHeadMap.set(agent.id, {
+							at: Date.now(),
+							route: {
+								provider: authorized.provider,
+								model: authorized.model
+							},
+							source: "authorized"
+						});
+						logger.info("llm-fallbacks: agent \"%s\" authorized child route %s/%s is the chain head — skipping role-inject", agent.id, authorized.provider, authorized.model);
+					} else {
+						const role = await resolveRoleAtDispatch(agent, config.roles.rules, roleIds, {
+							automatchEnabled: config.roleAutoMatch ?? true,
+							automatch: (agent) => pickRoleByLlm(ctx, config.roles, agent, { warn: logger.warn }),
+							warn: logger.warn
+						});
+						if (role !== "inherit") {
+							const { all, wildcard } = resolveChainViews(config.roles.list, config.rootChain, role, seed.provider, seed.model, logger.warn);
+							let to;
+							if (policy.state === "enabled") {
+								const routes = resolvedRoutes(all);
+								to = firstAllowedCandidate(routes, policy.allowedModels);
+								if (to === void 0 && routes.length > 0) logger.warn("llm-fallbacks: agent \"%s\" role-inject candidates are all outside the subagent allowlist — skipping inject (host seed stands)", agent.id);
+							} else {
+								const head = firstExactCandidate(all, wildcard);
+								if (head !== void 0 && head.model !== void 0) to = {
+									provider: head.provider,
+									model: head.model
+								};
+							}
+							if (to !== void 0 && !(to.provider === seed.provider && to.model === seed.model)) {
+								if (policy.state === "enabled") chainHeadMap.set(agent.id, {
+									at: Date.now(),
+									route: {
+										provider: to.provider,
+										model: to.model
+									},
+									source: "injected"
+								});
+								logger.info("llm-fallbacks: agent \"%s\" role-inject role=%s model=%s/%s", agent.id, role, to.provider, to.model);
+								return overrideConfig(seed, to);
+							}
+						}
 					}
 				}
 			} catch (error) {
@@ -2262,7 +2657,10 @@ function apply(ctx, config = defaultFallbacksConfig) {
 				commit(commitState, pending, turn, step);
 				const appliedCap = states.applyPending(commitState, turn, step);
 				if (appliedCap !== void 0) return overrideConfig(seed, appliedCap.to);
-			}
+			} else failHalfOpenProbe(agent.id, {
+				provider: seed.provider,
+				model: seed.model
+			});
 		}
 		return seed;
 	});
@@ -2275,24 +2673,46 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		states.delete(agent.id);
 		dispatchInjected.delete(agent.id);
 		slotWinners.delete(agent.id);
+		blockedAttemptMap.delete(agent.id);
+		chainHeadMap.delete(agent.id);
+		lastKnownPolicySettings.delete(agent.id);
+	});
+	ctx.on("session/event", (session, event) => {
+		if (event.type !== "assistant/message") return;
+		if ((source().recovery ?? "timer") !== "half-open") return;
+		if (event.data.interrupted === true) return;
+		const message = event.data.message;
+		if (message.source.kind !== "model") return;
+		const state = states.peek(session.id);
+		if (state === void 0) return;
+		states.observeSuccess(state, selectorKey(message.source.provider, message.source.model));
 	});
 	ctx.effect(() => () => {
 		states.clear();
 		dispatchInjected.clear();
 		slotWinners.clear();
+		blockedAttemptMap.clear();
+		chainHeadMap.clear();
+		lastKnownPolicySettings.clear();
 	}, "llm-fallbacks: clear per-agent state");
 	const fallbacksCommandController = {
 		getSnapshot(agent) {
 			const config = source();
 			const role = resolveRole(agent, config.roles.rules, roleIds, logger.warn);
 			const state = states.peek(agent.id);
+			const recovery = config.recovery ?? "timer";
+			if (state !== void 0 && recovery === "half-open") states.syncRecovery(state, Date.now(), recovery);
 			return {
 				origin: agent.session.header?.origin ?? "root",
 				role,
 				...resolveChainForDiagnostic(config.roles.list, config.rootChain, role, logger.warn),
 				slot: resolveSlotState(config, new Date(), config.tz ?? "Asia/Shanghai"),
 				switches: recentFallbacksSwitches(agent.session.events, 5),
-				cooldown: state === void 0 ? [] : state.cooldown.snapshot()
+				cooldown: state === void 0 ? [] : recovery === "half-open" ? [...state.cooldown.snapshot(), ...state.recovery.halfOpenEntries().map((entry) => ({
+					key: entry.key,
+					untilEpochMs: entry.untilEpochMs,
+					halfOpen: true
+				}))] : state.cooldown.snapshot()
 			};
 		},
 		getConfig() {
@@ -2351,4 +2771,4 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	});
 }
 //#endregion
-export { Config, FallbacksSeedManager, INHERIT_ROLE_ID, ROLE_ID_PATTERN, SelectorError, annotateCandidates, apply, countRetryEvents, createCandidateFilter, defaultFallbacksConfig, detectLegacyKeys, hasWildcardEntry, name, parseSelector, presetRoles, provide, resolveCandidate, resolveChain, resolveChainViews, resolveRole, selectCandidates, stateStore, validateFallbacksConfig };
+export { Config, FallbacksSeedManager, INHERIT_ROLE_ID, ROLE_ID_PATTERN, SelectorError, annotateCandidates, apply, blockedAttempts, chainHeads, countRetryEvents, createCandidateFilter, defaultFallbacksConfig, detectLegacyKeys, hasWildcardEntry, name, parseSelector, presetRoles, provide, resolveCandidate, resolveChain, resolveChainViews, resolveRole, selectCandidates, stateStore, validateFallbacksConfig };