dsh-llm-fallbacks 0.2.1 → 0.3.0

package/README.md

@@ -13,6 +13,25 @@ Automatic provider/model fallback chains for dsh (DeepSeek Harness): when an age
 
 Works in both dsh front ends: the **web** profile (Settings → 插件配置 → Fallbacks card) and the **dsh-tui** terminal profile (`/fallbacks` + `/fallbacks config`).
 
+## Time slots
+
+Time slots (分时切换) rotate the **effective root chain** by wall-clock windows: each slot row carries its own fallback chain, and the first row whose window contains the current moment replaces the all-day chain for the next root request — the all-day chain stays as the last resort when no slot matches. Peak and valley windows can therefore use different chains while the failure walk (降级切换) remains untouched.
+
+![Time slots](docs/assets/screenshot-1-en.png)
+
+Four frozen UTC+8 presets (windows are code constants; preset rows lock `tz` to Asia/Shanghai):
+
+| Preset | Window |
+|---|---|
+| `liang-peak` | 09:00–12:00 and 14:00–18:00, every day |
+| `liang-valley` | every other UTC+8 time (complement of Liang Peak) |
+| `glm-peak` | Monday–Friday 14:00–18:00 |
+| `glm-valley` | every other time (complement of GLM Peak) |
+
+GLM Peak and GLM Valley are offered in the card picker only when `zai-coding-cn` is configured.
+
+The first extra row whose window contains the current moment (in `fallbacks.tz`, default Asia/Shanghai) wins; no match → the all-day `rootChain`, whose tail (默认模型) must be exactly one official V4 model — `deepseek-official/deepseek-v4-flash` XOR `deepseek-official/deepseek-v4-pro`. Slot rotation is a routing seed, not a failure decision: it applies on the next root request, consumes no cooldown, and is logged as a time-slot switch (分时切换) — failure walks keep 降级切换. Full semantics → [Time-slot presets (分时切换)](#time-slot-presets-分时切换) and [docs/configuration.md](docs/configuration.md).
+
 ## Quick start
 
 ### Install
@@ -24,6 +43,20 @@ dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui terminal profile
 
 Same plugin, either front end — the only difference is the `--profile` flag. Pin a version with `@<version>`. A registry install fetches the **built package** (`dist/`), nothing builds on the target machine. Registry / git / local-directory variants, uninstall, and `--dump-config` verification → [docs/install.md](docs/install.md).
 
+### Repair existing sessions (versions before 0.2.2)
+
+Versions before 0.2.2 wrote durable `fallbacks/switch` session events that newer dsh releases refuse to load (issue #52 — the apply()-time event-type registration is ineffective because plugin and host resolve different module instances). If existing sessions fail to open after an upgrade, clone this repository and repair the logs (stop dsh first):
+
+```sh
+git clone https://github.com/omdsh-dev/dsh-llm-fallbacks.git
+cd dsh-llm-fallbacks
+pnpm install
+pnpm repair:fallbacks-switch-logs -- --dry-run            # preview which sessions would change
+pnpm repair:fallbacks-switch-logs -- --apply --backup     # mark legacy events ignorable
+```
+
+The script scans `~/.dsh/sessions` by default (override with `--root <dir>`), marks legacy `fallbacks/switch` events `ignorable: true` so the host read path accepts the session again, and keeps a `<file>.bak` per repaired log. `--apply` requires `--backup` and must run with dsh stopped. From 0.2.2 on, the plugin stops writing durable switch events, so no new sessions need repair.
+
 ### Minimal configuration
 
 Add a `fallbacks:` section to the dsh settings document (default `$DSH_HOME/settings.yaml`):
@@ -31,9 +64,21 @@ Add a `fallbacks:` section to the dsh settings document (default `$DSH_HOME/sett
 ```yaml
 fallbacks:
   enabled: true            # feature switch; defaults to false — set explicitly to enable
-  rootChain:               # block 1: root agent's chain, tried in order after the primary model fails
-    - anthropic/claude-3-5-sonnet
-    - openai/*
+  rootChain:               # all-day chain: LAST entry is 默认模型 (official V4);
+    - anthropic/claude-3-5-sonnet          # leading entries = 默认降级链 (walked first)
+    - deepseek-official/deepseek-v4-flash  # last = Flash XOR Pro last-resort fallback
+  timeSlots:               # optional: rotate the effective root chain by wall-clock windows
+    - kind: preset         # frozen UTC+8 windows; only the model chain is editable (locks tz to Asia/Shanghai)
+      preset: liang-peak   # 09:00–12:00 and 14:00–18:00, every day
+      chain:
+        - anthropic/claude-3-5-sonnet
+    - kind: custom         # custom window (may wrap midnight)
+      name: evening        # optional display name
+      start: '22:00'
+      end: '02:00'
+      days: [1, 5]         # optional; omitted/empty = every day (0=Sunday…6=Saturday)
+      chain:
+        - openai/gpt-4o
   roles:                   # block 2: declare role entities first, then let rules reference them
     list:
       - id: reviewer       # unique id (/^[a-z0-9-]{1,32}$/); "inherit" is reserved
@@ -41,28 +86,56 @@ fallbacks:
         chain:
           - openai/gpt-4o-mini
         fallback: inherit-root   # default: role chain, then append rootChain
-    rules:
-      - origin: subagent   # all subagents → reviewer role (own chain + inherited root)
-        role: reviewer
+    rules:                 # subagent-only: rules never match root requests
+      - role: reviewer     # all subagents → reviewer role (own chain + inherited root)
 ```
 
-No rule match → the built-in `inherit` → `rootChain`. `enabled` defaults to **off** — with no chains configured the plugin is a complete no-op. Full reference (role entities, fallback strategies, rules, selectors, preset roles) → [docs/configuration.md](docs/configuration.md).
+No rule match (or a root request) → the built-in `inherit` → `rootChain`. `enabled` defaults to **off** — with no chains configured the plugin is a complete no-op. The all-day `rootChain` must END with exactly one official V4 model (`deepseek-official/deepseek-v4-flash` or `deepseek-official/deepseek-v4-pro`) — the settings card and gateway reject any other tail on save (a legacy non-official-tail chain warns at startup and keeps working as a fallback-only walk, but cannot be saved as-is). Full reference (role entities, fallback strategies, rules, selectors, preset roles, time-slot presets) → [docs/configuration.md](docs/configuration.md).
 
 > **Upgrade note (behavior change)**: an existing `fallbacks:` section **without an explicit `enabled` key** resolves to `false` after upgrading — add `enabled: true` to keep the plugin active.
 
 ### Verify
 
-Save and restart the session, then type `/fallbacks` — the read-only in-session diagnostics (origin, resolved role, chain, recent `fallbacks/switch` events, cooldown status). Sessions containing `fallbacks/switch` events load after a restart because the plugin registers the event type at startup (rc.6 runtime registration; an upstream registration surface is pending) — without the plugin installed, such sessions refuse to load again until the upstream surface lands (see the Features note below). In a dsh-tui profile, `/fallbacks config` additionally reads back the composed configuration (the TUI has no settings page — config is file-only; see [docs/configuration.md](docs/configuration.md)).
+Save and restart the session, then type `/fallbacks` — the read-only in-session diagnostics (origin, resolved role, chain, recent `fallbacks/switch` events, cooldown status). The plugin no longer writes durable `fallbacks/switch` session events (issue #52 — the apply()-time registration was proven ineffective), so new switches show up in the info logs, not in the recent-switch surfaces; sessions written by older plugin versions that contain `fallbacks/switch` events are repaired with `scripts/repair-fallbacks-switch-logs.ts`, which marks legacy events ignorable so those sessions load again (see the Features note below). In a dsh-tui profile, `/fallbacks config` additionally reads back the composed configuration (the TUI has no settings page — config is file-only; see [docs/configuration.md](docs/configuration.md)).
 
 ## Features
 
 - **Automatic fallback for root and subagents**: any agent switches down the chain to the next available provider/model on model failure — no manual model switching.
 - **Two-block config**: `rootChain` for the root agent; declared role entities (`roles.list`) referenced by `roles.rules` (or the built-in `inherit`).
+- **Chain as root primary from the picker**: when `enabled` is on, the host model picker (web and TUI alike) shows a virtual `FallbacksChain` / `Auto` row — selecting it uses the configured chain as the root primary (a conforming all-day head is required for the override to succeed); selecting a real model keeps fallback-only (see [FallbacksChain in the model picker](#fallbackschain-in-the-model-picker)).
+- **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.
-- **Visible behavior**: every switch appends a persisted `fallbacks/switch` session event (from/to/role/reason) with info-level logs — no silent model switching. The event type is registered with the harness at plugin startup (rc.6 runtime registration; an upstream registration surface is pending), so persisted events stay loadable across restarts while the plugin is installed.
+- **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**: `enabled` defaults to off; with no chains configured the plugin behaves exactly like not being installed.
 
+## FallbacksChain in the model picker
+
+When `enabled: true`, the plugin registers a virtual provider, **FallbacksChain**, with a single catalog row: **Auto**. The web profile and dsh-tui both see the row: they share the same adapter catalog, so no TUI settings page or host patch is involved. The row is visible whenever the plugin is enabled — a legacy or empty all-day chain does NOT hide it (the override just refuses to fire).
+
+Selecting **FallbacksChain / Auto** uses the configured chain as the root **primary**: root requests route to the effective chain's first exact `provider/model` at request time, and the fallback engine degrades from that head as usual. Selecting any real catalog model keeps the v0.2.2 fallback-only behavior — the session model is primary and the chain engages only after it fails.
+
+There is **no `rootMode` switch** — no config key, YAML field, settings toggle, or gateway flag. The mode is the session's `{provider, model}` selection itself: `FallbacksChain` = chain primary; any real model = fallback-only.
+
+Notes:
+
+- **Picker label**: the row's catalog `name` (what the composer trigger shows) is live — `Auto: DeepSeek V4 Flash[Liang Peak]` / `Auto: DeepSeek V4 Flash[all-day]` (catalog display name, not the model id); the id stays `Auto`. Bare `Auto` if the all-day tail is not conforming. Refresh by reopening the picker.
+- **Root only**: the row is about the root agent. Subagent role resolution and injection are unchanged; a subagent session that inherits the selection still routes through the chain head — the virtual row is a thin delegate, never a second routing engine.
+- **Conformance gate on the tail**: a successful override/delegate requires the all-day chain to be **tail-conforming** — its last entry must be exactly one official V4 model (`deepseek-official/deepseek-v4-flash` or `deepseek-official/deepseek-v4-pro`, the card's 默认模型 panel); leading entries (默认降级链) are walked first. Disabling the plugin hides the row again (slot-row/chain edits never churn registration).
+- **Stale selection**: if the row disappears (plugin disabled) while `FallbacksChain / Auto` is selected, the session keeps showing it as the current model with `routable: false` — pick a real model from the catalog to continue (host-native catalog semantics).
+- **Capabilities follow the head**: the row's model metadata (context window, modalities, reasoning) mirrors the current effective head; retry attribution follows the permissive default — retries/failures are accounted to the real head pair, not to the `FallbacksChain` provider. Full semantics → [docs/configuration.md](docs/configuration.md).
+
+## Time-slot presets (分时切换)
+
+Time slots (分时切换) are introduced in the [featured overview](#time-slots) above; this section is the reference. Time-slot rows rotate the **effective root chain** by wall-clock windows — useful for peak/valley pricing without confusing wall-clock rotation with failure fallback. The copy split is strict: slot rotation logs and UI say **分时切换** (time-slot switch); the failure walk keeps **降级切换** (fallback switch); the conversation notice 模型已降级 / Model downgraded stays on the failure path only.
+
+- **Match order**: at every root request, the first extra row whose window contains the current moment (in `fallbacks.tz`, default `Asia/Shanghai` / UTC+8) wins — that row's chain **replaces** the all-day chain. No row matches → the all-day `rootChain` is used. The all-day row is always last and **required**: its last entry must be exactly one official V4 model (Flash XOR Pro; leading 默认降级链 entries are walked first).
+- **Presets** (frozen, not user-editable): `liang-peak` = 09:00–12:00 **and** 14:00–18:00 every day; `liang-valley` = every other UTC+8 time; `glm-peak` = Monday–Friday 14:00–18:00; `glm-valley` = every other time. One preset id = one row; the card picker never offers a duplicate.
+- **Custom rows**: `start` / `end` (`HH:mm`, may wrap midnight) + optional `days` (0=Sunday…6=Saturday; omitted/empty = every day) + models.
+- **Next-request apply**: a slot boundary crossing never preempts an in-flight step — the new row takes effect on the next root request. Rotation is mount-only: info log + card/`/fallbacks` status line, no durable switch event.
+- **Settings card**: the 主代理 section groups 分时槽设置 (extra rows — add preset / add custom / remove / reorder by buttons or **drag**; preset rows show a read-only window summary and edit models only; custom rows carry an editable name; the **timezone picker** lives here and **locks to Asia/Shanghai while any preset row exists**, since preset windows are frozen UTC+8 constants), 默认降级链 (walked first when no slot matches) and 默认模型 (the official V4 Flash | Pro last-resort fallback). Rows are collapsible to name + first model. There is no `timeSlots.enabled` master switch (adding a row is the opt-in) and no `rootMode` control.
+
 ## Preset roles
 
 The plugin ships **7 bundled generic subagent roles** out of the box — `designer` / `librarian` / `reviewer` / `scout` / `security-reviewer` / `sonic` / `task` — declared automatically on `apply` as seeded `roles.list` rows (`{ id, persona }`): idempotent, and never overwriting an operator persona. They appear in the Settings card (seed badge, id immutable) and in the `/fallbacks config` role summary, ready for `roles.rules` to reference.

package/README.zh-CN.md

@@ -13,6 +13,25 @@ dsh（DeepSeek Harness）的自动模型降级插件：当 root agent 或 subage
 
 两个 dsh 前端均可用：**web** profile（设置 → 插件配置 → Fallbacks 卡片）与 **dsh-tui** 终端 profile（`/fallbacks` + `/fallbacks config`）。
 
+## 峰谷无忧
+
+峰谷无忧（分时切换）按墙钟窗口轮换**生效 root 链**：每个时段槽行拥有自己的 fallback 链，第一个窗口包含当前时刻的行将在下一个 root 请求取代全时段链——无行命中时，全时段链作为兜底保持在最后。峰谷窗口因此可以使用不同的模型链，而失败降级路径（降级切换）保持不变。
+
+![峰谷无忧](docs/assets/screenshot-1-zh.png)
+
+四个冻结的 UTC+8 预设（窗口为代码常量；存在预设行时 `tz` 锁定 Asia/Shanghai）：
+
+| 预设 | 窗口 |
+|---|---|
+| `liang-peak` | 每天 09:00–12:00 与 14:00–18:00 |
+| `liang-valley` | 其它所有 UTC+8 时间（Liang Peak 的补集） |
+| `glm-peak` | 周一至周五 14:00–18:00 |
+| `glm-valley` | 其余时间（GLM Peak 的补集） |
+
+GLM 峰与 GLM 谷仅在已配置 `zai-coding-cn` 时出现在设置卡选择器中。
+
+每个 root 请求时刻，第一条窗口包含当前时刻（按 `fallbacks.tz`，默认 Asia/Shanghai）的额外行生效；无行命中 → 全时段 `rootChain`——其链尾（默认模型）必须是恰好一个官方 V4 模型：`deepseek-official/deepseek-v4-flash` 或 `deepseek-official/deepseek-v4-pro`（二选一）。分时切换是路由种子而非失败决策：在下一个 root 请求生效、不消耗冷却、不计入 `maxSwitchesPerStep`，日志记为**分时切换**；失败降级保持**降级切换**。完整语义 → [分时槽预设（分时切换）](#分时槽预设分时切换) 与 [docs/configuration.md](docs/configuration.md)。
+
 ## 快速开始
 
 ### 安装
@@ -24,6 +43,20 @@ dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui 终端 profile
 
 同一个插件、两个前端——区别只在 `--profile` 参数。钉版本：加 `@<version>`。registry 安装拉取的是**已构建产物**（`dist/`），目标机无需构建。registry / git / 本地目录变体、卸载与 `--dump-config` 验证 → [docs/install.md](docs/install.md)。
 
+### 修复旧会话（0.2.2 之前的版本）
+
+0.2.2 之前的版本会把 `fallbacks/switch` 事件写入会话持久化日志，而新版 dsh 拒绝加载这类会话（issue #52——apply() 时的注册因插件与宿主解析到不同模块实例而无效）。如果升级后已有会话打不开，clone 本仓库并修复日志（先停 dsh）：
+
+```sh
+git clone https://github.com/omdsh-dev/dsh-llm-fallbacks.git
+cd dsh-llm-fallbacks
+pnpm install
+pnpm repair:fallbacks-switch-logs -- --dry-run            # 预览哪些会话会被改动
+pnpm repair:fallbacks-switch-logs -- --apply --backup     # 给旧事件打 ignorable 标记
+```
+
+脚本默认扫描 `~/.dsh/sessions`（可用 `--root <dir>` 覆盖），把遗留 `fallbacks/switch` 事件标记为 `ignorable: true`，宿主读路径即可重新接受该会话；每个被修复的日志保留一份 `<file>.bak`。`--apply` 必须搭配 `--backup`，且须在 dsh 停止时运行。从 0.2.2 起插件不再写 durable 切换事件，新会话无需修复。
+
 ### 最小配置
 
 在 dsh 的设置文档（默认 `$DSH_HOME/settings.yaml`）中添加 `fallbacks:` 分节：
@@ -31,9 +64,21 @@ dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui 终端 profile
 ```yaml
 fallbacks:
   enabled: true          # 功能级开关；默认关闭（false），需显式打开后生效
-  rootChain:             # 块 1：root 主代理降级链；主模型失败后按顺序尝试
-    - anthropic/claude-3-5-sonnet
-    - openai/*
+  rootChain:             # 全时段链：最后一项是默认模型（官方 V4）
+    - anthropic/claude-3-5-sonnet          # 前面是默认降级链（先走）
+    - deepseek-official/deepseek-v4-flash  # 最后一档：Flash 或 Pro
+  timeSlots:             # 可选：按墙钟时段轮换 root 生效链
+    - kind: preset       # 冻结的 UTC+8 窗口；仅模型链可编辑（锁定 tz 为 Asia/Shanghai）
+      preset: liang-peak # 09:00–12:00 与 14:00–18:00，每天
+      chain:
+        - anthropic/claude-3-5-sonnet
+    - kind: custom       # 自定义窗口（可跨午夜）
+      name: evening      # 可选显示名称
+      start: '22:00'
+      end: '02:00'
+      days: [1, 5]       # 可选；缺省/空 = 每天（0=周日…6=周六）
+      chain:
+        - openai/gpt-4o
   roles:                 # 块 2：先声明角色，再让规则引用
     list:
       - id: reviewer     # 角色实体：id 唯一（/^[a-z0-9-]{1,32}$/）；inherit 为保留字
@@ -41,28 +86,56 @@ fallbacks:
         chain:
           - openai/gpt-4o-mini
         fallback: inherit-root   # 默认：角色链后追加 rootChain
-    rules:
-      - origin: subagent # 所有 subagent → reviewer 角色（自身链 + 继承 root）
-        role: reviewer
+    rules:               # 仅对子代理生效：规则不匹配 root 请求
+      - role: reviewer   # 所有 subagent → reviewer 角色（自身链 + 继承 root）
 ```
 
-未命中规则 → 内置 `inherit` → `rootChain`。`enabled` **默认关闭（`false`）**——未配置任何链时插件完全 no-op。完整参考（角色实体、fallback 策略、规则、selector、预设角色）→ [docs/configuration.md](docs/configuration.md)。
+未命中规则（或 root 请求）→ 内置 `inherit` → `rootChain`。`enabled` **默认关闭（`false`）**——未配置任何链时插件完全 no-op。全时段 `rootChain` 的**最后一项**必须恰好是一个官方 V4 模型（`deepseek-official/deepseek-v4-flash` 或 `deepseek-official/deepseek-v4-pro`）——设置卡与 gateway 在保存时拒绝其它尾巴（遗留非合规尾巴启动时告警并继续按 fallback-only 走原链，但无法原样保存）。完整参考（角色实体、fallback 策略、规则、selector、预设角色、分时槽预设）→ [docs/configuration.md](docs/configuration.md)。
 
 > **升级提示（行为变更）**：已有 `fallbacks:` 配置若**未显式写 `enabled` 键**，升级后解析为 `false`——请补上 `enabled: true` 以保持插件继续生效。
 
 ### 验证
 
-保存并重启会话后，键入 `/fallbacks`——只读的会话内诊断（来源、解析角色、链、最近的 `fallbacks/switch` 事件、冷却状态）。含 `fallbacks/switch` 事件的会话能在重启后正常加载，是因为插件在启动时注册了该事件类型（rc.6 运行时注册；上游注册面待落地）——卸载插件后，含此类事件的会话将再次拒绝加载，直到上游注册面落地（见下方「能力一览」说明）。在 dsh-tui profile 中，`/fallbacks config` 额外回读组合配置（TUI 无设置页——配置仅文件，见 [docs/configuration.md](docs/configuration.md)）。
+保存并重启会话后，键入 `/fallbacks`——只读的会话内诊断（来源、解析角色、链、最近的 `fallbacks/switch` 事件、冷却状态）。插件**不再写入** durable `fallbacks/switch` 会话事件（issue #52——apply() 时的注册被证伪无效），因此新切换只出现在 info 日志中，不再出现在 recent-switch 展示面；由旧版插件写入、含 `fallbacks/switch` 事件的会话，可用 `scripts/repair-fallbacks-switch-logs.ts` 修复——脚本把旧事件标记为 ignorable，会话即可重新加载（见下方「能力一览」说明）。在 dsh-tui profile 中，`/fallbacks config` 额外回读组合配置（TUI 无设置页——配置仅文件，见 [docs/configuration.md](docs/configuration.md)）。
 
 ## 能力一览
 
 - **root / subagent 自动降级**：任意 agent 在模型故障下按链切换到下一个可用 provider/model，无需手动换模型。
 - **两块制配置**：`rootChain` 管 root 代理；声明式角色实体（`roles.list`）供 `roles.rules` 引用（或内置 `inherit`）。
+- **选择器里把链当主模型**：`enabled` 开启时，宿主模型选择器（web 与 TUI 一致）出现虚拟 `FallbacksChain` / `Auto` 行——选中它即以配置的链作为 root 主模型（需要 all-day 链头合规才能成功覆盖）；选真实模型则保持 fallback-only（见 [模型选择器中的 FallbacksChain](#模型选择器中的-fallbackschain)）。
+- **峰谷无忧（分时切换）**：可选的 `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` 冷却到期后自动回主模型。
-- **行为可见**：每次切换追加持久化会话事件 `fallbacks/switch`（from/to/role/reason），配合 info 级日志——无静默换模型。插件在启动时把该事件类型注册进宿主（rc.6 运行时注册；上游注册面待落地），持久化事件在插件安装期间可跨重启加载。
+- **行为可见**：每次切换以 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` 默认关闭；未配置任何链时行为与未安装插件完全一致。
 
+## 模型选择器中的 FallbacksChain
+
+当 `enabled: true` 时，插件注册一个虚拟 provider **FallbacksChain**，目录中只有一行：**Auto**。web profile 与 dsh-tui 都能看到这一行：两者共享同一个 adapter catalog，无需 TUI 设置页或宿主补丁。该行只要插件启用就可见——遗留多模型或空的 all-day 链**不会**隐藏它（只是覆盖不会生效）。
+
+选择 **FallbacksChain / Auto** = 把配置的链作为 root **主模型**：root 请求路由到请求时刻生效链的第一个精确 `provider/model`，失败后由降级引擎从该链头照常沿链切换。选择任何真实目录模型则保持 v0.2.2 的 fallback-only 行为——会话模型为主，链只在它失败后介入。
+
+**没有 `rootMode` 开关**——没有配置键、YAML 字段、设置开关或 gateway 标志。模式就是会话的 `{provider, model}` 选择本身：`FallbacksChain` = 链为主模型；任意真实模型 = fallback-only。
+
+注意：
+
+- **选择器文案**：目录行的 `name`（composer 触发器显示）是动态的——`Auto: DeepSeek V4 Flash[Liang Peak]` / `Auto: DeepSeek V4 Flash[all-day]`（用 catalog 显示名，不是 model id）；id 仍是 `Auto`。all-day 尾巴不合规则只显示 `Auto`。重新打开选择器即可刷新。
+- **仅 root**：这一行只关乎 root 代理。subagent 的角色解析与注入不变；继承了该选择的 subagent 会话仍经链头路由——虚拟行只是薄委托，绝不是第二个路由引擎。
+- **链尾合规门槛**：覆盖/委托成功要求 all-day 链**尾巴合规**——最后一项必须是恰好一个官方 V4 模型（`deepseek-official/deepseek-v4-flash` 或 `deepseek-official/deepseek-v4-pro`，即设置卡的「默认模型」面板）；前面的默认降级链先走。禁用插件后该行隐藏（slot/链编辑不会触发注册抖动）。
+- **过期选择**：行消失（插件禁用）而会话仍选中 `FallbacksChain / Auto` 时，会话继续把它显示为当前模型，但 `routable: false`——从目录选一个真实模型即可继续（宿主原生目录语义）。
+- **能力跟随链头**：该行的模型元数据（上下文窗口、模态、推理）镜像当前生效链头；重试归属保持宽松默认——重试/失败记到被委托的真实链头，而非 `FallbacksChain` provider。完整语义 → [docs/configuration.md](docs/configuration.md)。
+
+## 分时槽预设（分时切换）
+
+峰谷无忧在[首页专题](#峰谷无忧)中介绍，本节是完整参考。分时槽行按墙钟窗口轮换**生效 root 链**——适合按峰谷切换模型，且不会把墙钟轮换误认为故障降级。文案严格区分：时段轮换的日志与 UI 用**分时切换**；失败降级保持**降级切换**；会话内「模型已降级」提示只出现在失败路径。
+
+- **匹配顺序**：每个 root 请求时刻，第一条窗口包含当前时刻（按 `fallbacks.tz`，默认 `Asia/Shanghai` / UTC+8）的额外行生效——该行的模型链**取代**全时段链；无行命中则用全时段 `rootChain`。全时段行固定最后且**必选**：最后一项必须是恰好一个官方 V4 模型（Flash 或 Pro；前面的降级条目先走）。
+- **预设**（冻结，不可编辑窗口）：`liang-peak` = 每天 09:00–12:00 **与** 14:00–18:00；`liang-valley` = 其它所有 UTC+8 时间；`glm-peak` = 周一至周五 14:00–18:00；`glm-valley` = 其余时间。一个预设 id 对应一行；设置卡的选择器不会重复提供已添加的预设。
+- **自定义行**：`start` / `end`（`HH:mm`，可跨午夜）+ 可选 `days`（0=周日…6=周六；缺省/空 = 每天）+ 模型。
+- **下一请求生效**：时段边界跨越绝不打断进行中的 step——新行在下一个 root 请求生效。轮换仅挂载生效：info 日志 + 设置卡/`/fallbacks` 状态行，无 durable 切换事件。
+- **设置卡**：主代理区块下分三块——**分时槽设置**（额外行：添加预设 / 添加自定义 / 删除 / 按钮或**拖拽**排序；预设行只读展示窗口摘要、仅可编辑模型链；自定义行带可编辑名称；**时区选择器**在此区块内，只要存在预设行就**锁定 Asia/Shanghai**——预设窗口是冻结的 UTC+8 常量）、**默认降级链**（all-day 链，可配置的 provider/model 选择器列表）与**默认模型**（官方 V4 Flash | Pro 二选一链头）。行可折叠为「名称 + 首个模型」。没有 `timeSlots.enabled` 总开关（添加行即开启），也没有 `rootMode` 控件。
+
 ## 预设角色（Preset roles）
 
 插件内置 **7 个通用子代理角色**，开箱即用——`designer` / `librarian` / `reviewer` / `scout` / `security-reviewer` / `sonic` / `task`——`apply` 时自动以 seeded `roles.list` 行（`{ id, persona }`）声明：幂等，且绝不覆盖 operator 同名 persona。它们出现在设置卡的 seed 徽标（id 不可改）与 `/fallbacks config` 的角色摘要中，可直接被 `roles.rules` 引用。

package/dist/automatch.d.ts

@@ -0,0 +1,98 @@
+/**
+ * LLM auto-match role selection (plan fallbacks-role-automatch Task 3).
+ *
+ * This module is the bounded LLM caller behind the resolver's stage-3
+ * auto-match hook (`resolveRoleAtDispatch`, `role-resolution.ts`). When the
+ * explicit and rules stages resolve to `'inherit'` and `roleAutoMatch` is
+ * enabled, `pickRoleByLlm` asks the model to pick the best-fit declared role
+ * from the taxonomy and returns its declared RAW id, or `null` (= `'inherit'`).
+ *
+ * Contract (architect-locked, plan Global Constraints · Auto-match bounded):
+ * - ONE bounded completion per decision: small `maxTokens`
+ *   ({@link AUTOMATCH_MAX_TOKENS}) and a timeout
+ *   ({@link AUTOMATCH_TIMEOUT_MS}, default 5s) that abandons the stream via
+ *   the streaming contract's cancellation (`options.signal`) — no dangling
+ *   iterator, no unhandled rejection.
+ * - Never throws. Every failure mode — throw, timeout, `none`, no valid id,
+ *   garbage answer, malformed inputs — resolves to `null`, so the "never
+ *   throws out of `agent/request`" invariant holds end-to-end (the resolver
+ *   deliberately does NOT catch the hook).
+ * - Fast paths that avoid an LLM call entirely: empty taxonomy, absent
+ *   `ctx.llm` service, and no concrete provider/model route for the judgment
+ *   call. The plugin does NOT listen on `llm/stream`, so this call cannot
+ *   recurse into the plugin.
+ *
+ * Judgment-call route choice (documented): the concrete provider/model for the
+ * judgment call is taken from the roles' DECLARED context first — the first
+ * exact (non-wildcard) `provider/model` selector across the declared chains,
+ * in declaration order (the operator's own taxonomy is the most stable route
+ * set). If no declared chain yields an exact selector, the agent's current
+ * `options.provider`/`options.model` is used when both halves are present;
+ * otherwise the call is skipped (`null`).
+ *
+ * Pure helpers exported for unit testing:
+ * - {@link buildAutomatchPrompt} — the taxonomy prompt (declared ids +
+ *   personas + agent origin/agentPreset; instructs exactly-one-declared-id-or-
+ *   `none`).
+ * - {@link parseAutomatchAnswer} — parses a declared id out of the model
+ *   answer with surrounding whitespace/punctuation/quote/backtick tolerance;
+ *   `none` (case-insensitive) and unknown ids → `null`. `roleIds` is the
+ *   trimmed-id → declared-raw-id map, the same canonicalization the resolver
+ *   uses.
+ *
+ * @module dsh-llm-fallbacks/automatch
+ */
+import { type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { FallbacksRole, FallbacksRoles } from './config.ts';
+import type { AgentLike } from './roles.ts';
+/** Default auto-match completion timeout in ms — abandons the stream. */
+export declare const AUTOMATCH_TIMEOUT_MS = 5000;
+/** Output bound (tokens) for the judgment call: one id or the literal `none`. */
+export declare const AUTOMATCH_MAX_TOKENS = 32;
+/**
+ * Minimal `llm` service surface {@link pickRoleByLlm} reads. The real
+ * `LlmRuntime.stream(options)` matches structurally; this face keeps the
+ * module free of the full cordis Context merge.
+ */
+export interface AutomatchLlm {
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/**
+ * Minimal context surface: `ctx.get('llm')` (optional service — absent →
+ * `null` fast-path). The broad `get(name: string)` face is satisfied by the
+ * real cordis `Context` (`ReflectService.get` overloads return `any`/the
+ * merged service), so the Task-4 wiring can pass `ctx` directly.
+ */
+export interface AutomatchContext {
+    get(name: string): AutomatchLlm | undefined;
+}
+/** Options for {@link pickRoleByLlm}. */
+export interface PickRoleByLlmOptions {
+    /** Completion timeout in ms; defaults to {@link AUTOMATCH_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Warning sink — the decision path injects the plugin logger. */
+    warn: (message: string) => void;
+}
+/**
+ * Build the auto-match taxonomy prompt: every declared role's trimmed id and
+ * persona, the agent's origin (and non-empty `agentPreset` when present), and
+ * the exactly-one-declared-id-or-`none` instruction. Pure — no I/O.
+ */
+export declare function buildAutomatchPrompt(roles: readonly FallbacksRole[], agent: AgentLike): string;
+/**
+ * Parse the model's answer into a declared role id.
+ *
+ * The answer is expected to BE an id (possibly wrapped in whitespace, quotes,
+ * backticks, or trailing punctuation); surrounding characters outside the id
+ * grammar (`[a-zA-Z0-9-]`) are stripped, then the remaining string must match
+ * a declared id exactly (case-insensitive) via `roleIds` (trimmed id →
+ * declared RAW id, the resolver's canonicalization). `none` (case-insensitive)
+ * and any unknown/malformed answer → `null`.
+ */
+export declare function parseAutomatchAnswer(answer: string, roleIds: ReadonlyMap<string, string>): string | null;
+/**
+ * Bounded LLM role-selection call (see module header). Resolves the declared
+ * RAW id of the best-fit role, or `null` on any fast path or failure. NEVER
+ * throws.
+ */
+export declare function pickRoleByLlm(ctx: AutomatchContext, roles: FallbacksRoles, agent: AgentLike, opts: PickRoleByLlmOptions): Promise<string | null>;

package/dist/client/FallbacksCard.d.ts

@@ -1,8 +1,9 @@
 /**
  * Fallbacks settings card — the `fallbacks` plugin card on the web settings
- * "插件配置" page (spec §4). Registered into the `settings.plugin.item` slot
- * (id `fallbacks`, order 30, alongside the upstream bash/agent-loop/web-search
- * cards and the advisor card); owner props are empty and all data flows
+ * "插件配置" page (spec §4). Registered into the `settings.plugin.item` keyed
+ * slot (key `fallbacks`, the settings namespace the card edits, alongside
+ * the upstream bash/agent-loop/web-search cards and the advisor card, in
+ * registration order); owner props are empty and all data flows
  * through {@link FallbacksSettingsController}.
  *
  * The card chrome replicates the upstream `PluginCard` contract (self-drawn:
@@ -11,12 +12,22 @@
  * description, with a dirty "unsaved" pill and a rotating chevron
  * (`IconChevronDownOutline14` from ui-primitives — a CLIENT_EXTERNALS value
  * import), `aria-expanded`/`aria-label` like the upstream header; a divider
- * under the header; then the form content; then a footer with
- * Discard / Reset / Save carrying the upstream disabled semantics — save =
- * `!dirty || saving || !writable`, discard = `!dirty || saving` (KD-U1).
- * Disclosure is card-local state: which card a user has open is a reading
- * gesture, and staged edits outlive collapsing — the pill rides the header
- * (upstream rationale).
+ * under the header; then the form content. PR #62 UX round 2: the card
+ * footer is gone — each big section (主代理 / 子代理 / 高级选项) carries its
+ * own Save/Discard actions beside its heading (高级选项: inside the expanded
+ * body) and its own validation / save-error surface. PR #62 UX round 3:
+ * each section's Save writes ONLY that section's fields — 主代理 owns
+ * rootChain / timeSlots / tz (+ the card-level `enabled`), 子代理 owns
+ * roles, 高级选项 owns the advanced scalars; the patch spreads the last
+ * ACCEPTED config for every other section, so a 主代理 Save can never
+ * ride along an unsaved 子代理 edit (and vice versa) — and validation /
+ * the dirty gate apply per section too (a bad role id never blocks 主代理,
+ * and only the saved section's Discard reverts that section's edits).
+ * Save/discard disabled terms: save = `!sectionDirty || saving ||
+ * !writable`, discard = `!sectionDirty || saving` (KD-U1). Disclosure is
+ * card-local state:
+ * which card a user has open is a reading gesture, and staged edits outlive
+ * collapsing — the pill rides the header (upstream rationale).
  *
  * The form body is the two-block editing surface (spec §8): the `enabled`
  * checkbox row, the 6 top-level scalar fields (trigger codes / revert
@@ -32,13 +43,14 @@
  * non-empty `state.legacyKeys` renders the migration banner at the top of
  * the card body. The row editors keep their filled editorCard surface
  * inside the card, with `--dsw-alias-*` tokens throughout. The reset-
- * to-defaults confirmation stays a `Modal` (the delete-confirm pattern of
- * the Models page) — no `window.confirm`.
+ * to-defaults affordance is GONE from the card (PR #62 UX round 3) — the
+ * gateway RPC `fallbacks/reset` and the store `resetToDefaults()` stay as
+ * host APIs (store/gateway tests unchanged), only the card UI was removed.
  *
  * The page-only chrome is gone (720px column wrapper, title/intro banners,
  * page-bottom status block): the AC-7 read-only status (derived effective
- * model + recent-switch summary) is folded into the card body above the
- * footer, and the plugin-config section owns the column width.
+ * model + recent-switch summary) is folded into the card body, and the
+ * plugin-config section owns the column width.
  *
  * Degraded/error/loading states keep the same card chrome (KD-U3): the
  * header always renders title+description+chevron, and the body carries the
@@ -52,8 +64,11 @@
  * 'error'`) also forces the body open with an error notice and — when the
  * form is inert (`!writable`, i.e. the load never landed) — a Retry button;
  * a save failure keeps the editable form so the Save action itself is the
- * retry (the single `state.error` surface covers both, unlike the advisor's
- * separate apply-failure hints).
+ * retry. PR #62 UX round 2: the single `state.error` surface is split by
+ * origin — a LOAD failure keeps the card-top notice (with Retry when
+ * inert), while a WRITE failure renders under the section whose Save was
+ * last clicked (`lastSaveSection`), unlike the advisor's separate
+ * apply-failure hints.
  *
  * The degraded derivation is latched in the card (the store stays untouched):
  * `present` only ever changes inside the store's `accept()`, so the settled

package/dist/client/fallbacks-store.d.ts

@@ -27,6 +27,7 @@
 import type { ClientConnectionRpc, ConfigurableProviderView, HistoryEntry, IApiClient, ModelProviderGroup, SessionId, SettingsNamespaceView } from '@deepseek-ai/dsh-client-connection/client';
 import { type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
 import { type FallbackStrategy, type FallbacksConfig, type FallbacksRole, type FallbacksRoleRule, type FallbacksRoles } from '../config.ts';
+import type { SlotRowConfig } from '../time-slots.ts';
 import type { FallbacksSwitchEventData } from '../events.ts';
 import type { SeedsWireStatus } from '../seeds.ts';
 /** The plugin's settings namespace on the host wire (settings/document-updated ns filter). */
@@ -180,12 +181,18 @@ export declare function classifyModel(provider: string, raw: string, catalog: Ca
  */
 export declare function extractRecentSwitches(entries: readonly HistoryEntry[], limit?: number): FallbacksSwitchSnapshot[];
 /**
- * Derive the status block's "current effective model" (spec §2.5 D-6): ①
- * disabled / empty rootChain → unavailable; ② a recent switch exists → the
- * latest one's `to`; ③ otherwise → the config's primary target. A **display
- * value** — never a live route probe (the section appends the non-probing
- * note inline right after the derived value, available case only; the
- * unavailable 空态 renders its own copy without the note).
+ * Derive the "current effective model" (spec §2.5 D-6): ① disabled / empty
+ * rootChain → unavailable; ② a recent switch exists → the latest one's `to`;
+ * ③ otherwise → the config's primary target. A **display value** — never a
+ * live route probe.
+ *
+ * INTENTIONAL D-6 CONTRACT RETENTION: after the AC-2 trim (plan
+ * fallbacks-settings-visibility Task 2) the settings card's status block no
+ * longer consumes this derivation, and no other production code imports it —
+ * it is retained (NOT dead code to delete) as the spec §2.5 D-6 derived-value
+ * surface, pinned by `tests/fallbacks-store.spec.ts` (D-6 display-value
+ * contract). Keep both exports until the spec derivation is removed or gains
+ * a real consumer.
  */
 export declare function deriveEffectiveModel(config: FallbacksConfig, switches: readonly FallbacksSwitchSnapshot[]): EffectiveModelView;
 /** One chain selector row: provider + model (or wildcard). */
@@ -210,6 +217,40 @@ export interface RootChainRow {
 export declare function rootChainToRows(rootChain: readonly string[], catalog?: CatalogLookup): RootChainRow[];
 /** Rebuild the rootChain from edited rows; rows with no usable selector drop out. */
 export declare function rowsToRootChain(rows: readonly RootChainRow[]): string[];
+/**
+ * One extra time-slot row in the editor (plan fallbacks-timeslots Task 3):
+ * preset rows freeze their windows (read-only summary, models-only edits);
+ * custom rows edit start/end/days + chain. `kind` rides the wire VERBATIM —
+ * a hand-written YAML row with an unknown kind reads back as a custom-shaped
+ * row and serializes back unchanged, so the dirty check stays quiet (save
+ * validation rejects it).
+ */
+export interface SlotEditorRow {
+    kind: string;
+    /** Frozen preset id — preset rows only (windows are code constants). */
+    preset?: string;
+    /** Custom rows: window start `HH:mm` text. */
+    start: string;
+    /** Custom rows: window end `HH:mm` text. */
+    end: string;
+    /** Custom rows: day mask 0=Sunday…6=Saturday; [] = every day. */
+    days: number[];
+    /** Custom rows: display name (PR #62 feedback round — collapsed rows). */
+    name: string;
+    /** UI-only collapse state — never serialized (dropped by rowsToTimeSlots). */
+    collapsed: boolean;
+    selectors: ChainSelectorRow[];
+}
+/** Project the time-slot rows into editable rows (chain selectors classified). */
+export declare function timeSlotsToRows(timeSlots: readonly SlotRowConfig[], catalog?: CatalogLookup): SlotEditorRow[];
+/** Rebuild the time-slot rows from edited rows; blank selectors drop out.
+ * `kind` rides verbatim (a hand-written unknown kind reads back unchanged;
+ * save validation rejects it) — the cast asserts the trusted editor shape.
+ * `days` is ALWAYS serialized ([] included): schemastery composes absent
+ * array fields as `[]`, so the composed config every card load accepts
+ * carries `days` on every row — the draft must too, or a clean card would
+ * read back dirty. */
+export declare function rowsToTimeSlots(rows: readonly SlotEditorRow[]): SlotRowConfig[];
 /**
  * One declared-role row in the editor (block 2 `roles.list`): identity
  * fields + the role's own chain selector list + its append strategy.
@@ -221,6 +262,8 @@ export interface RoleRow {
     persona: string;
     selectors: ChainSelectorRow[];
     fallback: FallbackStrategy;
+    /** UI-only collapse state — never serialized (dropped by rowsToRoles). */
+    collapsed: boolean;
 }
 /** Project the declared roles into editable rows (chain selectors classified). */
 export declare function rolesToRows(roles: readonly FallbacksRole[], catalog?: CatalogLookup): RoleRow[];
@@ -253,16 +296,18 @@ export declare function ruleRoleOptions(roles: Pick<FallbacksRoles, 'list'>): st
  * `chains`/`roles.default` keys never ride it).
  */
 export declare function detectLegacyClientKeys(config: FallbacksConfig): string[];
-/** One role-rule row in the editor; empty origin means "any". */
+/**
+ * One role-rule row in the editor (PR #62 feedback: no origin control —
+ * rules are subagent-only; a persisted wire `origin` is ignored).
+ */
 export interface RoleRuleRow {
-    origin: string;
     provider: CatalogSelection;
     model: CatalogSelection;
     role: string;
 }
 /** Project the role rules into editable rows (provider/model classified). */
 export declare function rulesToRows(rules: readonly FallbacksRoleRule[], catalog?: CatalogLookup): RoleRuleRow[];
-/** Rebuild the role rules from edited rows; empty origin/provider/model drop out. */
+/** Rebuild the role rules from edited rows; empty provider/model drop out. */
 export declare function rowsToRules(rows: readonly RoleRuleRow[]): FallbacksRoleRule[];
 /** Controller joining Settings reads, writes, and pushed invalidations. */
 export declare class FallbacksSettingsController {
@@ -363,10 +408,15 @@ export declare class FallbacksSettingsController {
      * reason }` outcome is still a successful RPC — the post-write read
      * result (config / legacyKeys / seeds) lands either way, and the revert
      * button stays disabled while the write is in flight.
+     *
+     * Returns the seed-default persona when the outcome is `{ reverted:
+     * true, persona }` — including the persist no-op (persisted already
+     * equals the seed). The card applies that string to the row's **draft**
+     * so an unsaved persona edit still snaps back (issue #59).
      * @param id - the seeded role id; the host matches it by trimmed id
      *   against the seed registry (spec §9.3).
      */
-    revertSeed(id: string): Promise<void>;
+    revertSeed(id: string): Promise<string | undefined>;
     /** Stop in-flight responses from publishing after plugin disposal. */
     dispose(): void;
     /**

package/dist/client/index.d.ts

@@ -1,8 +1,9 @@
 /**
  * dsh-llm-fallbacks client half: registers the Fallbacks card into the
- * plugin-config page's `settings.plugin.item` slot (the official "插件配置"
- * settings page — id `fallbacks`, order 30, alongside the upstream bash /
- * agent-loop / web-search cards and the advisor card).
+ * plugin-config page's `settings.plugin.item` keyed slot (the official
+ * "插件配置" settings page — key `fallbacks`, the settings namespace the card
+ * edits, appearing after the upstream bash / agent-loop / web-search cards
+ * and the advisor card in registration order).
  *
  * Wiring (mirrors dsh-advisor):
  * - Registers the `fallbacks` locale dictionaries (zh/en).
@@ -11,10 +12,11 @@
  *   `/api/fallbacks/get|set|reset`), while `settings.describe` (writable +
  *   namespace directory) and the provider/model catalog stay on
  *   `connection.api` (see `fallbacks-store.ts`).
- * - Registers the `settings.plugin.item` card `id: 'fallbacks'` (order 30)
- *   with a business-only inject face ({@link FallbacksSettingsController} +
- *   the snapshot-selector hook); the old Settings-nav section registration
- *   is removed — deleting the section registration deletes the nav entry.
+ * - Registers the `settings.plugin.item` card `key: 'fallbacks'` (the rc.7
+ *   keyed slot — no `id`/`order`) with a business-only inject face
+ *   ({@link FallbacksSettingsController} + the snapshot-selector hook); the
+ *   old Settings-nav section registration is removed — deleting the section
+ *   registration deletes the nav entry.
  * - Refreshes the store on pushed invalidations — the forwarded remote
  *   events `settings/document-updated` (ns-filtered to the fallbacks
  *   namespace; refetches the descriptor + recent-switch summary) and