dsh-continual-evolve 0.7.0 → 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-600%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.
 
@@ -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
@@ -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:
 
@@ -106,7 +113,7 @@ Example profile patch:
 
 ```bash
 pnpm install && pnpm build   # deps + tsc -> lib/
-pnpm test                    # vitest (600 tests)
+pnpm test                    # vitest (665 tests)
 pnpm test:coverage           # v8 coverage, thresholds enforced in CI
 pnpm lint                    # oxlint src test
 ```
@@ -114,8 +121,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 (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-600%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-665%20passing-brightgreen)]()
 
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的持续自进化插件：一套**版本化、可审计、可回滚**的 harness 状态层——提示词补充、记忆、技能、子代理规格——从会话轨迹中沉淀而来。
 
@@ -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。
 
 ## 配置
@@ -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 示例：
 
@@ -106,7 +113,7 @@ profile patch 示例：
 
 ```bash
 pnpm install && pnpm build   # 依赖 + tsc -> lib/
-pnpm test                    # vitest（600 例）
+pnpm test                    # vitest（665 例）
 pnpm test:coverage           # v8 覆盖率，CI 强制阈值
 pnpm lint                    # oxlint src test
 ```
@@ -114,8 +121,8 @@ pnpm lint                    # oxlint src test
 目录结构：
 
 ```
-├── src/                   # 引擎、工具、命令、门禁、fate、benchmark、usage…
-├── test/                  # vitest 测试套件（37 个文件）
+├── 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;

package/lib/auto.js

@@ -28,6 +28,8 @@ 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;
@@ -42,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
@@ -67,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) => {
@@ -99,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;
@@ -107,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({
@@ -228,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)}` });
@@ -253,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) {
@@ -270,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
@@ -317,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;
 /**

package/lib/command.js

@@ -5,7 +5,8 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { requireGlobalApproval } from "./approval.js";
 import { saveHarnessState } from "./state.js";
-import { appendResult, storePaths } from "./store.js";
+import { appendResult, pruneJsonlFile, storePaths } from "./store.js";
+import { DEFAULT_REFINEMENTS_RETAIN } from "./store.js";
 import { entrySourceOf } from "./source.js";
 import { filterLogBySession, formatLogLine, pluginLogFilePath } from "./logfile.js";
 import { collectFailureSummary, formatFailureSummary } from "./failures.js";
@@ -14,8 +15,10 @@ import { executeMountCommand, executeUnmountCommand } from "./mount-command.js";
 import { executeBenchmarkCommand } from "./benchmark-command.js";
 import { executeWrapupCommand } from "./wrapup-command.js";
 import { projectKeyOf } from "./project.js";
-import { loadUsage } from "./usage.js";
+import { loadUsage, getUsageCount } from "./usage.js";
+import { loadGateRuntime, saveGateRuntime } from "./runtime.js";
 import { planConsolidation } from "./consolidate.js";
+import { loadTokenUsage, renderTokenUsageReport } from "./token-usage.js";
 const USAGE = `Usage:
   /evolve                  show this help and the current local store
   /evolve list [project|global]    list entries (default local staging; "project" = this project's cross-session store, "global" = cross-project store)
@@ -40,7 +43,10 @@ const USAGE = `Usage:
   /evolve unmount <id>       remove a hot-mounted plugin
   /evolve goal               show the evolution goal (round-driven auto-review)
   /evolve goal <objective>   create/update the evolution goal
-  /evolve goal done          complete the evolution goal`;
+  /evolve goal done          complete the evolution goal
+  /evolve pause | resume     pause/resume the auto-review gate (manual tools and commands keep working)
+  /evolve status             gate state (patch flag + runtime switch) plus store entry counts
+  /evolve usage              injection counts + exact direct-call token usage (benchmark subagents excluded)`;
 export function registerEvolveCommand(ctx, engine, opts, runtime) {
     ctx.commands.register({
         name: "evolve",
@@ -323,6 +329,14 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                             appendResult(paths, result);
                         }
                     }
+                    // Storage hygiene (#20): an imported history obeys the
+                    // same tail budget as a live one.
+                    try {
+                        pruneJsonlFile(paths.resultsPath, engine.retention?.refinements ?? DEFAULT_REFINEMENTS_RETAIN);
+                    }
+                    catch {
+                        // ignored — the next apply retries
+                    }
                 }
                 return success(`imported ${scope} store from ${path}`);
             }
@@ -338,6 +352,12 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
                     ...(instructions ? { instructions } : {}),
                     global: scope === "global",
                     signal: invocation.signal,
+                    tokenUsage: {
+                        baseDir: engine.baseDir,
+                        sessionId,
+                        retain: engine.retention.tokenUsage,
+                        onError: (cause) => ctx.logger("continual-evolve").warn(`token-usage ledger failed for ${sessionId}: ${cause instanceof Error ? cause.message : String(cause)}`),
+                    },
                     // skill-creator template facts (fallback: builtin guide).
                     skillsRoot: join(engine.baseDir, "skills"),
                 });
@@ -354,6 +374,27 @@ async function executeEvolveCommand(ctx, engine, invocation, opts, runtime) {
             case "wrapup": {
                 return await executeWrapupCommand(ctx, engine, invocation, runtime.promotionPolicy);
             }
+            case "pause":
+            case "resume": {
+                // #21 P2 runtime switch: pause the AUTOMATIC gate only. Manual
+                // evolve_* tools and /evolve commands keep working — the human
+                // is acting explicitly there, so no gate is being bypassed.
+                const pausing = sub === "pause";
+                const current = loadGateRuntime(engine.baseDir);
+                if (current.paused === pausing) {
+                    return success(`auto-review gate is already ${pausing ? "paused" : "running"} (no change).`);
+                }
+                saveGateRuntime(engine.baseDir, pausing);
+                return success(pausing
+                    ? "auto-review gate paused: no automatic reviews, fate assessments, or gate LLM calls until /evolve resume. Manual evolve_* tools and /evolve commands keep working."
+                    : "auto-review gate resumed: automatic reviews run again on their configured cadence.");
+            }
+            case "status": {
+                return success(renderGateStatus(engine, sessionId, projectKeyOf(invocation.agent), runtime));
+            }
+            case "usage": {
+                return success(renderUsageReport(engine, sessionId, projectKeyOf(invocation.agent)));
+            }
             case "goal": {
                 return executeGoalCommand(ctx, invocation, rest);
             }
@@ -412,6 +453,101 @@ function demoteEntry(engine, id, sessionId, projectKey) {
     }
     return error(`entry ${id} not found in the global, project, or local store`);
 }
+/**
+ * #21 status: one screen answering "is the gate on, and what is in the
+ * stores". The patch flag says whether the gate was registered at boot;
+ * the runtime switch says whether the human paused it since.
+ */
+function renderGateStatus(engine, sessionId, projectKey, runtime) {
+    const paused = loadGateRuntime(engine.baseDir).paused;
+    const patch = runtime.autoReview === undefined ? "unknown" : runtime.autoReview ? "on" : "off";
+    const gateLine = patch === "off"
+        ? "gate: disabled in patch config (autoReview off — /evolve pause has nothing to pause)"
+        : `gate: ${patch === "unknown" ? "patch flag unknown" : "enabled in patch config"} · ${paused ? "PAUSED by /evolve pause (resume with /evolve resume)" : "running"}`;
+    const countEntries = (state) => Object.values(state.entries).reduce((n, byKind) => n + Object.keys(byKind).length, 0);
+    const lines = [gateLine];
+    lines.push(`stores: global ${countEntries(engine.load("global", undefined))} entries · local(${sessionId}) ${countEntries(engine.load("local", sessionId))} entries`);
+    if (projectKey) {
+        try {
+            lines[lines.length - 1] += ` · project ${countEntries(engine.load("project", projectKey))} entries`;
+        }
+        catch {
+            lines[lines.length - 1] += " · project (unavailable)";
+        }
+    }
+    const retention = engine.retention;
+    if (retention) {
+        lines.push(`retention: snapshots ${retention.snapshots} · refinements ${retention.refinements} · reviews ${retention.reviews} · token usage ${retention.tokenUsage} (historyRetain)`);
+    }
+    return lines.join("\n");
+}
+/**
+ * #21 P0 usage ledger: injection counts per entry across the stores the
+ * human can see (global + this session + this project). Counts are
+ * per-session since the v2 usage shape — "in how many sessions did this
+ * entry surface" — the exposure half of the #18a归零实验 verdict.
+ */
+function renderUsageReport(engine, sessionId, projectKey) {
+    const store = loadUsage(engine.baseDir);
+    const rows = [];
+    const seen = new Set();
+    const collect = (state) => {
+        for (const kind of Object.keys(state.entries)) {
+            for (const entry of Object.values(state.entries[kind])) {
+                const key = `${kind}:${entry.id}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                const count = getUsageCount(store, kind, entry.id);
+                rows.push({
+                    key,
+                    title: entry.title,
+                    count,
+                    ...(store.lastSession?.[`${kind}:${entry.id}`] ? { lastSession: store.lastSession[`${kind}:${entry.id}`] } : {}),
+                });
+            }
+        }
+    };
+    collect(engine.load("global", undefined));
+    collect(engine.load("local", sessionId));
+    if (projectKey) {
+        try {
+            collect(engine.load("project", projectKey));
+        }
+        catch {
+            // project store unavailable here — global+local still report
+        }
+    }
+    const liveKeys = new Set(rows.map((r) => r.key));
+    const orphaned = Object.keys(store.counts).filter((k) => !liveKeys.has(k)).length;
+    const total = rows.reduce((n, r) => n + r.count, 0);
+    const injected = rows.filter((r) => r.count > 0).sort((a, b) => b.count - a.count || (a.key < b.key ? -1 : 1));
+    const stale = rows.filter((r) => r.count === 0).sort((a, b) => (a.key < b.key ? -1 : 1));
+    const lines = [`injected entries: ${total} injections across ${injected.length} of ${rows.length} stored entries${orphaned > 0 ? ` (+${orphaned} historical key(s) for deleted entries)` : ""}`];
+    if (injected.length > 0) {
+        lines.push("injected (top 15):");
+        for (const row of injected.slice(0, 15)) {
+            lines.push(`  ${row.key} — ${row.count}× · ${row.title}${row.lastSession ? ` (last in ${row.lastSession})` : ""}`);
+        }
+        if (injected.length > 15) {
+            lines.push(`  … and ${injected.length - 15} more`);
+        }
+    }
+    else {
+        lines.push("injected: (none yet — nothing has surfaced into a session prompt)");
+    }
+    if (stale.length > 0) {
+        lines.push(`never injected (${stale.length}):`);
+        for (const row of stale.slice(0, 20)) {
+            lines.push(`  ${row.key} · ${row.title}`);
+        }
+        if (stale.length > 20) {
+            lines.push(`  … and ${stale.length - 20} more`);
+        }
+    }
+    lines.push("", ...renderTokenUsageReport(loadTokenUsage(engine.baseDir), engine.retention.tokenUsage));
+    return lines.join("\n");
+}
 function renderResult(result) {
     const applied = result.appliedEdits.filter((e) => e.applied);
     const failed = result.appliedEdits.filter((e) => !e.applied);

package/lib/evolve-event.d.ts

@@ -32,7 +32,9 @@ export declare function buildEvolveCompleteEvent(result: RefinementResult, trigg
 /**
  * Emit an evolve_complete event to the reviews.jsonl audit trail. The event
  * is JSONL-formatted (one line) so consumers can tail and parse it. This is
- * a best-effort write — failure never blocks the refinement path.
+ * a best-effort write — failure never blocks the refinement path. Storage
+ * hygiene (#20): the trail is truncated to its tail after the append so the
+ * audit file cannot grow without bound; readers only need a recent window.
  */
-export declare function emitEvolveComplete(baseDir: string, event: EvolveCompleteEvent): void;
+export declare function emitEvolveComplete(baseDir: string, event: EvolveCompleteEvent, reviewsRetain?: number): void;
 //# sourceMappingURL=evolve-event.d.ts.map

package/lib/evolve-event.js

@@ -11,6 +11,7 @@
  */
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
+import { DEFAULT_REVIEWS_RETAIN, pruneJsonlFile, reviewsPath } from "./store.js";
 /** Build a structured evolve-complete event from a refinement result. */
 export function buildEvolveCompleteEvent(result, trigger, sessionId) {
     return {
@@ -34,9 +35,11 @@ export function buildEvolveCompleteEvent(result, trigger, sessionId) {
 /**
  * Emit an evolve_complete event to the reviews.jsonl audit trail. The event
  * is JSONL-formatted (one line) so consumers can tail and parse it. This is
- * a best-effort write — failure never blocks the refinement path.
+ * a best-effort write — failure never blocks the refinement path. Storage
+ * hygiene (#20): the trail is truncated to its tail after the append so the
+ * audit file cannot grow without bound; readers only need a recent window.
  */
-export function emitEvolveComplete(baseDir, event) {
+export function emitEvolveComplete(baseDir, event, reviewsRetain = DEFAULT_REVIEWS_RETAIN) {
     try {
         const dir = join(baseDir, "evolve");
         mkdirSync(dir, { recursive: true });
@@ -44,6 +47,13 @@ export function emitEvolveComplete(baseDir, event) {
     }
     catch {
         // Event emission is diagnostic; never interrupt the refinement path.
+        return;
+    }
+    try {
+        pruneJsonlFile(reviewsPath(baseDir), reviewsRetain);
+    }
+    catch {
+        // ignored — the next emission retries
     }
 }
 //# sourceMappingURL=evolve-event.js.map

package/lib/fate.js

@@ -201,6 +201,12 @@ export async function runLocalFatePhase(ctx, engine, agent, config, state, reaso
         return;
     const logger = ctx.logger("continual-evolve");
     const sessionId = agent.id;
+    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 localState = engine.load("local", sessionId);
     const globalState = engine.load("global", undefined);
     const candidates = listLocalCandidates(localState, globalState, engine.baseDir);
@@ -218,7 +224,7 @@ export async function runLocalFatePhase(ctx, engine, agent, config, state, reaso
     state.lastFateAt = state.turns;
     let assessment;
     try {
-        assessment = await assessLocalEntries(ctx, agent, candidates);
+        assessment = await assessLocalEntries(ctx, agent, candidates, { tokenUsage, tokenUsagePhase: "fate" });
     }
     catch (cause) {
         const message = cause instanceof Error ? cause.message : String(cause);