dsh-continual-evolve 0.6.1 → 0.7.1

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-576%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-665%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.
 
@@ -17,7 +17,8 @@ Continual self-evolution for [DeepSeek Harness](https://github.com/deepseek-ai/d
 
 Agents accumulate reusable experience (repeated failures, durable facts, reusable procedures) and forget it next session. This plugin turns that experience into first-class state:
 
-- **Local scope** per session; **global scope** across sessions with merge semantics — plus mechanical promotion guards so only portable, substantial, non-duplicate knowledge reaches global
+- **Three scopes** with merge semantics (global < project < local): **local** per-session staging, **project** per-workspace cross-session store, **global** cross-project — plus mechanical promotion guards so only portable, substantial, non-duplicate knowledge reaches global
+- **Typed one-fact memories**: every memory entry carries a recall type (`user | feedback | project | reference`); pitfalls (`feedback`) must include Why + How to apply
 - **Deterministic rollback**: inverse edits generated from applied results — no LLM re-guessing
 - **Benchmark loop**: candidate refinements are evaluated against frozen cases by a separate scorer before acceptance (rubric encrypted at rest)
 - **Store hygiene**: `/evolve consolidate` turns write-time conflict hints and zero-use staleness into one approved, fully reversible batch of archives — with `merge`, near-duplicate content folds into the surviving original
@@ -26,8 +27,8 @@ Agents accumulate reusable experience (repeated failures, durable facts, reusabl
 
 1. **Sediment** — the model creates entries via `evolve_add`, or the automatic review gate proposes them from the session trajectory (turn-interval + 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 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 capped directory index.
+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).
 5. **Validate & roll back** — benchmarks score candidates against frozen cases; rejected candidates roll back deterministically and are captured as draft regression cases (`auto_regression` benchmark).
 
 ## Install
@@ -49,7 +50,7 @@ Commands (in-session):
 | Command | Effect |
 |---|---|
 | `/evolve` | help + current local store |
-| `/evolve list · history · rollback <id>` | inspect and revert (add `global` for the cross-session store) |
+| `/evolve list · history · rollback <id>` | inspect and revert (add `project` for this project's store, `global` for the cross-project store) |
 | `/evolve plan [msg]` | run the LLM planner against the store |
 | `/evolve wrapup` | assess this session's local entries: promote / archive / keep |
 | `/evolve archive · unarchive · demote <id>` | hide from injection (data kept, restorable) — `demote` targets global noise |
@@ -60,12 +61,16 @@ 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.
 
-Injection shape: prompt notes and delegation specs inject with content (≤6/kind × 180 chars, relevance-ranked). Memories and skills appear as a directory index (`[kind:id] title`, capped at 15 lines with a fold counter) — full text via `evolve_list`. Empty store = zero injected tokens.
+`/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
 
@@ -77,7 +82,7 @@ Injection shape: prompt notes and delegation specs inject with content (≤6/kin
 | `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 |
-| `requireGlobalApproval` | `true` | global edits ask for explicit approval |
+| `requireGlobalApproval` | `true` | global and project edits ask for explicit approval |
 | `localFate` | `true` | gate audits local entries and proposes promote/archive (consulted, never silent) |
 | `fateIntervalTurns` | follows `reviewIntervalTurns` | minimum turns between fate assessments |
 | `goalBlockedWrapupTurns` | `3` | consecutive blocked-goal gate runs trigger one fate assessment (`0` disables) |
@@ -91,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:
 
@@ -105,7 +113,7 @@ Example profile patch:
 
 ```bash
 pnpm install && pnpm build   # deps + tsc -> lib/
-pnpm test                    # vitest (576 tests)
+pnpm test                    # vitest (665 tests)
 pnpm test:coverage           # v8 coverage, thresholds enforced in CI
 pnpm lint                    # oxlint src test
 ```
@@ -113,8 +121,8 @@ pnpm lint                    # oxlint src test
 Project layout:
 
 ```
-├── src/                   # engine, tools, commands, gate, fate, benchmark, usage…
-├── test/                  # vitest suites (36 files)
+├── src/                   # engine, tools, commands, gate, fate, benchmark, injection + token usage…
+├── test/                  # vitest suites (41 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-576%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-665%20passing-brightgreen)]()
 
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的持续自进化插件：一套**版本化、可审计、可回滚**的 harness 状态层——提示词补充、记忆、技能、子代理规格——从会话轨迹中沉淀而来。
 
@@ -17,7 +17,8 @@
 
 Agent 在每个会话里积累可复用经验（重复失败、持久事实、可复用流程），下个会话就忘掉。本插件把这些经验变成一等公民的持久状态：
 
-- **local 会话级 / global 跨会话** 双作用域与合并语义——配合机械化晋升守卫，只有可携带、有分量、非重复的知识才能进全局
+- **三作用域**与合并语义（global < project < local）：**local** 本会话暂存、**project** 本项目跨会话库、**global** 跨项目——配合机械化晋升守卫，只有可携带、有分量、非重复的知识才能进全局
+- **类型化单条记忆**：每条 memory 带召回类型（`user | feedback | project | reference`）；踩坑（`feedback`）必须含 Why + How to apply
 - **确定性回滚**：逆操作编辑由已应用结果生成——不靠 LLM 重新猜测
 - **benchmark 闭环**：候选沉淀先经冻结用例 + 独立评分者评估再接受（rubric 加密落盘）
 - **store 卫生**：`/evolve consolidate` 把写入时冲突提示与零使用陈旧条目变成一次批准、完全可逆的批量归档——加 `merge` 可将近重复内容并入幸存原条目
@@ -26,8 +27,8 @@ Agent 在每个会话里积累可复用经验（重复失败、持久事实、
 
 1. **沉淀**——模型经 `evolve_add` 创建条目，或自动 review 门禁从会话轨迹提议（回合间隔 + 压缩检查点）。
 2. **守卫**——代码强制校验：编辑 schema、blast-radius 与作用域一致性、晋升政策（项目专属标记 / 过薄内容 / 近似重复检测 / 凭据筛查保持全局库干净——密钥类内容在所有写入出口被拒，含 mount 物化）。全局 create 与既有条目高度相似（≥0.8）时写入即拒；中等重叠带 `conflictHint` 供后续合并。
-3. **审批**——全局写入需明确人工批准；local 归宿提议先征询后落地。
-4. **应用与注入**——原子应用带快照与审计事件。prompt 补充与委派规格注入系统提示词（封顶、按相关性排序、被证伪条目降权、空 store 零 token）；memory/skill 以目录索引出现。
+3. **审批**——全局与项目写入需明确人工批准；local 归宿提议先征询后落地。
+4. **应用与注入**——原子应用带快照与审计事件。prompt 补充与委派规格注入系统提示词（封顶、按相关性排序、被证伪条目降权、空 store 零 token）；memory/skill 以按相关性排序的目录索引出现（`[memory:type:id] 标题`钩子）。
 5. **验证与回滚**——benchmark 用冻结用例为候选打分；被拒候选确定性回滚，并自动沉淀为 draft 回归用例（`auto_regression` 基准）。
 
 ## 安装
@@ -49,7 +50,7 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | 命令 | 效果 |
 |---|---|
 | `/evolve` | 帮助 + 当前 local store |
-| `/evolve list · history · rollback <id>` | 查看与回滚（加 `global` 操作跨会话库） |
+| `/evolve list · history · rollback <id>` | 查看与回滚（加 `project` 操作本项目库，`global` 操作跨项目库） |
 | `/evolve plan [msg]` | 对 store 运行 LLM 规划器 |
 | `/evolve wrapup` | 收尾本会话 local 条目：晋升 / 归档 / 保留 |
 | `/evolve archive · unarchive · demote <id>` | 从注入中隐藏（数据保留可恢复）——`demote` 针对全局噪声 |
@@ -60,12 +61,16 @@ 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`），与人类可读的审计记录并存。
 
-注入形态：prompt 补充与委派规格带内容注入（每 kind ≤6 条 × 180 字符，按相关性排序）。memory/skill 以目录索引出现（`[kind:id] 标题`，15 行封顶 + 折叠计数行）——全文经 `evolve_list` 获取。空 store = 零注入 token。
+`/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。
 
 ## 配置
 
@@ -77,7 +82,7 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | `maxReviewInputChars` | `40000` | 交给门禁的轨迹切片 |
 | `reviewBudgetTokens` | `4096` | 门禁调用输出预算 |
 | `notifyOnAutoReview` | `true` | 门禁应用后发可见跟进通知 |
-| `requireGlobalApproval` | `true` | 全局写入需明确批准 |
+| `requireGlobalApproval` | `true` | 全局与项目写入需明确批准 |
 | `localFate` | `true` | 门禁审计本地条目并提议晋升/归档（先征询，绝不静默） |
 | `fateIntervalTurns` | 跟随 `reviewIntervalTurns` | 归宿评估的最小回合间隔 |
 | `goalBlockedWrapupTurns` | `3` | 连续阻塞目标的门禁轮数触发一次归宿评估（`0` 关闭） |
@@ -91,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 示例：
 
@@ -105,7 +113,7 @@ profile patch 示例：
 
 ```bash
 pnpm install && pnpm build   # 依赖 + tsc -> lib/
-pnpm test                    # vitest（576 例）
+pnpm test                    # vitest（665 例）
 pnpm test:coverage           # v8 覆盖率，CI 强制阈值
 pnpm lint                    # oxlint src test
 ```
@@ -113,8 +121,8 @@ pnpm lint                    # oxlint src test
 目录结构：
 
 ```
-├── src/                   # 引擎、工具、命令、门禁、fate、benchmark、usage…
-├── test/                  # vitest 测试套件（36 个文件）
+├── src/                   # 引擎、工具、命令、门禁、fate、benchmark、注入 + token 用量…
+├── test/                  # vitest 测试套件（41 个文件）
 ├── 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,6 +4,7 @@ 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 {
     intervalTurns: number;
     maxInputChars: number;
@@ -29,6 +30,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,6 +59,12 @@ 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;
@@ -103,14 +116,16 @@ export declare function parseReviewModel(reviewModel: string | undefined, fallba
 } | undefined;
 /**
  * The state view the gate and planner judge: the session's local entries
- * merged with the global store, each entry carrying its real scope. Without
- * the global half the gate cannot see that a topic is already covered
- * cross-session and happily re-sediments a local duplicate of it.
+ * merged with the project and global stores, each entry carrying its real
+ * scope. Without the global half the gate cannot see that a topic is already
+ * covered cross-session and happily re-sediments a local duplicate of it.
  *
  * The merged view is read-only context — applying still targets the raw
  * local state (baseline checks compare local entries only).
  */
-export declare function loadGateHarnessView(engine: EvolutionEngine, sessionId: string): HarnessState;
+export declare function loadGateHarnessView(engine: EvolutionEngine, sessionId: string, opts?: {
+    projectKey?: string;
+}): HarnessState;
 /**
  * D3 (goal blocked → wrap-up coupling, reverse direction): count consecutive
  * gate runs whose goal is in phase "blocked"; when the streak reaches

package/lib/auto.js

@@ -25,8 +25,11 @@ 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 { isGatePaused } from "./runtime.js";
 import { captureAutoCase } from "./autocase.js";
 /** Turns a rejected skill candidate stays silent before being offered again. */
 export const SKILL_CONSULT_COOLDOWN_TURNS = 10;
@@ -41,6 +44,14 @@ 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
@@ -66,6 +77,12 @@ export function registerAutoReview(ctx, engine, config) {
         const goalDriven = goalDrivesRounds(goalServiceOf(ctx)?.get(agent));
         if (!goalDriven && state.turns - state.lastReviewAt < config.intervalTurns)
             return;
+        // #21 P2 runtime switch: a paused gate stays fully dormant — no LLM
+        // calls, no fate assessments, no audit records. Checked after the
+        // cheap in-memory interval check so the paused path costs one file
+        // read at most. Manual tools/commands are unaffected (separate path).
+        if (isGatePaused(engine.baseDir))
+            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) => {
@@ -98,6 +115,12 @@ export function registerAutoReview(ctx, engine, config) {
     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("session/event", (session, event) => {
         if (event.type !== "compaction/start")
             return;
@@ -106,7 +129,11 @@ 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.
+        // Compaction is unconditional — unless the human paused the gate
+        // (#21): a paused gate skips even the compaction run, so "pause"
+        // is a true zero-LLM-call state.
+        if (isGatePaused(engine.baseDir))
+            return;
         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({
@@ -153,15 +180,16 @@ function stateFor(map, sessionId) {
 }
 /**
  * The state view the gate and planner judge: the session's local entries
- * merged with the global store, each entry carrying its real scope. Without
- * the global half the gate cannot see that a topic is already covered
- * cross-session and happily re-sediments a local duplicate of it.
+ * merged with the project and global stores, each entry carrying its real
+ * scope. Without the global half the gate cannot see that a topic is already
+ * covered cross-session and happily re-sediments a local duplicate of it.
  *
  * The merged view is read-only context — applying still targets the raw
  * local state (baseline checks compare local entries only).
  */
-export function loadGateHarnessView(engine, sessionId) {
-    return mergeHarnessStates(engine.load("global", undefined), engine.load("local", sessionId));
+export function loadGateHarnessView(engine, sessionId, opts) {
+    const projectState = opts?.projectKey ? engine.load("project", opts.projectKey) : undefined;
+    return mergeHarnessStates(engine.load("global", undefined), engine.load("local", sessionId), projectState ? { projectState } : undefined);
 }
 /**
  * One gate run = review phase + local-fate phase (#11 P2). The review phase
@@ -226,6 +254,12 @@ async function runReviewPhase(ctx, engine, agent, config, state, reason, record)
     const sessionId = agent.id;
     const turnsSinceLastReview = state.turns - state.lastReviewAt;
     const logger = ctx.logger("continual-evolve");
+    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 = 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)}` });
@@ -239,7 +273,8 @@ async function runReviewPhase(ctx, engine, agent, config, state, reason, record)
     // can recognize topics already covered globally and decline duplicates;
     // applying still targets the raw local store.
     const localState = engine.load("local", sessionId);
-    const harnessState = loadGateHarnessView(engine, sessionId);
+    const projectKey = projectKeyOf(agent);
+    const harnessState = loadGateHarnessView(engine, sessionId, projectKey ? { projectKey } : undefined);
     const history = engine.history("local", sessionId);
     // Gap C1: resolve optional review model override.
     const reviewRoute = parseReviewModel(config.reviewModel, agent.options.provider);
@@ -250,7 +285,16 @@ async function runReviewPhase(ctx, engine, agent, config, state, reason, record)
         trajectory,
         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) {
@@ -267,6 +311,15 @@ async function runReviewPhase(ctx, engine, agent, config, state, reason, record)
         // 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
@@ -314,7 +367,7 @@ 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
     // the agent mid-compaction — and only when something was actually applied

package/lib/command.d.ts

@@ -17,6 +17,12 @@ export interface CommandRuntimeOptions {
     autoCase: boolean;
     /** Mechanical promotion guards for wrapup/fate (2026-08-22 policy). */
     promotionPolicy: PromotionPolicy;
+    /**
+     * Static patch flag for the auto-review gate (#21 status display).
+     * Absent (older wiring/tests) renders as unknown — the runtime pause
+     * switch still works.
+     */
+    autoReview?: boolean;
 }
 export declare function registerEvolveCommand(ctx: Context, engine: EvolutionEngine, opts: CommandGateOptions, runtime: CommandRuntimeOptions): void;
 /**