dsh-continual-evolve 0.7.0 → 0.7.2

package/README.md

@@ -7,7 +7,7 @@
 [![CI](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml/badge.svg)](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-339933)](package.json)
-[![Tests](https://img.shields.io/badge/tests-600%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-675%20passing-brightgreen)]()
 
 Continual self-evolution for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): a versioned, auditable, rollback-safe harness state layer — prompt notes, memories, skills, subagent specs — refined from session trajectories.
 
@@ -25,7 +25,7 @@ Agents accumulate reusable experience (repeated failures, durable facts, reusabl
 
 ## How it works
 
-1. **Sediment** — the model creates entries via `evolve_add`, or the automatic review gate proposes them from the session trajectory (turn-interval + compaction checkpoints).
+1. **Sediment** — the model creates entries via `evolve_add`, or the automatic review gate proposes them from incremental snapshots captured after successful turns (plus compaction checkpoints).
 2. **Guard** — code-enforced validation: edit schema, blast-radius/scope coherence, and the promotion policy (project-scoped markers, thin content, near-duplicate detection, credential screening keep the global store clean — secrets are rejected at every write sink, including mount materialization). Global creates that near-duplicate an existing entry are rejected at write time (≥0.8 similarity); moderate overlaps carry a `conflictHint` for later consolidation.
 3. **Approve** — global and project writes require explicit human approval; local-fate proposals are consulted before they land.
 4. **Apply & inject** — atomic apply with snapshot + audit event. Prompt notes and delegation specs inject into the system prompt (capped, relevance-ranked, contradicted entries demoted, zero tokens when empty); memories/skills appear as a relevance-ordered capped directory index (`- [memory:type:id] title` hooks, full text one `evolve_list` away).
@@ -61,11 +61,15 @@ Commands (in-session):
 | `/evolve mount · unmount <skillId>` | hot-mount an executable skill as a live plugin |
 | `/evolve goal [objective · done · block]` | round-driven auto-review goal |
 | `/evolve benchmark …` | case lifecycle, runs, acceptance |
+| `/evolve pause · resume · status` | pause/resume the auto-review gate (manual tools keep working), gate state |
+| `/evolve usage` | per-entry injection counts + exact provider-reported tokens for direct review/planner/wrapup/fate calls (benchmark host subagents excluded) |
 
-Model tools: `evolve_list / add / update / delete / rollback`.
+Model tools: `evolve_list / add / update / delete / rollback` (`evolve_delete` takes `id` or a batch `ids` array — one refinement, one approval).
 
 For third-party consumers: every applied evolution (gate or manual) appends a structured `evolve_complete` event to `reviews.jsonl` (`src/evolve-event.ts` defines the shape) alongside the human-readable audit records.
 
+`/evolve usage` also reads `evolve/token-usage.jsonl`: exact provider-reported input/cache/output/total tokens for the plugin's direct review, planner, manual-wrapup, and automatic-fate calls. The report covers a retained tail rather than lifetime usage, distinguishes missing provider samples, and explicitly excludes host benchmark subagents, their agent-loop calls, and per-entry injection attribution.
+
 Injection shape: prompt notes and delegation specs inject with content (≤6/kind × 180 chars, relevance-ranked). Memories and skills appear as a relevance-ordered directory index (`[memory:type:id] title` hooks, capped at 15 lines with a fold counter) — full text via `evolve_list`. Empty store = zero injected tokens.
 
 ## Configuration
@@ -73,8 +77,8 @@ Injection shape: prompt notes and delegation specs inject with content (≤6/kin
 | Key | Default | Meaning |
 |---|---|---|
 | `baseDir` | resolved DSH home | root for the `evolve/` stores |
-| `autoReview` | `false` | enable the automatic review gate |
-| `reviewIntervalTurns` | `6` | gate cadence on the turn-interval path |
+| `autoReview` | `false` | initial automatic-review default when no runtime switch exists; the listener is always registered |
+| `reviewIntervalTurns` | `6` | legacy local-fate cadence fallback; successful-turn review no longer waits for this interval |
 | `maxReviewInputChars` | `40000` | trajectory slice handed to the gate |
 | `reviewBudgetTokens` | `4096` | output budget for the gate call |
 | `notifyOnAutoReview` | `true` | visible follow-up notice after an applied gate run |
@@ -92,6 +96,9 @@ Injection shape: prompt notes and delegation specs inject with content (≤6/kin
 | `autoRollbackOnReject` | `true` | deterministic rollback after a benchmark rejection |
 | `autoCase` | `true` | failed evolution attempts are captured as draft regression cases (`auto_regression` benchmark) |
 | `reviewModel` | agent's own | optional cheaper model for the gate (`"provider/model"`) |
+| `plannerPrefixCache` | `auto` | Route A session-prefix input when cache evidence exists (`session` always, `off` legacy flat text) |
+| `plannerPrefixMaxChars` | `12000` | session-prefix budget for Route A planning inputs (chars) |
+| `historyRetain` | `{snapshots: 20, refinements: 500, reviews: 500, tokenUsage: 500}` | storage hygiene: snapshots per store, tail lines per store history, shared `reviews.jsonl` tail, and direct-call `token-usage.jsonl` tail |
 
 Example profile patch:
 
@@ -102,11 +109,18 @@ Example profile patch:
     reviewIntervalTurns: 6
 ```
 
+The listener is registered even when `autoReview` is `false`. Use `/evolve resume`
+to enable successful-turn snapshots immediately, `/evolve pause` to suppress new
+snapshots and fate/model work, and `/evolve status` to inspect the configured
+default plus the current runtime state. The runtime switch is stored in
+`evolve/runtime.json`; manual `evolve_*` tools and `/evolve` commands are not
+paused.
+
 ## Development
 
 ```bash
 pnpm install && pnpm build   # deps + tsc -> lib/
-pnpm test                    # vitest (600 tests)
+pnpm test                    # vitest (675 tests)
 pnpm test:coverage           # v8 coverage, thresholds enforced in CI
 pnpm lint                    # oxlint src test
 ```
@@ -114,8 +128,8 @@ pnpm lint                    # oxlint src test
 Project layout:
 
 ```
-├── src/                   # engine, tools, commands, gate, fate, benchmark, usage…
-├── test/                  # vitest suites (37 files)
+├── src/                   # engine, tools, commands, gate, fate, benchmark, injection + token usage…
+├── test/                  # vitest suites (43 files)
 ├── lib/                   # build output (tsc)
 ├── docs/
 │   ├── design.md          # full design doc (hardening matrix)

package/README.zh.md

@@ -7,7 +7,7 @@
 [![CI](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml/badge.svg)](https://github.com/ZK-Andy/dsh-continual-evolve/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-339933)](package.json)
-[![Tests](https://img.shields.io/badge/tests-600%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-675%20passing-brightgreen)]()
 
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的持续自进化插件：一套**版本化、可审计、可回滚**的 harness 状态层——提示词补充、记忆、技能、子代理规格——从会话轨迹中沉淀而来。
 
@@ -25,7 +25,7 @@ Agent 在每个会话里积累可复用经验（重复失败、持久事实、
 
 ## 工作原理
 
-1. **沉淀**——模型经 `evolve_add` 创建条目，或自动 review 门禁从会话轨迹提议（回合间隔 + 压缩检查点）。
+1. **沉淀**——模型经 `evolve_add` 创建条目，或自动 review 门禁从成功回合后的增量 snapshot（以及压缩检查点）提议。
 2. **守卫**——代码强制校验：编辑 schema、blast-radius 与作用域一致性、晋升政策（项目专属标记 / 过薄内容 / 近似重复检测 / 凭据筛查保持全局库干净——密钥类内容在所有写入出口被拒，含 mount 物化）。全局 create 与既有条目高度相似（≥0.8）时写入即拒；中等重叠带 `conflictHint` 供后续合并。
 3. **审批**——全局与项目写入需明确人工批准；local 归宿提议先征询后落地。
 4. **应用与注入**——原子应用带快照与审计事件。prompt 补充与委派规格注入系统提示词（封顶、按相关性排序、被证伪条目降权、空 store 零 token）；memory/skill 以按相关性排序的目录索引出现（`[memory:type:id] 标题`钩子）。
@@ -61,11 +61,15 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | `/evolve mount · unmount <skillId>` | 把可执行技能热挂载为 live 插件 |
 | `/evolve goal [objective · done · block]` | 回合驱动的自进化目标 |
 | `/evolve benchmark …` | 用例生命周期、运行、接受决策 |
+| `/evolve pause · resume · status` | 暂停/恢复自动门禁（手动工具不受影响）、门禁状态 |
+| `/evolve usage` | 每条目注入次数 + review/planner/wrapup/fate 直属调用的 provider 精确 token（不含 benchmark 宿主子代理） |
 
-模型工具：`evolve_list / add / update / delete / rollback`。
+模型工具：`evolve_list / add / update / delete / rollback`（`evolve_delete` 支持 `id` 或批量 `ids` 数组——一次 refinement、一次审批）。
 
 第三方消费：每次进化落地（门禁或手动）都会向 `reviews.jsonl` 追加结构化 `evolve_complete` 事件（shape 见 `src/evolve-event.ts`），与人类可读的审计记录并存。
 
+`/evolve usage` 还会读取 `evolve/token-usage.jsonl`：插件直属 review、planner、手动 wrapup 与自动 fate 调用的 provider 精确 input/cache/output/total token。报告只覆盖保留尾部而非终身累计，单独显示 provider 未返回 usage 的调用，并明确排除宿主 benchmark 子代理、其 agent-loop 调用与逐条 memory 注入归因。
+
 注入形态：prompt 补充与委派规格带内容注入（每 kind ≤6 条 × 180 字符，按相关性排序）。memory/skill 以按相关性排序的目录索引出现（`[memory:type:id] 标题`钩子，15 行封顶 + 折叠计数行）——全文经 `evolve_list` 获取。空 store = 零注入 token。
 
 ## 配置
@@ -73,8 +77,8 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | 键 | 默认 | 含义 |
 |---|---|---|
 | `baseDir` | 解析后的 DSH home | `evolve/` 存储根目录 |
-| `autoReview` | `false` | 启用自动 review 门禁 |
-| `reviewIntervalTurns` | `6` | 回合间隔路径的门禁节奏 |
+| `autoReview` | `false` | 没有 runtime 开关时的自动 review 初始默认；监听器始终注册 |
+| `reviewIntervalTurns` | `6` | local-fate 的兼容节奏；成功回合 review 不再等待这个间隔 |
 | `maxReviewInputChars` | `40000` | 交给门禁的轨迹切片 |
 | `reviewBudgetTokens` | `4096` | 门禁调用输出预算 |
 | `notifyOnAutoReview` | `true` | 门禁应用后发可见跟进通知 |
@@ -92,6 +96,9 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | `autoRollbackOnReject` | `true` | benchmark 拒绝后自动确定性回滚 |
 | `autoCase` | `true` | 失败的进化尝试自动沉淀为 draft 回归用例（`auto_regression` 基准） |
 | `reviewModel` | agent 自身 | 门禁可选更便宜的模型（`"provider/model"`） |
+| `plannerPrefixCache` | `auto` | 有缓存证据时用会话前缀输入（`session` 总是前缀，`off` 保持旧扁平文本） |
+| `plannerPrefixMaxChars` | `12000` | Route A 会话前缀预算（字符） |
+| `historyRetain` | `{snapshots: 20, refinements: 500, reviews: 500, tokenUsage: 500}` | 存储卫生：每 store 快照数、每 store 历史尾行、共享 `reviews.jsonl` 尾行、直属调用 `token-usage.jsonl` 尾行 |
 
 profile patch 示例：
 
@@ -102,11 +109,13 @@ profile patch 示例：
     reviewIntervalTurns: 6
 ```
 
+即使 `autoReview` 为 `false`，监听器也会注册。使用 `/evolve resume` 立即开启成功回合 snapshot，使用 `/evolve pause` 抑制新 snapshot、fate 和模型调用，使用 `/evolve status` 查看配置默认值与运行时状态。开关保存在 `evolve/runtime.json`；手动 `evolve_*` 工具和 `/evolve` 命令不受暂停影响。
+
 ## 开发
 
 ```bash
 pnpm install && pnpm build   # 依赖 + tsc -> lib/
-pnpm test                    # vitest（600 例）
+pnpm test                    # vitest（675 例）
 pnpm test:coverage           # v8 覆盖率，CI 强制阈值
 pnpm lint                    # oxlint src test
 ```
@@ -114,8 +123,8 @@ pnpm lint                    # oxlint src test
 目录结构：
 
 ```
-├── src/                   # 引擎、工具、命令、门禁、fate、benchmark、usage…
-├── test/                  # vitest 测试套件（37 个文件）
+├── src/                   # 引擎、工具、命令、门禁、fate、benchmark、注入 + token 用量…
+├── test/                  # vitest 测试套件（43 个文件）
 ├── lib/                   # 构建产物（tsc）
 ├── docs/
 │   ├── design.md          # 完整设计文档（硬化矩阵）

package/lib/apply.js

@@ -7,15 +7,23 @@ export function applyRefinementProposal(state, proposal, options) {
     const now = new Date().toISOString();
     for (const edit of proposal.edits) {
         // Store-prefix hygiene: planner edits are written against the MERGED
-        // view, where colliding local ids carry a `local:` / `global:` prefix.
-        // A CREATE must never bake that view prefix into a permanent id
-        // (observed: global entries literally named "local:handoff_todo_…").
-        // Updates/deletes keep the raw id — they address existing entries.
-        // (Review audit 2026-08-28 S7: planner update/delete edits against
-        // the merged view carry the same prefix — strip it there too, they
-        // address the same underlying entry.)
-        const prefixlessId = edit.id?.replace(/^(?:local|global):/, "");
-        const requestedId = edit.action === "create" ? prefixlessId : edit.id && prefixlessId;
+        // view, where colliding project/local ids carry a `project:` /
+        // `local:` / `global:` prefix. A CREATE must never bake that view
+        // prefix into a permanent id (observed: global entries literally
+        // named "local:handoff_todo_…").
+        // Non-create edits address existing entries: the literal id wins —
+        // legacy stores contain entries whose literal id carries a colon
+        // prefix, and stripping unconditionally would resolve them to a
+        // sibling that does not exist ("entry not found", forcing file-level
+        // surgery). Only when the literal id is absent does the stripped
+        // form serve as the merged-view fallback.
+        // (Review audit 2026-08-28 S7 origin; literal-first fix 2026-09-24.)
+        const strippedId = edit.id?.replace(/^(?:local|project|global):/, "");
+        const requestedId = edit.action === "create"
+            ? strippedId
+            : edit.id !== undefined && state.entries[edit.kind]?.[edit.id] !== undefined
+                ? edit.id
+                : edit.id && strippedId;
         const computedId = requestedId ?? (edit.action === "create" ? slug(edit.title ?? edit.kind, edit.kind) : undefined);
         const id = computedId ?? "";
         // Unknown kinds fail per-edit — a malformed proposal must never crash

package/lib/auto.d.ts

@@ -4,8 +4,12 @@ import type { HarnessState, RefinementEdit, RefinementProposal } from "./types.j
 import type { EvolutionEngine } from "./service.js";
 import { type AutoRefineReason } from "./review.js";
 import type { PromotionPolicy } from "./promotion.js";
+import type { PlannerPrefixCacheMode } from "./prefix-cache.js";
 export interface AutoReviewConfig {
+    /** Legacy fate cadence; successful turns are no longer gated by this value. */
     intervalTurns: number;
+    /** Initial runtime state when no runtime.json exists. */
+    enabledByDefault?: boolean;
     maxInputChars: number;
     budgetTokens: number;
     /** Queue a visible follow-up notice after an approved, applied gate run. */
@@ -17,10 +21,9 @@ export interface AutoReviewConfig {
      */
     localFate: boolean;
     /**
-     * Minimum turns between local-fate assessments on the turn-interval path
-     * (compaction is unconditional). Independent of the review cadence so
-     * goal-driven sessions (gate every round) do not pay an assessment per
-     * round.
+     * Minimum turns between local-fate assessments on the successful-turn path
+     * (compaction is unconditional). Independent of snapshot review cadence so
+     * eligible turns do not pay an assessment every round.
      */
     fateIntervalTurns: number;
     /**
@@ -29,6 +32,12 @@ export interface AutoReviewConfig {
      * When absent, the review gate uses the agent's own provider/model.
      */
     reviewModel?: string;
+    /**
+     * Prefix-cache routing for the gate input (see reviewAutoRefine).
+     * Absent mode → auto-detect; absent budget → the default prefix budget.
+     */
+    prefixCacheMode?: PlannerPrefixCacheMode;
+    prefixMaxChars?: number;
     /**
      * Goal-blocked trigger (D3): after this many CONSECUTIVE gate runs that
      * observe the session goal in phase "blocked", run one local-fate
@@ -52,9 +61,19 @@ export interface AutoReviewConfig {
     autoCase: boolean;
     /** Resolved rubric key for the capture's encrypted scaffold rubric. */
     rubricKey?: Buffer;
+    /**
+     * Storage hygiene (#20): tail lines kept in the shared reviews.jsonl
+     * audit trail. Absent → the store default (readers need a recent
+     * window, not the full past).
+     */
+    reviewsRetain?: number;
 }
 export interface GateState {
     turns: number;
+    /** Latest successful turn boundary seen by the listener. */
+    completedTurn: number;
+    /** Latest turn whose snapshot acquisition was reserved. */
+    lastSnapshotTurn: number;
     lastReviewAt: number;
     running: boolean;
     /**
@@ -85,7 +104,7 @@ export interface ReviewRecord {
     sessionId: string;
     reason: AutoRefineReason;
     turnsSinceLastReview: number;
-    outcome: "approved" | "declined" | "failed" | "assessed" | "deferred";
+    outcome: "approved" | "declined" | "failed" | "assessed" | "deferred" | "skipped" | "armed";
     rationale?: string;
     refinementId?: string;
 }

package/lib/auto.js

@@ -5,36 +5,42 @@
  * fire-and-forget with error containment: an auto-review failure never
  * disturbs the agent loop.
  *
- * Every gate decision (approved / declined / failed) is appended to
+ * Every gate decision (approved / declined / failed / skipped) is appended to
  * `<dshHome>/evolve/reviews.jsonl` so auto-review activity is durably
  * auditable — the server console is not a reliable place to look.
  *
  * Hook wiring:
- * - `agent/turn-stopping` increments a per-session turn counter (sync, cheap).
- * - `agent/status` (idle) checks the interval and may start the gate.
- * - `session/event` (compaction/start) starts an unconditional gate run so
- *   experiences about to be summarized away are persisted first.
+ * - `agent/turn-stopping` records the successful turn boundary.
+ * - `agent/status` (idle) captures an incremental snapshot and feeds the
+ *   per-session latest-pending serial scheduler.
+ * - `session/event` (compaction/start) forces a snapshot flush before data is
+ *   summarized away.
  */
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { slug } from "./types.js";
 import { planWithLlm } from "./planner.js";
-import { reviewAutoRefine, serializeSurface } from "./review.js";
-import { goalDrivesRounds, goalServiceOf } from "./goal.js";
+import { reviewAutoRefine } from "./review.js";
+import { goalServiceOf } from "./goal.js";
 import { notifyAutoReview } from "./notify.js";
 import { runLocalFatePhase } from "./fate.js";
-import { entrySourceOf } from "./source.js";
 import { mergeHarnessStates } from "./state.js";
 import { projectKeyOf } from "./project.js";
 import { questionServiceOf } from "./approval.js";
 import { buildEvolveCompleteEvent, emitEvolveComplete } from "./evolve-event.js";
+import { DEFAULT_REVIEWS_RETAIN, pruneJsonlFile } from "./store.js";
+import { isGateEnabled } from "./runtime.js";
+import { createReviewScheduler } from "./review-scheduler.js";
+import { captureTurnSnapshot } from "./turn-snapshot.js";
 import { captureAutoCase } from "./autocase.js";
 /** Turns a rejected skill candidate stays silent before being offered again. */
 export const SKILL_CONSULT_COOLDOWN_TURNS = 10;
 export function registerAutoReview(ctx, engine, config) {
     const perSession = new Map();
+    const schedulers = new Map();
     const logger = ctx.logger("continual-evolve");
     const reviewsPath = join(engine.baseDir, "evolve", "reviews.jsonl");
+    const defaultEnabled = config.enabledByDefault ?? true;
     const record = (entry) => {
         try {
             mkdirSync(join(engine.baseDir, "evolve"), { recursive: true });
@@ -42,11 +48,87 @@ export function registerAutoReview(ctx, engine, config) {
         }
         catch (cause) {
             logger.warn(`failed to record auto-review: ${cause instanceof Error ? cause.message : String(cause)}`);
+            return;
+        }
+        // Storage hygiene (#20): bound the audit trail at write time.
+        try {
+            pruneJsonlFile(reviewsPath, config.reviewsRetain ?? DEFAULT_REVIEWS_RETAIN);
+        }
+        catch {
+            // ignored — the next record retries
         }
     };
-    // Turn counting uses `agent/turn-stopping` — empirically the only event
-    // whose payload carries the agent subject in every dispatch (verified: the
-    // gate fired under it at 20:56). `agent/status` serves as the idle trigger.
+    const schedulerFor = (agent, state) => {
+        const existing = schedulers.get(agent.id);
+        if (existing)
+            return existing;
+        const scheduler = createReviewScheduler(async ({ snapshot, signal }) => {
+            if (!isGateEnabled(engine.baseDir, defaultEnabled))
+                return "aborted";
+            if (!snapshot.eligible) {
+                record({
+                    sessionId: snapshot.sessionId,
+                    reason: snapshot.reason,
+                    turnsSinceLastReview: state.turns - state.lastReviewAt,
+                    outcome: "skipped",
+                    rationale: `snapshot ${snapshot.cursor} skipped: ${snapshot.skipReason ?? "not eligible"}`,
+                });
+                return "no-op";
+            }
+            try {
+                await runGate(ctx, engine, agent, config, state, snapshot, record, signal);
+                return "success";
+            }
+            catch (cause) {
+                const message = cause instanceof Error ? cause.message : String(cause);
+                logger.warn(`auto-review failed for ${agent.id}: ${message}`);
+                record({
+                    sessionId: agent.id,
+                    reason: snapshot.reason,
+                    turnsSinceLastReview: state.turns - state.lastReviewAt,
+                    outcome: "failed",
+                    rationale: `gate error: ${message}`,
+                });
+                return "error";
+            }
+        }, (snapshot) => snapshot.cursor);
+        schedulers.set(agent.id, scheduler);
+        return scheduler;
+    };
+    const captureAndSchedule = (agent, state, reason) => {
+        if (!isGateEnabled(engine.baseDir, defaultEnabled))
+            return;
+        const turn = state.completedTurn;
+        const previousSnapshotTurn = state.lastSnapshotTurn;
+        if (reason === "turn_snapshot" && turn <= previousSnapshotTurn)
+            return;
+        if (reason === "turn_snapshot")
+            state.lastSnapshotTurn = turn;
+        const cursor = schedulerFor(agent, state).getCursor();
+        void captureTurnSnapshot(ctx, agent, {
+            turn,
+            reason,
+            ...(cursor !== undefined ? { cursor } : {}),
+            maxChars: config.maxInputChars,
+        })
+            .then((snapshot) => schedulerFor(agent, state).schedule(snapshot))
+            .catch((cause) => {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            logger.warn(`auto-review snapshot failed for ${agent.id}: ${message}`);
+            record({
+                sessionId: agent.id,
+                reason,
+                turnsSinceLastReview: state.turns - state.lastReviewAt,
+                outcome: "failed",
+                rationale: `snapshot error: ${message}`,
+            });
+            if (reason === "turn_snapshot" && state.lastSnapshotTurn === turn) {
+                state.lastSnapshotTurn = previousSnapshotTurn;
+            }
+        });
+    };
+    // DSH emits this awaited boundary when a turn is about to close. The idle
+    // transition is the safe point at which to read the durable surface.
     ctx.on("agent/turn-stopping", (payload) => {
         const agent = payload.agent;
         if (!agent) {
@@ -55,36 +137,20 @@ export function registerAutoReview(ctx, engine, config) {
         }
         const state = stateFor(perSession, agent.id);
         state.turns += 1;
+        if (typeof payload.turn === "number")
+            state.completedTurn = Math.max(state.completedTurn, payload.turn);
     });
     ctx.on("agent/status", (payload) => {
         const agent = payload.agent;
         if (!agent || payload.status !== "idle")
             return;
         const state = stateFor(perSession, agent.id);
-        // v3 optional: an active evolution goal drives the gate EVERY round
-        // (the goal's round machine keeps the session continuing); without a
-        // goal the plain turn interval applies.
-        const goalDriven = goalDrivesRounds(goalServiceOf(ctx)?.get(agent));
-        if (!goalDriven && state.turns - state.lastReviewAt < config.intervalTurns)
+        if (state.completedTurn <= state.lastSnapshotTurn)
             return;
-        // Run the gate outside the listener turn: agent is idle, work is auxiliary.
-        // Every failure is durably recorded — nothing fails silently.
-        void runGate(ctx, engine, agent, config, state, "turn_interval", record).catch((cause) => {
-            const message = cause instanceof Error ? cause.message : String(cause);
-            logger.warn(`auto-review failed for ${agent.id}: ${message}`);
-            record({
-                sessionId: agent.id,
-                reason: "turn_interval",
-                turnsSinceLastReview: state.turns - state.lastReviewAt,
-                outcome: "failed",
-                rationale: `gate error: ${message}`,
-            });
-            state.lastReviewAt = state.turns; // back off until the interval elapses again
-        });
+        captureAndSchedule(agent, state, "turn_snapshot");
     });
-    // Diagnostic: the armed marker proves registerAutoReview ran with the
-    // configured interval; a restart that writes it but nothing after means the
-    // trigger events are not reaching this listener.
+    // Diagnostic: the armed marker proves the listener was registered even when
+    // its runtime default is off, distinguishing "not registered" from "off".
     try {
         mkdirSync(join(engine.baseDir, "evolve"), { recursive: true });
         appendFileSync(reviewsPath, `${JSON.stringify({
@@ -93,12 +159,26 @@ export function registerAutoReview(ctx, engine, config) {
             reason: "boot",
             turnsSinceLastReview: 0,
             outcome: "armed",
-            rationale: `auto-review gate registered (interval=${config.intervalTurns})`,
+            rationale: `auto-review gate registered (default=${defaultEnabled ? "on" : "off"}; per-success-turn snapshots; local-fate every ${config.fateIntervalTurns} turns)`,
         })}\n`, "utf8");
     }
     catch (cause) {
         logger.warn(`failed to write armed marker: ${cause instanceof Error ? cause.message : String(cause)}`);
     }
+    try {
+        pruneJsonlFile(reviewsPath, config.reviewsRetain ?? DEFAULT_REVIEWS_RETAIN);
+    }
+    catch {
+        // ignored — the next record retries
+    }
+    ctx.on("agent/disposed", (payload) => {
+        const agent = payload.agent;
+        if (!agent)
+            return;
+        schedulers.get(agent.id)?.shutdown();
+        schedulers.delete(agent.id);
+        perSession.delete(agent.id);
+    });
     ctx.on("session/event", (session, event) => {
         if (event.type !== "compaction/start")
             return;
@@ -107,17 +187,7 @@ export function registerAutoReview(ctx, engine, config) {
         if (!agent)
             return; // no live agent for that session (e.g. cold read)
         const state = stateFor(perSession, agent.id);
-        // Compaction is unconditional: persist what is about to be summarized away.
-        void runGate(ctx, engine, agent, config, state, "compact", record).catch((cause) => {
-            logger.warn(`auto-review failed at compaction for ${agent.id}: ${cause instanceof Error ? cause.message : String(cause)}`);
-            record({
-                sessionId: agent.id,
-                reason: "compact",
-                turnsSinceLastReview: state.turns - state.lastReviewAt,
-                outcome: "failed",
-                rationale: `gate error at compaction: ${cause instanceof Error ? cause.message : String(cause)}`,
-            });
-        });
+        captureAndSchedule(agent, state, "compact");
     });
 }
 /**
@@ -141,6 +211,8 @@ function stateFor(map, sessionId) {
     if (!state) {
         state = {
             turns: 0,
+            completedTurn: 0,
+            lastSnapshotTurn: 0,
             lastReviewAt: 0,
             running: false,
             skillRejects: new Map(),
@@ -173,23 +245,22 @@ export function loadGateHarnessView(engine, sessionId, opts) {
  * review's baseline fresh — fate re-loads the store and never races the
  * review's optimistic-concurrency checks.
  */
-async function runGate(ctx, engine, agent, config, state, reason, record) {
+async function runGate(ctx, engine, agent, config, state, snapshot, record, signal) {
     // Reentry guard (review audit 2026-08-28 S3): a gate run holds LLM calls
     // and possibly a user question for a long time; an idle/compaction
     // trigger overlapping the run would start a second concurrent pipeline
     // whose stale whole-file saves clobber the first run's writes.
     if (state.running) {
-        ctx.logger("continual-evolve").info(`auto-review skipped [${agent.id}]: previous gate run still in flight`);
-        return;
+        throw new Error(`previous gate run still in flight for ${agent.id}`);
     }
     state.running = true;
     try {
-        await runReviewPhase(ctx, engine, agent, config, state, reason, record);
+        await runReviewPhase(ctx, engine, agent, config, state, snapshot, record, signal);
         // D3: a goal stuck in "blocked" for consecutive gate runs gets one
         // local-fate assessment (the pipeline below), so whatever led the
         // goal astray is distilled before the session moves on.
-        await runGoalBlockedFate(ctx, engine, agent, config, state, reason, record);
-        await runLocalFatePhase(ctx, engine, agent, config, state, reason, record);
+        await runGoalBlockedFate(ctx, engine, agent, config, state, snapshot.reason, record);
+        await runLocalFatePhase(ctx, engine, agent, config, state, snapshot.reason, record);
     }
     finally {
         state.running = false;
@@ -224,18 +295,20 @@ export async function runGoalBlockedFate(ctx, engine, agent, config, state, _rea
     logger.info(`auto-review goal-blocked trigger [${agent.id}]: ${config.goalBlockedWrapupTurns} consecutive blocked gate runs → local-fate assessment`);
     await runLocalFatePhase(ctx, engine, agent, config, state, "goal_blocked", record);
 }
-async function runReviewPhase(ctx, engine, agent, config, state, reason, record) {
+async function runReviewPhase(ctx, engine, agent, config, state, snapshot, record, signal) {
     const sessionId = agent.id;
+    const reason = snapshot.reason;
     const turnsSinceLastReview = state.turns - state.lastReviewAt;
     const logger = ctx.logger("continual-evolve");
-    const trajectory = await readTrajectory(ctx, agent, config.maxInputChars).catch((cause) => {
-        logger.warn(`auto-review skipped for ${sessionId}: trajectory unavailable: ${cause instanceof Error ? cause.message : String(cause)}`);
-        record({ sessionId, reason, turnsSinceLastReview, outcome: "failed", rationale: `trajectory unavailable: ${cause instanceof Error ? cause.message : String(cause)}` });
-        return undefined;
-    });
+    const tokenUsage = {
+        baseDir: engine.baseDir,
+        sessionId,
+        retain: engine.retention.tokenUsage,
+        onError: (cause) => logger.warn(`token-usage ledger failed for ${sessionId}: ${cause instanceof Error ? cause.message : String(cause)}`),
+    };
+    const trajectory = snapshot.trajectory;
     if (!trajectory) {
-        state.lastReviewAt = state.turns;
-        return;
+        throw new Error("eligible snapshot has no trajectory");
     }
     // The gate judges the merged view (global + local, scopes labeled) so it
     // can recognize topics already covered globally and decline duplicates;
@@ -251,9 +324,20 @@ async function runReviewPhase(ctx, engine, agent, config, state, reason, record)
         state: harnessState,
         history,
         trajectory,
+        trajectoryEvents: snapshot.events,
+        ...(signal ? { signal } : {}),
         context: { reason, turnsSinceLastReview },
         budgetTokens: config.budgetTokens,
+        tokenUsage,
         ...(reviewRoute ? { overrideProvider: reviewRoute.provider, overrideModel: reviewRoute.model } : {}),
+        ...((config.prefixCacheMode !== undefined || config.prefixMaxChars !== undefined
+            ? {
+                prefixCache: {
+                    ...(config.prefixCacheMode !== undefined ? { mode: config.prefixCacheMode } : {}),
+                    ...(config.prefixMaxChars !== undefined ? { maxChars: config.prefixMaxChars } : {}),
+                },
+            }
+            : {})),
     });
     state.lastReviewAt = state.turns;
     if (!review.shouldRefine) {
@@ -265,11 +349,23 @@ async function runReviewPhase(ctx, engine, agent, config, state, reason, record)
         agent,
         state: harnessState,
         history,
+        trajectory: snapshot.trajectory,
+        trajectoryEvents: snapshot.events,
+        ...(signal ? { signal } : {}),
         ...(review.instructions ? { instructions: review.instructions } : {}),
         global: false,
         // Read the skill-creator template facts (fallback: builtin distilled
         // guide) so skill proposals follow the standard.
         skillsRoot: join(engine.baseDir, "skills"),
+        tokenUsage,
+        ...((config.prefixCacheMode !== undefined || config.prefixMaxChars !== undefined
+            ? {
+                prefixCache: {
+                    ...(config.prefixCacheMode !== undefined ? { mode: config.prefixCacheMode } : {}),
+                    ...(config.prefixMaxChars !== undefined ? { maxChars: config.prefixMaxChars } : {}),
+                },
+            }
+            : {})),
     });
     // Skills are governed resources: an auto-created skill is OFFERED to the
     // user for a decision (固化/不固化) before it lands — the gate never
@@ -308,7 +404,7 @@ async function runReviewPhase(ctx, engine, agent, config, state, reason, record)
         record({ sessionId, reason, turnsSinceLastReview, outcome: "declined", rationale: `${review.rationale}${withheld}` });
         return;
     }
-    const source = entrySourceOf(agent, sessionId);
+    const source = { sessionId, ...(snapshot.sourceSeqs.length > 0 ? { seqs: [...snapshot.sourceSeqs] } : {}) };
     const result = engine.apply("local", sessionId, finalProposal, {
         scope: "local",
         baselineState: localState,
@@ -317,23 +413,15 @@ async function runReviewPhase(ctx, engine, agent, config, state, reason, record)
     logger.info(`auto-review approved (${reason}) [${sessionId}] after ${turnsSinceLastReview} turns; auto-refine ${result.id}: ${result.appliedEdits.filter((e) => e.applied).length} applied, ${result.appliedEdits.filter((e) => !e.applied).length} failed — ${review.rationale}`);
     record({ sessionId, reason, turnsSinceLastReview, outcome: "approved", rationale: review.rationale, refinementId: result.id });
     // Gap C4: emit structured evolve_complete event for third-party consumers.
-    emitEvolveComplete(engine.baseDir, buildEvolveCompleteEvent(result, `auto_review:${reason}`, sessionId));
+    emitEvolveComplete(engine.baseDir, buildEvolveCompleteEvent(result, `auto_review:${reason}`, sessionId), config.reviewsRetain ?? DEFAULT_REVIEWS_RETAIN);
     // Visibility: tell the user what the gate just persisted. Only the
-    // turn-interval path notifies — a compaction-triggered gate must not wake
+    // turn snapshot path notifies — a compaction-triggered gate must not wake
     // the agent mid-compaction — and only when something was actually applied
     // (a notice for zero edits is noise). Failure is contained in notifyAutoReview.
-    if (config.notifyOnAutoReview && reason === "turn_interval" && result.appliedEdits.some((e) => e.applied)) {
+    if (config.notifyOnAutoReview && reason === "turn_snapshot" && result.appliedEdits.some((e) => e.applied)) {
         notifyAutoReview(ctx, agent, result, turnsSinceLastReview);
     }
 }
-async function readTrajectory(ctx, agent, maxChars) {
-    const sessionQuery = ctx.sessionQuery;
-    if (!sessionQuery) {
-        throw new Error("sessionQuery unavailable");
-    }
-    const snapshot = await sessionQuery.readSurface(agent.id);
-    return serializeSurface(snapshot.events, maxChars);
-}
 /**
  * Split a proposal into skill edits and everything else. Skill edits are the
  * governed part: they need explicit user consent before the gate applies