dsh-llm-fallbacks 0.3.4 → 0.3.5

package/README.md

@@ -2,6 +2,7 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
+[![npm](https://img.shields.io/npm/dt/dsh-llm-fallbacks)](https://www.npmjs.com/package/dsh-llm-fallbacks)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
 ![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
@@ -130,6 +131,7 @@ Save the config and restart the session, then type `/fallbacks` — the read-onl
 - **Time slots**: optional `fallbacks.timeSlots` rows rotate the effective root chain by wall-clock windows in the config-level `tz` timezone (default `Asia/Shanghai`) — four frozen UTC+8 presets (`liang-peak` / `liang-valley` / `glm-peak` / `glm-valley`, windows are code constants, models-only edits) or custom `start`/`end`/`days` windows. The first matching row wins; the all-day row is always last. A slot change applies on the **next** root request and is logged as a **time-slot switch** — a routing seed, never a failure decision: it consumes no cooldown and does not count against `maxSwitchesPerStep`. Failure walks keep the **fallback switch** copy (see [Time-slot presets](#time-slot-presets)).
 - **Dispatch-time role resolution**: on a subagent's first request its role is resolved in three stages — explicit (`agentPreset` matches a declared role id) → deterministic rules (unchanged) → LLM auto-match from the declared role taxonomy (`fallbacks.roleAutoMatch`, default `true`). The resolved role's chain-head model is injected into the first request and recorded via an explicit `role → model` log line (no durable `fallbacks/switch` event is written — issue #52 stop-write); set `roleAutoMatch: false` to disable the LLM auto-match stage (the explicit `agentPreset` stage still applies — with no explicit role this reproduces the previous rules-only behavior). The settings card always renders an **Enable role auto-match** switch (default `true`) to toggle it — the schema default applies even to legacy configs that never declared the key.
 - **Cooldown and revert**: failed / switched-away models are not re-selected during cooldown; `revertPolicy: cooldown-expiry` returns to the primary model automatically.
+- **Half-open recovery (opt-in)**: `recovery: half-open` makes recovery evidence-driven — an expired cooldown leaves the route half-open for one logged probe instead of restoring the preference; consecutive failures escalate the suppression duration (×2 per failure, capped at 1 h); an observed completion closes the circuit and fully restores the preference. `revertPolicy: 'never'` keeps the mechanism inert; state is session-scoped in-memory (a restart resets). YAML-only — the default `timer` keeps every existing behavior byte-identical (see [docs/configuration.md](docs/configuration.md#recovery-mode-recovery-key)).
 - **Visible behavior**: every switch is recorded in an info-level log line (from/to/role/reason) — no silent model switching. The plugin deliberately writes **no** durable `fallbacks/switch` session events (issue #52: the apply()-time event-type registration was proven ineffective, and a session containing the event refused to load after a dsh restart). Sessions written by older plugin versions that contain such events are repaired by `scripts/repair-fallbacks-switch-logs.ts`, which marks legacy events ignorable so affected sessions load again.
 - **Safety valves**: `maxSwitchesPerStep` caps switches per step and `alwaysModeRetryCap` caps always-mode retries — chain loops cannot amplify latency.
 - **No-config no-op**: with no chains configured the plugin behaves exactly like not being installed (`enabled` is off by default — see [Minimal configuration](#minimal-configuration)).
@@ -138,7 +140,7 @@ Save the config and restart the session, then type `/fallbacks` — the read-onl
 
 In a dsh-tui profile the plugin has three operator surfaces, with a strict duty split:
 
-- **`/fallbacks`** — what happened this session: origin, resolved role, effective chain, recent fallback switches, cooldown status. Read-only.
+- **`/fallbacks`** — what happened this session: origin, resolved role, effective chain, recent fallback switches, cooldown status (half-open marker rows when `recovery: half-open` is active). Read-only.
 - **`/fallbacks config`** — what is configured: composed-config readback (trigger codes, root chain, time slots, timezone, roles, role rules, cooldown, revert policy, safety valves, presets, role auto-match). Read-only apart from the one action command **`/fallbacks config revert-seed <role-id>`**, which restores a seeded role's persona to its declared seed default (a web-card action the settings seam cannot express).
 - **`/settings`** — the edit surface. The plugin registers a **fallbacks** section with full parity to the web settings card: booleans (`enabled`, `roleAutoMatch`) render as toggles, selects (`presets`, `revertPolicy`) as pickers, and numbers (`cooldownMs`, `maxSwitchesPerStep`, `alwaysModeRetryCap`) as numeric inputs; complex structures (`rootChain`, `timeSlots`, `roles.list`, `roles.rules`) are JSON text fields and `triggerCodes` a comma-separated text field. Invalid drafts (bad JSON, non-conforming chains, malformed time-slot rows) block the save — the section never corrupts the config.
 

package/README.zh-CN.md

@@ -2,6 +2,7 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
+[![npm](https://img.shields.io/npm/dt/dsh-llm-fallbacks)](https://www.npmjs.com/package/dsh-llm-fallbacks)
 [![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 ![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
 ![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
@@ -130,6 +131,7 @@ fallbacks:
 - **峰谷无忧（分时切换）**：可选的 `fallbacks.timeSlots` 行按墙钟窗口（配置级 `tz` 时区，默认 `Asia/Shanghai`）轮换 root 生效链——四个冻结的 UTC+8 预设（`liang-peak` / `liang-valley` / `glm-peak` / `glm-valley`，窗口为代码常量、仅模型链可编辑），或自定义 `start`/`end`/`days` 窗口。第一条命中的行生效；全时段行固定最后。时段切换在**下一个** root 请求生效，日志记为**分时切换**——路由种子而非失败决策：不消耗冷却、不计入 `maxSwitchesPerStep`。失败降级保留**降级切换**文案（见 [分时槽预设（分时切换）](#分时槽预设分时切换)）。
 - **派发时角色解析**：在 subagent 的首次请求上，其角色按三个阶段解析——显式（`agentPreset` 匹配已声明角色 id）→ 确定性规则（不变）→ LLM 自动匹配（从已声明角色体系中选择，`fallbacks.roleAutoMatch` 默认 `true`）。解析出的角色的链头模型注入首次请求，并以显式 `role → model` 日志行记录（不写 durable `fallbacks/switch` 事件——issue #52 停写）；设 `roleAutoMatch: false` 仅关闭 LLM 自动匹配阶段（显式 `agentPreset` 阶段仍生效——无显式角色时即复现原有仅规则行为）。设置卡总是渲染「启用角色自动匹配」开关（默认 `true`）以切换之——即使是从未声明过该键的旧配置，schema 默认值同样生效。
 - **冷却与回主**：被切离/失败的模型在冷却期内不再入选；`revertPolicy: cooldown-expiry` 冷却到期后自动回主模型。
+- **半开恢复（可选）**：`recovery: half-open` 让恢复以证据驱动——冷却到期后路由进入 **half-open**，以一次记录探针（logged probe）放行，而不是直接恢复首选；连续失败使抑制时长按 **×2** 逐次升级、**1 小时**封顶；观察到完成即闭合回路、完全恢复首选。`revertPolicy: 'never'` 使该机制完全失效；状态为会话级内存态（重启即重置）。仅 YAML 配置——默认 `timer` 保持所有既有行为逐字节一致（见 [docs/configuration.md](docs/configuration.md#recovery-mode-recovery-key)）。
 - **行为可见**：每次切换以 info 级日志行（from/to/role/reason）记录——无静默换模型。插件**刻意不写** durable `fallbacks/switch` 会话事件（issue #52——apply() 时的事件类型注册被证伪无效，含该事件的会话在 dsh 重启后拒绝加载）。由旧版插件写入、含此类事件的会话由 `scripts/repair-fallbacks-switch-logs.ts` 修复——旧事件被标记 ignorable 后，受影响会话可重新加载。
 - **安全阀**：`maxSwitchesPerStep` 限制每 step 切换次数、`alwaysModeRetryCap` 限制 always 模式重试——链循环不会放大延迟。
 - **无配置回归（no-op）**：未配置任何链时行为与未安装插件完全一致——`enabled` 默认关闭（见 [最小配置](#最小配置)）。
@@ -138,7 +140,7 @@ fallbacks:
 
 在 dsh-tui profile 中，插件有三个操作面——职责严格区分：
 
-- **`/fallbacks`** —— 本次会话发生了什么：来源、解析角色、生效链、最近降级切换、冷却状态。只读。
+- **`/fallbacks`** —— 本次会话发生了什么：来源、解析角色、生效链、最近降级切换、冷却状态（`recovery: half-open` 生效时显示 half-open 标记行）。只读。
 - **`/fallbacks config`** —— 配置了什么：组合配置回读（触发码、根链、分时槽、时区、角色、角色规则、冷却、回主策略、安全阀、预置、角色自动匹配）。除唯一的动作命令 **`/fallbacks config revert-seed <role-id>`** 外只读——该命令把某个 seed 角色的 persona 还原为已声明的默认（设置 seam 无法表达 Web 卡的这类动作能力）。
 - **`/settings`** —— 编辑界面。插件注册 **fallbacks** 区块，与 **Web 设置卡完全一致**：布尔（`enabled`、`roleAutoMatch`）渲染为开关、下拉（`presets`、`revertPolicy`）为选择器、数值（`cooldownMs`、`maxSwitchesPerStep`、`alwaysModeRetryCap`）为数字输入；复杂结构（`rootChain`、`timeSlots`、`roles.list`、`roles.rules`）为 JSON 文本字段，`triggerCodes` 为逗号分隔文本字段。非法草稿（JSON 解析失败、链尾不合规、分时行畸形）会阻止保存——区块绝不写入损坏配置。
 

package/dist/client/index.js

@@ -486,7 +486,8 @@ window.__ModuleLoader__.load({
 			presets: "bundled",
 			roleAutoMatch: true,
 			timeSlots: [],
-			tz: "Asia/Shanghai"
+			tz: "Asia/Shanghai",
+			recovery: "timer"
 		};
 		/**
 		* Reserved role id: legal as a rule target (`roles.rules[].role`) and as
@@ -643,6 +644,8 @@ window.__ModuleLoader__.load({
 			}))) throw new TypeError("fallbacks descriptor timeSlots must be an array of slot rows (kind/preset/start/end strings, chain string array, days number array)");
 			const tz = value.tz;
 			if (tz !== void 0 && typeof tz !== "string") throw new TypeError("fallbacks descriptor tz must be a string");
+			const recovery = value.recovery;
+			if (recovery !== void 0 && recovery !== "timer" && recovery !== "half-open") throw new TypeError("fallbacks descriptor recovery must be timer|half-open");
 			return {
 				enabled: enabled ?? defaultFallbacksConfig.enabled,
 				triggerCodes: triggerCodes ?? [...defaultFallbacksConfig.triggerCodes],
@@ -658,7 +661,8 @@ window.__ModuleLoader__.load({
 				presets: presets ?? defaultFallbacksConfig.presets,
 				roleAutoMatch: roleAutoMatch ?? defaultFallbacksConfig.roleAutoMatch,
 				timeSlots: timeSlots ?? [...defaultFallbacksConfig.timeSlots ?? []],
-				tz: tz ?? defaultFallbacksConfig.tz
+				tz: tz ?? defaultFallbacksConfig.tz,
+				recovery: recovery ?? defaultFallbacksConfig.recovery
 			};
 		}
 		/** The raw selector string a selection serializes to ('' when empty). */

package/dist/commands.d.ts

@@ -57,6 +57,8 @@ export interface FallbacksCooldownEntry {
     readonly key: string;
     /** Expiry epoch ms; `Infinity` for `revertPolicy: 'never'`. */
     readonly untilEpochMs: number;
+    /** True for a half-open marker row (an expired cooldown awaiting a recovery probe). */
+    readonly halfOpen?: boolean;
 }
 /** The read-only diagnostic snapshot the `/fallbacks` handler renders. */
 export interface FallbacksCommandSnapshot {
@@ -192,6 +194,7 @@ export declare const FALLBACKS_COMMAND_LOCALES: {
         readonly cooldownNone: "无活跃冷却";
         readonly cooldownLine: "{key} 冷却至 {time}";
         readonly cooldownNever: "{key} 会话内不再回主";
+        readonly cooldownHalfOpen: "{key} half-open（等待恢复探针）";
         readonly reason: {
             readonly 'trigger-code': "触发码";
             readonly 'always-cap': "always 上限";
@@ -246,6 +249,7 @@ export declare const FALLBACKS_COMMAND_LOCALES: {
         readonly cooldownNone: "none active";
         readonly cooldownLine: "{key} suppressed until {time}";
         readonly cooldownNever: "{key} not reverting this session";
+        readonly cooldownHalfOpen: "{key} half-open (awaiting recovery probe)";
         readonly reason: {
             readonly 'trigger-code': "trigger-code";
             readonly 'always-cap': "always-cap";

package/dist/config.d.ts

@@ -28,6 +28,8 @@
  * @module dsh-llm-fallbacks/config
  */
 import type { SlotRowConfig } from './time-slots.ts';
+/** How an expired cooldown recovers the route (plan fallbacks-half-open-recovery Task 1). */
+export type RecoveryPolicy = 'timer' | 'half-open';
 /** How a cooled-down model comes back (spec §4). */
 export type RevertPolicy = 'cooldown-expiry' | 'never';
 /** A single role rule: match on provider/model patterns (spec §3). */
@@ -125,6 +127,18 @@ export interface FallbacksConfig {
      * UTC+8). Not per-slot.
      */
     tz?: string;
+    /**
+     * Cooldown-expiry recovery mode (plan fallbacks-half-open-recovery Task
+     * 1): `'timer'` restores the preferred candidate when the cooldown
+     * expires (today's behavior); `'half-open'` leaves the route half-open
+     * for one logged probe instead. Optional on purpose, mirroring
+     * `presets` — a required field would break library consumers that
+     * construct `FallbacksConfig` literals with the existing keys
+     * (additive, non-breaking). The value domain is guarded by the schema
+     * (`Config` in `src/schema.ts`), NOT by `validateFallbacksConfig`, and
+     * every resolved config carries a value via the schema default.
+     */
+    recovery?: RecoveryPolicy;
 }
 /**
  * Spec §4 defaults — `Config({})` must equal this (no-op install).

package/dist/cooldown.d.ts

@@ -24,6 +24,15 @@ export declare class CooldownStore {
     suppress(key: string, untilEpochMs: number): void;
     /** True while `key` is suppressed at time `now` (default `Date.now()`); expired entries are removed. */
     isSuppressed(key: string, now?: number): boolean;
+    /**
+     * Raw expiry read — no lazy drop (plan fallbacks-half-open-recovery P2
+     * rule 3). `undefined` for unknown keys; `Infinity` for
+     * `revertPolicy: 'never'` entries. The half-open read path uses this to
+     * observe the lapsed `until` before the decision-path drop.
+     */
+    peek(key: string): number | undefined;
+    /** Unfiltered map keys, in insertion order (plan P4 display sync). */
+    keys(): IterableIterator<string>;
     /**
      * Read-only diagnostic accessor: the active (non-expired) entries, in
      * insertion order. This is a pure read — expired entries are FILTERED OUT

package/dist/index.d.ts

@@ -85,7 +85,7 @@ export type { FallbackSwitchReason, FallbacksSwitchEventData } from './events.ts
 export type { AgentFallbackState, FallbackStateStore, PendingSwitch, StepFailures } from './state.ts';
 export { resolveRole, type AgentLike, type Origin, } from './roles.ts';
 export { annotateCandidates, createCandidateFilter, hasWildcardEntry, resolveCandidate, resolveChain, resolveChainViews, selectCandidates, type AnnotatedCandidate, type CandidateFilterOptions, type CandidateSkipReason, type FailingModel, } from './chains.ts';
-export { defaultFallbacksConfig, detectLegacyKeys, INHERIT_ROLE_ID, ROLE_ID_PATTERN, validateFallbacksConfig, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRole, type FallbacksRoles, type FallbacksRoleRule, type FallbackStrategy, type RevertPolicy, } from './config.ts';
+export { defaultFallbacksConfig, detectLegacyKeys, INHERIT_ROLE_ID, ROLE_ID_PATTERN, validateFallbacksConfig, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRole, type FallbacksRoles, type FallbacksRoleRule, type FallbackStrategy, type RevertPolicy, type RecoveryPolicy, } from './config.ts';
 export { parseSelector, SelectorError, type Selector, } from './selectors.ts';
 export { FallbacksSeedManager, type EffectiveRole, type EffectiveRolesReadback, type SeedConflict, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertFailReason, type SeedRevertOutcome, type SeedSkipReason, type SeedsIo, type SeedsWireStatus, } from './seeds.ts';
 export { presetRoles } from './presets.ts';

package/dist/index.js

@@ -259,6 +259,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 +339,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 +385,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 +455,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 = [
@@ -651,6 +713,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 +769,8 @@ var FallbackStateStore = class {
 					failed: new StepFailureSet(),
 					switchCount: 0
 				},
-				cooldown: new CooldownStore()
+				cooldown: new CooldownStore(),
+				recovery: new RecoveryStore()
 			};
 			this.states.set(agentId, state);
 		}
@@ -752,8 +821,21 @@ 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
@@ -771,7 +853,8 @@ const CONFIG_KEYS = {
 	presets: true,
 	roleAutoMatch: true,
 	timeSlots: true,
-	tz: true
+	tz: true,
+	recovery: true
 };
 const ROLES_KEYS = {
 	list: true,
@@ -1005,6 +1088,7 @@ const FALLBACKS_COMMAND_LOCALES = {
 		cooldownNone: "无活跃冷却",
 		cooldownLine: "{key} 冷却至 {time}",
 		cooldownNever: "{key} 会话内不再回主",
+		cooldownHalfOpen: "{key} half-open（等待恢复探针）",
 		reason: {
 			"trigger-code": "触发码",
 			"always-cap": "always 上限"
@@ -1059,6 +1143,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 +1236,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());
 }
@@ -2148,7 +2234,7 @@ 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,
@@ -2157,6 +2243,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		}), modelExists);
 		const target = surviving[0];
 		if (target === void 0 || target.model === 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 +2265,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 +2288,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) {
@@ -2262,7 +2361,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;
 	});
@@ -2276,6 +2378,16 @@ function apply(ctx, config = defaultFallbacksConfig) {
 		dispatchInjected.delete(agent.id);
 		slotWinners.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();
@@ -2286,13 +2398,19 @@ function apply(ctx, config = defaultFallbacksConfig) {
 			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() {

package/dist/recovery.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Half-open recovery state machine (plan fallbacks-half-open-recovery Task 2).
+ *
+ * `RecoveryStore` tracks per-route consecutive-failure counters and half-open
+ * episode flags, keyed `${provider}/${model}` via `selectorKey`. It is held
+ * per-agent on `AgentFallbackState` and is session-scoped in-memory (same
+ * lifetime as the cooldown store; a restart resets every route to a flat
+ * first cooldown).
+ *
+ * The store is pure logic — zero imports, the cooldown.ts purity precedent —
+ * so it is unit-testable without a host (recovery.spec.ts imports this module
+ * directly).
+ *
+ * State machine (plan P2):
+ * 1. `recordFailure` — a suppression write: increments the consecutive-failure
+ *    counter and clears any half-open episode (rule 1).
+ * 2. `escalatedCooldownMs` — bounded geometric escalation of the suppression
+ *    duration (rule 2).
+ * 3. `markHalfOpen` — an expired cooldown leaves the route half-open for one
+ *    logged probe (rule 3).
+ * 4. `tryMarkProbeLogged` — the once-per-episode admission marker, not a gate
+ *    (rule 4).
+ * 5. `isHalfOpen` — probe-failure gate for the no-surviving-target path
+ *    (rule 5b).
+ * 6. `close` — an observed completion closes the circuit, only from half-open
+ *    (rule 6).
+ *
+ * @module dsh-llm-fallbacks/recovery
+ */
+/** Escalation multiplier applied per consecutive failure (rule 2). */
+export declare const ESCALATION_MULTIPLIER = 2;
+/** Escalation ceiling: 1 hour (rule 2). */
+export declare const ESCALATION_CAP_MS = 3600000;
+/**
+ * Bounded geometric escalation of the suppression duration (rule 2):
+ * `max(ms, min(ESCALATION_CAP_MS, ms * ESCALATION_MULTIPLIER ** (n - 1)))`
+ * for `n >= 1`. `n = 1` is flat `ms`; the `max(ms, ...)` floor keeps
+ * escalation from ever shortening below the configured flat cooldown when
+ * `ms >= ESCALATION_CAP_MS`; `ms = 0` degenerates to today's flat-0
+ * semantics.
+ */
+export declare function escalatedCooldownMs(ms: number, n: number): number;
+/**
+ * Per-route half-open recovery state (plan P2). Pure logic — no host
+ * dependencies, no `@deepseek-ai/*` imports.
+ */
+export declare class RecoveryStore {
+    private entries;
+    /**
+     * Record a suppression write for `key` (rule 1): increments the
+     * consecutive-failure counter and clears any in-progress half-open episode
+     * (a failure while half-open re-suppresses escalated — rule 5). Returns the
+     * new counter value `n`; the caller computes the escalated duration with
+     * {@link escalatedCooldownMs}.
+     */
+    recordFailure(key: string): number;
+    /**
+     * Open a half-open episode for `key` (rule 3): the lapsed cooldown leaves
+     * the route half-open for one logged probe. Resets the per-episode probe
+     * marker; the consecutive-failure counter survives the episode so a probe
+     * failure escalates to `n + 1` (rule 5). Creates the entry on first sight
+     * (mid-session mode flips can surface a cooldown entry with no recovery
+     * entry — rule 8).
+     */
+    markHalfOpen(key: string, until: number): void;
+    /**
+     * Mark the episode's one logged admission (rule 4). Returns `true` only for
+     * the first admission of a half-open episode; later admissions while the
+     * episode is unresolved return `false` and route normally (the marker is
+     * not a gate — there is no admission limit).
+     */
+    tryMarkProbeLogged(key: string): boolean;
+    /** True while `key` has an in-progress half-open episode (rule 5b gate). */
+    isHalfOpen(key: string): boolean;
+    /**
+     * Close the circuit for `key` (rule 6): acts only when the entry exists and
+     * is half-open — the entry is deleted (counter reset by deletion, preference
+     * fully restored). A completion observed while the route is actively
+     * suppressed, or with no entry, is a no-op: a stale in-flight success must
+     * not cancel a fresher escalated re-suppression.
+     */
+    close(key: string): void;
+    /**
+     * The in-progress half-open episodes, in insertion order (display path —
+     * plan P4). `untilEpochMs` is the lapsed expiry epoch that drives the
+     * `/fallbacks` marker row.
+     */
+    halfOpenEntries(): Array<{
+        key: string;
+        untilEpochMs: number;
+    }>;
+}

package/dist/state.d.ts

@@ -29,6 +29,8 @@
  */
 import type { FallbackSwitchReason } from './events.ts';
 import { CooldownStore, StepFailureSet } from './cooldown.ts';
+import { RecoveryStore } from './recovery.ts';
+import type { RecoveryPolicy } from './config.ts';
 /** Decision awaiting application at the next `agent/request` boundary (spec §5.1). */
 export interface PendingSwitch {
     from: {
@@ -64,6 +66,8 @@ export interface AgentFallbackState {
     stepFailures: StepFailures;
     /** `provider/model → expiry epoch ms`; lazily expired on read. */
     cooldown: CooldownStore;
+    /** Half-open recovery bookkeeping (plan fallbacks-half-open-recovery P2). */
+    recovery: RecoveryStore;
 }
 /**
  * The `Map<agent.id, AgentFallbackState>` store plus the state-machine
@@ -107,6 +111,27 @@ export declare class FallbackStateStore {
     clearStepState(state: AgentFallbackState): void;
     /** Suppress `key` until `untilEpochMs` (`Infinity` for `revertPolicy: 'never'`). */
     suppress(state: AgentFallbackState, key: string, untilEpochMs: number): void;
-    /** Lazy cooldown read: expired entries are dropped on read (spec §5.1). */
-    isSuppressed(state: AgentFallbackState, key: string, now?: number): boolean;
+    /**
+     * Lazy cooldown read (spec §5.1; plan fallbacks-half-open-recovery P2
+     * rule 3). Under `'timer'` (the default) today's body runs verbatim:
+     * expired entries are dropped on read. Under `'half-open'` the raw `until`
+     * is read via `CooldownStore.peek` (no lazy drop): absent ⇒ false;
+     * `until > now` ⇒ true; `until <= now` ⇒ the entry is dropped via the
+     * existing `isSuppressed` and the route is marked half-open, returning
+     * false. `Infinity` (`revertPolicy: 'never'`) never satisfies `until <=
+     * now` ⇒ the never short-circuit is structural on the read side.
+     */
+    isSuppressed(state: AgentFallbackState, key: string, now?: number, recovery?: RecoveryPolicy): boolean;
+    /**
+     * Bulk half-open transition for the display path (plan P4): walks the
+     * cooldown keys applying rule 3 per key. A pure no-op under `'timer'` —
+     * internal state and output stay byte-identical in default mode.
+     */
+    syncRecovery(state: AgentFallbackState, now: number, mode: RecoveryPolicy): void;
+    /**
+     * Observed completion ⇒ close the circuit (plan P2 rule 6): acts only when
+     * the entry exists and is half-open; otherwise a no-op (a stale in-flight
+     * success must not cancel a fresher escalated re-suppression).
+     */
+    observeSuccess(state: AgentFallbackState, key: string): void;
 }

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.3.4",
+  "version": "0.3.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",