dsh-llm-fallbacks 0.6.13 → 0.8.0

package/README.md

@@ -1,3 +1,5 @@
+![preview](https://raw.githubusercontent.com/omdsh-dev/dsh-llm-fallbacks/main/docs/preview.png)
+
 # dsh-llm-fallbacks
 
 [English](README.md) | [Chinese](README.zh-CN.md)
@@ -7,10 +9,10 @@
 ![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
 ![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
 ![dsh tui](https://img.shields.io/badge/dsh%20tui-compatible-4B32C3.svg)
-![dsh](https://img.shields.io/badge/DSH-0.2.1--rc.4-4B32C3.svg)
+![dsh](https://img.shields.io/badge/DSH-0.2.2--rc.1-4B32C3.svg)
 [![dshfind](https://dshfind.com/api/badge/omdsh-dev/dsh-llm-fallbacks?lang=en)](https://dshfind.com/zh/plugins/omdsh-dev/dsh-llm-fallbacks?ref=badge)
 
-Automatic provider/model fallback chains for dsh (DeepSeek Harness): when an agent's LLM requests keep failing — retries exhausted, auth errors, quota exceeded, rate limiting (429) — the plugin switches provider/model along the fallback chain for the current role, and the current step/turn continues on the target model: tasks are not interrupted by model problems.
+Automatic provider/model fallback chains for dsh (DeepSeek Harness): the plugin registers N **named virtual chains**, each selectable in the model picker as **`FallbacksChain / <chain id>`** — a session routed to one walks that chain, so an LLM request that keeps failing on a listed code (auth, quota, rate limiting 429, …) is retried on the next available provider/model and tasks are not interrupted by model problems. A session on any **real** provider/model has **no plugin fallback**: `llm-retry` alone handles it. Create a chain in the Fallbacks settings card, then select its `FallbacksChain / <id>` row to get it.
 
 Works in both dsh front ends: the **web** profile (Settings → Plugins → Fallbacks card) and the **dsh-tui** terminal profile (`/fallbacks` session diagnostics, `/fallbacks config` readback, and the `/settings` fallbacks section for editing).
 
@@ -18,18 +20,20 @@ Works in both dsh front ends: the **web** profile (Settings → Plugins → Fall
 
 ### Automatic model failover
 
-Any agent — root or subagent — that keeps failing on a listed failure code walks its chain to the next available provider/model and keeps the step alive. No manual model switching, and nothing happens until you configure content.
+A session routed to `FallbacksChain / <chain id>` — the root agent by selection, or a subagent whose role points at that chain (「指定降级链」) — walks it: a request that fails on a listed code **before emitting any output** is retried on the next available provider/model inside the same request, and the step stays alive. Sessions on a real provider/model get no plugin fallback at all. No manual model switching, and nothing happens until you configure a chain (empty `chains` is the only first-run state).
 
-- **Triggers**: `triggerCodes` (default `AUTH` / `QUOTA` / `RATE_LIMIT`) — **any** dsh failure code is accepted, including `CONTEXT_WINDOW_EXCEEDED`, which fails over to a larger-context candidate. Retryable failures (5xx, `TRANSPORT`, `TIMEOUT`, …) stay with llm-retry first.
+- **Who gets a chain**: only sessions whose model selection routes to `FallbacksChain / <chain id>`. That is the root agent when the row is selected, and a subagent the seam mounted there at dispatch (local backend, no explicit route on the request). A real provider/model selection — root or subagent — is left entirely to llm-retry.
+- **Triggers**: `triggerCodes` (default `AUTH` / `QUOTA` / `RATE_LIMIT`) — **any** dsh failure code is accepted, including `CONTEXT_WINDOW_EXCEEDED`, which fails over to a larger-context candidate. Retryable failures (5xx, `TRANSPORT`, `TIMEOUT`, …) stay with llm-retry first; each of its retries re-enters the walk, which starts past the head that just went on cooldown.
+- **Partial output is committed**: once an attempt has emitted a chunk, a later failure is **not** switched inside the request — yielded output cannot be unsent. The failure surfaces to the loop; recovery is llm-retry re-entry (a fresh walk) or the terminal error.
 - **Recovery**: a failed / switched-away model is held out of selection for `cooldownMs`, and `revertPolicy: cooldown-expiry` returns to the primary model on expiry. The opt-in `recovery: half-open` mode (YAML-only) makes that return evidence-driven instead of timer-based.
-- **Safety valves**: `maxSwitchesPerStep` caps switches per step and `alwaysModeRetryCap` caps always-mode retries — chain loops cannot amplify latency.
-- **Visibility**: every switch is recorded in an info-level log line (from/to/role/reason) — no silent model switching.
+- **Safety valve**: `maxSwitchesPerStep` caps switches per request walk (attempts ≤ cap + 1) — chain loops cannot amplify latency.
+- **Visibility**: every switch is recorded in an info-level log line (from/to/role/reason/candidates) — no silent model switching.
 
 → [Automatic model failover](docs/features.md#automatic-model-failover) · [Context-window-aware fallback](docs/features.md#context-window-aware-fallback)
 
 ### Peak/valley time slots
 
-Time slots rotate the **effective root chain** by wall-clock windows: each 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 the last resort when no row matches. Rotation is a routing seed, not a failure decision: it consumes no cooldown and leaves the failure walk (fallback switch) untouched.
+Time slots are configured **per chain** and rotate that chain's effective entries by wall-clock windows: the first row whose window contains the current moment replaces the chain's default entries for the next request — the chain's own entries stay the last resort when no row matches. Rotation is a routing seed, not a failure decision: it consumes no cooldown and leaves the failure walk (fallback switch) untouched.
 
 ![Time slots](docs/assets/screenshot-1-en.png)
 
@@ -50,7 +54,7 @@ GLM Peak and GLM Valley are offered in the card picker only when `zai-coding-cn`
 
 A subagent's role is declared in its dispatch prompt — the Assignment header `**Execute as**: <id>` — and it is resolved against the role ids declared in `roles.list`. Only that **declared header** delivers the child's identity: the role's `persona` is installed on the child as a system-prompt section, the child's own session gets exactly one `[role: <id>]` notice row, and its session header shows a role badge.
 
-Role **routing** is resolved separately, in four ordered stages, first hit winning — explicit `agentPreset` → **dispatch-declared** `**Execute as**: <id>` header → rules → LLM auto-match. If the child's dispatch prompt declares `**Execute as**: <id>`, that role's persona, `[role: <id>]` notice and badge are delivered **regardless of which routing stage wins** — an earlier explicit `agentPreset` can route the child as another role while the identity carriers stay the declared header's. A child with **no declared dispatch header** gets no persona, no notice row and no role half of the badge (the model half still renders when the child has a recorded route), even when rules or auto-match resolve a role for routing. Making the resolved role's chain head the child's model is plugin-originated and conditional: with the host `subagent-model-selection` policy enabled, an explicit authorized route is preserved (inject skipped) and an injected head must be inside the effective allowlist — an empty intersection injects nothing ([host policy](docs/features.md#host-subagent-model-selection-policy-dsh-012)).
+Role **identity** is resolved at dispatch in two ordered stages, first hit winning — explicit `agentPreset` → the **dispatch-declared** `**Execute as**: <id>` header. If the child's dispatch prompt declares `**Execute as**: <id>`, that role's persona, `[role: <id>]` notice and badge are delivered. A child with **no declared dispatch header** is NOT SPECIFIED: no persona, no notice row, no role half of the badge — and the plugin does not intervene. The role can also carry a **manual chain pointer** (「指定降级链」): at dispatch the seam stamps a local, non-explicit-route child onto `FallbacksChain / <role.chain>` — an explicit route is **authorized** and never touched, and an external-backend child keeps pure inheritance. There is no rule matching and no host-policy consultation: the mapping is your static config.
 
 This covers an **ordinary subagent dispatch and an Agent Team teammate** (`spawn_teammate`) alike: both are children dispatched with the same header, which the model writes — the same dispatch seam, no mechanism-specific configuration.
 
@@ -85,30 +89,30 @@ The plugin's settings live in a shared `fallbacks:` namespace, editable from thr
 
 ```yaml
 fallbacks:
-  rootChain:               # all-day chain: leading entries = fallback walk, last = Default model (official)
-    - anthropic/claude-3-5-sonnet
-    - deepseek-official/deepseek-flash
-  timeSlots:               # optional: rotate the effective root chain by wall-clock windows
-    - kind: preset
-      preset: liang-peak
-      chain:
+  chains:                  # named virtual chains: one picker row each (FallbacksChain/<id>)
+    - id: Auto             # the picker model id (case-sensitive, unique)
+      label: Default chain # tab title + picker prefix (display only)
+      entries:             # 默认降级链 …then the 默认模型 tail (exactly one official model)
         - anthropic/claude-3-5-sonnet
-  roles:                   # optional: declare role entities, then reference them from rules
+        - deepseek-official/deepseek-v4-pro
+      timeSlots: []        # optional: this chain's own wall-clock rows
+    - id: Coding
+      label: Coding
+      entries:
+        - openai/gpt-4o-mini
+        - deepseek-official/deepseek-flash
+  roles:                   # optional: role identities + an optional chain POINTER
     list:
       - id: reviewer
         persona: Code-review subagents
-        chain:
-          - openai/gpt-4o-mini
-        fallback: inherit-root
-    rules:                 # subagent-only: rules never match root requests
-      - role: reviewer
+        chain: Coding      # 指定降级链: children under this role mount FallbacksChain/Coding
 ```
 
 Three rules of thumb:
 
-- **There is no feature switch**: the plugin intervenes exactly when content is configured — a non-empty `rootChain`, at least one `timeSlots` row, or one declared role. An empty section is a complete no-op, and the Plugins-page row toggle is the master switch.
-- **The all-day `rootChain` tail must be exactly one official model** — `deepseek-official/deepseek-flash` **or** `deepseek-official/deepseek-v4-pro` (XOR); the leading entries are the fallback walk, walked first.
-- **Slots and roles are optional**: the first time-slot row whose window matches replaces the all-day chain for the next root request; rules map subagents to declared roles and never match root requests.
+- **There is no feature switch**: the plugin intervenes exactly when a chain is configured (`chains` non-empty). An empty section is a complete no-op, and the Plugins-page row toggle is the master switch.
+- **A chain's LAST entry (默认模型) must be exactly one official model** — `deepseek-official/deepseek-flash` **or** `deepseek-official/deepseek-v4-pro` (XOR); the leading 默认降级链 entries are walked first.
+- **Slots and roles are optional**: each chain's first matching time-slot row replaces that chain's entries; a role's `chain` pointer (or nothing) decides which chain a dispatched child mounts.
 
 Full reference (keys, entry syntax, selector rules, migration) → [docs/configuration.md](docs/configuration.md).
 
@@ -120,12 +124,12 @@ Save the config and restart the session, then type `/fallbacks` — the read-onl
 
 ## Feature highlights
 
-- **Automatic failover** for root and subagents — any agent walks its chain on a listed failure code and the step continues. → [details](docs/features.md#automatic-model-failover)
+- **Automatic failover** on a virtual route — a `FallbacksChain / <id>` session (root or role-stamped subagent) walks its chain on a listed failure code and the step continues; real-model sessions have no plugin fallback. → [details](docs/features.md#automatic-model-failover)
 - **Context-window-aware fallback** — `CONTEXT_WINDOW_EXCEEDED` fails over to a larger-context candidate; the switch is request-scoped (no cooldown). → [details](docs/features.md#context-window-aware-fallback)
-- **Peak/valley time slots** — four frozen UTC+8 presets or custom windows rotate the effective root chain. → [details](docs/features.md#time-slots)
-- **Role-based subagents** — a dispatch-declared role brings persona, notice row and badge to the child; its chain head is injected subject to host policy. → [details](docs/features.md#role-based-subagents)
-- **FallbacksChain in the picker** — select `FallbacksChain / Auto` to make the chain the root primary; any real model stays fallback-only. → [details](docs/features.md#fallbackschain-in-the-model-picker)
-- **Host subagent model policy** — the dsh 0.1.2 allowlist is a hard constraint on every plugin-originated subagent route. → [details](docs/features.md#host-subagent-model-selection-policy-dsh-012)
+- **Peak/valley time slots** — four frozen UTC+8 presets or custom windows rotate a chain's own effective entries. → [details](docs/features.md#time-slots)
+- **Role-based subagents** — a dispatch-declared role brings persona, notice row and badge to the child, and its optional `chain` pointer puts the child on `FallbacksChain/<id>`. → [details](docs/features.md#role-based-subagents)
+- **FallbacksChain in the picker** — select `FallbacksChain / <chain id>` to make the configured chain the session route; any real model is served by llm-retry alone, with no plugin fallback. → [details](docs/features.md#fallbackschain-in-the-model-picker)
+- **Host subagent model policy** — dsh enforces its 0.1.2 child-model allowlist on the dispatching side; this plugin does not consult it. An explicit child selection is limited to the parent route unless the host allowlist admits it. → [details](docs/features.md#role-based-subagents)
 - **Five bundled preset roles** — `reviewer` / `scout` / `security-reviewer` / `sonic` / `task`, declared on apply. → [details](docs/features.md#preset-roles)
 - **dsh-tui surfaces** — `/fallbacks`, `/fallbacks config`, and a `/settings` section with web-card parity. → [details](docs/features.md#dsh-tui-surfaces)
 
@@ -139,7 +143,7 @@ The plugin installs as a **pure mount**: bundle insert + client inject + its own
 |---|---|
 | [docs/install.md](docs/install.md) | desktop/web plugin page / profile install (web + dsh-tui) / registry / git / local variants / uninstall / `--dump-config` verification |
 | [docs/configuration.md](docs/configuration.md) | full `fallbacks` namespace reference, selector syntax, example YAML, plugin-config card usage, TUI readback, behavior notes, preset roles |
-| [docs/features.md](docs/features.md) | capability reference: failover, context-window fallback, time slots, role-based subagents, picker, host policy, preset roles, agent presets, dsh-tui |
+| [docs/features.md](docs/features.md) | capability reference: failover, context-window fallback, time slots, role-based subagents, picker, preset roles, agent presets, dsh-tui |
 | [docs/repair.md](docs/repair.md) | session-log repair: refusal classes, `--apply` publishing, flags, exit codes, lossy `--drop-legacy-events` |
 | [docs/consumer-api.md](docs/consumer-api.md) | developer consumption contract: library API + named `llm-fallbacks` service + role seeds, export inventory, lifecycle, typing |
 | [docs/release.md](docs/release.md) | release process: Trusted Publishing setup, Release prep SOP, fragment format, rollback |

package/README.zh-CN.md

@@ -1,3 +1,5 @@
+![preview](https://raw.githubusercontent.com/omdsh-dev/dsh-llm-fallbacks/main/docs/preview.zh.png)
+
 # dsh-llm-fallbacks
 
 [English](README.md) | [中文](README.zh-CN.md)
@@ -7,10 +9,10 @@
 ![node](https://img.shields.io/badge/node-%3E%3D22-339933.svg)
 ![pnpm](https://img.shields.io/badge/pnpm-%3E%3D10-f69220.svg)
 ![dsh tui](https://img.shields.io/badge/dsh%20tui-compatible-4B32C3.svg)
-![dsh](https://img.shields.io/badge/DSH-0.2.1--rc.4-4B32C3.svg)
+![dsh](https://img.shields.io/badge/DSH-0.2.2--rc.1-4B32C3.svg)
 [![dshfind](https://dshfind.com/api/badge/omdsh-dev/dsh-llm-fallbacks?lang=zh)](https://dshfind.com/zh/plugins/omdsh-dev/dsh-llm-fallbacks?ref=badge)
 
-dsh（DeepSeek Harness）的自动模型降级插件：当 agent 的模型请求持续失败（重试耗尽、权限错误、配额超限、限流 429）时，插件按当前角色的 fallback 链切换 provider/model，当前 step/turn 在目标模型上继续——任务不会因模型问题中断。
+dsh（DeepSeek Harness）的自动模型降级插件：插件注册 N 条**命名虚拟链**，每条在模型选择器中都是一行 **`FallbacksChain / <链 id>`**——选择某条链的会话沿该链行走，llm 请求在列出的失败码上持续失败（权限错误、配额超限、限流 429 等）时，请求会在下一个可用 provider/model 上重试，任务不会因模型问题中断。选择**真实** provider/model 的会话**没有插件降级**，只由 `llm-retry` 处理。在 Fallbacks 设置卡中创建链，然后选择它的 `FallbacksChain / <id>` 行即可。
 
 两个 dsh 前端均可用：**web** profile（设置 → 插件配置 → Fallbacks 卡片）与 **dsh-tui** 终端 profile（`/fallbacks` 会话诊断、`/fallbacks config` 回读、`/settings` 的 fallbacks 分区用于编辑）。
 
@@ -18,12 +20,14 @@ dsh（DeepSeek Harness）的自动模型降级插件：当 agent 的模型请求
 
 ### 自动模型降级
 
-root 或 subagent，只要持续命中触发码，就沿自身链切到下一个可用 provider/model，step 继续运行。无需手动切换模型；在配置了内容之前，插件不做任何事。
+会话模型选择走 `FallbacksChain / <链 id>` 时——root agent 选中该行，或子代理的角色以「指定降级链」指向该链——沿该链行走：请求在**输出任何内容之前**命中触发码，就在同一个请求内改到下一个可用 provider/model，step 继续运行。选择真实 provider/model 的会话不获得任何插件降级。无需手动切换模型；在配置链之前（`chains` 为空是唯一初始状态）插件不做任何事。
 
-- **触发**：`triggerCodes`（默认 `AUTH` / `QUOTA` / `RATE_LIMIT`）——**任何** dsh 失败码都可用，包括 `CONTEXT_WINDOW_EXCEEDED`（会降级到上下文窗口更大的候选）。可重试失败（5xx、`TRANSPORT`、`TIMEOUT` 等）先交给 llm-retry。
+- **谁能拿到链**：只有模型选择走 `FallbacksChain / <链 id>` 的会话。包括选中该行的 root agent，以及角色「指定降级链」指向该链、分发时被盖章到该行的 subagent（本地 backend、请求上没有显式路由）。真实 provider/model 选择——无论 root 还是 subagent——完全交给 llm-retry。
+- **触发**：`triggerCodes`（默认 `AUTH` / `QUOTA` / `RATE_LIMIT`）——**任何** dsh 失败码都可用，包括 `CONTEXT_WINDOW_EXCEEDED`（会降级到上下文窗口更大的候选）。可重试失败（5xx、`TRANSPORT`、`TIMEOUT` 等）先交给 llm-retry；它的每次重试都会重新进入 walk，并从刚进入冷却的链头之后开始。
+- **已输出即提交**：某个尝试一旦吐出 chunk，之后的失败**不会**在该请求内切换——已产出的输出无法撤回。失败上抛给 loop；恢复路径是 llm-retry 重入（新的一次 walk）或终止失败。
 - **恢复**：失败或被切走的模型在 `cooldownMs` 内不再被选中，`revertPolicy: cooldown-expiry` 在冷却到期后回到主模型；可选的 `recovery: half-open` 模式（YAML-only）把这次回归改为证据驱动，而非定时器驱动。
-- **保险丝**：`maxSwitchesPerStep` 限制单 step 的切换次数，`alwaysModeRetryCap` 限制 always 模式的重试次数——链式循环不会放大延迟。
-- **可见性**：每次切换都写入 info 日志（from/to/role/reason），不存在静默切换。
+- **保险丝**：`maxSwitchesPerStep` 限制单次请求 walk 的切换次数（尝试数 ≤ 上限 + 1）——链式循环不会放大延迟。
+- **可见性**：每次切换都写入 info 日志（from/to/role/reason/candidates），不存在静默切换。
 
 → [自动模型降级](docs/features.md#automatic-model-failover) · [上下文窗口降级](docs/features.md#context-window-aware-fallback)
 
@@ -50,7 +54,7 @@ GLM Peak / GLM Valley 仅在配置了 `zai-coding-cn` 时才会出现在卡片
 
 subagent 的角色由分发提示词声明——Assignment 头部字段 `**Execute as**: <id>`；它与 `roles.list` 中已声明的角色 id 匹配。只有这个**已声明头部**才投递子代理的身份：`persona` 以 system-prompt 分区安装到子代理，子会话恰好写入一行 `[role: <id>]` 通知行，会话头部显示角色徽章。
 
-角色**路由**是另一套解析，按四个有序阶段、先命中者生效——显式 `agentPreset` → **派发声明** `**Execute as**: <id>` 头部 → 规则 → LLM 自动匹配。只要子代理的分发提示词声明了 `**Execute as**: <id>`，该角色的 persona、`[role: <id>]` 通知行与徽章就会投递，**无论哪个路由阶段胜出**——更早的显式 `agentPreset` 可以把子代理路由成另一个角色，而身份载体仍属已声明头部。完全没有声明分发头部的子代理不会获得 persona、通知行与徽章，即使规则或自动匹配为路由解析出了角色。把解析到的角色链头作为子代理模型由插件发起、且带条件：宿主 `subagent-model-selection` 策略启用时，显式授权路由会被保留（跳过注入），注入的链头必须落在生效 allowlist 内——交集为空则不注入任何内容（[宿主策略](docs/features.md#host-subagent-model-selection-policy-dsh-012)）。
+角色**身份**在分发时按两个有序阶段解析、先命中者生效——显式 `agentPreset` → **派发声明** `**Execute as**: <id>` 头部。只要子代理的分发提示词声明了 `**Execute as**: <id>`，该角色的 persona、`[role: <id>]` 通知行与徽章就会投递。完全没有声明分发头部的子代理是**未指定**：没有 persona、通知行与徽章角色半边——插件也不干预。角色还可携带**手动链指针**（「指定降级链」）：分发时 seam 把本地、无显式路由的子代理盖到 `FallbacksChain / <role.chain>` 上——带显式路由的请求属于**已授权**，插件永不改写；外部 backend 的子代理保持纯继承。没有规则匹配，也没有宿主策略咨询：映射就是你的静态配置。
 
 这一套同时覆盖**普通 subagent 分发与 Agent Team 队友**（`spawn_teammate`）：两者都是带着同一头部（由模型写入）经同一分发 seam 创建的子代理，不需要任何按机制区分的配置。
 
@@ -85,29 +89,29 @@ dsh plugin --profile dsh-tui add dsh-llm-fallbacks  # dsh-tui 终端 profile
 
 ```yaml
 fallbacks:
-  rootChain:               # 全时段链：前置项 = 降级链，末项 = 默认模型（官方模型）
-    - anthropic/claude-3-5-sonnet
-    - deepseek-official/deepseek-flash
-  timeSlots:               # 可选：按墙钟窗口轮换生效 root 链
-    - kind: preset
-      preset: liang-peak
-      chain:
+  chains:                  # 命名虚拟链：每条 = picker 一行（FallbacksChain/<id>）
+    - id: Auto             # picker 模型 id（大小写敏感、唯一）
+      label: 默认链         # tab 标题 + picker 前缀（仅展示）
+      entries:             # 默认降级链 …末尾是默认模型（恰好一个官方模型）
         - anthropic/claude-3-5-sonnet
-  roles:                   # 可选：先声明角色实体，再由规则引用
+        - deepseek-official/deepseek-v4-pro
+      timeSlots: []        # 可选：该链自己的分时行
+    - id: Coding
+      label: 编码
+      entries:
+        - openai/gpt-4o-mini
+        - deepseek-official/deepseek-flash
+  roles:                   # 可选：角色身份 + 可选链指针
     list:
       - id: reviewer
         persona: Code-review subagents
-        chain:
-          - openai/gpt-4o-mini
-        fallback: inherit-root
-    rules:                 # 仅 subagent：规则永不匹配 root 请求
-      - role: reviewer
+        chain: Coding      # 指定降级链：该角色派发的子代理挂到 FallbacksChain/Coding
 ```
 
 三条要点：
 
-- **没有功能开关**：只要配置了内容——非空 `rootChain`、至少一行 `timeSlots`、或一个已声明角色——插件才介入；空配置是完全的 no-op，Plugins 页的行开关是总开关。
-- **全时段 `rootChain` 的末项必须恰好是一个官方模型**——`deepseek-official/deepseek-flash` **或** `deepseek-official/deepseek-v4-pro`（XOR）；前置项是降级链，优先进走。
+- **没有功能开关**：只要配置了链（`chains` 非空）插件才介入；空配置是完全的 no-op，Plugins 页的行开关是总开关。
+- **每条链的末项（默认模型）必须恰好是一个官方模型**——`deepseek-official/deepseek-flash` **或** `deepseek-official/deepseek-v4-pro`（XOR）；前部「默认降级链」条目优先进走。
 - **分时槽与角色都是可选的**：第一个窗口命中的分时行会在下一个 root 请求取代全时段链；规则把 subagent 映射到已声明角色，且永不匹配 root 请求。
 
 完整参考（字段、条目语法、选择器规则、迁移）→ [docs/configuration.md](docs/configuration.md)。
@@ -120,12 +124,12 @@ fallbacks:
 
 ## 能力一览
 
-- **自动降级**（root 与 subagent 通用）——命中触发码的 agent 沿链切换，step 继续运行。 → [详情](docs/features.md#automatic-model-failover)
+- **自动降级**（仅虚拟路由）——`FallbacksChain / <id>` 会话（root 或角色盖章的 subagent）命中触发码时沿链切换，step 继续运行；真实模型会话没有插件降级。 → [详情](docs/features.md#automatic-model-failover)
 - **上下文窗口感知降级**——`CONTEXT_WINDOW_EXCEEDED` 会切到窗口更大的候选；该切换是请求级的（不消耗冷却）。 → [详情](docs/features.md#context-window-aware-fallback)
-- **峰谷无忧（分时槽）**——四个冻结的 UTC+8 预设或自定义窗口轮换生效 root 链。 → [详情](docs/features.md#time-slots)
-- **角色化 subagent**——派发声明的角色为子代理带来 persona、通知行与徽章；链头注入受宿主策略约束。 → [详情](docs/features.md#role-based-subagents)
-- **模型选择器中的 FallbacksChain**——选择 `FallbacksChain / Auto` 即把配置链作为 root 主模型；选择真实模型仍是仅降级。 → [详情](docs/features.md#fallbackschain-in-the-model-picker)
-- **宿主子代理模型策略**——dsh 0.1.2 的 allowlist 是插件发起的所有 subagent 路由的硬约束。 → [详情](docs/features.md#host-subagent-model-selection-policy-dsh-012)
+- **峰谷无忧（分时槽）**——四个冻结的 UTC+8 预设或自定义窗口轮换该链自己的生效条目。 → [详情](docs/features.md#time-slots)
+- **角色化 subagent**——派发声明的角色为子代理带来 persona、通知行与徽章，其可选的 `chain` 指针把子代理挂到 `FallbacksChain/<id>`。 → [详情](docs/features.md#role-based-subagents)
+- **模型选择器中的 FallbacksChain**——选择 `FallbacksChain / <链 id>` 即由配置链承载该会话；选择真实模型则只由 llm-retry 处理，没有插件降级。 → [详情](docs/features.md#fallbackschain-in-the-model-picker)
+- **宿主子代理模型策略**——dsh 在**派发侧**执行自己的 0.1.2 子模型 allowlist；本插件不读取它。显式子代理选择只允许父路由，除非该路由在宿主 allowlist 内。 → [详情](docs/features.md#role-based-subagents)
 - **五个内置预设角色**——`reviewer` / `scout` / `security-reviewer` / `sonic` / `task`，随 apply 自动声明。 → [详情](docs/features.md#preset-roles)
 - **dsh-tui 操作面**——`/fallbacks`、`/fallbacks config`，以及与 web 卡片等价的 `/settings` 分区。 → [详情](docs/features.md#dsh-tui-surfaces)
 
@@ -139,7 +143,7 @@ fallbacks:
 |---|---|
 | [docs/install.md](docs/install.md) | 桌面/Web 插件页 / profile 安装（web + dsh-tui）/ registry / git / 本地目录 / 卸载 / `--dump-config` 校验 |
 | [docs/configuration.md](docs/configuration.md) | `fallbacks` 命名空间完整参考、选择器语法、示例 YAML、插件配置卡片用法、TUI 回读、行为说明、预设角色 |
-| [docs/features.md](docs/features.md) | 能力参考：降级、上下文窗口降级、分时槽、角色化 subagent、选择器、宿主策略、预设角色、agent 预设、dsh-tui |
+| [docs/features.md](docs/features.md) | 能力参考：降级、上下文窗口降级、分时槽、角色化 subagent、选择器、预设角色、agent 预设、dsh-tui |
 | [docs/repair.md](docs/repair.md) | 会话日志修复：拒载类别、`--apply` 发布、参数、退出码、有损 `--drop-legacy-events` |
 | [docs/consumer-api.md](docs/consumer-api.md) | 开发者消费契约：库 API + 具名 `llm-fallbacks` 服务 + 角色种子、导出清单、生命周期、类型 |
 | [docs/release.md](docs/release.md) | 发布流程：Trusted Publishing 配置、Release prep SOP、fragment 格式、回滚 |

package/dist/chain-walk.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The chain walk (design dsh-022-rc1-upgrade §2/§3/§6.1): the fallback
+ * decision, executed inside the virtual `FallbacksChain/Auto` adapter's
+ * `stream()` instead of on the `agent/request` / `agent/request-error`
+ * waterfalls.
+ *
+ * One walk per `stream()` call: resolve the selected named chain and its
+ * slot-effective tail, then attempt the chain's heads in order. Root and
+ * subagent walks are the SAME shape — every walk is the selected chain. A
+ * pre-output terminal `finish` whose failure code is a trigger code is
+ * swallowed, booked (cooldown / recovery) and the walk advances; anything
+ * else — a normal finish, an aborted finish, a non-trigger failure, or any
+ * failure after the attempt already yielded output — is forwarded verbatim
+ * and ends the walk. A `usage` chunk is metadata, so it neither commits the
+ * attempt nor stops the advance.
+ *
+ * A pre-output parameter rejection (`UNSUPPORTED_REASONING_EFFORT`, or a
+ * `max_tokens`-shaped `INVALID_REQUEST`) is repaired first: the SAME candidate
+ * is retried once with the offending control dropped, because a route that
+ * discloses no capability only reveals its real cap through that rejection.
+ *
+ * The COMMITTED rule (§3.1 / §7.5) is why a post-output failure cannot be
+ * replayed: yielded chunks cannot be unsent, so a second provider's output
+ * cannot be concatenated behind a partial one. Such a failure is still BOOKED
+ * (cooldown / recovery) before it is forwarded — the attempt boundary is where
+ * both transactions happen — and then surfaces to the loop, which settles the
+ * partial attempt; llm-retry (or the terminal error) takes over from there, and
+ * a retry re-enters this walk, which resumes past the cooled head on its own.
+ *
+ * Bookkeeping survives a walk exactly as far as the state store does: cooldown
+ * (`cooldownMs` / `revertPolicy` / half-open escalation) is the cross-call
+ * memory keyed by session, so an llm-retry re-entry starts past a failed head;
+ * the per-call failed set and the switch cap live only for this walk
+ * (`maxSwitchesPerStep` = switches per walk, attempts ≤ cap + 1).
+ *
+ * The pre-attempt guards (`UNKNOWN_CHAIN` / `EMPTY_EFFECTIVE_CHAIN` /
+ * `UNDISPATCHABLE_EFFECTIVE_HEAD` / `LLM_UNAVAILABLE`) are owned here, and
+ * `slotWinners` carries the per-(agent, chain) 分时切换 rotation log.
+ *
+ * @module dsh-llm-fallbacks/chain-walk
+ */
+import { type GenerateOptions, type LlmRuntime, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import { type FailingModel } from './chains.ts';
+import type { FallbacksConfig } from './config.ts';
+import type { FallbackStateStore } from './state.ts';
+/**
+ * `LlmError` code: the effective chain is empty — the selected named chain has
+ * no entries to walk (the pre-attempt guard; the walk is the only point that
+ * knows WHICH chain the session selected, `options.model` being the chain id).
+ */
+export declare const EMPTY_EFFECTIVE_CHAIN_CODE = "EMPTY_EFFECTIVE_CHAIN";
+/**
+ * `LlmError` code: the chain cannot be walked — its entries tail is not
+ * conforming (the last entry must be exactly one official model), or no entry
+ * is a dispatchable real pair (wildcard selector, malformed selector, or a
+ * self-route back to `FallbacksChain/*` — the recursion guard).
+ */
+export declare const UNDISPATCHABLE_HEAD_CODE = "UNDISPATCHABLE_EFFECTIVE_HEAD";
+/**
+ * `LlmError` code: `options.model` names no declared chain — reachable only
+ * once a chain the session selected is deleted or renamed (the migrated
+ * default id `Auto` is unchanged, so an upgrade alone never hits this).
+ * Thrown synchronously before any chunk; the host surfaces a terminal error
+ * finish and the user re-selects in the picker. No silent fallback to
+ * another chain — picking the wrong named chain silently would be a
+ * data-routing surprise.
+ */
+export declare const UNKNOWN_CHAIN_CODE = "UNKNOWN_CHAIN";
+/** `LlmError` code (defensive): the `llm` runtime disappeared mid-flight. */
+export declare const LLM_UNAVAILABLE_CODE = "LLM_UNAVAILABLE";
+/**
+ * dsh core's canonical failure code for a request larger than the model's
+ * context window (`@deepseek-ai/dsh-llm` `CONTEXT_WINDOW_EXCEEDED_CODE`; the
+ * DeepSeek adapter's `httpErrorCode()` and llm-pi-ai's `mapStopReason()` both
+ * map the provider 400 "maximum context length" to it). Declared as a literal
+ * for the same reason `triggerCodes` is `string[]` — the plugin compares dsh
+ * failure codes as plain strings and never imports a peer value.
+ *
+ * It is NOT in llm-retry's retryable set, so the plugin sees it only when the
+ * operator lists it in `triggerCodes` — and once listed, this walk handles the
+ * rejection BEFORE the harness's compaction plugin compacts anything
+ * (measured 2026-09-09: the first overflow switches to the fallback, no
+ * compaction happens). Operators who want compaction tried first leave the
+ * code out of `triggerCodes`.
+ *
+ * A `CONTEXT_WINDOW_EXCEEDED` switch is REQUEST-scoped
+ * ({@link REQUEST_SCOPED_CODES}): the route is healthy and the request was too
+ * big, so the per-call failed key is recorded but no cooldown and no recovery
+ * counter are written.
+ */
+export declare const CONTEXT_WINDOW_EXCEEDED_CODE = "CONTEXT_WINDOW_EXCEEDED";
+/**
+ * Failure codes whose switch is REQUEST-scoped: the route is healthy and the
+ * request was the problem, so a switch records the per-call failed key but
+ * writes no cooldown and no recovery counter. Cooling the route down would
+ * send the next SHORT prompt to the fallback for no reason.
+ */
+export declare const REQUEST_SCOPED_CODES: ReadonlySet<string>;
+/**
+ * The exact-route capabilities a walk reads from `resolveModelInfo`: the
+ * context window (wildcard / overflow expansions) plus the two request
+ * controls parameter adaptation compares against. Every field is optional — a
+ * host that discloses nothing leaves every request untouched.
+ */
+interface ModelInfoLike {
+    context?: {
+        contextWindow?: number;
+    };
+    defaultMaxTokens?: number;
+    reasoning?: {
+        efforts: readonly {
+            id: string;
+            name: string;
+        }[];
+    };
+}
+/**
+ * Model-catalog view the wildcard / context-window probes read. `contextWindow`
+ * is a host-disclosed extra on the advisory catalog row (the dsh `LlmModelInfo`
+ * does not type it), while `resolveModelInfo` is where the host actually
+ * carries it — both are optional and read structurally, so a host offering
+ * neither reports every window as unknown (never a skip).
+ */
+export interface ModelCatalogLike {
+    listModels(provider: string): Promise<readonly {
+        id: string;
+        contextWindow?: number;
+    }[]>;
+    resolveModelInfo?(provider: string, model: string): Promise<ModelInfoLike>;
+}
+/**
+ * The `provider/*`-entry existence probe: the target provider's advertised
+ * catalog, fetched once per expansion and cached per provider. A
+ * missing/unknown provider or a failing catalog reads as "no such model", so
+ * wildcard candidates to it are skipped; without a catalog no filtering
+ * happens (`() => true`).
+ *
+ * simplify: catalog fetched per expansion, never cached across walks. Walks
+ * are failure-driven and rare; cache per provider in the plugin if they ever
+ * become hot.
+ */
+export declare function makeModelExists(catalog: ModelCatalogLike | undefined, providers: readonly string[]): Promise<(provider: string, model: string) => boolean>;
+/**
+ * The context-window lookup for a `CONTEXT_WINDOW_EXCEEDED` expansion: a
+ * `provider/model → contextWindow` map over the failing route plus every
+ * resolved candidate route, fetched once per expansion (the
+ * {@link makeModelExists} pattern — failure-driven and rare, never cached).
+ *
+ * Two sources, cheapest first: the advertised catalog row when it discloses a
+ * window (one `listModels` per distinct provider), then — for routes still
+ * unknown — the exact-route `resolveModelInfo` metadata, which is where the
+ * dsh host puts `context.contextWindow`. A missing catalog, a throwing probe,
+ * or a route that discloses nothing all read as UNKNOWN (`undefined`), and
+ * unknown always KEEPS the candidate: an undisclosed window must never empty a
+ * chain.
+ */
+export declare function makeContextWindowOf(catalog: ModelCatalogLike | undefined, routes: readonly FailingModel[]): Promise<(provider: string, model: string) => number | undefined>;
+/**
+ * Key of one (agent, chain) 分时切换 marker. Both the walk's write and the
+ * wiring's `agent/disposed` cleanup build keys through here, so the two halves
+ * of the contract cannot drift apart.
+ */
+export declare function slotMarkerKey(agentId: string, chainId: string): string;
+/** Key prefix covering every chain marker of one agent (the cleanup sweep). */
+export declare function slotMarkerPrefix(agentId: string): string;
+/** Everything one walk reads from the plugin wiring. */
+export interface ChainWalkDeps {
+    readConfig(): FallbacksConfig;
+    getLlm(): LlmRuntime | undefined;
+    states: FallbackStateStore;
+    /**
+     * Per-(agent, chain id) last time-slot winner (P7 分时切换 marker): the
+     * caller owns the map (re-baselined on a settings change, cleared on
+     * dispose), the walk reads and writes it — the log only, never a failure
+     * decision. Absent ⇒ no log.
+     */
+    slotWinners?: Map<string, {
+        key: string;
+        label: string;
+    }>;
+    log: {
+        info(message: string, ...args: unknown[]): void;
+        warn(message: string, ...args: unknown[]): void;
+        /** Optional: the request-rewriting lines (parameter adaptation) are diagnostics only. */
+        debug?(message: string, ...args: unknown[]): void;
+    };
+}
+/**
+ * Walk one virtual call's chain (design §6.1): an async iterable of the
+ * attempts' chunks, ending in exactly one terminal `finish`.
+ *
+ * Throws only for the pre-attempt conditions (empty chain, undispatchable
+ * head, vanished runtime) — every per-attempt failure is either swallowed into
+ * another attempt or forwarded as that attempt's own terminal `finish`.
+ */
+export declare function walkChain(deps: ChainWalkDeps, options: GenerateOptions): AsyncIterable<StreamChunk>;
+export {};