dsh-autoctx 1.2.4 → 1.2.5

package/README.en.md

@@ -1,12 +1,12 @@
 # dsh-autoctx
 
-Context and subagent decision plugin for dsh, version **1.2.4**. Jev scores options and makes structured choices; the plugin implements them through native dsh sessions, tools, subagents and compaction. The executor model still does all the coding.
+Context and subagent decision plugin for dsh, version **1.2.5**. Jev scores options and makes structured choices; the plugin implements them through native dsh sessions, tools, subagents and compaction. The executor model still does all the coding.
 
 [中文](https://github.com/ZhiweiWei-NAMI/dsh-autoctx/blob/main/README.md) · [Source](https://github.com/ZhiweiWei-NAMI/dsh-autoctx) · MIT
 
 ## Environment and accounts
 
-Verified hosts are **dsh `0.2.0-rc.2` and `0.2.1-rc.2`**, using Node 22. Peer dependencies for the `@deepseek-ai/dsh-*` packages accept `^0.1.5-rc.1 || ^0.2.0-rc.1 || ^0.2.1-rc.1`. 1.2.4 adapts to dsh 0.2.1's subagent start API (`startActivation`) while keeping 0.2.0 support; scheduling and learning logic are unchanged from 1.2.3. The npm package is `dsh-autoctx`, its entry is `index.js`, and its web client is `./client.js`.
+Unit tests pass on **dsh `0.2.0-rc.2` and `0.2.1-rc.2`**, using Node 22; the benchmark below ran on `0.2.0-rc.2`, and real smoke runs were verified on `0.2.1-rc.2`. Peer dependencies for the `@deepseek-ai/dsh-*` packages accept `^0.1.5-rc.1 || ^0.2.0-rc.1 || ^0.2.1-rc.1`. 1.2.5 decides thinking/effort at decision points per trigger, using evidence and a cost estimate per option, as detailed under “How it works”; compatibility with dsh 0.2.1's subagent start API (`startActivation`) and 0.2.0 is kept. The npm package is `dsh-autoctx`, its entry is `index.js`, and its web client is `./client.js`.
 
 You must provide:
 
@@ -31,7 +31,7 @@ Without `apiKey`, the plugin makes no network call, the session runs in native m
    ```sh
    dsh plugin --profile autoctx add dsh-autoctx
    # Or use the release tag
-   dsh plugin --profile autoctx add github:ZhiweiWei-NAMI/dsh-autoctx#v1.2.4
+   dsh plugin --profile autoctx add github:ZhiweiWei-NAMI/dsh-autoctx#v1.2.5
    ```
 
    `dsh plugin --profile <name> <pnpm-args...>` passes arguments to pnpm. Profiles live in `$DSH_HOME/profiles/<name>`. The package's declared dsh bundle patch (`cordis.patch.yml`) mounts the plugin and disables native `compaction-basic`; no duplicate manual mount is needed.
@@ -61,7 +61,7 @@ Upgrade to the latest version, or pin this version:
 ```sh
 dsh plugin --profile autoctx add dsh-autoctx@latest
 # Or pin the version
-dsh plugin --profile autoctx add dsh-autoctx@1.2.4
+dsh plugin --profile autoctx add dsh-autoctx@1.2.5
 ```
 
 Before uninstalling, delete any `- id: dsh-autoctx` override you added to the profile's `cordis.patch.yml`, then run:
@@ -91,9 +91,13 @@ In the web UI, open bottom-left **Settings → DSH AutoCTX**, or **Plugins → d
 | `advisorMaxConsults` | `1`; advisor consultation cap |
 | `advisorStallSteps` | `6`; stall step threshold |
 | `adaptiveEffort` | `high`; effort used when Jev's thinking policy calls for it; `off` keeps the default effort |
+| `effortSwitchFreeTokens` | `4096`; a decision-point thinking switch whose estimated uncached re-read is at most this proceeds without asking Jev |
+| `maxEffortDecisions` | `6`; separate Jev effort-decision calls per root task; never spends `maxDecisions` |
+| `effortPhaseRequests` | `4`; maximum high-effort requests in a thinking phase; a new trigger renews the window |
+| `cacheTtlSeconds` | `300`; assumed cache-reuse lifetime used in runtime estimates; the provider TTL is unverified |
 | `learning` | `frozen`; choices: `auto`, `manual`, `frozen` |
 | `contextSelection` | `jev`; choices: `jev`, `summary` |
-| `maxDecisions` | `12`; Jev decision calls per root task |
+| `maxDecisions` | `12`; Jev routing/context decision calls per root task |
 | `maxChildren` | `2`; child count cap |
 | `maxConcurrent` | `2`; concurrent child count cap |
 | `maxChildRequests` | `16`; child request cap |
@@ -106,7 +110,9 @@ In the web UI, open bottom-left **Settings → DSH AutoCTX**, or **Plugins → d
 
 **Decisions.** A plain single agent keeps one growing context; native subagents are chosen by the executor through spawn/fork, and native compaction summarizes old context. AutoCTX asks Jev for structured decisions at specific points. Jev is a scoring/choice model; it does not write plans or code. It decides whether a proposed delegation is worth a child and which route to use; gives a task tag and thinking policy at turn start; selects evidence under context pressure and chooses whether to replace context now or later, weighing the cost of re-reading uncached content against smaller later requests; and selects reviewer/advisor models when those roles are set to `auto`.
 
-Thinking policies are `off`, `decision_points`, or `always`; decision points are turn start, test failure, review/advisor report and stall. Calls per task are capped by `maxDecisions`. A transient Jev gateway/network failure is retried once, then Jev pauses for 60 seconds. Authentication, billing or HTTP 429 stops Jev for the task, and local fallbacks take over: native compaction and no delegation.
+Thinking policies are `off`, `decision_points`, or `always`; decision points are turn start, test failure, review/advisor report and stall. In 1.2.5, each trigger supplies evidence such as a failing-test output excerpt, diff hunk, review/advisor report text or task head, with an estimated cost per option at catalog prices: `skip` stays in the current cache space; `pulse` makes one high-effort request; `phase` keeps high effort until the trigger is resolved (test passes, report acted on, progress) or `effortPhaseRequests` requests. Cheap switches (estimated uncached re-read ≤ `effortSwitchFreeTokens`) and switches right after a context replacement proceed without asking Jev. Effort questions use their own `maxEffortDecisions` budget and never spend the 12 routing/context decisions in `maxDecisions`. Cache reuse is estimated from exact request prefixes, with no rewriting, reordering or dropping of context for cache; these runtime estimates are theoretical, not actual bills.
+
+A transient Jev gateway/network failure is retried once, then Jev pauses for 60 seconds. Authentication, billing or HTTP 429 stops Jev for the task, and local fallbacks take over: native compaction and no delegation.
 
 **Context selection.** With `contextSelection: jev`, when context passes `pressureTokens`, the old region is split into evidence pieces—test-failure sections, diff hunks, code by function/class and paragraphs—rather than whole outputs. Jev scores how much each piece adds given the stated open problem, such as which test still fails, and the content kept regardless. Locally, duplicates keep one copy; a kept report pulls in the definition it refers to; pieces that add little are archived as one line each. At `pressureTokens × ceilingRatio`, the session must shrink, using native compaction if needed. `summary` lets the executor summarize instead.
 
@@ -124,42 +130,56 @@ Automatic learning is expected to maintain quality while lowering cost over time
 
 ## Extra calls and cost
 
-Jev calls, reviewer/advisor children and their executor-model calls, and the turn-end learning call all cost money on your own API accounts. These are not free services. The model table in `models.json` lists `jev-1.13` at **$0.042 per 1 million input tokens, $0 for output tokens**; `jev-1.13-free` is rate limited. Benchmark costs below are estimates at API catalog prices.
+Jev calls, reviewer/advisor children and their executor-model calls, and the turn-end learning call all cost money on your own API accounts. These are not free services. The model table in `models.json` lists catalog prices for `jev-1.13` at **$0.042 per 1 million input tokens, $0 for output tokens**; `jev-1.13-free` is rate limited. Benchmark costs below are theoretical estimates at catalog prices, not actual bills (defined in the benchmark section). Over the 72 cases, 1.2.5 makes 368 Jev calls versus 233 for 1.2.3 frozen; these calls also count toward a task's request limit.
 
 ## Benchmark results and limitations
 
 These results describe this run, not general superiority. Every arm uses the same **72 graded cases = 12 fixed SWE-bench Verified pytest tasks (`bench/tasks.json`) × 3 executor models × 2 runs per model**. Executors are `deepseek-v4.1-flash`, `glm-5.3-flash` and `deepseek-v4-flash`. The official SWE-bench harness **v4.1.0** decides resolved; a finished run or HTTP 200 is not a pass.
 
-Limits are identical for every arm: **600 seconds per task, 64 model requests per task (including Jev calls for AutoCTX), case parallelism 3, at most 2 children / 2 concurrent children**.
+Shared limits are **600 seconds per task, 64 model requests per task (Jev included), case parallelism 3, at most 2 children / 2 concurrent children**. AutoCTX and H used a $0.10 per-case spend cap; B and C used the harness default $0.50. No case in any arm exceeded $0.066 (theoretical, at catalog prices), so the spend cap never bound.
 
 | Arm | Configuration |
 | --- | --- |
 | B | Single agent; no subagent tools, native compaction |
 | C | Native spawn/fork with the executor model only; native compaction, no reviewer/advisor/extra models |
 | H | Native heterogeneous subagents; one native subagent tool per (model, effort) over the executor plus 3 extra models, chosen by the executor |
-| AutoCTX frozen / auto | 1.2.3; reviewer `auto`, advisor `auto`, the same 3 extra models, `jev-1.13`; frozen and auto learning respectively; auto carries the ledger across cases within a run |
+| AutoCTX 1.2.5 frozen | New release; reviewer `auto`, advisor `auto`, the same 3 extra models, `jev-1.13`; frozen learning |
+| AutoCTX 1.2.3 frozen / auto | Previous release, same harness; reviewer `auto`, advisor `auto`, the same 3 extra models, `jev-1.13`; frozen and auto learning respectively; auto carries the ledger across cases within a run |
+
+The 3 extra models are `glm-5.3-flash` (use `deepseek-v4.1-flash` when the executor is glm), `deepseek-v4-pro` and `claude-haiku-5-5`. 1.2.5 ran on dsh `0.2.0-rc.2`, the same host version as 1.2.3/B/C/H. B/C/H do not load the plugin and were run before 1.2.3. B/C used the same harness entry as AutoCTX; H run 1 used an earlier harness snapshot (its `run.py` differs) with the same tasks and shared limits above.
+
+**Theoretical cost basis.** All cost and cache figures below are **theoretical estimates at catalog prices, not actual bills**. Provider-reported cache hits vary with routing, accounts and eviction, so all arms are compared on the prompt cache they could reuse given exactly what they sent, with identical assumptions and prices: a request reuses the longest prefix it shares with an earlier request of the same task in the same cache space (model + thinking/effort config [+ tools]); no expiry within a task. Uncached input uses the catalog input price (cache-write price where listed), reused input the cache-read price, and output the output price; Jev is $0.042/M input, output free; executor, child and Jev costs are all included. This benchmark's no-expiry-within-task assumption differs from the runtime lifetime assumption in `cacheTtlSeconds`.
+
+Two measurement methods: `exact` uses per-message prefix hashes recorded by the bench observer (AutoCTX 1.2.x runs). B/C/H were recorded before prefix hashes existed, so they use a `log` reconstruction (append-only growth per session; an input drop marks a context rewrite). Validation by re-running B and C on 12 tasks with `deepseek-v4.1-flash` and prefix hashes (24 cases): `log` gave 2.4% (B) and 3.1% (C) lower cost than `exact`; on AutoCTX it gives about 11% lower cost, because context replacement changes earlier prompt content without necessarily shrinking it. The baseline theoretical figures below are therefore probably ~3% low, and the AutoCTX premium is slightly overstated rather than understated.
+
+Costs and cache rates in this table are theoretical estimates, not actual bills.
+
+| Metric (72 cases per arm) | AutoCTX 1.2.5 frozen | AutoCTX 1.2.3 frozen | AutoCTX 1.2.3 auto | B | C | H |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Resolved / 72 | 53/72 | 52/72 | 49/72 | 39/72 | 44/72 | 42/72 |
+| Paired wins/losses of 1.2.5 frozen vs this arm (exact McNemar p) | — | 6/5 (p=1.0) | — | 15/1 (p=0.001) | 12/3 (p=0.035) | 13/2 (p=0.007) |
+| Theoretical cost, total USD (method) | $1.738 (exact) | $1.810 (exact) | $1.603 (exact) | $0.908 (log) | $0.975 (log) | $1.027 (log) |
+| Of which theoretical cost: executor / children / Jev (USD) | 1.383 / 0.273 / 0.082 | 1.451 / 0.284 / 0.076 | 1.321 / 0.214 / 0.068 | 0.805 / 0.102 / 0 | 0.844 / 0.131 / 0 | 0.867 / 0.160 / 0 |
+| Theoretical cost per resolved case | $0.0328 | $0.0348 | $0.0327 | $0.0233 | $0.0222 | $0.0244 |
+| Theoretical executor cache rate | 87.0% | 85.4% | 86.5% | 94.8% | 95.1% | 95.1% |
+| Wall time sum (seconds) | 17580 | 18060 | 17670 | 17454 | 16520 | 17076 |
+| Jev calls ok/all | 367/368 | 233/233 | 260/260 | — | — | — |
 
-The 3 extra models are `glm-5.3-flash` (use `deepseek-v4.1-flash` when the executor is glm), `deepseek-v4-pro` and `claude-haiku-5-5`. These results were measured with 1.2.3 on dsh 0.2.0-rc.2; 1.2.4 changes only the host compatibility layer and was not re-benchmarked. B/C/H do not load the plugin and were run before 1.2.3. B/C used the same harness entry as 1.2.3; H run 1 used an earlier harness snapshot (its `run.py` differs) with the same tasks and the limits above.
+With the `log` method applied to every arm, the theoretical total is $1.547 for AutoCTX 1.2.5 frozen versus B $0.908, C $0.975 and H $1.027.
 
-| Metric (72 cases per arm) | AutoCTX frozen | AutoCTX auto | B | C | H |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| Resolved / 72 | 52/72 | 49/72 | 39/72 | 44/72 | 42/72 |
-| Estimated API catalog cost, executor + children + Jev (USD) | $1.514 | $1.374* | $0.876 | $0.933 | $1.018 |
-| Jev portion of the above cost (USD) | $0.076 | $0.068* | N/A | N/A | N/A |
-| Wall time sum (seconds) | 18060 | 17670 | 17454 | 16520 | 17076 |
-| Prompt cache hit rate | 87.5% | 88.4% | 94.3% | 94.6% | 93.9% |
+AutoCTX resolves more cases than B, C and H on this sample and costs more; on theoretical cost, 1.2.5 frozen is about 70–80% more than C overall and ~48% more per resolved case. Comparing 1.2.5 with 1.2.3 frozen, lane-matched and `exact`: 53 vs 52 resolved (6 wins / 5 losses, no quality difference); theoretical total cost is down 4.0% ($1.738 vs $1.810), theoretical executor cache rate is 87.0% vs 85.4%, and theoretical Jev cost is up $0.006.
 
-\* Auto had 1 request without usage, which is unpriced.
+1.2.5 effort decisions across 72 cases: 201 cheap (no Jev call), 86 skip, 51 phase, 9 pulse, 11 after context replacement, and 11 fell back after the effort budget was spent; 19 cases reached the 64-request limit (1.2.3: 18). The limit counts Jev calls, so AutoCTX reaches it with fewer executor requests than the baselines: 10 of those 19 cases were unresolved, and Jev made 77 of their 640 requests (12%). B/C/H also hit the limit (17/20/16 cases), with executor requests only. This benchmark keeps the shared limit; a rerun excluding Jev from it has not been done.
 
-| Executor (24 cases per model per arm; resolved / 24) | Frozen | Auto | B | C | H |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| deepseek-v4.1-flash | 17/24 | 16/24 | 11/24 | 15/24 | 14/24 |
-| glm-5.3-flash | 18/24 | 18/24 | 17/24 | 18/24 | 18/24 |
-| deepseek-v4-flash | 17/24 | 15/24 | 11/24 | 11/24 | 10/24 |
+| Executor (24 cases per model per arm; resolved / 24) | AutoCTX 1.2.5 frozen | AutoCTX 1.2.3 frozen | AutoCTX 1.2.3 auto | B | C | H |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| deepseek-v4.1-flash | 18/24 | 17/24 | 16/24 | 11/24 | 15/24 | 14/24 |
+| glm-5.3-flash | 17/24 | 18/24 | 18/24 | 17/24 | 18/24 | 18/24 |
+| deepseek-v4-flash | 18/24 | 17/24 | 15/24 | 11/24 | 11/24 | 10/24 |
 
-In the auto run, 49 completed turns reached learning: 35/49 were judged unassessable and left weights unchanged; 14/49 applied small updates. Auto did not outperform frozen here. Possible explanations for the lower cache rate include context replacement rewriting part of the prompt, review/advisor briefs, and Jev-switched thinking modes adding new uncached input. These are hypotheses, not proven causes.
+In the auto run, 49 completed turns reached learning: 35/49 were judged unassessable and left weights unchanged; 14/49 applied small updates. Auto did not outperform frozen here.
 
-Only these 12 pytest tasks and 3 flash executors were measured; between repeats, resolved counts vary by about ±2 cases per 12-task run. AutoCTX costs more than the baselines here; auto learning remains beta. There is also a host limitation: a fork created mid-turn is seeded only with completed turns, so the review brief must carry the current turn's evidence itself.
+Only these 12 pytest tasks and 3 flash executors were measured; between repeats, resolved counts vary by about ±2 cases per 12-task run. AutoCTX costs more than the baselines here on the theoretical cost basis; auto learning remains beta and off by default. There is also a host limitation: a fork created mid-turn is seeded only with completed turns, so the review brief must carry the current turn's evidence itself.
 
 ## Reproduce
 
@@ -173,10 +193,11 @@ python3 bench/run.py --model deepseek-v4.1-flash --arms B,C --tasks bench/tasks.
 python3 bench/run.py --model deepseek-v4.1-flash --arms H --tasks bench/tasks.json --out <dir> --plugin . --parallel 3 \
   --extra-models glm-5.3-flash,deepseek-v4-pro,claude-haiku-5-5 --max-usd 0.10
 python3 bench/grade.py <dir> --parallel 3
+python3 bench/theoretical_cost.py "A=<dir>/*/A" "B=<dir>/*/B" "C=<dir>/*/C"
 ```
 
-Replace `<dir>` with an output directory. A is AutoCTX; use separate directories for frozen and auto. Run for all 3 executor models, with 2 runs per model and separate directories for independent runs. For `glm-5.3-flash`, change `--extra-models` to `deepseek-v4.1-flash,deepseek-v4-pro,claude-haiku-5-5`; `deepseek-v4-flash` uses the extra models shown above. Re-running the same command resumes unfinished cases. `--max-usd 0.10` is the bench observer's $0.10 per-case spend cap.
+Replace `<dir>` with an output directory. A is AutoCTX; use separate directories for frozen and auto. Run for all 3 executor models, with 2 runs per model and separate directories for independent runs. For `glm-5.3-flash`, change `--extra-models` to `deepseek-v4.1-flash,deepseek-v4-pro,claude-haiku-5-5`; `deepseek-v4-flash` uses the extra models shown above. Re-running the same command resumes unfinished cases. `--max-usd 0.10` is the bench observer's $0.10 per-case spend cap. `bench/theoretical_cost.py` estimates cost and cache reuse with the method above; its outputs are theoretical estimates, not actual bills.
 
 ## Upgrading from older versions
 
-Install 1.2.4 using the upgrade steps above and check profile overrides against the current configuration table. Do not carry over the old README's default model or installation tag: the current default is billed `jev-1.13`, and the release tag is `v1.2.4`.
+Install 1.2.5 using the upgrade steps above and check profile overrides against the current configuration table. Do not carry over the old README's default model or installation tag: the current default is billed `jev-1.13`, and the release tag is `v1.2.5`.

package/README.md

@@ -1,12 +1,12 @@
 # dsh-autoctx
 
-面向 dsh 的上下文与子代理决策插件，版本 **1.2.4**。Jev 负责评分和结构化选择，插件通过 dsh 原生会话、工具、子代理和压缩执行决策；编码仍由执行模型完成。
+面向 dsh 的上下文与子代理决策插件，版本 **1.2.5**。Jev 负责评分和结构化选择，插件通过 dsh 原生会话、工具、子代理和压缩执行决策；编码仍由执行模型完成。
 
 [English](https://github.com/ZhiweiWei-NAMI/dsh-autoctx/blob/main/README.en.md) · [源码](https://github.com/ZhiweiWei-NAMI/dsh-autoctx) · MIT
 
 ## 环境与所需账号
 
-已验证的宿主为 **dsh `0.2.0-rc.2` 与 `0.2.1-rc.2`**，使用 Node 22。`@deepseek-ai/dsh-*` 包的 peer dependency 范围为 `^0.1.5-rc.1 || ^0.2.0-rc.1 || ^0.2.1-rc.1`。1.2.4 适配 dsh 0.2.1 的子代理启动接口（`startActivation`），同时兼容 0.2.0；调度与学习逻辑与 1.2.3 相同。npm 包名为 `dsh-autoctx`，入口为 `index.js`，Web 客户端为 `./client.js`。
+单元测试通过的宿主为 **dsh `0.2.0-rc.2` 与 `0.2.1-rc.2`**，使用 Node 22；下方基准运行于 `0.2.0-rc.2`，真实 smoke 运行已在 `0.2.1-rc.2` 验证。`@deepseek-ai/dsh-*` 包的 peer dependency 范围为 `^0.1.5-rc.1 || ^0.2.0-rc.1 || ^0.2.1-rc.1`。1.2.5 按每次触发的证据和各选项成本估算决定决策点的思考强度，细节见「工作方式」；保留对 dsh 0.2.1 子代理启动接口（`startActivation`）及 0.2.0 的兼容。npm 包名为 `dsh-autoctx`，入口为 `index.js`，Web 客户端为 `./client.js`。
 
 你需要提供：
 
@@ -31,7 +31,7 @@
    ```sh
    dsh plugin --profile autoctx add dsh-autoctx
    # 或使用发布标签
-   dsh plugin --profile autoctx add github:ZhiweiWei-NAMI/dsh-autoctx#v1.2.4
+   dsh plugin --profile autoctx add github:ZhiweiWei-NAMI/dsh-autoctx#v1.2.5
    ```
 
    `dsh plugin --profile <name> <pnpm-args...>` 把参数传给 pnpm。Profile 位于 `$DSH_HOME/profiles/<name>`。包声明的 dsh bundle patch（`cordis.patch.yml`）会挂载插件并停用原生 `compaction-basic`，无需手工重复挂载。
@@ -61,7 +61,7 @@ dsh --profile autoctx --patch "$DSH_HOME/profiles/autoctx/node_modules/dsh-autoc
 ```sh
 dsh plugin --profile autoctx add dsh-autoctx@latest
 # 或固定版本
-dsh plugin --profile autoctx add dsh-autoctx@1.2.4
+dsh plugin --profile autoctx add dsh-autoctx@1.2.5
 ```
 
 卸载前，先删除自己在 profile 的 `cordis.patch.yml` 中添加的 `- id: dsh-autoctx` 覆盖项，再执行：
@@ -91,9 +91,13 @@ Web 界面：左下角 **Settings → DSH AutoCTX**，或 **Plugins → dsh-auto
 | `advisorMaxConsults` | `1`；顾问咨询上限 |
 | `advisorStallSteps` | `6`；停滞步数阈值 |
 | `adaptiveEffort` | `high`；Jev 思考策略要求时使用的 effort；`off` 保留默认 effort |
+| `effortSwitchFreeTokens` | `4096`；决策点切换思考强度时，预计未缓存重读量不超过此值则不询问 Jev |
+| `maxEffortDecisions` | `6`；每个根任务独立的 Jev 思考决策调用上限；不占用 `maxDecisions` |
+| `effortPhaseRequests` | `4`；思考阶段内高强度请求上限；新触发会续期 |
+| `cacheTtlSeconds` | `300`；运行时估算假设的缓存复用寿命；提供方 TTL 未验证 |
 | `learning` | `frozen`；可选 `auto`、`manual`、`frozen` |
 | `contextSelection` | `jev`；可选 `jev`、`summary` |
-| `maxDecisions` | `12`；每个根任务的 Jev 决策调用上限 |
+| `maxDecisions` | `12`；每个根任务的 Jev 路由/上下文决策调用上限 |
 | `maxChildren` | `2`；子代理数量上限 |
 | `maxConcurrent` | `2`；并发子代理数量上限 |
 | `maxChildRequests` | `16`；子代理请求上限 |
@@ -106,7 +110,9 @@ Web 界面：左下角 **Settings → DSH AutoCTX**，或 **Plugins → dsh-auto
 
 **决策。** 普通单代理持续累积一份上下文；原生子代理由执行模型自行选择 spawn/fork，原生压缩总结旧上下文。AutoCTX 在特定节点向 Jev 请求结构化决策。Jev 是评分/选择模型，不编写计划或代码。它判断拟议委派是否值得创建子代理及采用哪条路由；在回合开始给出任务标签与思考策略；在上下文压力下选择证据并判断现在还是稍后替换上下文，权衡重新读取未缓存内容的成本与后续请求缩小的收益；当角色设为 `auto` 时选择 reviewer/advisor 模型。
 
-思考策略为 `off`、`decision_points` 或 `always`；决策点包括回合开始、测试失败、审查/顾问报告和停滞。每个任务的决策次数受 `maxDecisions` 限制。临时 Jev 网关/网络失败会重试一次，随后暂停 Jev 60 秒；认证、计费或 HTTP 429 会停止该任务的 Jev 调用，由本地回退接管：原生压缩、不委派。
+思考策略为 `off`、`decision_points` 或 `always`；决策点包括回合开始、测试失败、审查/顾问报告和停滞。1.2.5 为每次触发提供失败测试输出摘录、diff hunk、审查/顾问报告文本或任务开头等证据，并按目录价给出各选项的估算成本：`skip` 留在当前缓存空间；`pulse` 仅一次高强度请求；`phase` 保持高强度，直到触发问题解决（测试通过、报告已处理、取得进展）或达到 `effortPhaseRequests` 次请求。预计未缓存重读量不超过 `effortSwitchFreeTokens` 的低成本切换，以及紧接上下文替换后的切换，不询问 Jev。思考决策使用独立的 `maxEffortDecisions`，不占用 `maxDecisions` 的 12 次路由/上下文决策。缓存复用按实际请求的精确前缀估算，不为缓存改写、重排或丢弃上下文；这些运行时估算均为理论值，非实际账单。
+
+临时 Jev 网关/网络失败会重试一次，随后暂停 Jev 60 秒；认证、计费或 HTTP 429 会停止该任务的 Jev 调用，由本地回退接管：原生压缩、不委派。
 
 **上下文选择。** `contextSelection: jev` 在上下文超过 `pressureTokens` 时，把旧区域拆成测试失败段、diff hunk、按函数/类划分的代码和段落等证据片段，而非整块输出。Jev 根据明确的待解决问题（例如仍失败的测试）以及必留内容，评估每片证据额外提供了什么。插件本地去重只保留一份；保留的报告会带入其引用的定义；增益低的片段各归档为一行。达到 `pressureTokens × ceilingRatio` 时必须缩减，必要时使用原生压缩。`summary` 则由执行模型总结。
 
@@ -124,42 +130,56 @@ Web 界面：左下角 **Settings → DSH AutoCTX**，或 **Plugins → dsh-auto
 
 ## 额外调用与费用
 
-Jev 调用、reviewer/advisor 子代理及其执行模型调用、回合结束时的学习调用，均由用户自己的 API 账号承担费用，不是免费服务。`models.json` 模型表中 `jev-1.13` 的价格为 **每 100 万输入 tokens $0.042，输出 tokens $0**；`jev-1.13-free` 有限流。下方基准的费用为 API 目录价估算。
+Jev 调用、reviewer/advisor 子代理及其执行模型调用、回合结束时的学习调用，均由用户自己的 API 账号承担费用，不是免费服务。`models.json` 模型表中 `jev-1.13` 的目录价为 **每 100 万输入 tokens $0.042，输出 tokens $0**；`jev-1.13-free` 有限流。下方基准费用均为按目录价的理论估算，非实际账单（定义见基准一节）。1.2.5 在 72 个案例中调用 Jev 368 次，1.2.3 frozen 为 233 次；这些调用也占用任务请求上限。
 
 ## 基准结果与限制
 
 仅报告本次运行，不代表普遍优势。每组使用相同的 **72 个评分案例 = 12 个固定 SWE-bench Verified pytest 任务（`bench/tasks.json`）× 3 个执行模型 × 每模型 2 次运行**。执行模型为 `deepseek-v4.1-flash`、`glm-5.3-flash`、`deepseek-v4-flash`。官方 SWE-bench harness **v4.1.0** 判定 resolved；运行完成或 HTTP 200 均不等于通过。
 
-每组限制相同：**每任务 600 秒、每任务 64 个模型请求（AutoCTX 包含 Jev 调用）、案例并行数 3、最多 2 个子代理/2 个并发子代理**。
+共同限制为：**每任务 600 秒、每任务 64 个模型请求（包含 Jev 调用）、案例并行数 3、最多 2 个子代理/2 个并发子代理**。AutoCTX 与 H 的每案例花费上限为 $0.10，B 与 C 使用 harness 默认的 $0.50；各组均无案例的理论费用（目录价）超过 $0.066，因此花费上限未起约束作用。
 
 | 组别 | 配置 |
 | --- | --- |
 | B | 单代理；无子代理工具，原生压缩 |
 | C | 原生 spawn/fork，仅执行模型；原生压缩，无 reviewer/advisor/额外模型 |
 | H | 原生异构子代理；在执行模型及额外 3 个模型的每个（模型，effort）组合上提供一个原生子代理工具，由执行模型选择 |
-| AutoCTX frozen / auto | 1.2.3；reviewer `auto`、advisor `auto`、相同的额外 3 个模型、`jev-1.13`；分别使用 frozen 和 auto 学习；auto 在同一次运行的案例间沿用账本 |
+| AutoCTX 1.2.5 frozen | 新版本；reviewer `auto`、advisor `auto`、相同的额外 3 个模型、`jev-1.13`；frozen 学习 |
+| AutoCTX 1.2.3 frozen / auto | 上一版本，相同 harness；reviewer `auto`、advisor `auto`、相同的额外 3 个模型、`jev-1.13`；分别使用 frozen 和 auto 学习；auto 在同一次运行的案例间沿用账本 |
+
+额外 3 个模型为 `glm-5.3-flash`（执行模型为它时改用 `deepseek-v4.1-flash`）、`deepseek-v4-pro`、`claude-haiku-5-5`。1.2.5 与 1.2.3/B/C/H 均运行于 dsh `0.2.0-rc.2`。B/C/H 不加载插件，均早于 1.2.3 运行。B/C 与 AutoCTX 使用同一 harness 入口；H 第 1 轮使用更早的 harness 快照（`run.py` 有差异），任务和上述共同限制相同。
+
+**理论费用依据。** 下文所有费用与缓存数据均为**按目录价的理论估算，非实际账单**。提供方报告的缓存命中受路由、账号和驱逐影响，因此各组按实际发送的 prompt 可复用的缓存，以相同假设和价格比较：请求复用同任务、同缓存空间（模型 + thinking/effort 配置［+ tools］）内与此前请求共享的最长前缀；任务内不设过期。未缓存输入按目录输入价（列有缓存写入价时用写入价），复用输入按缓存读取价，输出按输出价；Jev 输入 $0.042/百万 tokens，输出免费；包含执行模型、子代理及 Jev 的全部费用。此基准的任务内不设过期假设与运行时 `cacheTtlSeconds` 的寿命假设不同。
+
+两种测量方法：`exact` 使用 bench observer 记录的逐消息前缀哈希（AutoCTX 1.2.x）；B/C/H 运行时尚无前缀哈希，使用 `log` 重建（每个 session 按追加增长，输入量下降标记上下文改写）。在 12 个任务上用 `deepseek-v4.1-flash` 重跑 B/C、记录前缀哈希（24 个案例）验证：`log` 比 `exact` 的费用低 2.4%（B）和 3.1%（C）；在 AutoCTX 上约低 11%，因为上下文替换会改动较早的 prompt 内容却不一定缩短输入。因此下表基线理论费用可能低估约 3%，AutoCTX 溢价略被高估，而非低估。
+
+下表费用与缓存率为理论估算，非实际账单。
+
+| 指标（每组 72 个案例） | AutoCTX 1.2.5 frozen | AutoCTX 1.2.3 frozen | AutoCTX 1.2.3 auto | B | C | H |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| Resolved / 72 | 53/72 | 52/72 | 49/72 | 39/72 | 44/72 | 42/72 |
+| 1.2.5 frozen 对该组的配对胜/负（精确 McNemar p） | — | 6/5 (p=1.0) | — | 15/1 (p=0.001) | 12/3 (p=0.035) | 13/2 (p=0.007) |
+| 理论总费用 USD（方法） | $1.738 (exact) | $1.810 (exact) | $1.603 (exact) | $0.908 (log) | $0.975 (log) | $1.027 (log) |
+| 其中理论费用：执行模型 / 子代理 / Jev（USD） | 1.383 / 0.273 / 0.082 | 1.451 / 0.284 / 0.076 | 1.321 / 0.214 / 0.068 | 0.805 / 0.102 / 0 | 0.844 / 0.131 / 0 | 0.867 / 0.160 / 0 |
+| 每个 resolved 案例的理论费用 | $0.0328 | $0.0348 | $0.0327 | $0.0233 | $0.0222 | $0.0244 |
+| 执行模型理论缓存率 | 87.0% | 85.4% | 86.5% | 94.8% | 95.1% | 95.1% |
+| 墙钟时间总和（秒） | 17580 | 18060 | 17670 | 17454 | 16520 | 17076 |
+| Jev 调用成功/总数 | 367/368 | 233/233 | 260/260 | — | — | — |
 
-额外 3 个模型为 `glm-5.3-flash`（执行模型为它时改用 `deepseek-v4.1-flash`）、`deepseek-v4-pro`、`claude-haiku-5-5`。以下结果为 1.2.3 在 dsh 0.2.0-rc.2 上的测量；1.2.4 只改动宿主兼容层，未重新跑基准。B/C/H 不加载插件，均早于 1.2.3 运行。B/C 与 1.2.3 使用同一 harness 入口；H 第 1 轮使用更早的 harness 快照（`run.py` 有差异），任务和上述限制相同。
+若全部组统一用 `log` 方法，理论总费用为 AutoCTX 1.2.5 frozen $1.547，B 为 $0.908、C 为 $0.975、H 为 $1.027。
 
-| 指标（每组 72 个案例） | AutoCTX frozen | AutoCTX auto | B | C | H |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| Resolved / 72 | 52/72 | 49/72 | 39/72 | 44/72 | 42/72 |
-| API 目录价估算费用，执行模型 + 子代理 + Jev（USD） | $1.514 | $1.374* | $0.876 | $0.933 | $1.018 |
-| 上述费用中的 Jev（USD） | $0.076 | $0.068* | 不适用 | 不适用 | 不适用 |
-| 墙钟时间总和（秒） | 18060 | 17670 | 17454 | 16520 | 17076 |
-| Prompt 缓存命中率 | 87.5% | 88.4% | 94.3% | 94.6% | 93.9% |
+AutoCTX 在此样本中比 B、C、H 解决更多案例，也更贵；按理论费用，1.2.5 frozen 比 C 总费用约高 70–80%，每个 resolved 案例约高 48%。1.2.5 与 1.2.3 frozen 按相同运行通道配对、使用 `exact` 比较：53 对 52 个 resolved（6 胜 / 5 负，无质量差异）；理论总费用降低 4.0%（$1.738 对 $1.810），执行模型理论缓存率 87.0% 对 85.4%，Jev 理论费用增加 $0.006。
 
-\* Auto 有 1 个请求缺少 usage，未计价。
+1.2.5 在 72 个案例中的思考决策：201 次低成本切换（不调用 Jev）、86 次 skip、51 次 phase、9 次 pulse、11 次紧接上下文替换、11 次在思考预算用尽后回退；19 个案例达到 64 请求上限（1.2.3 为 18 个）。该上限包含 Jev 调用，因此 AutoCTX 在执行请求更少时就会触顶：这 19 个案例中有 10 个未解决，其 640 次请求里 77 次（12%）为 Jev 调用。B/C/H 也分别有 17/20/16 个案例触顶，但全部为执行请求。本基准保持该共同上限；把 Jev 排除在上限之外的重跑尚未进行。
 
-| 执行模型（每组、每模型 24 个案例；resolved / 24） | Frozen | Auto | B | C | H |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| deepseek-v4.1-flash | 17/24 | 16/24 | 11/24 | 15/24 | 14/24 |
-| glm-5.3-flash | 18/24 | 18/24 | 17/24 | 18/24 | 18/24 |
-| deepseek-v4-flash | 17/24 | 15/24 | 11/24 | 11/24 | 10/24 |
+| 执行模型（每组、每模型 24 个案例；resolved / 24） | AutoCTX 1.2.5 frozen | AutoCTX 1.2.3 frozen | AutoCTX 1.2.3 auto | B | C | H |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| deepseek-v4.1-flash | 18/24 | 17/24 | 16/24 | 11/24 | 15/24 | 14/24 |
+| glm-5.3-flash | 17/24 | 18/24 | 18/24 | 17/24 | 18/24 | 18/24 |
+| deepseek-v4-flash | 18/24 | 17/24 | 15/24 | 11/24 | 11/24 | 10/24 |
 
-Auto 运行中，49 个已完成回合进入学习：35/49 个被判无法评估，权重不变；14/49 个应用了小幅更新。此处 auto 未超过 frozen。较低缓存命中率的可能解释包括上下文替换改写部分 prompt、review/advisor 简报以及 Jev 切换思考模式带来新的未缓存输入；这些仅是假设，未证实因果。
+Auto 运行中，49 个已完成回合进入学习：35/49 个被判无法评估，权重不变；14/49 个应用了小幅更新。此处 auto 未超过 frozen。
 
-测量范围仅为上述 12 个 pytest 任务和 3 个 flash 执行模型；重复运行之间，每次共 12 个任务的运行，resolved 数约波动 ±2 个。AutoCTX 在此处比基线更贵；auto learning 仍为 beta。宿主还存在限制：回合中途创建的 fork 只继承已完成回合，因此审查简报须自行携带当前回合证据。
+测量范围仅为上述 12 个 pytest 任务和 3 个 flash 执行模型；重复运行之间，每次共 12 个任务的运行，resolved 数约波动 ±2 个。按理论费用，AutoCTX 在此处比基线更贵；auto learning 仍为 beta，默认关闭。宿主还存在限制：回合中途创建的 fork 只继承已完成回合，因此审查简报须自行携带当前回合证据。
 
 ## 复现
 
@@ -173,10 +193,11 @@ python3 bench/run.py --model deepseek-v4.1-flash --arms B,C --tasks bench/tasks.
 python3 bench/run.py --model deepseek-v4.1-flash --arms H --tasks bench/tasks.json --out <dir> --plugin . --parallel 3 \
   --extra-models glm-5.3-flash,deepseek-v4-pro,claude-haiku-5-5 --max-usd 0.10
 python3 bench/grade.py <dir> --parallel 3
+python3 bench/theoretical_cost.py "A=<dir>/*/A" "B=<dir>/*/B" "C=<dir>/*/C"
 ```
 
-`<dir>` 替换为输出目录。A 是 AutoCTX；frozen 与 auto 使用各自目录。对全部 3 个执行模型分别运行，每个模型做 2 次运行，独立运行使用不同目录。`glm-5.3-flash` 对应的 `--extra-models` 改为 `deepseek-v4.1-flash,deepseek-v4-pro,claude-haiku-5-5`；`deepseek-v4-flash` 使用示例中的额外模型。重跑相同命令会续跑未完成案例。`--max-usd 0.10` 是 bench observer 的每案例 $0.10 花费上限。
+`<dir>` 替换为输出目录。A 是 AutoCTX；frozen 与 auto 使用各自目录。对全部 3 个执行模型分别运行，每个模型做 2 次运行，独立运行使用不同目录。`glm-5.3-flash` 对应的 `--extra-models` 改为 `deepseek-v4.1-flash,deepseek-v4-pro,claude-haiku-5-5`；`deepseek-v4-flash` 使用示例中的额外模型。重跑相同命令会续跑未完成案例。`--max-usd 0.10` 是 bench observer 的每案例 $0.10 花费上限。`bench/theoretical_cost.py` 按上文方法估算费用与缓存，输出均为理论估算，非实际账单。
 
 ## 从旧版本升级
 
-按上面的升级步骤安装 1.2.4，并对照当前配置表检查 profile 覆盖项。不要沿用旧 README 中的默认模型或安装标签；当前默认是计费的 `jev-1.13`，发布标签为 `v1.2.4`。
+按上面的升级步骤安装 1.2.5，并对照当前配置表检查 profile 覆盖项。不要沿用旧 README 中的默认模型或安装标签；当前默认是计费的 `jev-1.13`，发布标签为 `v1.2.5`。

package/briefs.js

@@ -39,7 +39,28 @@ function boundedDiff(diff, maxChars) {
   return { diff: kept + (maxChars >= marker.length ? marker : ''), truncated: true };
 }
 
-export async function workspaceDiff(cwd, { maxChars = 12000, timeoutMs = 5000 } = {}) {
+// Rank complete hunks against the failure before truncating; later files can be the relevant ones.
+function effortDiff(diff, focus, maxChars = 1500) {
+  const files = diff.split(/(?=^diff --git )/m).filter(Boolean), candidates = [];
+  let added = 0, removed = 0;
+  const terms = focus.filter(term => typeof term === 'string' && term.length > 2).slice(0, 40);
+  for (const file of files) {
+    for (const line of file.split('\n')) {
+      if (line.startsWith('+') && !line.startsWith('+++')) added++;
+      if (line.startsWith('-') && !line.startsWith('---')) removed++;
+    }
+    const parts = file.split(/(?=^@@ -\d+(?:,\d+)? \+\d+(?:,\d+)? @@)/m);
+    for (const hunk of parts.length > 1 ? parts.slice(1) : ['']) {
+      const value = parts[0] + hunk;
+      candidates.push({ value, score: terms.reduce((sum, term) => sum + Number(value.includes(term)), 0) });
+    }
+  }
+  const stat = `${files.length} files changed, ${added} insertions(+), ${removed} deletions(-)`;
+  const relevant = candidates.sort((a, b) => b.score - a.score)[0]?.value ?? '(no diff)';
+  return (stat + '\n' + relevant).slice(0, maxChars);
+}
+
+export async function workspaceDiff(cwd, { maxChars = 12000, timeoutMs = 5000, focus } = {}) {
   // Without a workspace, git would diff whatever directory the host process runs in.
   if (!cwd) return { diff: '', files: [], untracked: [], truncated: false, error: 'no workspace' };
   try {
@@ -89,7 +110,8 @@ export async function workspaceDiff(cwd, { maxChars = 12000, timeoutMs = 5000 }
       }
     }
     const bounded = boundedDiff(combined, budget(maxChars, 12000));
-    return { ...bounded, files, untracked, truncated: bounded.truncated || omitted };
+    return { ...bounded, files, untracked, truncated: bounded.truncated || omitted,
+      ...(focus ? { evidence: effortDiff(combined, focus) } : {}) };
   } catch (error) {
     return { diff: '', files: [], untracked: [], truncated: false, error: errorText(error) };
   }

package/cachespace.js

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+const nonnegative = (value) => {
+  if (!Number.isFinite(value) || value < 0) throw new RangeError("Expected a finite nonnegative token count");
+  return value;
+};
+
+// Retain digests and counts only. The second chain lets sharedPrefix ignore effort while
+// hashes still fingerprint the complete configuration, including effort, as sent.
+export function fingerprint({ provider, model, reasoningEffort, tools, messages }, tokensOf) {
+  const effort = reasoningEffort ?? null;
+  const config = hash(JSON.stringify({ provider, model, effort, tools }));
+  const toolsHash = hash(JSON.stringify({ tools }));
+  const hashes = [], prefixes = [], tokens = [];
+  let previous = config, prefix = toolsHash;
+  for (const message of messages) {
+    const serialized = JSON.stringify(message);
+    previous = hash(previous + serialized);
+    prefix = hash(prefix + serialized);
+    hashes.push(previous);
+    prefixes.push(prefix);
+    tokens.push(nonnegative(tokensOf(message)));
+  }
+  return { space: `${provider}|${model}|${effort ?? "default"}`, config, toolsHash, hashes, prefixes, tokens };
+}
+
+export function sharedPrefix(a, b) {
+  if (!a || !b || a.toolsHash !== b.toolsHash) return 0;
+  let k = 0;
+  while (k < Math.min(a.prefixes.length, b.prefixes.length) && a.prefixes[k] === b.prefixes[k]) k++;
+  return k;
+}
+
+export function reusableTokens(target, latest, { now, at, ttlMs }) {
+  if (!target || now - at > ttlMs || !Number.isFinite(at)) return 0;
+  // Provider/model identity must match too; effort identifies the destination cache space.
+  const route = (value) => value.space.slice(0, value.space.lastIndexOf("|"));
+  if (route(target) !== route(latest)) return 0;
+  return latest.tokens.slice(0, sharedPrefix(target, latest)).reduce((sum, value) => sum + value, 0);
+}
+
+export function switchEstimate({ latest, target, at, now, ttlMs, pendingTokens, price }) {
+  const totalTokens = latest.tokens.reduce((sum, value) => sum + value, 0) + nonnegative(pendingTokens);
+  const reused = reusableTokens(target, latest, { now, at, ttlMs });
+  const uncachedTokens = totalTokens - reused;
+  const usd = Math.round(uncachedTokens * (price.input - (price.cacheRead ?? price.input))) / 1e6;
+  return { totalTokens, reusableTokens: reused, uncachedTokens, usd };
+}

package/index.js

@@ -26,6 +26,7 @@ import {
   DELEGATION_GUIDANCE,
 } from "./routing.js";
 import { newStats, applyStatsRecord } from "./stats.js";
+import { fingerprint, sharedPrefix, reusableTokens, switchEstimate } from "./cachespace.js";
 import { contributionFacts, learningQuestions, proposalsFrom } from "./learning.js";
 import { segmentUnits, focusTerms } from "./segments.js";
 import { workspaceDiff, hunkContext, failureExcerpt, adviceQuestion, advisorBrief, reviewBrief, attemptsFrom } from "./briefs.js";
@@ -189,6 +190,14 @@ export const Config = z.object({
     .description(
       "Reasoning effort used when Jev judges a phase needs it; it stays for the turn and changes only at a context checkpoint. off keeps the default",
     ),
+  effortSwitchFreeTokens: z.number().min(0).default(4096)
+    .description("Decision-point pulses with at most this estimated uncached re-read proceed without asking Jev"),
+  maxEffortDecisions: z.number().min(0).default(6)
+    .description("Separate Jev effort decision calls per root task; never spends the routing/context budget"),
+  effortPhaseRequests: z.number().min(1).default(4)
+    .description("Maximum high-effort requests after a phase trigger; a new trigger renews this window"),
+  cacheTtlSeconds: z.number().min(0).default(300)
+    .description("Conservative assumed reuse lifetime in seconds; provider cache TTL is unverified"),
   learning: z
     .union(["auto", "manual", "frozen"])
     .default("frozen")
@@ -333,6 +342,14 @@ const THINKING_POLICIES = {
 // Measured in dsh-bench (12 SWE-bench Verified pytest tasks, 600 s, 64 calls incl. Jev; resolved tasks).
 const THINKING_MEASURED =
   "dsh-bench, 12 SWE-bench Verified tasks per run: deepseek-v4.1-flash resolved 18/24 with decision_points and 15/24 with thinking off for the whole turn; glm-5.3-flash 18/24 with decision_points and 7/12 with off; always was not measured. Small samples.";
+const EFFORT_STATE_BYTES = 8000;
+const shortText = (value, chars) => String(value ?? "").slice(0, chars);
+const jsonBytes = (value) => Buffer.byteLength(JSON.stringify(value));
+const EFFORT_CHOICES = {
+  skip: "Keep the current effort/cache space; no effort change.",
+  pulse: "High effort for the next request only.",
+  phase: "High effort until the trigger is resolved or the request window/turn ends; new triggers renew the window.",
+};
 // Measured on deepseek-v4.1-flash through WorkBuddy (same affinity id): thinking on and off are separate
 // provider cache spaces. Other routes were not measured.
 const thinkingCacheFact = (model) =>
@@ -483,6 +500,17 @@ export function apply(ctx, options) {
     effortSet = new Map(),
     effortDue = new Map(),
     effortStall = new Map(),
+    effortSkips = new Map(),
+    effortPulses = new Map(),
+    effortPhases = new Map(),
+    effortRequests = new Map(),
+    effortOutputs = new Map(),
+    effortReports = new Map(),
+    effortTools = new Map(),
+    taskHeads = new Map(),
+    turnHeads = new Map(),
+    admittedMessages = new Map(),
+    cacheSpaces = new Map(),
     userEffort = new Set(),
     childEffort = new Map(),
     // Per-root accounting of the current turn: role use, cost and cache by category.
@@ -554,6 +582,7 @@ export function apply(ctx, options) {
         pending: new Set(),
         childRequests: 0,
         decisions: 0,
+        effortDecisions: 0,
       });
     return budgets.get(id);
   };
@@ -607,6 +636,8 @@ export function apply(ctx, options) {
         "turn_plan",
         "effort_checkpoint",
         "effort_raised",
+        "effort_decision",
+        "effort_phase_end",
         "context_deferred",
         "learning",
       ].includes(value.kind)
@@ -815,7 +846,7 @@ export function apply(ctx, options) {
     record({ kind: "jev_unavailable", session, model: config.jevModel, httpStatus: status, error: detail,
       ...(transient ? { pausedMs: JEV_PAUSE_MS } : {}) });
   }
-  // `unbudgeted` is for the turn-end learning call, which must not compete with the task's decisions.
+  // Learning and effort calls do not compete with routing/context decisions. Effort has its own cap.
   async function decide(agent, request, signal, { unbudgeted = false } = {}) {
     const root = rootOf(agent),
       state = budget(root);
@@ -833,6 +864,11 @@ export function apply(ctx, options) {
     return memoFor(root)(key, async () => {
       if (!unbudgeted && state.decisions >= config.maxDecisions)
         throw new Error("Jev task decision budget exhausted.");
+      if (unbudgeted && request.trigger === "effort_decision") {
+        if (state.effortDecisions >= (config.maxEffortDecisions ?? 6))
+          throw Object.assign(new Error("Jev effort decision budget exhausted."), { code: "EFFORT_BUDGET" });
+        state.effortDecisions++;
+      }
       if (!unbudgeted) state.decisions++;
       updateStats(root);
       const started = performance.now();
@@ -886,6 +922,11 @@ export function apply(ctx, options) {
       const usd = jevCostUSD(config.jevModel, result.usage);
       if (usd !== undefined) useOf(root).cost.jev += usd;
       else useOf(root).unpriced++;
+      // The effort state contains raw task/failure evidence. Keep only the validated choice and
+      // billing counters even if a gateway echoes state or adds free-text explanations.
+      const logged = request.trigger === "effort_decision" ? { model: result.model, usage: result.usage,
+        answers: { thinking: { type: "choice", choice: result.answers.thinking.choice,
+          confidence: result.answers.thinking.confidence } } } : result;
       record({
         kind: "jev",
         session: agent.session.id,
@@ -893,7 +934,7 @@ export function apply(ctx, options) {
         httpStatus: response.status,
         wallMs: performance.now() - started,
         ...(usd === undefined ? {} : { usd }),
-        ...result,
+        ...logged,
       });
       return result;
     });
@@ -1111,14 +1152,18 @@ export function apply(ctx, options) {
           .flatMap((test) => test.runs)
           .filter((run) => run.via === undefined && run.event > since)
           .at(-1);
+        const recent = effortTools.get(id) ?? [];
+        recent.push({ name: shortText(exec.name, 80), outcome: latest?.outcome ?? (result.isError ? "error" : "success") });
+        effortTools.set(id, recent.slice(-6));
+        resolveEffortPhase(exec, result, latest);
         if (latest && (latest.outcome === "fail" || latest.outcome === "error")) {
-          wantEffort(exec.agent, "test_failure");
           const key = Object.entries(graphFor(id).tests).find(([, test]) => test.runs.includes(latest))?.[0];
           if (key) {
             if (!failureOutput.has(id)) failureOutput.set(id, new Map());
             const text = (result.content ?? []).filter((block) => block.type === "text").map((block) => block.text).join("\n");
             failureOutput.get(id).set(key, text.slice(-40000));
           }
+          wantEffort(exec.agent, "test_failure", { testKey: key });
         }
       }
     }
@@ -1169,6 +1214,12 @@ export function apply(ctx, options) {
     active.delete(info.id);
     advisorChildren.delete(info.id);
     settled.set(info.id, info);
+    const role = childRoles.get(info.id);
+    if (role === "reviewer" || role === "advisor") {
+      if (!effortReports.has(running.parent)) effortReports.set(running.parent, new Map());
+      effortReports.get(running.parent).set(role === "reviewer" ? "review_report" : "advisor_report",
+        shortText((info.lastAssistantMessage ?? []).filter(block => block.type === "text").map(block => block.text).join("\n"), 1500));
+    }
     if (childRoles.get(info.id) === "worker" && childModels.has(info.id)) {
       const use = roleUse(running.parent, "worker", childModels.get(info.id));
       if (info.stopReason === "completed") use.completed++;
@@ -1270,11 +1321,213 @@ export function apply(ctx, options) {
     return plan;
   }
 
-  // Under the decision-points policy, the root's next request thinks after one of these events.
-  function wantEffort(agent, reason) {
+  const phaseWindow = () => Math.max(1, Math.floor(config.effortPhaseRequests ?? 4));
+  const failingTest = (id) => Object.entries(graphFor(id).tests)
+    .map(([key, test]) => ({ key, run: test.runs.filter(run => run.via === undefined).at(-1) }))
+    .filter(({ run }) => ["fail", "error"].includes(run?.outcome))
+    .sort((a, b) => b.run.event - a.run.event)[0];
+  function phaseTrigger(id, reason, details = {}) {
+    return { reason, testKey: details.testKey ?? (reason === "test_failure" ? failingTest(id)?.key : undefined),
+      progress: progressKey(graphFor(id)), event: graphFor(id).sequence };
+  }
+  function extendEffortPhase(id, phase, trigger) {
+    phase.triggers.set(trigger.reason + "|" + (trigger.testKey ?? ""), trigger);
+    phase.until = (effortRequests.get(id) ?? 0) + phaseWindow();
+  }
+  function endEffortPhase(id, endedBy) {
+    const phase = effortPhases.get(id);
+    if (!phase) return;
+    effortPhases.delete(id);
+    record({ kind: "effort_phase_end", session: id, reason: phase.reason, requests: phase.requests, endedBy });
+  }
+  function resolveEffortPhase(exec, result, latest) {
+    const id = exec.agent.session.id, phase = effortPhases.get(id);
+    if (!phase) return;
+    const successful = !result.isError && !["fail", "error", "unknown"].includes(latest?.outcome);
+    let endedBy;
+    for (const [key, trigger] of phase.triggers) {
+      if (graphFor(id).sequence <= trigger.event) continue;
+      if (trigger.reason === "test_failure") {
+        const test = graphFor(id).tests[trigger.testKey];
+        const run = test?.runs.filter(run => run.via === undefined).at(-1);
+        if (!successful || run?.outcome !== "pass" || run.event <= trigger.event) continue;
+        endedBy = "test_passed";
+      } else if (["review_report", "advisor_report"].includes(trigger.reason)) {
+        if (!successful || !(latest?.outcome === "pass" || changesFilesCall(exec.name, exec.arguments))) continue;
+        endedBy = "report_acted_on";
+      } else {
+        if (!successful || progressKey(graphFor(id)) === trigger.progress) continue;
+        endedBy = "progress";
+      }
+      phase.triggers.delete(key);
+    }
+    if (!phase.triggers.size) endEffortPhase(id, endedBy);
+  }
+
+  // A fresh trigger renews an active phase locally, without spending another Jev decision.
+  function wantEffort(agent, reason, details = {}) {
     if (agent.session.header.parentSession !== undefined) return;
-    if (turnPlans.get(agent.session.id)?.thinking !== "decision_points") return;
-    if (!effortDue.has(agent.session.id)) effortDue.set(agent.session.id, reason);
+    const id = agent.session.id;
+    if (turnPlans.get(id)?.thinking !== "decision_points") return;
+    const trigger = phaseTrigger(id, reason, details), phase = effortPhases.get(id);
+    if (phase) extendEffortPhase(id, phase, trigger);
+    else if (!effortDue.has(id) || ["turn_start", "stall"].includes(effortDue.get(id).reason))
+      effortDue.set(id, trigger);
+  }
+
+  function invalidateCache(id, reason) {
+    const cache = cacheSpaces.get(id);
+    record({ kind: "cache_invalidated", session: id, reason,
+      spaces: cache?.spaces.size ?? 0, hadLatest: !!cache?.latest });
+    cacheSpaces.set(id, { spaces: new Map(), latest: undefined, invalidated: reason, failed: false });
+  }
+  function checkCacheGeneration(agent) {
+    const cache = cacheSpaces.get(agent.session.id), generation = agent.session.surface?.contentGeneration;
+    if (cache?.generation !== undefined && generation !== undefined && cache.generation !== generation)
+      invalidateCache(agent.session.id, "surface_generation_changed");
+  }
+
+  // Use the live projected messages, never an old request plus a token-count delta when available.
+  function effortEstimate(agent, resolved, payload) {
+    checkCacheGeneration(agent);
+    const id = agent.session.id, cache = cacheSpaces.get(id), price = modelInfo(resolved.model)?.price;
+    const projected = agent.session.deriveMessages?.();
+    const messages = payload.messages ?? resolved.messages ?? (projected === undefined ? undefined :
+      [...projected, ...(admittedMessages.get(id) ?? [])]);
+    let current = cache?.latest, source = "latest_plus_pending", pendingTokens = 0;
+    if (messages !== undefined) {
+      current = fingerprint({ ...resolved, tools: payload.tools ?? resolved.tools ?? agent.session.requestHeader?.()?.tools,
+        messages }, message => ctx.tokenMeter.estimateMessage(message));
+      source = payload.messages !== undefined || resolved.messages !== undefined ? "request_messages" : "session.deriveMessages+admitted";
+    } else if (current) {
+      pendingTokens = Math.max(0, ctx.tokenMeter.measure(agent.session).totalTokens -
+        current.tokens.reduce((sum, value) => sum + value, 0));
+    }
+    const totalTokens = current ? current.tokens.reduce((sum, value) => sum + value, 0) + pendingTokens : null;
+    if (cache?.invalidated && !cache.latest)
+      return { totalTokens, reusableTokens: 0, uncachedTokens: 0, usd: 0, source,
+        postReplacement: true };
+    if (!current || !price)
+      return { totalTokens, reusableTokens: null, uncachedTokens: null, usd: null, source };
+    const target = cache?.spaces.get(`${resolved.provider}|${resolved.model}|${config.adaptiveEffort}`);
+    const estimate = switchEstimate({ latest: current, target: target?.fingerprint, at: target?.at,
+      now: Date.now(), ttlMs: (config.cacheTtlSeconds ?? 300) * 1000, pendingTokens, price });
+    // Reuse in the current space is the baseline: entering high cannot lose tokens the baseline also
+    // has to read. After a replacement both spaces must read the new prefix, so the premium is zero.
+    const baseline = cache?.spaces.get(`${resolved.provider}|${resolved.model}|${effortSet.get(id) ?? resolved.reasoningEffort ?? "default"}`);
+    const baselineReuse = reusableTokens(baseline?.fingerprint, current, { now: Date.now(), at: baseline?.at,
+      ttlMs: (config.cacheTtlSeconds ?? 300) * 1000 });
+    estimate.uncachedTokens = Math.max(0, baselineReuse - estimate.reusableTokens);
+    estimate.usd = round(estimate.uncachedTokens * (price.input - (price.cacheRead ?? price.input)) / 1e6);
+    return { ...estimate, source };
+  }
+
+  function effortOptionCosts(id, resolved, estimate) {
+    const price = modelInfo(resolved.model)?.price;
+    const measured = effortOutputs.get(id)?.get(`${resolved.provider}|${resolved.model}`);
+    const pulses = effortPulses.get(id) ?? { count: 0, reasons: {}, rePulsedWithin3: 0 };
+    const average = measured?.calls ? measured.outputTokens / measured.calls : null;
+    const reasoning = measured?.reasoningCalls ? measured.reasoningTokens / measured.reasoningCalls : null;
+    const churn = { pulses: pulses.count, rePulsedWithin3: pulses.rePulsedWithin3,
+      reentryIfTriggeredSoon: { uncachedTokens: estimate.uncachedTokens, usd: estimate.usd,
+        basis: "Same prefix/target-space reuse as now; future growth and cache hits are unknown." },
+      observed: "1.2.3: 58% of switches reverted within 3 requests" };
+    const option = (requests) => ({ label: "estimate, cache hit not guaranteed", expectedRequests: requests,
+      enter: { uncachedTokens: estimate.uncachedTokens, usd: estimate.usd },
+      extraOutput: { averageTokens: average, averageReasoningTokens: reasoning, reasoningIncludedInOutput: true,
+        tokens: average === null ? null : round(average * requests),
+        usd: average === null || !price ? null : round(average * requests * price.output / 1e6),
+        basis: average === null ? THINKING_MEASURED : "session high-effort output (including reasoning); upper estimate, no off-output subtraction" },
+      churn, requestsPotentiallySaved: "Not measured; consider whether deliberate reasoning avoids later failed attempts/requests." });
+    return { skip: { label: "estimate, cache hit not guaranteed", expectedRequests: 0,
+      enter: { uncachedTokens: 0, usd: 0 }, extraOutput: { tokens: 0, usd: 0 } },
+      pulse: option(1), phase: option(phaseWindow()) };
+  }
+
+  async function effortEvidence(agent, trigger) {
+    const id = agent.session.id, graph = graphFor(id), reason = trigger.reason;
+    const evidence = { task: shortText(taskHeads.get(id), 800) };
+    if (reason === "test_failure") {
+      const key = trigger.testKey ?? failingTest(id)?.key;
+      const runs = graph.tests[key]?.runs.filter(run => run.via === undefined) ?? [];
+      const raw = failureOutput.get(id)?.get(key);
+      const excerpt = raw === undefined ? "(no raw failure output captured)" : failureExcerpt(raw, { maxChars: 1500 });
+      const focus = focusTerms({ failingTests: key ? [key] : [],
+        errors: excerpt.match(/\b[A-Za-z_$][\w$]*(?:Error|Exception)\b/g) ?? [],
+        symbols: [...(key?.match(/\btest_\w+|[\w./-]+\.(?:py|js|ts|go|rs)\b/g) ?? []),
+          ...(excerpt.match(/[\w./-]+\.(?:py|js|ts|tsx|jsx|go|rs|java|c|cpp)\b/g) ?? [])] });
+      const change = await workspaceDiff(workspaceOf(agent), { maxChars: 1500, focus });
+      evidence.testKey = shortText(key, 400);
+      evidence.failureExcerpt = shortText(excerpt, 1500);
+      evidence.attempts = { count: runs.length, outcomes: runs.map(run => run.outcome),
+        summary: shortText(attemptsFrom(graph, key), 1000) };
+      evidence.change = shortText(change.evidence ?? (change.error ? "Diff unavailable: " + change.error : change.diff), 1500);
+    } else if (["review_report", "advisor_report"].includes(reason)) {
+      evidence.report = shortText(effortReports.get(id)?.get(reason), 1500);
+    } else if (reason === "stall") {
+      evidence.stepsWithoutProgress = graphStep(id) - (effortStall.get(id)?.step ?? graphStep(id));
+      evidence.tools = (effortTools.get(id) ?? []).slice(-6);
+    } else evidence.request = shortText(turnHeads.get(id), 800);
+    return evidence;
+  }
+
+  // Bound the entire serialized state (and question) in UTF-8 bytes, including JSON escaping. Preserve
+  // the observed failure ahead of background/diff text when non-ASCII evidence needs more space.
+  function boundEffortRequest(request) {
+    const evidence = request.evidence;
+    const fields = [[evidence, "task"], [evidence, "request"], [evidence, "change"],
+      [evidence.attempts, "summary"], [evidence, "testKey"], [evidence, "report"], [evidence, "failureExcerpt"]];
+    while (jsonBytes(request) > EFFORT_STATE_BYTES) {
+      const field = fields.find(([object, key]) => typeof object?.[key] === "string" && object[key].length > 64);
+      if (field) {
+        const [object, key] = field;
+        object[key] = object[key].slice(0, Math.max(64, Math.floor(object[key].length / 2)));
+      } else if (evidence.tools?.length) evidence.tools.pop();
+      else throw new Error("Effort state metadata exceeds byte budget");
+    }
+  }
+
+  async function decisionPointEffort(agent, resolved, trigger, payload) {
+    const id = agent.session.id, reason = trigger.reason;
+    let estimate = { totalTokens: null, reusableTokens: null, uncachedTokens: null, usd: null },
+      decision = "fallback", optionCosts = effortOptionCosts(id, resolved, estimate), evidenceBytes = 0, evidenceKey;
+    try {
+      estimate = effortEstimate(agent, resolved, payload);
+      optionCosts = effortOptionCosts(id, resolved, estimate);
+      if (estimate.postReplacement) decision = "post_replacement";
+      else if (estimate.uncachedTokens !== null && estimate.uncachedTokens <= (config.effortSwitchFreeTokens ?? 4096))
+        decision = "cheap";
+      else if (budget(id).effortDecisions >= (config.maxEffortDecisions ?? 6)) decision = "fallback_budget";
+      else {
+        const evidence = await effortEvidence(agent, trigger);
+        const request = { trigger: "effort_decision", reason, evidence,
+          estimate: { ...estimate, label: "estimate, cache hit not guaranteed" }, optionCosts,
+          preference: roots.get(id)?.policy?.weights,
+          questions: { thinking: { type: "choice", criteria: EFFORT_CHOICES, instructions:
+            "Choose the effort justified by this evidence. Quality comes first; skip is right for a mechanical fix. Weigh entry, output, churn and requests a phase may save." } } };
+        boundEffortRequest(request);
+        evidenceBytes = jsonBytes(evidence);
+        evidenceKey = createHash("sha256").update(JSON.stringify([reason, evidence, progressKey(graphFor(id))])).digest("hex");
+        const skipped = effortSkips.get(id)?.get(reason);
+        if (skipped === evidenceKey) decision = "skip";
+        else {
+          if (!config.apiKey) throw new Error("Effort decision unavailable");
+          const timeout = AbortSignal.timeout(15000);
+          const signal = payload.signal ? AbortSignal.any([payload.signal, timeout]) : timeout;
+          decision = (await decide(agent, request, signal, { unbudgeted: true })).answers.thinking.choice;
+          if (decision === "skip") {
+            if (!effortSkips.has(id)) effortSkips.set(id, new Map());
+            effortSkips.get(id).set(reason, evidenceKey);
+          }
+        }
+      }
+    } catch (error) {
+      if (payload.signal?.aborted) throw error;
+      decision = error.code === "EFFORT_BUDGET" ? "fallback_budget" : "fallback";
+    }
+    record({ kind: "effort_decision", session: id, reason, decision, ...estimate,
+      optionCosts, evidenceBytes, ...(evidenceKey ? { evidenceHash: evidenceKey } : {}) });
+    return decision;
   }
 
   // The root's sticky effort through dsh's request-config waterfall on the agent's own scoped context, as
@@ -1298,12 +1551,53 @@ export function apply(ctx, options) {
       const root = rootOf(agent);
       let effort;
       if (id === root) {
+        const requestNumber = (effortRequests.get(id) ?? 0) + 1;
+        effortRequests.set(id, requestNumber);
+        checkCacheGeneration(agent);
         const plan = effortSupported.get(root) === true ? turnPlans.get(root) : undefined;
-        if (plan?.thinking === "always") effort = plan.effort;
-        else if (plan?.thinking === "decision_points" && effortDue.has(id)) {
-          effort = config.adaptiveEffort;
-          record({ kind: "effort_raised", session: id, effort, reason: effortDue.get(id), step: payload.step });
-          effortDue.delete(id);
+        if (effortPhases.has(id) && plan?.thinking !== "decision_points") endEffortPhase(id, "policy_changed");
+        if (plan?.thinking === "always") {
+          effort = plan.effort;
+          if (effort !== undefined)
+            record({ kind: "effort_raised", session: id, effort, reason: "always", step: payload.step });
+        }
+        else if (plan?.thinking === "decision_points") {
+          let phase = effortPhases.get(id);
+          if (phase && requestNumber > phase.until) {
+            endEffortPhase(id, "request_limit");
+            phase = undefined;
+          }
+          const trigger = effortDue.get(id);
+          let decision;
+          if (!phase && trigger) {
+            decision = await decisionPointEffort(agent, resolved, trigger, payload);
+            if (decision === "phase") {
+              phase = { reason: trigger.reason, requests: 0, triggers: new Map(),
+                until: requestNumber + phaseWindow() - 1 };
+              phase.triggers.set(trigger.reason + "|" + (trigger.testKey ?? ""), trigger);
+              effortPhases.set(id, phase);
+            }
+            effortDue.delete(id);
+          }
+          if (phase) {
+            effort = config.adaptiveEffort;
+            phase.requests++;
+            record({ kind: "effort_raised", session: id, effort, reason: phase.reason, step: payload.step, phase: true });
+          } else if (decision === "skip") {
+            // A skip leaves the currently selected space intact, even if the previous pulse was high.
+            effort = effortSet.get(id) ?? resolved.reasoningEffort;
+            if (effort === config.adaptiveEffort)
+              record({ kind: "effort_raised", session: id, effort, reason: trigger.reason, step: payload.step });
+          } else if (decision !== undefined) {
+            effort = config.adaptiveEffort;
+            const pulses = effortPulses.get(id) ?? { count: 0, reasons: {}, rePulsedWithin3: 0 };
+            if (pulses.lastRequest !== undefined && requestNumber - pulses.lastRequest <= 3) pulses.rePulsedWithin3++;
+            pulses.count++;
+            pulses.lastRequest = requestNumber;
+            pulses.reasons[trigger.reason] = (pulses.reasons[trigger.reason] ?? 0) + 1;
+            effortPulses.set(id, pulses);
+            record({ kind: "effort_raised", session: id, effort, reason: trigger.reason, step: payload.step });
+          }
         }
       } else {
         // A same-model child keeps the effort its branch started with (only an always-thinking parent
@@ -1533,6 +1827,10 @@ export function apply(ctx, options) {
       // LGTM ends the turn as is: steering the report back reopened it, and flash executors chased
       // the reviewer's caveats until the request cap.
       if (!lgtm) {
+        if (!effortReports.has(id)) effortReports.set(id, new Map());
+        const received = (settled.get(run.id)?.lastAssistantMessage ?? [])
+          .filter(block => block.type === "text").map(block => block.text).join("\n");
+        effortReports.get(id).set("review_report", shortText(received || report, 1500));
         agent.steer(note(reviewMessage(report)));
         wantEffort(agent, "review_report");
         return true;
@@ -1561,6 +1859,7 @@ export function apply(ctx, options) {
       if (!steered && modeOf(agent) === "auto")
         await settleTurn(agent.session, turn).catch((error) =>
           record({ kind: "learning_failed", session: agent.session.id, error: String(error) }));
+      if (!steered) endEffortPhase(agent.session.id, "turn_end");
     } finally {
       await saved;
     }
@@ -2015,6 +2314,10 @@ export function apply(ctx, options) {
         .join("\n")
         .trim();
       if (!reply) throw new Error("Advisor returned no text.");
+      if (!effortReports.has(id)) effortReports.set(id, new Map());
+      const received = (settled.get(run.id)?.lastAssistantMessage ?? [])
+        .filter(block => block.type === "text").map(block => block.text).join("\n");
+      effortReports.get(id).set("advisor_report", shortText(received || reply, 1500));
       record({ kind: "advisor_end", session: id, model: model.id, chars: reply.length });
       const use = roleUse(id, "advisor", model.id);
       use.completed++;
@@ -2079,7 +2382,12 @@ export function apply(ctx, options) {
     graphFor(id);
     const newTurn = !isChild && turnStartSteps.get(id)?.turn !== payload.turn;
     if (newTurn) {
+      endEffortPhase(id, "turn_end");
       turnStartSteps.set(id, { turn: payload.turn, step: graphStep(id) });
+      effortPulses.delete(id);
+      effortSkips.delete(id);
+      effortRequests.delete(id);
+      effortDue.delete(id);
       if (turnUses.get(id)?.turn !== payload.turn) turnUses.set(id, newUse(payload.turn));
     }
     const reopened = !isChild && turnUses.get(id);
@@ -2151,6 +2459,16 @@ export function apply(ctx, options) {
           )
             tasks.set(id, tasks.get(id) + "\n\nFollow-up assignment:\n" + text(message));
     }
+    if (!isChild && (!taskHeads.has(id) || newTurn)) {
+      const previous = agent.session.snapshotEvents()
+        .filter(event => event.type === "user/message")
+        .map(event => agent.session.deriveEventMessage(event))
+        .filter(message => message?.source.kind === "user");
+      const pending = messages.filter(message => message.source.kind === "user");
+      const first = previous[0] ?? pending[0], current = pending.at(-1) ?? previous.at(-1);
+      if (first && !taskHeads.has(id)) taskHeads.set(id, shortText(text(first), 800));
+      if (current && newTurn) turnHeads.set(id, shortText(text(current), 800));
+    }
     if (
       !isChild &&
       (!roots.has(id) || roots.get(id).configuredMode !== (config.apiKey ? config.mode : "native"))
@@ -2232,7 +2550,9 @@ export function apply(ctx, options) {
     const admitted = await next();
     if (admitted.kind === "reject") return admitted;
     graphSteps.set(id, graphStep(id) + 1);
-    return appendNotes(agent, admitted, { advisor, finalRequest, staleNotes });
+    const withNotes = appendNotes(agent, admitted, { advisor, finalRequest, staleNotes });
+    if (!isChild) admittedMessages.set(id, withNotes.messages ?? []);
+    return withNotes;
   });
   ctx.on("llm/stream", async function* (options, next) {
     const agent = options.sessionId ? ctx.agents.get(options.sessionId) : undefined;
@@ -2248,7 +2568,36 @@ export function apply(ctx, options) {
       state.childRequests++;
     }
     const started = performance.now();
-    let usage;
+    let usage, cacheFingerprint, prefixReuse;
+    const rootExecution = agent && agent.session.header.parentSession === undefined && options.purpose === undefined;
+    const fingerprintFailed = () => {
+      const cache = cacheSpaces.get(agent.session.id);
+      // The last successfully fingerprinted request may no longer describe the current prefix.
+      cache.latest = undefined;
+      if (!cache.failed) {
+        cache.failed = true;
+        record({ kind: "cache_fingerprint_failed", session: agent.session.id });
+      }
+    };
+    if (rootExecution) {
+      // The host has now committed these messages. Retries derive them from the surface itself.
+      admittedMessages.delete(agent.session.id);
+      checkCacheGeneration(agent);
+      if (!cacheSpaces.has(agent.session.id))
+        cacheSpaces.set(agent.session.id, { spaces: new Map(), latest: undefined, failed: false });
+      try {
+        cacheFingerprint = fingerprint(options, (message) => ctx.tokenMeter.estimateMessage(message));
+        const previous = cacheSpaces.get(agent.session.id).spaces.get(cacheFingerprint.space);
+        prefixReuse = { space: cacheFingerprint.space,
+          sharedMessages: sharedPrefix(previous?.fingerprint, cacheFingerprint),
+          estReusedTokens: reusableTokens(previous?.fingerprint, cacheFingerprint, {
+            now: Date.now(), at: previous?.at, ttlMs: (config.cacheTtlSeconds ?? 300) * 1000,
+          }) };
+      } catch {
+        cacheFingerprint = undefined;
+        fingerprintFailed();
+      }
+    }
     const dispatchEstimate = agent ? ctx.tokenMeter.measure(agent.session).totalTokens : undefined;
     if (agent) updateStats(rootOf(agent), { nativeEstimate: dispatchEstimate });
     try {
@@ -2256,9 +2605,34 @@ export function apply(ctx, options) {
         if (chunk.type === "usage") usage = chunk.usage;
         yield chunk;
       }
+      if (cacheFingerprint) {
+        try {
+          const cache = cacheSpaces.get(agent.session.id);
+          cache.latest = cacheFingerprint;
+          delete cache.invalidated;
+          cache.generation = agent.session.surface?.contentGeneration;
+          cache.spaces.delete(cacheFingerprint.space);
+          cache.spaces.set(cacheFingerprint.space, { fingerprint: cacheFingerprint, at: Date.now() });
+          if (cache.spaces.size > 4) cache.spaces.delete(cache.spaces.keys().next().value);
+        } catch {
+          fingerprintFailed();
+        }
+      }
     } finally {
       const wallMs = performance.now() - started;
       const spent = agent ? account(agent, options, usage, wallMs) : undefined;
+      if (rootExecution && options.reasoningEffort === config.adaptiveEffort && Number.isFinite(usage?.outputTokens)) {
+        const id = agent.session.id, route = `${options.provider}|${options.model}`;
+        if (!effortOutputs.has(id)) effortOutputs.set(id, new Map());
+        const sample = effortOutputs.get(id).get(route) ?? { calls: 0, outputTokens: 0, reasoningTokens: 0, reasoningCalls: 0 };
+        sample.calls++;
+        sample.outputTokens += usage.outputTokens;
+        if (Number.isFinite(usage.reasoningTokens)) {
+          sample.reasoningTokens += usage.reasoningTokens;
+          sample.reasoningCalls++;
+        }
+        effortOutputs.get(id).set(route, sample);
+      }
       if (agent && options.purpose === undefined && usage) lastCached.set(agent.session.id, usage.cacheReadTokens ?? 0);
       if (agent && options.purpose === undefined) {
         if (Number.isFinite(usage?.totalTokens) && Number.isFinite(usage?.outputTokens))
@@ -2277,6 +2651,7 @@ export function apply(ctx, options) {
         wallMs,
         ...(spent ?? {}),
         ...(usage === undefined ? {} : { usage }),
+        ...(prefixReuse === undefined ? {} : { prefixReuse }),
       });
     }
   });
@@ -2286,6 +2661,13 @@ export function apply(ctx, options) {
       pendingLedgers.add(session.id);
     }
     if (session.header.parentSession !== undefined) return;
+    if (event.type === "compaction/summary" || event.type === "compaction/prune" ||
+        event.type === "image/offload" || event.surfaceOp?.op === "replace")
+      invalidateCache(session.id, event.surfaceOp?.op === "replace" ? "surface_replaced" : event.type);
+    if (event.type === "turn/end") {
+      endEffortPhase(session.id, "turn_end");
+      effortDue.delete(session.id);
+    }
     // Learning settles once per completed root turn, outside the turn: it never delays the user.
     if (event.type === "turn/end" && event.data?.reason?.kind === "completed")
       settleTurn(session, event.data.turn).catch((error) =>
@@ -2513,6 +2895,7 @@ export function apply(ctx, options) {
           agent,
           signal,
         );
+        if (agent.session.header.parentSession === undefined) invalidateCache(id, "context_replaced:" + reason);
         record({
           kind: "context_replaced",
           session: id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-autoctx",
-  "version": "1.2.4",
+  "version": "1.2.5",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -12,6 +12,7 @@
     "index.js",
     "client.js",
     "stats.js",
+    "cachespace.js",
     "decisions.js",
     "routing.js",
     "graph.js",

package/stats.js

@@ -6,7 +6,7 @@ export function newStats(mode,maxDecisions,pressureTokens) {
     // USD by category (unpriced counts calls without a catalog price) and provider-reported cache by role.
     cost:{executor:0,children:0,jev:0,compaction:0},unpriced:0,
     cache:{},historySeeded:0,forks:0,deferrals:0,
-    plan:null,choices:{},learning:null,
+    plan:null,choices:{},learning:null,effortDecisions:{},effortPhases:0,effortPhaseRequests:0,estUncachedTokensAvoided:0,
     updatedAt:0,pendingSaved:{}};
 }
 export function applyStatsRecord(stats,record,decisions=stats.decisions) {
@@ -51,7 +51,15 @@ export function applyStatsRecord(stats,record,decisions=stats.decisions) {
     case 'turn_plan': next.plan={tag:record.tag,thinking:record.thinking??null,effort:record.effort,via:record.via,
       probabilities:record.probabilities??null,raised:0}; break;
     case 'effort_checkpoint': next.plan={...(stats.plan??{}),thinking:record.to,via:'checkpoint'}; break;
-    case 'effort_raised': if (stats.plan) next.plan={...stats.plan,raised:(stats.plan.raised??0)+1}; break;
+    case 'effort_raised': if (stats.plan) next.plan={...stats.plan,raised:(stats.plan.raised??0)+1};
+      if (record.phase) next.effortPhaseRequests=(stats.effortPhaseRequests??0)+1; break;
+    case 'effort_decision':
+      next.effortDecisions={...stats.effortDecisions,
+        [record.decision]:(stats.effortDecisions?.[record.decision]??0)+1};
+      if (record.decision==='phase') next.effortPhases=(stats.effortPhases??0)+1;
+      if (record.decision==='skip' && Number.isFinite(record.uncachedTokens))
+        next.estUncachedTokensAvoided=(stats.estUncachedTokensAvoided??0)+record.uncachedTokens;
+      break;
     case 'context_deferred': next.deferrals=stats.deferrals+1; break;
     case 'learning': next.learning={mode:record.mode,version:record.version??null,proposed:record.proposed,
       applied:record.applied??[],pending:record.pending??null,reason:record.reason??null}; break;