dsh-connect-workbuddy 4.6.7 → 4.8.0

package/CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## 4.8.0 (2026-10-18)
+
+> 版本号是 **minor**：这不是只改内部的 patch —— 它**会改动会话历史**。跨区/跨窗口切换后原本必然卡死的那一类会话，本版能把上下文折回去继续用。没有溢出时行为完全不变。
+
+### Fixes
+
+- **切到窗口更小的路由后，会话永久卡在 `400 code 11115 prompt is too long`（#59 后半）**
+  - **症状**：会话在一个 1M 窗口的模型上跑得很长，切成国际区（`workbuddy-global`，窗口 1,048,576）后，**每一条**请求都返回 `prompt is too long: 1374460 tokens > 1048576 maximum`。换回原区域能用，再切过去还是卡死；手动压缩同样 400。会话实质报废。
+  - **根因（宿主侧，两处叠加）**：
+    1. **压力阈值按「当前模型」窗口现算**，`compaction-basic/src/config.ts:188-192` 的 `thresholdTokens = min(contextWindow × thresholdRatio, messageBudgetTokens)`。1M 窗口下阈值是 800,000，而 707,801 未到 —— 会话在**切区那一刻就已经超了新模型的窗口**，可自动压缩的触发点还在旧模型的尺度上，永远等不到。
+    2. **溢出兜底把整段历史塞进一次摘要请求**，`compaction-basic/src/index.ts:299` 的 `selectCompactableRange(session, measurement, 0)` 保留量为 0 → `region.ts:150-154` 选出「除最后一条外的全部历史」；`summarizer.ts:141-151` 又把这份摘要发给**当前那条小窗口路由**。于是救援请求和它要救援的请求一样溢出 —— 死锁。
+    宿主侧已按 deepseek-ai/deepseek-harness#9814 提交，上面两处即该 issue 的 A、B 两点。
+  - **本版做的事**：适配器在溢出错误**仍然持有 session id** 的那一刻接手，用宿主**自己的**压缩事务（`ctx.compaction.compactRegion`）把历史折回去，而不是另发一次摘要请求。
+    - 分块上限 = 模型窗口的 **35%**，因此摘要请求本身**按构造**一定装得下（宿主默认那一次是 131%）。
+    - 折叠目标是窗口的 **60%**，逐块折叠直到低于目标；块边界来自宿主自己的 `tokenMeter`。
+    - **绝不折掉当前请求携带的那条消息**（`nodes.at(-1)` 永远保留）。
+    - 宿主拒绝某个区间（切断了 tool call 与 result 的配对、或正有压缩在跑）时，把尾边向内收一格重试；仍是拒绝就放弃，绝不空转。
+    - 折完仍降不下去（单条消息本身就超过窗口）时立刻停手 —— 这是结构性问题，重试只会烧掉重试预算。
+  - **实测（真实 GL 400 载荷）**：`isContextOverflow` 对 `prompt is too long: 1374460 tokens > 1048576 maximum` 与 `{"code":11115,...,"type":"CONTEXT_WINDOW_EXCEEDED"}` 均判定为真，对 `rate limit exceeded` 判定为假 —— 只在真溢出时动手。
+  - **降级路径**：宿主没装压缩包（`compaction` 服务不存在）、或请求没带 `sessionId`（非主循环调用）时，适配器原样返回，行为与本版之前**逐字节相同**。
+
+### 已知未修
+
+- **跨区 prompt token 计数漂移**（#59 前半）：同一份 3.6 MB 请求体，CN 计 642,800、GL 计 447,306。这不是网关数错 —— 历史里的 thinking 块按上游当初实际返回的字段名（`reasoning` / `reasoning_content`）原样回放（宿主 `pi-ai` 0.85.1 `openai-completions.js:428` → `:1006`），同一批字节因此落进不同计费桶。归属宿主，本插件没有改写历史的权限，详见 #59 与 `src/body-report.ts` 头部说明。
+
+## 4.7.0 (2026-10-17)
+
+> 版本号是 **minor**：这不是只改内部的 patch —— 它**改变了发往上游的请求体**。DSH Desktop 0.2.1-rc.1 随包 pi-ai 1.1.0，本版修的是该组合下「请求静默丢掉 system prompt 与全部工具声明」。若你停留在更早的宿主，行为不变。
+
+### Fixes
+
+- **DSH 0.2.1-rc.1 下所有 workbuddy 模型静默丢失 system prompt 与工具声明（新一轮 #24/#25/#26 同族缺陷）**
+  - **症状**：升级到 DSH `0.2.1-rc.1`（随包 `@earendil-works/pi-ai@1.1.0`）后，workbuddy / workbuddy-global 的模型**全部**不再调用工具，界面上**没有任何报错**。模型有时把 DSML 标记当正文吐出来——和 4.4.2 记录的现象一模一样。
+  - **根因（三环叠加，缺一不成立）**：
+    1. `dsh-llm-pi-ai` **两版都不做归一化**。0.1.7 与 0.2.1 的 `piContext()` 都直接返回 `{systemPrompt, messages, tools}`，两版里 `normalizeContext` 出现次数均为 **0**。
+    2. pi-ai **0.85.1 读顶层字段**：`dist/api/openai-completions.js:909` 的 `if (context.systemPrompt)`，工具读 `context.tools`。所以 0.85 能自己兜底，宿主不归一化也看不出问题。
+    3. pi-ai **1.1.0 只读 `messages`**：走 `resolveTranscript()` → `collapseSystemMessages()`，顶层 `systemPrompt` / `tools` **从不读取**。
+    于是 `withLegacyContext()` 的 **modern 分支原样透传**（当时一行 `return api`），把 0.85 形状的原始信封直接交给 1.1.0 的 api → 请求体里 system prompt 与 tools 双双为空。
+  - **为什么 4.4.2 的修复不够**：4.4.2 修的是「1.x 被判成 legacy → 折成 0.85 形状 → 工具丢」。本版是**同一失效模式的反面**——「1.x 判成 modern（判定是对的）→ 不折 → 工具和 prompt 一起丢」。门是对的，空的是那个分支。`generationOf()` 无需改动。
+  - **实测证据（真实 `createProvider` + 真实 `openAICompletionsApi` + 本地 SSE 服务器抓线上 body）**：
+
+    | pi-ai | 线上 `messages[].role` | system 文本 | `body.tools` |
+    |---|---|---|---|
+    | 0.85.1 | `["system","user"]` | 原样 | 1 ✅ |
+    | **1.1.0（修复前）** | **`["user"]`** | **丢失** | **0** |
+    | 1.1.0（修复后） | `["system","user"]` | 原样 | 1 ✅ |
+    | 1.1.0（已归一化输入） | `["system","user"]` | 原样 | 1 ✅（幂等） |
+
+  - **改了什么**：新增 `foldModernContext()`，modern 分支改为**归一化**而非透传——把顶层的 `systemPrompt`/`tools` 折进首条 `system` 消息（文本进 `content`、工具进 `toolsAdded`），并**删掉**这两个顶层字段，与 pi-ai 官方 `normalizeContext` 的输出形状一致。
+  - **为什么内联而不是调 `normalizeContext`**：该函数在 **0.85.1 里不存在**，静态 import 会在那里变成 `undefined`；而本模块一贯「绝不静态 import pi-ai」（`pi-ai-runtime.ts` 头部教条，正是它让独立 `bin` 能在没装 peer 的 profile 里跑）。内联折叠零新依赖。
+  - **幂等**：输入若已归一化（顶层两字段都不存在），直接原样返回——否则会再前置一条**空的** system 消息。
+  - **★ 守卫为什么一直没抓到**：`tests/adapter-outgoing-body.spec.ts` 是唯一断言「线上 body 真的带 tools 与 system」的用例，却被 `it.skipIf(piAiRuntimeInfo().generation !== 'legacy')` 限死，**modern 分支零覆盖**；而作者 checkout 解析到 0.85.1，它一直是绿的。`adapter.spec.ts` 也帮不上忙——它 mock 了 api，只断言「交给 wrapper 的 context」，这个断言恰好**认证**了缺陷。
+  - **本版把守卫扩成 2×2 矩阵**：{legacy, modern} × {原始信封, 已归一化 transcript} 四格都断言 `body.tools` 与首条 system 文本。在原用例的基础上补了「modern × 原始信封」这一格——**它就是本缺陷的回归钉**。另加幂等用例与「只有 tools、没有 systemPrompt」用例。
+  - **本机与 CI 的代际约束（写在用例注释里）**：legacy 两格只能在 0.85 checkout 上跑（1.x 的 api 读不了 0.85 扁平形状）；modern 两格只能在 0.87+/1.x 上跑（0.85 的 `estimateMessageTokens` 会对 system 消息的**字符串**逐字符迭代并读 `block.name.length` 而崩溃，即 #24 的崩溃）。用例按**已安装版本**选格，不会让任何一代完全无人看管。
+  - **变异验证**：把 modern 分支改回 `return api` → 新增的「FOLDS a raw seam envelope」用例**红**（1 例）。验证后已还原。
+  - **实机验证**：临时把 checkout 的 `node_modules/@earendil-works/pi-ai` 换成 1.1.0（连同 1.1.0 新需要的 `typebox`/`partial-json`/`openai`），modern 四格**全绿**；legacy 两格如预期红（1.1.0 读不了扁平形状）。验证后已完整还原 0.85.1 与依赖树。
+
+- **「可关闭思考」的模型被锁成不可关闭，不可关闭的反倒可关（`adapter.ts` 既有缺陷，非本次升级引入）**
+  - **根因**：`workBuddyThinkingLevelMap()` 的判断写反了 —— `if (canDisableThinking !== true) map.off = null`，而 `null` 在 pi-ai 里的语义是「该档位**不支持**」（`getSupportedThinkingLevels` 按 `mapped === null` 过滤；`openai-completions` 用 `thinkingLevelMap?.off !== null` 决定能否发「关闭思考」的请求）。
+  - **实际后果**：上游声明 `canDisableThinking: true` 且用户没取消勾选 → `off` 被置 `null` → 关闭思考**不可选**；上游声明 `false`/未声明 → 不置 `null` → `off` 落成字符串 `'off'` → **反而可选**。与 `offDefaultFor()` 的语义正好相反。
+  - **为什么一直没发现**：`tests/adapter.spec.ts` 只探了 `canDisableThinking: false` 那半边，而写反的形式在那半边也恰好通过；另外两条对 `true` 的用例把期望值写成了「没有 off」或「off 缺失」，**把缺陷当成了规格**。
+  - **改了什么**：改为 `canDisableThinking === true ? 'off' : null`，并把三条用例的期望值改正，新增「能力未声明时不给 off」一例。
+  - **变异验证**：把判断改回 `!== true` → 2 例红。
+
+- **DSH 宿主线守卫的 semver 比较器是错的：判 `0.2.1-rc.1` 通过，而 npm 实算是 false**
+  - **根因**：`tests/dsh-line.spec.ts` 自写的 `satisfiesRange()` 只做朴素 `>=` / `<` 比较，没有实现 semver 的**预发布悬崖**——预发布版本只有当同一比较器集合里存在**同一 `major.minor.patch` 元组**上的预发布比较符时才被放行。`>=0.1.7-rc.1` 只对 `0.1.7-x` 开口，`<0.3.0-0` 排除整个 `0.3.0` 元组，`0.2.1-rc.1`（元组 `0.2.1`）两条都不满足。
+  - **为什么夹具没触发**：原夹具是 `['0.1.7-rc.1','0.1.7-rc.2','0.2.0-rc.1','0.2.0-rc.9','0.2.0','0.2.1','0.2.99']`——恰好跳过真实发布的 `0.2.1-rc.1`；而 `0.2.0-rc.1` / `0.2.0-rc.9` 被断言成 admitted，那本身也是错的（npm 判 false）。
+  - **改了什么**：比较器按规范重写（`parseVersion` / `compareParsed` / `sameTuple` + 悬崖规则），夹具拆成「正式版放行」与「已知预发布偏差」两组，并新增 5 条照抄 npm 实际输出的悬崖用例。
+  - **新增的「已知偏差」用例**：显式断言 `0.2.1-rc.1` 与 `0.2.0-rc.1` 在现声明下 **不** admitted、而 `0.2.1` GA admitted。于是偏差是**被记录、被解释**的，而不是被错比较器掩盖；将来若改清单，这条会提醒同步更新说明。
+  - **为什么可以暂不改清单**：详见下一条。宿主 `evaluatePluginCompatibility()` 只校验 `@deepseek-ai/dsh*` 命名空间，本机 profile 用 `link:` + 默认不自动装 peer，rc 宿主上插件照常加载；等宿主发 `0.2.1` GA，现声明即放行。
+  - **变异验证**：去掉悬崖规则 → 2 例红。
+
+### Changed
+
+- **`@earendil-works/pi-ai` 的 peer 范围放宽到 1.x：`>=0.85.0 <0.88.0 || >=1.0.0-0 <2.0.0`（peer 与 dev 两处同步）**
+  - **为什么必须改**：旧范围 `>=0.85.0 <0.88.0` **不**放行 DSH 0.2.1-rc.1 随包的 1.1.0，而 1.1.0 恰恰是本版修好后要支持的版本 —— 声明与实际支持面自相矛盾。
+  - **范围是实算出来的，不是猜的**：`0.85.0 / 0.85.1 / 0.87.1 / 1.0.0 / 1.0.2 / 1.1.0` 均 `true`；`2.0.0` 与 `1.1.0-beta.1` 均 `false`。上界停在 `<2.0.0` 与 `generationOf()` 刻意不认 2.x 的判断保持一致；预发布串不承诺。
+  - **注意**：宿主门禁只校验 `@deepseek-ai/dsh*`，所以这条 peer **从不参与**宿主校验（4.4.2 已记录）。改它主要是让**清单说真话**，真正保护用户的是上面那条代码修复。
+  - **`dsh-*` 那 9 条 peer 本版未动**：理由见上一条「已知偏差」——任何为 `0.2.x` rc 硬凑的静态范围都会有漏（已逐一实算否证：`|| >=0.2.0-rc.1 <0.2.99`、`|| >=0.3.0-0 <0.3.0`、`>=0.1.7-rc.1-0 <0.3.0-0`、去掉预发布上界、`0.2.x` 通配符，全部失败）。
+
+### CI
+
+- **新增 `test-pi-ai-next` 作业：在 pi-ai 1.1.0 上跑一遍完整 typecheck + 测试 + 构建**
+  - **为什么必须有**：`tests/adapter-outgoing-body.spec.ts` 的矩阵是 2×2，但**一个代际跑不了另一个代际的库**——0.85 checkout 上只能跑 legacy 两格（1.x 的 api 读不了扁平形状），1.x checkout 上只能跑 modern 两格（0.85 的分词器在 system 消息上崩，即 #24）。主 `test` 作业钉的是 0.85.1，**modern 半边从未在 CI 里运行过**，而这正是 0.2.1-rc.1 坏掉的那一半。
+  - **怎么切版本**：pi-ai 既是 peer 又是直接 devDependency，`pnpm-workspace.yaml` 的 `overrides` 是官方支持的改法。作业用 `sed` 改那一条 override，再 `--no-frozen-lockfile` 让 pnpm 只为它重解析。
+  - **有一道断言防止作业空转**：装完立刻 `node -p` 读实际版本并要求等于矩阵值，否则「跑了一遍绿」可能跑的根本不是 1.1.0。
+  - **本作业当场抓到一个本机永远看不到的缺陷**：pi-ai 1.x 给 provider 侧上下文加了**品牌**（`TranscriptContext`，`unique symbol` 字段，声明为「只有 `normalizeContext()` 能产出」）。在 1.x 的**类型**上，`stream`/`streamSimple` 的两条分支都收到品牌类型，于是把普通 `Context` 传进去会 `TS2345`——而 `modern` 分支的 `return api` 也一并被类型系统拒绝。本机 0.85 的类型面是裸 `Context`，**这个错误在 0.85 上不存在**。修法是一处**有注释的** `transcript<T>()` 断言，理由写在函数上：调用点已经完成 `normalizeContext` 的职责，而 `normalizeContext` 在 0.85 不存在、不能导入。**变异验证**：去掉该断言 → 1.1.0 上 `tsc` 报 4 个 `TS2345`。
+  - **验证过它真的会响**：把 modern 分支改回 `return api`，1.1.0 作业**红 4 例**（`adapter.spec.ts` 与 `adapter-outgoing-body.spec.ts` 各自的 modern 守卫），而 0.85.1 作业保持全绿。这正是本作业存在的意义。
+  - 仅跑 ubuntu：这是库层面的断言，不是平台断言；OS 矩阵已由主 `test` 作业覆盖。
+
+### Docs
+
+- `src/pi-ai-runtime.ts` 头部更正：peer 范围同步为新值；删去把 1.x 说成「未发布」的过时表述（DSH 0.2.1-rc.1 已随包 1.1.0）；补一句「落在 modern 是必要但**不充分**——modern 分支还必须折叠原始信封」。
+- `src/adapter.ts` 的 `adaptLegacyPiAiContext()` 补注 **legacy-only**：它的结果是 0.85 扁平形状，绝不能交给 1.x 的 api（1.x 从 `messages[].toolsAdded` 读工具，会一个都看不到）。
+- 新增 `docs/DSH-0.2.1-RC1-FOLLOWUP.md`：本次升级的完整调研档，含逐包对照表、四项「已核对无需改动」、失败候选与证据来源。
+
 ## 4.6.7 (2026-10-17)
 
 > 版本号是 **patch**：只改账号池的排序规则，没有接口或配置变更。但它是**行为变更**——开启账号池的机器上，「这次请求用谁」可能变了，且新行为正是本版要的。

package/README.en.md

@@ -152,7 +152,7 @@ One class of state in the pool **does not go through a draft**: probe results, c
 
 ## Install
 
-> ⚠️ **Version requirement: DSH 0.1.7-rc.1 or newer (current window: `0.1.7-rc.1` – `0.2.x`).** Since v2.1.0 this plugin only supports hosts on DSH 0.1.7-rc.1 and above (older hosts cannot resolve the dependencies to install this version); hosts on 0.1.5 and earlier should stay on v2.0.15. Since v2.1.2 the upper bound is **`<0.3.0-0`**: the **whole 0.2.0 line, GA included, is verified**; the 0.3.0 line is explicitly refused. See [Supported host range](#supported-host-range) below.
+> ⚠️ **Version requirement: DSH 0.1.7-rc.1 or newer (current window: `0.1.7-rc.1` – `0.2.x` GA).** Since v2.1.0 this plugin only supports hosts on DSH 0.1.7-rc.1 and above (older hosts cannot resolve the dependencies to install this version); hosts on 0.1.5 and earlier should stay on v2.0.15. Since v2.1.2 the upper bound is **`<0.3.0-0`**; the 0.3.0 line is explicitly refused. See [Supported host range](#supported-host-range) below.
 
 ### Supported host range
 
@@ -161,11 +161,20 @@ DSH's shipped gate (`evaluatePluginCompatibility` in `packages/boot/app-boot/src
 | Host version | Verdict |
 | --- | --- |
 | `0.1.7-rc.1` – `0.1.7-rc.2` | ✅ supported |
-| `0.2.0-rc.1` – `0.2.x` (`0.2.0` GA included) | ✅ supported (verified from 2.1.2) |
+| `0.2.x` **GA** (`0.2.0`, `0.2.1`, …) | ✅ supported (verified from 2.1.2) |
+| `0.2.x` **prerelease** (`0.2.0-rc.1`, `0.2.1-rc.1`, …) | ⚠️ outside the declared range — see below |
 | `0.3.0-0` and above | ❌ explicitly refused (that line is unverified) |
 | `0.1.6` and earlier | ❌ explicitly refused (0.1.5 users should stay on v2.0.15) |
 
-> The upper bound is written `<0.3.0-0`, not `<0.3.0`: **every DSH tag to date is a prerelease** (`-alpha.N` / `-rc.N`), so `<0.3.0` alone would admit the entire unverified `0.3.0-alpha.1` / `0.3.0-rc.1` line, leaving the guardrail inert — exactly the defect shape 2.1.2 fixes. `tests/dsh-line.spec.ts` guards this contract.
+> **On `0.2.x` prereleases (corrected in v4.7.0)**: this table previously listed `0.2.0-rc.1` as "✅ supported". That was **wrong**.
+> npm semver admits a prerelease only when a comparator carries a prerelease on the **same `major.minor.patch` tuple**.
+> The declared `>=0.1.7-rc.1 <0.3.0-0` opens only `0.1.7-x`, while `<0.3.0-0` excludes the `0.3.0` tuple — so versions such as
+> **`0.2.1-rc.1` satisfy neither comparator** (`satisfies('0.2.1-rc.1', …) === false`).
+> The practical impact is small: the host gate only evaluates the `@deepseek-ai/dsh*` namespace, and on rc hosts this plugin loads
+> normally via `link:` / a manual install. It is also **not fixable by editing the range** — no static range can cover "any `0.2.x`
+> prerelease"; five candidate formulations were computed and refuted (see CHANGELOG 4.7.0). It resolves itself once the host ships `0.2.1` GA.
+
+> The upper bound is written `<0.3.0-0`, not `<0.3.0`: **every DSH tag to date is a prerelease** (`-alpha.N` / `-rc.N`), so `<0.3.0` alone would admit the entire unverified `0.3.0-alpha.1` / `0.3.0-rc.1` line, leaving the guardrail inert — exactly the defect shape 2.1.2 fixes. `tests/dsh-line.spec.ts` guards this contract, including the prerelease cliff.
 
 > 🪟 **Platform support: Windows, macOS, and Linux are supported side by side.** **Windows is a first-class target**, not an afterthought: CI runs the full suite on `windows-latest`, and four areas carry Windows-specific branches with their own tests — credential paths, process heartbeat, desktop-app executable lookup, and settings writes. **When fixing a defect that only reproduces on Windows, the Windows reporter's field evidence and an encryption vector captured from a real Windows install are what the fix is judged against** (see the 2.0.6 / 2.0.11 / 2.0.12 sections of [CHANGELOG](CHANGELOG.md)). See the [Platform support](#platform-support) section for the per-platform differences and known limitations.
 

package/README.md

@@ -160,7 +160,7 @@ DSH PiAiAdapter（每个 provider 一套）
 
 ## 安装
 
-> ⚠️ **版本要求：DSH 0.1.7-rc.1 及以上（当前窗口：`0.1.7-rc.1` ~ `0.2.x`）。** 自 v2.1.0 起本插件只支持 DSH 0.1.7-rc.1 及以上的宿主（旧版宿主无法通过依赖解析安装本版）；0.1.5 及更早的宿主请停留在 v2.0.15。自 v2.1.2 起上界放宽为 **`<0.3.0-0`**——**0.2.0 全线（含正式版）已实测支持**，0.3.0 线则被明确拒绝。详见下方[受支持的宿主范围](#受支持的宿主范围)。
+> ⚠️ **版本要求：DSH 0.1.7-rc.1 及以上（当前窗口：`0.1.7-rc.1` ~ `0.2.x` 正式版）。** 自 v2.1.0 起本插件只支持 DSH 0.1.7-rc.1 及以上的宿主（旧版宿主无法通过依赖解析安装本版）；0.1.5 及更早的宿主请停留在 v2.0.15。自 v2.1.2 起上界放宽为 **`<0.3.0-0`**，0.3.0 线被明确拒绝。详见下方[受支持的宿主范围](#受支持的宿主范围)。
 
 ### 受支持的宿主范围
 
@@ -169,11 +169,20 @@ DSH 的随包门禁（`packages/boot/app-boot/src/plugin-compatibility.ts` 的 `
 | 宿主版本 | 判定 |
 | --- | --- |
 | `0.1.7-rc.1` ~ `0.1.7-rc.2` | ✅ 支持 |
-| `0.2.0-rc.1` ~ `0.2.x`（含 `0.2.0` 正式版） | ✅ 支持（2.1.2 起实测） |
+| `0.2.x` **正式版**（`0.2.0`、`0.2.1` …） | ✅ 支持（2.1.2 起实测） |
+| `0.2.x` **预发布**（`0.2.0-rc.1`、`0.2.1-rc.1` …） | ⚠️ 不落在声明范围内，见下方说明 |
 | `0.3.0-0` 及以上 | ❌ 明确拒绝（该线尚未验证） |
 | `0.1.6` 及更早 | ❌ 明确拒绝（0.1.5 线请停留在 v2.0.15） |
 
-> 上界写作 `<0.3.0-0` 而非 `<0.3.0`：DSH 至今**全部 tag 都是预发布**（`-alpha.N` / `-rc.N`），只写 `<0.3.0` 会放行整条 `0.3.0-alpha.1` / `0.3.0-rc.1` 这条从未验证过的线，围栏形同虚设——这正是 2.1.2 修掉的缺陷形状。该口径由 `tests/dsh-line.spec.ts` 守卫。
+> **关于 `0.2.x` 预发布（v4.7.0 更正）**：此前本表把 `0.2.0-rc.1` 写作「✅ 支持」，那是**错的**。
+> npm semver 规定：预发布版本只有当一个比较器**在同一条 `major.minor.patch` 元组上**带预发布标签时才被放行。
+> 现声明 `>=0.1.7-rc.1 <0.3.0-0` 只对 `0.1.7-x` 开口，`<0.3.0-0` 又排除了 `0.3.0` 元组，因此
+> **`0.2.1-rc.1` 这类版本两条比较器都不满足**（`satisfies('0.2.1-rc.1', …) === false`）。
+> 实际影响很小：宿主门禁只校验 `@deepseek-ai/dsh*` 命名空间，且 rc 宿主上本插件按 `link:` / 手工安装照常加载。
+> 这**不是**靠改范围能解决的问题——任何静态范围都覆盖不了「任意 `0.2.x` 预发布」，已逐一实算否证五种写法
+> （见 CHANGELOG 4.7.0）。等宿主发 `0.2.1` 正式版即自然成立。
+
+> 上界写作 `<0.3.0-0` 而非 `<0.3.0`：DSH 至今**全部 tag 都是预发布**（`-alpha.N` / `-rc.N`），只写 `<0.3.0` 会放行整条 `0.3.0-alpha.1` / `0.3.0-rc.1` 这条从未验证过的线，围栏形同虚设——这正是 2.1.2 修掉的缺陷形状。该口径由 `tests/dsh-line.spec.ts` 守卫（含预发布悬崖的用例）。
 
 > 🪟 **平台支持：Windows、macOS、Linux 三者并列支持。** **Windows 是一等目标平台**，不是「顺带能跑」：CI 在 `windows-latest` 上跑完整套件，凭据路径、进程心跳、App 可执行文件定位、设置写入四处都有 Windows 专属分支与测试，并且**修复只对 Windows 生效的缺陷时，以 Windows 用户回报的现场与真机取证的加密向量为准**（见 [CHANGELOG](CHANGELOG.md) 的 2.0.6 / 2.0.11 / 2.0.12 各节）。见下方[平台支持](#平台支持)一节了解各平台的具体差异与已知限制。
 

package/lib/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { C as defaultDesktopAuthDirs, F as WorkBuddyUpstreamClient, K as WORKBUDDY_APP_EXECUTABLE_ENV, O as legacyWorkbuddyOwnAuthPath, Q as findWorkbuddyAppExecutableWithSource, S as defaultDesktopAuthCandidates, a as readHostHeartbeat, c as WORKBUDDY_CONNECT_VERSION, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, j as workbuddyOwnAuthPath, l as piAiRuntimeInfo, o as workbuddyHostHeartbeatPath, ot as hostPeersInfo, r as isHeartbeatProcessAlive, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, y as WorkBuddyCredentialStore } from "./host-heartbeat-D7a100yu.js";
+import { C as defaultDesktopAuthDirs, F as WorkBuddyUpstreamClient, K as WORKBUDDY_APP_EXECUTABLE_ENV, O as legacyWorkbuddyOwnAuthPath, Q as findWorkbuddyAppExecutableWithSource, S as defaultDesktopAuthCandidates, a as readHostHeartbeat, c as WORKBUDDY_CONNECT_VERSION, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, j as workbuddyOwnAuthPath, l as piAiRuntimeInfo, o as workbuddyHostHeartbeatPath, ot as hostPeersInfo, r as isHeartbeatProcessAlive, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, y as WorkBuddyCredentialStore } from "./host-heartbeat--S6JVSci.js";
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 //#region src/bin.ts

package/lib/{host-heartbeat-D7a100yu.js → host-heartbeat--S6JVSci.js}

@@ -3801,9 +3801,9 @@ var WorkBuddyCatalog = class {
 * Which `@earendil-works/pi-ai` copy THIS plugin actually resolves at runtime.
 *
 * WHY THIS EXISTS (issues #24 / #25 / #26). The plugin declares pi-ai as a
-* peer (`>=0.85.0 <0.88.0`), so the module it imports is whatever the host
-* environment provides — and the two generations consume DIFFERENT context
-* shapes:
+* peer (`>=0.85.0 <0.88.0 || >=1.0.0-0 <2.0.0`), so the module it imports is
+* whatever the host environment provides — and the two generations consume
+* DIFFERENT context shapes:
 *
 * - 0.87 hands providers a normalized transcript: `{ messages: [ {role:
 *   'system', content, toolsAdded}, … ] }`. The system prompt and the tool
@@ -3920,8 +3920,9 @@ function readVersion(moduleFile) {
 * doctor shows it as unreadable, so the guess is visible rather than silent).
 *
 * The 1.x line MUST land on `modern`, and it is not a hypothetical: DSH
-* 0.2.1-alpha.2 ships `@earendil-works/pi-ai@1.0.2`, while npm currently
-* publishes 1.1.0. Both 0.87.1 and 1.0.2/1.1.0 read tools from the same place
+* 0.2.1-alpha.2 ships `@earendil-works/pi-ai@1.0.2`, and DSH 0.2.1-rc.1 ships
+* 1.1.0 (which is the version this plugin is now tested against). Both 0.87.1
+* and 1.0.2/1.1.0 read tools from the same place
 * (`context.messages` → the leading system message's `toolsAdded`; see
 * pi-ai's `resolveTranscriptTools`). Matching only `0.<minor>.` classified
 * 1.0.2 as `legacy`, so `withLegacyContext` folded the transcript into the
@@ -3937,6 +3938,13 @@ function readVersion(moduleFile) {
 * observed 1.x line (including current 1.1.0) without assuming an uninspected
 * future major such as 2.x keeps the same transcript contract. The declared
 * peer range remains the plugin's supported-version boundary.
+*
+* ⚠️ Being on `modern` is necessary but NOT sufficient. The modern branch must
+* also FOLD a raw seam envelope: `dsh-llm-pi-ai` never normalizes, and 1.x
+* reads only `context.messages`. Between 4.4.2 (which taught this function
+* about major 1) and the 0.2.1-rc.1 fix, `withLegacyContext` returned the
+* modern api UNWRAPPED, so every request on pi-ai 1.x went upstream with no
+* prompt and no tool declarations. See `foldModernContext` in `adapter.ts`.
 */
 function generationOf(version) {
 	if (version === void 0) return "legacy";
@@ -3949,7 +3957,7 @@ function generationOf(version) {
 //#endregion
 //#region src/version.ts
 /** The npm package version this build was produced from. */
-const WORKBUDDY_CONNECT_VERSION = "4.6.7";
+const WORKBUDDY_CONNECT_VERSION = "4.8.0";
 //#endregion
 //#region src/host-heartbeat.ts
 /**

package/lib/index.d.ts

@@ -1200,9 +1200,9 @@ declare function createWorkBuddyShim(options: WorkBuddyShimOptions): WorkBuddySh
  * Which `@earendil-works/pi-ai` copy THIS plugin actually resolves at runtime.
  *
  * WHY THIS EXISTS (issues #24 / #25 / #26). The plugin declares pi-ai as a
- * peer (`>=0.85.0 <0.88.0`), so the module it imports is whatever the host
- * environment provides — and the two generations consume DIFFERENT context
- * shapes:
+ * peer (`>=0.85.0 <0.88.0 || >=1.0.0-0 <2.0.0`), so the module it imports is
+ * whatever the host environment provides — and the two generations consume
+ * DIFFERENT context shapes:
  *
  * - 0.87 hands providers a normalized transcript: `{ messages: [ {role:
  *   'system', content, toolsAdded}, … ] }`. The system prompt and the tool
@@ -1246,6 +1246,18 @@ declare function createWorkBuddyShim(options: WorkBuddyShimOptions): WorkBuddySh
 /** The resolved pi-ai generation, by context-shape capability. */
 type PiAiGeneration = 'modern' | 'legacy';
 //#endregion
+//#region src/context-rescue.d.ts
+interface ContextRescue {
+  /**
+   * Fold history until the next request fits the given window.
+   *
+   * @param sessionId - session whose history should be folded.
+   * @param window - context window of the route that just overflowed.
+   * @returns whether any history was folded.
+   */
+  rescue(sessionId: string, window: number): Promise<boolean>;
+}
+//#endregion
 //#region src/adapter.d.ts
 /** Provider route this bundle owns for the domestic (CN) gateway. */
 declare const WORKBUDDY_PROVIDER = "workbuddy";
@@ -1270,6 +1282,12 @@ interface WorkBuddyAdapterOptions {
   displayName?: string;
   /** Resolve the durable attachment service at request time, when present. */
   resolveAttachments?: () => AttachmentStore | undefined;
+  /**
+   * Resolve the host-side context-overflow rescue, when this host exposes one.
+   * Omitted (or resolving to `undefined`) leaves the adapter exactly as it was:
+   * a provider overflow is forwarded and the host's own recovery decides.
+   */
+  resolveContextRescue?: () => ContextRescue | undefined;
   /**
    * Override the pi-ai generation gate (see {@link piAiRuntimeInfo}); tests
    * inject both branches because this checkout only ever RESOLVES one of
@@ -1300,7 +1318,27 @@ declare function workBuddyModelInput(info: WorkBuddyModelInfo): ('text' | 'image
  * `x0.00`, matching WorkBuddy's rendering of free models.
  */
 declare function workBuddyDisplayName(info: WorkBuddyModelInfo): string;
-/** Map only levels advertised by WorkBuddy; undeclared DSH levels stay unavailable. */
+/**
+ * Map only levels advertised by WorkBuddy; undeclared DSH levels stay unavailable.
+ *
+ * `off` is offered EXACTLY when `canDisableThinking === true` and withheld
+ * (mapped to `null`) otherwise. `null` is pi-ai's "this level is not
+ * supported": `getSupportedThinkingLevels` filters on `mapped === null`, and
+ * `openai-completions` reads `thinkingLevelMap?.off !== null` to decide whether
+ * it may send a thinking-disabled request.
+ *
+ * This condition used to be inverted (`!== true` set the null), which locked
+ * `off` OFF for precisely the models that CAN disable thinking while leaving it
+ * ON for those that cannot. It stayed invisible because the only test probed
+ * the `canDisableThinking: false` half, which the inverted form also passes.
+ *
+ * The value read here is already the EFFECTIVE one: the runtime catalog is
+ * stamped by `withEffectiveOff()` before it reaches the adapter, so this is the
+ * user's `off` selection when they made one (and the upstream declaration,
+ * minus `REFUSES_OFF_MODEL_IDS`, when they never did). Absence is "unknown" and
+ * stays unoffered, matching how the rest of the plugin treats undeclared
+ * capability.
+ */
 declare function workBuddyThinkingLevelMap(info: WorkBuddyModelInfo): WorkBuddyThinkingLevelMap | undefined;
 /**
  * Assemble the adapter. The provider's `getModels` reads the live catalog,

package/lib/index.js

@@ -1,9 +1,9 @@
-import { $ as isEncryptedFieldWrapper, A as workbuddyAccountId, B as modelIdOfBody, C as defaultDesktopAuthDirs, D as isVaultAccountId, E as isEncryptedCredentialError, F as WorkBuddyUpstreamClient, G as regionOf, H as parseReasoning, I as classifyUpstreamError, J as deriveAtRestKey, K as WORKBUDDY_APP_EXECUTABLE_ENV, L as declaredTools, M as CREDENTIAL_REJECTED_CODE, N as WORKBUDDY_FALLBACK_SYSTEM_PROMPT, O as legacyWorkbuddyOwnAuthPath, P as WorkBuddyCredentialRejectedError, R as isCredentialRejectedError, S as defaultDesktopAuthCandidates, T as hasEncryptedCredentialFields, U as parseUpstreamModel, V as parseCreditMultiplier, W as prepareChatBody, X as fetchAtRestKeyPayload, Y as deriveAtRestKeyId, Z as findWorkbuddyAppExecutable, _ as WORKBUDDY_AUTH_FILENAME, a as readHostHeartbeat, at as workbuddyAppExecutableCandidates, b as WorkBuddyEncryptedCredentialError, c as WORKBUDDY_CONNECT_VERSION, ct as withFileLock, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, et as isWorkbuddyBundle, f as WorkBuddyCatalog, g as ENCRYPTED_CREDENTIAL_CODE, h as fallbackModelsFor, i as processStartTimeMs, it as readAtRestKey, j as workbuddyOwnAuthPath, k as parseWorkBuddyAuth, l as piAiRuntimeInfo, lt as writeFileAtomic, m as deriveCatalog, n as clearHostHeartbeat, nt as macosNestedAppBundles, o as workbuddyHostHeartbeatPath, p as applyContextBudgets, q as clearAtRestKeyCache, r as isHeartbeatProcessAlive, rt as openEncryptedField, s as writeHostHeartbeat, st as resolveDshHome, t as WORKBUDDY_HOST_HEARTBEAT_FILENAME, tt as macosBundleExecutable, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, w as defaultDesktopAuthPath, x as authFileName, y as WorkBuddyCredentialStore, z as knownRegionOf } from "./host-heartbeat-D7a100yu.js";
+import { $ as isEncryptedFieldWrapper, A as workbuddyAccountId, B as modelIdOfBody, C as defaultDesktopAuthDirs, D as isVaultAccountId, E as isEncryptedCredentialError, F as WorkBuddyUpstreamClient, G as regionOf, H as parseReasoning, I as classifyUpstreamError, J as deriveAtRestKey, K as WORKBUDDY_APP_EXECUTABLE_ENV, L as declaredTools, M as CREDENTIAL_REJECTED_CODE, N as WORKBUDDY_FALLBACK_SYSTEM_PROMPT, O as legacyWorkbuddyOwnAuthPath, P as WorkBuddyCredentialRejectedError, R as isCredentialRejectedError, S as defaultDesktopAuthCandidates, T as hasEncryptedCredentialFields, U as parseUpstreamModel, V as parseCreditMultiplier, W as prepareChatBody, X as fetchAtRestKeyPayload, Y as deriveAtRestKeyId, Z as findWorkbuddyAppExecutable, _ as WORKBUDDY_AUTH_FILENAME, a as readHostHeartbeat, at as workbuddyAppExecutableCandidates, b as WorkBuddyEncryptedCredentialError, c as WORKBUDDY_CONNECT_VERSION, ct as withFileLock, d as FALLBACK_WORKBUDDY_MODELS_GLOBAL, et as isWorkbuddyBundle, f as WorkBuddyCatalog, g as ENCRYPTED_CREDENTIAL_CODE, h as fallbackModelsFor, i as processStartTimeMs, it as readAtRestKey, j as workbuddyOwnAuthPath, k as parseWorkBuddyAuth, l as piAiRuntimeInfo, lt as writeFileAtomic, m as deriveCatalog, n as clearHostHeartbeat, nt as macosNestedAppBundles, o as workbuddyHostHeartbeatPath, p as applyContextBudgets, q as clearAtRestKeyCache, r as isHeartbeatProcessAlive, rt as openEncryptedField, s as writeHostHeartbeat, st as resolveDshHome, t as WORKBUDDY_HOST_HEARTBEAT_FILENAME, tt as macosBundleExecutable, u as FALLBACK_WORKBUDDY_MODELS, v as WORKBUDDY_AUTH_FILE_ENV, w as defaultDesktopAuthPath, x as authFileName, y as WorkBuddyCredentialStore, z as knownRegionOf } from "./host-heartbeat--S6JVSci.js";
 import z from "@deepseek-ai/schemastery";
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
 import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { join } from "node:path";
-import { createProvider } from "@earendil-works/pi-ai";
+import { createAssistantMessageEventStream, createProvider, isContextOverflow } from "@earendil-works/pi-ai";
 import { openAICompletionsApi } from "@earendil-works/pi-ai/api/openai-completions.lazy";
 import { resolveRetryPolicy } from "@deepseek-ai/dsh-llm";
 import { PiAiAdapter } from "@deepseek-ai/dsh-llm-pi-ai";
@@ -184,12 +184,33 @@ function workBuddyModelInput(info) {
 function workBuddyDisplayName(info) {
 	return info.creditMultiplier === void 0 ? info.name : `${info.name} · x${info.creditMultiplier.toFixed(2)}`;
 }
-/** Map only levels advertised by WorkBuddy; undeclared DSH levels stay unavailable. */
+/**
+* Map only levels advertised by WorkBuddy; undeclared DSH levels stay unavailable.
+*
+* `off` is offered EXACTLY when `canDisableThinking === true` and withheld
+* (mapped to `null`) otherwise. `null` is pi-ai's "this level is not
+* supported": `getSupportedThinkingLevels` filters on `mapped === null`, and
+* `openai-completions` reads `thinkingLevelMap?.off !== null` to decide whether
+* it may send a thinking-disabled request.
+*
+* This condition used to be inverted (`!== true` set the null), which locked
+* `off` OFF for precisely the models that CAN disable thinking while leaving it
+* ON for those that cannot. It stayed invisible because the only test probed
+* the `canDisableThinking: false` half, which the inverted form also passes.
+*
+* The value read here is already the EFFECTIVE one: the runtime catalog is
+* stamped by `withEffectiveOff()` before it reaches the adapter, so this is the
+* user's `off` selection when they made one (and the upstream declaration,
+* minus `REFUSES_OFF_MODEL_IDS`, when they never did). Absence is "unknown" and
+* stays unoffered, matching how the rest of the plugin treats undeclared
+* capability.
+*/
 function workBuddyThinkingLevelMap(info) {
 	const supported = info.reasoning?.supportedEfforts?.filter((effort) => THINKING_LEVELS.includes(effort));
 	if (supported === void 0 || supported.length === 0) return void 0;
 	const map = Object.fromEntries(THINKING_LEVELS.map((level) => [level, supported.includes(level) ? level : null]));
-	if (info.reasoning?.canDisableThinking !== true) map.off = null;
+	if (info.reasoning?.canDisableThinking === true) map.off = "off";
+	else map.off = null;
 	return map;
 }
 /** Build one pi-ai model descriptor pointing at the loopback shim. */
@@ -267,6 +288,14 @@ function toPiModel(info, baseUrl, providerId) {
 *   text is empty but which carries `toolsAdded` still folds its TOOLS up; the
 *   placeholder for the missing prompt then comes from `ensureSystemHead` at
 *   the wire (the last of the three layers).
+*
+* LEGACY-ONLY. This is the inverse direction from {@link foldModernContext}:
+* it produces the FLAT `{systemPrompt, tools, messages}` shape that ONLY
+* pi-ai 0.85 reads. Never hand its result to a 1.x api — 1.x reads tools from
+* `messages[].toolsAdded` and would see none (issues #25/#26). Type note: the
+* parameter is the 0.85 `Context`; pi-ai 1.1.0 types the api's second parameter
+* as `TranscriptContext`, so this function cannot be called with 1.x typings —
+* that is intentional, and it is why the modern branch below does not touch it.
 */
 function adaptLegacyPiAiContext(context) {
 	if (context === null || typeof context !== "object") return context;
@@ -330,30 +359,162 @@ function systemTextOf(message) {
 	return texts.join("\n\n");
 }
 /**
+* Fold a RAW context into the normalized transcript the modern generation
+* consumes: a leading `system` message carrying the prompt AND the tool
+* declarations in its `toolsAdded` field.
+*
+* WHY THIS IS NEEDED AT ALL (the 0.2.1-rc.1 regression). This used to be
+* unnecessary: the modern branch returned pi-ai's api UNWRAPPED, on the belief
+* that the modern generation normalized for itself. It does not.
+* `dsh-llm-pi-ai` — both the 0.1.7 and the 0.2.1 lines — hands every provider a
+* RAW envelope (`piContext()` builds `{systemPrompt, messages, tools}` and
+* never calls `normalizeContext`), while:
+*
+*   - pi-ai 0.85.x READS that raw shape (its request builder consults
+*     `context.systemPrompt` / `context.tools` directly), and
+*   - pi-ai 1.x READS ONLY `context.messages` (it resolves the transcript and
+*     collapses system messages; the top-level fields are consulted nowhere).
+*
+* On pi-ai 1.x a pass-through request therefore went upstream with NO system
+* prompt and NO tool declarations, silently: the model stopped calling tools,
+* and the domestic gateway tolerated the prompt-less body. Same failure class
+* as issues #24/#25/#26, reached from the opposite side — 4.4.2 fixed "1.x
+* misjudged as legacy and folded"; this fixes "1.x judged modern and NOT
+* folded, though nothing had normalized".
+*
+* Built inline rather than by importing pi-ai's `normalizeContext`, which does
+* not exist in 0.85.x: a static import would be `undefined` there, and this
+* module deliberately never imports pi-ai statically (see `pi-ai-runtime.ts` —
+* that doctrine is what lets the standalone `bin` run in a profile where the
+* peer is never installed). The folded shape matches what `normalizeContext`
+* produces for the same input: `{role:'system', content, toolsAdded, timestamp:0}`.
+*
+* The top-level `systemPrompt`/`tools` fields are DROPPED, exactly as
+* `normalizeContext` drops them, so a raw transcript and an already-normalized
+* one converge on the same object.
+*/
+function foldModernContext(context) {
+	const prompt = context.systemPrompt;
+	const tools = context.tools;
+	const hasPrompt = prompt !== void 0 && prompt !== "";
+	const hasTools = Array.isArray(tools) && tools.length > 0;
+	if (!hasPrompt && !hasTools) return context;
+	const system = {
+		role: "system",
+		content: prompt ?? "",
+		...hasTools ? { toolsAdded: tools } : {},
+		timestamp: 0
+	};
+	const { systemPrompt: _prompt, tools: _tools, ...rest } = context;
+	return {
+		...rest,
+		messages: [system, ...context.messages]
+	};
+}
+/**
 * Wrap one pi-ai API module so both stream entry points receive a context this
-* build can actually consume (see {@link adaptLegacyPiAiContext}) — but only
-* when the module RESOLVED for this plugin is the legacy generation.
+* generation can actually consume.
 *
 * The gate is the plugin's own module, resolved via {@link piAiRuntimeInfo}
-* (manifest version of the copy this plugin resolves — no pi-ai import): a
-* modern (0.87+) api consumes the normalized
-* transcript natively — its request builder reads the prompt from the leading
-* system message and the tools from that message's `toolsAdded`, and never
-* reads the top-level `systemPrompt`/`tools` fields at all. Folding for it
-* would delete the only carrier of both (issues #25/#26: the international
-* gateway answers the prompt-less body with 400 / 11128, the domestic one
-* accepts it and the model fabricates tool calls it can never actually make).
-* The unwrapped modern api is returned AS-IS — byte-for-byte pass-through.
+* (manifest version of the copy this plugin resolves — no pi-ai import):
+*
+* - `legacy` (0.85) wants the flat `{systemPrompt, tools, messages}` shape, so
+*   a normalized transcript is UN-folded by {@link adaptLegacyPiAiContext}.
+* - `modern` (0.87+, incl. 1.x) wants the normalized transcript, so a raw
+*   envelope is FOLDED by {@link foldModernContext}. Passing it through
+*   unnormalized is what silently deleted the prompt and the tools on pi-ai
+*   1.x — the regression this branch now prevents.
+*
+* Both branches are idempotent, so a future seam that starts normalizing on its
+* own side changes nothing here.
 *
 * The deferred-fetch entry points take no context and are passed through as-is
 * in both branches.
 */
+/**
+* Present an adapted context as the type the api's parameter currently expects.
+*
+* pi-ai 1.x BRANDS its provider-facing context (`TranscriptContext`, a
+* `unique symbol` field) precisely so a raw `Context` cannot reach provider
+* code by accident; the brand's stated sole producer is `normalizeContext()`.
+* On a 1.x typings surface BOTH branches below receive that branded type, so
+* merely returning a plain `Context` fails `tsc` with TS2345 — an error that
+* only appears when the peer TYPES are 1.x, which is why the 0.85 checkout
+* never saw it.
+*
+* The cast is a deliberate, documented assertion of exactly what the brand
+* protects, and it is true after the call site has done the work:
+*
+* - modern: {@link foldModernContext} has already performed
+*   `normalizeContext`'s job — prompt and tools live on the leading system
+*   message, top-level fields gone;
+* - legacy: {@link adaptLegacyPiAiContext} produced the FLAT 0.85 shape, which
+*   is only ever observed on a 0.85 checkout, where this type is a plain
+*   `Context` and the cast is an upcast.
+*
+* Do NOT "fix" this by importing `normalizeContext`: it does not exist in
+* 0.85, so that import would be `undefined` at runtime on the very hosts this
+* code must keep working — the same reason `pi-ai-runtime.ts` documents why
+* this module never imports pi-ai statically.
+*/
+function transcript(context) {
+	return context;
+}
 function withLegacyContext(api, generation) {
-	if (generation === "modern") return api;
+	if (generation === "modern") return {
+		...api,
+		stream: (model, context, options) => api.stream(model, transcript(foldModernContext(context)), options),
+		streamSimple: (model, context, options) => api.streamSimple(model, transcript(foldModernContext(context)), options)
+	};
 	return {
 		...api,
-		stream: (model, context, options) => api.stream(model, adaptLegacyPiAiContext(context), options),
-		streamSimple: (model, context, options) => api.streamSimple(model, adaptLegacyPiAiContext(context), options)
+		stream: (model, context, options) => api.stream(model, transcript(adaptLegacyPiAiContext(context)), options),
+		streamSimple: (model, context, options) => api.streamSimple(model, transcript(adaptLegacyPiAiContext(context)), options)
+	};
+}
+/**
+* Layer the host-side context-overflow rescue onto a provider's streams.
+*
+* pi-ai reports a provider failure as an `error` event rather than a throw, so
+* the rescue runs while the failing assistant message is still in hand: history
+* is folded before the event continues on its way, and the host's retry then
+* rebuilds its request against a smaller surface. Nothing is swallowed — the
+* error event is forwarded unchanged, because deciding whether to retry is the
+* host's policy, not this transport's.
+*
+* Both gates are deliberate. Without `sessionId` there is no session to fold,
+* and without a declared `contextWindow` there is no budget to fold against;
+* either absence leaves the stream untouched.
+*/
+function withContextRescue(api, resolve) {
+	if (resolve === void 0) return api;
+	const wrap = (inner) => (model, context, options) => {
+		const source = inner(model, context, options);
+		const rescue = resolve();
+		const sessionId = options?.sessionId;
+		const window = model.contextWindow;
+		if (rescue === void 0 || sessionId === void 0 || window === void 0) return source;
+		const out = createAssistantMessageEventStream();
+		let final;
+		(async () => {
+			try {
+				for await (const event of source) {
+					if (event.type === "done") final = event.message;
+					if (event.type === "error") final = event.error;
+					if (event.type === "error" && isContextOverflow(event.error)) await rescue.rescue(sessionId, window);
+					out.push(event);
+				}
+				out.end(final);
+			} catch {
+				out.end(final);
+			}
+		})();
+		return out;
+	};
+	return {
+		...api,
+		stream: wrap(api.stream),
+		streamSimple: wrap(api.streamSimple)
 	};
 }
 /**
@@ -385,7 +546,7 @@ function createWorkBuddyAdapter(options) {
 				}
 			} },
 			models: buildModels(),
-			api: withLegacyContext(openAICompletionsApi(), generation)
+			api: withContextRescue(withLegacyContext(openAICompletionsApi(), generation), options.resolveContextRescue)
 		}),
 		getModels: () => buildModels()
 	};
@@ -413,6 +574,104 @@ function createWorkBuddyAdapter(options) {
 	};
 }
 //#endregion
+//#region src/context-rescue.ts
+/** Share of the window one fold chunk may consume, leaving room for the prompt. */
+const CHUNK_FRACTION = .35;
+/** Post-fold measurement target: comfortably below the window the route allows. */
+const TARGET_FRACTION = .6;
+/** A session is never folded more than this many times by one rescue. */
+const MAX_ROUNDS = 8;
+/** How many times one chunk may shrink its tail edge before giving up. */
+const MAX_SHRINK = 24;
+/** A single fold is abandoned after this long. */
+const FOLD_TIMEOUT_MS = 18e4;
+/**
+* Create the rescue bound to a live host.
+*
+* @param resolve - resolves host services at call time.
+* @returns the rescue handle the adapter calls on a provider overflow.
+*/
+function createContextRescue(resolve) {
+	const inflight = /* @__PURE__ */ new Set();
+	return { async rescue(sessionId, window) {
+		if (inflight.has(sessionId)) return false;
+		inflight.add(sessionId);
+		try {
+			return await foldUntilFits(resolve(), sessionId, window);
+		} catch (error) {
+			resolve().log?.("dsh-connect-workbuddy: context rescue failed", error);
+			return false;
+		} finally {
+			inflight.delete(sessionId);
+		}
+	} };
+}
+async function foldUntilFits(deps, sessionId, window) {
+	const { meter, compaction, agents } = deps;
+	if (meter === void 0 || compaction === void 0 || agents === void 0) return false;
+	const agent = agents.get(sessionId);
+	if (agent === void 0) return false;
+	const target = Math.max(1, Math.floor(window * TARGET_FRACTION));
+	let foldedAny = false;
+	let previous = Number.POSITIVE_INFINITY;
+	for (let round = 0; round < MAX_ROUNDS; round += 1) {
+		const measurement = meter.measure(agent.session);
+		if (measurement.totalTokens <= target) return foldedAny;
+		if (measurement.totalTokens >= previous) return foldedAny;
+		previous = measurement.totalTokens;
+		if (!await foldOnce(deps, agent, measurement, window, target)) return foldedAny;
+		foldedAny = true;
+	}
+	return foldedAny;
+}
+/**
+* Fold the oldest chunk that fits, shrinking its tail edge when the host
+* refuses the range.
+*
+* The host rejects a range whose edges split a tool call from its result, and
+* it rejects an active or missing range before appending anything — so a
+* refused attempt costs no durable state and the edge can simply move inward.
+*
+* @returns whether one chunk was folded.
+*/
+async function foldOnce(deps, agent, measurement, window, target) {
+	const nodes = measurement.nodes;
+	if (nodes.length < 2) return false;
+	const budget = Math.floor(window * CHUNK_FRACTION);
+	const excess = measurement.totalTokens - target;
+	const chunk = Math.max(1, Math.min(budget, excess));
+	const head = nodes[0];
+	const compaction = deps.compaction;
+	if (head === void 0 || compaction === void 0) return false;
+	let end = -1;
+	let accumulated = 0;
+	for (let index = 0; index < nodes.length - 1; index += 1) {
+		const node = nodes[index];
+		if (node === void 0) break;
+		accumulated += node.tokens;
+		end = index;
+		if (accumulated >= chunk) break;
+	}
+	if (end < 0) return false;
+	const signal = AbortSignal.timeout(FOLD_TIMEOUT_MS);
+	const floor = Math.max(0, end - MAX_SHRINK);
+	for (; end >= floor; end -= 1) {
+		const tail = nodes[end];
+		if (tail === void 0) break;
+		try {
+			await compaction.compactRegion(head.seq, tail.seq, agent, signal);
+			return true;
+		} catch (error) {
+			if (signal.aborted) {
+				deps.log?.("dsh-connect-workbuddy: context rescue timed out", error);
+				return false;
+			}
+		}
+	}
+	deps.log?.("dsh-connect-workbuddy: context rescue found no foldable range");
+	return false;
+}
+//#endregion
 //#region src/body-report.ts
 /**
 * Body-composition report: WHAT was sent upstream, in counts (issue #59).
@@ -425,16 +684,32 @@ function createWorkBuddyAdapter(options) {
 *   - the gateways count identical bytes differently (upstream's business); or
 *   - the two requests did not carry the same messages (ours to fix).
 *
-* The second world was left standing by two independent measurements. The
-* reporter ran this project's `--kind`/`--language` probe on BOTH regions and
-* got the same tokens-per-1000-chars on byte-identical prose, code and JSON
-* (ratios 0.98–1.06 across six cells), so identical bytes really do bill
-* identically. And a code trace showed historical `reasoning` never reaches the
-* wire at all: pi-ai only forwards `thinking` blocks as text when
-* `compat.requiresThinkingAsText` is set — this plugin never sets it — and the
-* `reasoning_details` route needs a signature the stream parser never writes.
-* With the counting difference excluded and reasoning excluded, the remaining
-* candidate is that the two bodies differ in the first place.
+* Neither world, it turned out — the answer was a third one, and this report is
+* what produced it. A paired capture in one session (4.6.7) measured
+* `bodyBytes` 3,628,068 vs 3,626,374, a ratio of 0.9995: both requests carried
+* the same bytes. What differed was the BUCKET each byte was counted in — CN
+* text 741,952 vs GL 184,821, CN reasoning 72,270 vs GL 627,994, with a
+* complementary residual of 0.3%. The gateways did not miscount; the same
+* history was labelled differently on the two sides.
+*
+* The labelling is pi-ai's replay, not this plugin's. `openai-completions.js`
+* records the reasoning field name the upstream stream actually used into
+* `thinkingSignature` (`:428`), and on the way back out writes
+* `assistantMsg[<that name>] = <the thinking text>` (`:1006`), so a
+* transcript produced against a gateway that says `reasoning` is replayed as
+* `reasoning` and one that says `reasoning_content` as `reasoning_content`.
+* This plugin sets only `compat.supportsReasoningEffort` (`src/adapter.ts:200`),
+* so the `else` branch is taken and the field goes out raw rather than folded
+* into text.
+*
+* An earlier revision of this comment claimed the opposite — that historical
+* `reasoning` never reaches the wire, because `requiresThinkingAsText` is unset
+* and the `reasoning_details` route needs a signature the parser never writes.
+* Both halves are wrong under pi-ai 0.85.1: the unset flag is precisely what
+* routes thinking out as a raw field, and the parser does write the
+* `reasoning_details` signature (`:188–193`). The correction matters because it
+* turns `reasoning` into a bucket that can be non-zero — and diffing it across
+* regions is the direct measurement of the drift.
 *
 * This module exists to settle exactly that, and it can do it WITHOUT either
 * region having credit: the body is assembled locally, before the upstream ever
@@ -6493,6 +6768,15 @@ function apply(ctx, config) {
 	Promise.all(REGION_KEYS.map((region) => stacks[region].shim.ready)).then(async () => {
 		if (stopped) return;
 		const adapters = {};
+		const hostService = (name) => ctx.get(name);
+		const contextRescue = createContextRescue(() => ({
+			meter: hostService("tokenMeter"),
+			compaction: hostService("compaction"),
+			agents: hostService("agents"),
+			log: (message, error) => {
+				ctx.logger.warn(message, error);
+			}
+		}));
 		try {
 			for (const region of REGION_KEYS) adapters[region] = createWorkBuddyAdapter({
 				shim: stacks[region].shim,
@@ -6500,7 +6784,8 @@ function apply(ctx, config) {
 				catalog: stacks[region].catalog,
 				provider: WORKBUDDY_PROVIDERS[region],
 				displayName: WORKBUDDY_PROVIDER_DISPLAY_NAMES[region],
-				resolveAttachments: () => ctx.get("attachments")
+				resolveAttachments: () => ctx.get("attachments"),
+				resolveContextRescue: () => contextRescue
 			});
 			invalidateCatalog = () => {
 				for (const region of REGION_KEYS) adapters[region].invalidate();

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-connect-workbuddy",
   "displayName": "DSH Connect WorkBuddy",
   "description": "把本机登录的 WorkBuddy 模型接入 DeepSeek Harness，并提供只读的积分概览与模型管理。",
-  "version": "4.6.7",
+  "version": "4.8.0",
   "author": "dingminhua",
   "copyright": "Copyright (c) 2026 LaoDing",
   "license": "MIT",
@@ -91,7 +91,7 @@
     "@deepseek-ai/dsh-llm-pi-ai": ">=0.1.7-rc.1 <0.3.0-0",
     "@deepseek-ai/dsh-settings": ">=0.1.7-rc.1 <0.3.0-0",
     "@deepseek-ai/schemastery": ">=3.18.1-rc.1 <4.0.0 || >=3.18.2 <4.0.0",
-    "@earendil-works/pi-ai": ">=0.85.0 <0.88.0",
+    "@earendil-works/pi-ai": ">=0.85.0 <0.88.0 || >=1.0.0-0 <2.0.0",
     "react": "^18.2.0"
   },
   "devDependencies": {
@@ -110,7 +110,7 @@
     "@deepseek-ai/dsh-llm-pi-ai": ">=0.1.7-rc.1 <0.3.0-0",
     "@deepseek-ai/dsh-settings": ">=0.1.7-rc.1 <0.3.0-0",
     "@deepseek-ai/schemastery": ">=3.18.1 <4.0.0 || >=3.18.2 <4.0.0",
-    "@earendil-works/pi-ai": ">=0.85.0 <0.88.0",
+    "@earendil-works/pi-ai": ">=0.85.0 <0.88.0 || >=1.0.0-0 <2.0.0",
     "@types/node": "^22.20.0",
     "@types/react": "~18.3.31",
     "@types/react-dom": "18.3.7",