dsh-continual-evolve 0.10.6 → 0.11.0

package/README.md

@@ -7,9 +7,9 @@
 [![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-1097%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-1020%20passing-brightgreen)]()
 [![Coverage · statements](https://img.shields.io/badge/coverage_statements-98%25-brightgreen)]()
-[![Coverage · branches](https://img.shields.io/badge/coverage_branches-92%25-green)]()
+[![Coverage · branches](https://img.shields.io/badge/coverage_branches-93%25-green)]()
 [![Coverage · functions](https://img.shields.io/badge/coverage_functions-99%25-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.
@@ -22,7 +22,7 @@ Agents accumulate reusable experience (repeated failures, durable facts, reusabl
 
 - **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
-- **Dedicated background memory agent**: eligible successful turns feed a bounded ZCode-style loop that searches the frozen memory manifest and proposes memory-only edits through a closed tool set; it cannot call agents, MCP, the network, or write source files. The generic review/planner/fate path is not run by this listener
+- **Moment-driven background memory agent**: a bounded ZCode-style loop wakes only at low-frequency moments (compaction, goal-blocked streaks, the session-close drain, manual wrapup), searches the frozen memory manifest, and proposes memory-only edits through a closed tool set; it cannot call agents, MCP, the network, or write source files. Successful turns never cost an LLM call — conversation writes own routine sedimentation
 - **Memory recall, projection, and receipts**: `evolve_recall` reads back full memory content by query/kind/scope/type; every memory apply also materializes a readable `MEMORY.md` index plus one fact file per entry; each extraction lands a unified audit receipt (no-op/applied/declined with duration and turn stats) and only applied outcomes notify the session
 - **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)
@@ -30,8 +30,8 @@ Agents accumulate reusable experience (repeated failures, durable facts, reusabl
 
 ## How it works
 
-1. **Sediment** — the model creates entries via `evolve_add`, or the automatic Memory Agent consumes incremental snapshots after successful turns. Generic review/planner remains manual unless separately invoked.
-2. **Capability-aware auxiliary calls** — the memory loop, review, planner, wrapup, and fate resolve exact provider/model metadata through [`src/llm-text.ts`](src/llm-text.ts), use the lowest advertised enabled reasoning effort (falling back to a closing effort only when no enabled level exists), and forward the host session id for provider routing; models without reasoning metadata use their provider default.
+1. **Sediment** — the model creates entries via `evolve_add`; the automatic Memory Agent consumes incremental snapshots only at the four low-frequency moments (compaction, goal-blocked streak, session-close drain, manual wrapup).
+2. **Capability-aware auxiliary calls** — the memory loop, planner, and wrapup resolve exact provider/model metadata through [`src/llm-text.ts`](src/llm-text.ts), use the lowest advertised enabled reasoning effort (falling back to a closing effort only when no enabled level exists), and forward the host session id for provider routing; models without reasoning metadata use their provider default.
 3. **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.
 4. **Approve** — global and project writes require explicit human approval; the dialog shows the bounded structured edit diff and conflict warnings, while malformed/lost responses remain retryable rather than counting as rejection.
 5. **Apply & inject** — memory batches preflight every persistent approval, recheck abort before writes, and compensate earlier scope writes if a later batch fails; every successful scope still passes through snapshot + audit. Prompt notes and delegation specs inject into the system prompt (capped, relevance-ranked, contradicted entries demoted, zero tokens when empty); memory CONTENT injects at session start under a hard character budget, frozen per session, with the when_to_save guide riding along; skills still appear as a relevance-ordered capped directory index.
@@ -86,15 +86,12 @@ Injection shape: prompt notes and delegation specs inject with content (≤6/kin
 | `autoReview` | `false` | initial Memory Agent default when no `evolve/runtime.json` exists yet; the listener is always registered, so this is not a registration gate |
 | `memoryMinUserWords` | `3` | ZCode-style minimum lexical words in one direct user text part; uses CJK-aware segmentation |
 | `sessionCloseDrainMs` | `15000` | session-close bounded drain for in-flight extraction in ms (`0` aborts immediately) |
-| `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 |
+| `maxReviewInputChars` | `40000` | trajectory slice handed to the extractor |
+| `reviewBudgetTokens` | `4096` | output budget for the extraction loop |
+| `notifyOnAutoReview` | `true` | visible follow-up receipt after an applied goal-blocked moment (compaction and session-close stay audit-only) |
 | `requireGlobalApproval` | `true` | global and project edits ask for explicit approval |
 | `recordLanguage` | `auto` | authoring **and dialog** language: `auto` follows the DSH client preference, then the session's own user text, then `en`; `zh`/`en` pin it |
-| `localFate` | `false` | optional local-entry promote/archive fate assessment; unreachable while the listener runs memory-only, so it only affects direct/full callers |
-| `fateIntervalTurns` | follows `reviewIntervalTurns` | minimum turns between fate assessments |
-| `goalBlockedWrapupTurns` | `3` | consecutive blocked-goal gate runs trigger one fate assessment (`0` disables) |
+| `goalBlockedWrapupTurns` | `3` | consecutive blocked-goal idle probes trigger one memory extraction (`0` disables) |
 | `promotionBlockPatterns` | POSIX paths, session ids, `~/.dsh` | content matching these is project-scoped and never promoted to global |
 | `promotionMinChars` | `100` | whole promotions below this length stay local |
 | `injectionDirectoryLines` | `15` | entry-directory lines per build before folding into a counter |
@@ -108,7 +105,7 @@ Injection shape: prompt notes and delegation specs inject with content (≤6/kin
 | `logToFile` / `logLevel` / `logMaxBytes` | `true` / `1` / 5 MiB | plugin-owned JSONL file log with rotation |
 | `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 dedicated memory agent and review gate (`"provider/model"`) |
+| `reviewModel` | agent's own | optional cheaper model for the dedicated memory agent (`"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 |
@@ -119,32 +116,28 @@ Example profile patch:
 - id: continual-evolve
   config:
     autoReview: true
-    reviewIntervalTurns: 6
 ```
 
 The Memory Agent listener is registered even when `autoReview` is `false` —
 `autoReview` only supplies the initial default, so an install works without
-editing the profile. Use `/evolve resume` to enable successful-turn snapshots
-immediately, `/evolve pause` to suppress new snapshots and 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. Only the Memory Agent runs
-automatically: the generic review/planner, prompt/skill writes, and local-fate
-phases are not reachable from this listener. The memory trigger follows ZCode's
+editing the profile. Use `/evolve resume` to enable extraction moments
+immediately, `/evolve pause` to suppress new 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. The memory trigger follows ZCode's
 lightweight eligibility: direct user text must contain at least
 `memoryMinUserWords` lexical words (CJK-aware segmentation), while
-empty/internal/direct-memory-write snapshots are skipped; compaction does not
-add a separate memory-only trigger. Every extraction writes a unified audit
-receipt (`noop`/`applied`/`declined` with duration and turn/search stats) to
-`reviews.jsonl`; only applied outcomes queue a visible follow-up, and a
-closing session lets in-flight extraction settle up to `sessionCloseDrainMs`
-before aborting.
+empty/internal/direct-memory-write snapshots are skipped. Every extraction
+writes a unified audit receipt (`noop`/`applied`/`declined` with duration and
+turn/search stats) to `reviews.jsonl`; only an applied goal-blocked moment
+queues a visible follow-up, and a closing session lets in-flight extraction
+settle up to `sessionCloseDrainMs` before aborting.
 
 ## Development
 
 ```bash
 pnpm install && pnpm build   # deps + tsc -> lib/
-pnpm test                    # vitest (1097 tests)
+pnpm test                    # vitest (1020 tests)
 pnpm test:coverage           # v8 coverage, thresholds enforced in CI
 pnpm coverage:gaps           # locate uncovered lines per file (read-only)
 pnpm lint                    # oxlint src test
@@ -153,11 +146,11 @@ pnpm lint                    # oxlint src test
 Project layout:
 
 ```
-├── src/                   # engine, tools, commands, memory agent, recall, projection, gate, fate, benchmark, injection + token usage…
-├── test/                  # vitest suites (59 files)
+├── src/                   # engine, tools, commands, memory agent, recall, projection, benchmark, injection + token usage…
+├── test/                  # vitest suites (57 files)
 ├── lib/                   # build output (tsc)
 ├── docs/
-│   ├── design.md          # full design doc (hardening matrix)
+│   ├── design.md          # the one-loop design narrative
 │   ├── FAQ.md             # real failure/fix records
 │   ├── gap-analysis.md    # vs prime-agent /refine + penguin-harness
 │   ├── research/pi-dsh-competitor-gap-analysis.md  # pi/dsh ecosystem competitors

package/README.zh.md

@@ -7,9 +7,9 @@
 [![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-1097%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-1020%20passing-brightgreen)]()
 [![Coverage · statements](https://img.shields.io/badge/coverage_statements-98%25-brightgreen)]()
-[![Coverage · branches](https://img.shields.io/badge/coverage_branches-92%25-green)]()
+[![Coverage · branches](https://img.shields.io/badge/coverage_branches-93%25-green)]()
 [![Coverage · functions](https://img.shields.io/badge/coverage_functions-99%25-brightgreen)]()
 
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）的持续自进化插件：一套**版本化、可审计、可回滚**的 harness 状态层——提示词补充、记忆、技能、子代理规格——从会话轨迹中沉淀而来。
@@ -22,7 +22,7 @@ Agent 在每个会话里积累可复用经验（重复失败、持久事实、
 
 - **三作用域**与合并语义（global < project < local）：**local** 本会话暂存、**project** 本项目跨会话库、**global** 跨项目——配合机械化晋升守卫，只有可携带、有分量、非重复的知识才能进全局
 - **类型化单条记忆**：每条 memory 带召回类型（`user | feedback | project | reference`）；踩坑（`feedback`）必须含 Why + How to apply
-- **专用后台记忆 Agent**：成功回合通过机械 eligibility 后，有界 ZCode 式 loop 检索冻结的 memory manifest，并经闭集工具提出纯 memory 编辑；不能调用 Agent、MCP、网络，也不能写源码。该 listener 不运行通用 review/planner/fate
+- **时刻驱动的后台记忆 Agent**：有界 ZCode 式 loop 只在四个低频时刻醒来（压缩、goal 连续受阻、会话收尾 drain、手动 wrapup），检索冻结的 memory manifest，并经闭集工具提出纯 memory 编辑；不能调用 Agent、MCP、网络，也不能写源码。成功回合零 LLM 成本——日常沉淀由对话直写承担
 - **记忆召回、投影与回执**：`evolve_recall` 按 query/kind/scope/type 精确读回记忆全文；每次 memory 落盘同时生成可读的 `MEMORY.md` 索引 + 单事实文件；每次提取留统一审计回执（no-op/applied/declined + 耗时与轮次统计），只有实际沉淀才通知会话
 - **确定性回滚**：逆操作编辑由已应用结果生成——不靠 LLM 重新猜测
 - **benchmark 闭环**：候选沉淀先经冻结用例 + 独立评分者评估再接受（rubric 加密落盘）
@@ -30,8 +30,8 @@ Agent 在每个会话里积累可复用经验（重复失败、持久事实、
 
 ## 工作原理
 
-1. **沉淀**——模型经 `evolve_add` 创建条目，或由专用 Memory Agent 消费成功回合后的增量 snapshot。通用 review/planner 保持手动，除非另行显式调用。
-2. **能力感知的辅助调用**——memory loop、review、planner、wrapup、fate 通过 [`src/llm-text.ts`](src/llm-text.ts) 解析精确 provider/model 能力并使用模型公布的最低开启 reasoning effort，同时转发 host session id 供 provider 路由；只有没有开启档时才回退关闭档，没有 reasoning 元数据时使用 provider 默认行为。
+1. **沉淀**——模型经 `evolve_add` 创建条目；专用 Memory Agent 只在四个低频时刻消费增量 snapshot（压缩、goal 连续受阻、会话收尾 drain、手动 wrapup）。
+2. **能力感知的辅助调用**——memory loop、planner、wrapup 通过 [`src/llm-text.ts`](src/llm-text.ts) 解析精确 provider/model 能力并使用模型公布的最低开启 reasoning effort，同时转发 host session id 供 provider 路由；只有没有开启档时才回退关闭档，没有 reasoning 元数据时使用 provider 默认行为。
 3. **守卫**——代码强制校验：编辑 schema、blast-radius 与作用域一致性、晋升政策（项目专属标记 / 过薄内容 / 近似重复检测 / 凭据筛查保持全局库干净——密钥类内容在所有写入出口被拒，含 mount 物化）。全局 create 与既有条目高度相似（≥0.8）时写入即拒；中等重叠带 `conflictHint` 供后续合并。
 4. **审批**——全局与项目写入需明确人工批准；弹窗展示有界结构化编辑 diff 与冲突提示，弹窗丢失/响应畸形会重试，不会被误记为拒绝。
 5. **应用与注入**——memory 批次先完成所有持久化审批，写前重查 abort；后续 scope 失败时补偿回滚先前写入，成功 scope 仍保留快照与审计。prompt 补充与委派规格注入系统提示词（封顶、按相关性排序、被证伪条目降权、空 store 零 token）；**memory 正文**在会话开场按硬预算注入（会话内冻结，when_to_save 指南随行）；skill 仍以按相关性排序的目录索引出现。
@@ -67,14 +67,14 @@ 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` | 每条目注入次数 + memory/review/planner/wrapup/fate 直属调用的 provider 精确 token（不含 benchmark 宿主子代理） |
+| `/evolve pause · resume · status` | 暂停/恢复自动提取（手动工具不受影响）、运行时状态 |
+| `/evolve usage` | 每条目注入次数 + memory/planner/wrapup 直属调用的 provider 精确 token（不含 benchmark 宿主子代理） |
 
 模型工具：`evolve_list / add / update / delete / rollback / recall`（`evolve_delete` 支持 `id` 或批量 `ids` 数组——一次 refinement、一次审批；`evolve_recall` 按 query/kind/scope/memoryType/limit 过滤，返回全文 + 版本 + 来源 + 过时信号）。记忆的读写都在对话里完成——模型手里有注入的记忆索引 + `evolve_recall`/`evolve_add`——因此不再有 `/evolve remember · forget · recall` 对应命令：直接在对话里说。
 
 第三方消费：每次进化落地（门禁或手动）都会向 `reviews.jsonl` 追加结构化 `evolve_complete` 事件（shape 见 `src/evolve-event.ts`），与人类可读的审计记录并存。
 
-`/evolve usage` 还会读取 `evolve/token-usage.jsonl`：插件直属 memory Agent、review、planner、手动 wrapup 与自动 fate 调用的 provider 精确 input/cache/output/total token。报告只覆盖保留尾部而非终身累计，单独显示 provider 未返回 usage 的调用，并明确排除宿主 benchmark 子代理、其 agent-loop 调用与逐条 memory 注入归因。
+`/evolve usage` 还会读取 `evolve/token-usage.jsonl`：插件直属 memory Agent、planner 与手动 wrapup 调用的 provider 精确 input/cache/output/total token。报告只覆盖保留尾部而非终身累计，单独显示 provider 未返回 usage 的调用，并明确排除宿主 benchmark 子代理、其 agent-loop 调用与逐条 memory 注入归因。
 
 注入形态：prompt 补充与委派规格带内容注入（每 kind ≤6 条 × 180 字符，按相关性排序）。memory 以**正文**在会话开场注入：`evolve:memory-index` section（order 400）承载 when_to_save 指南 + 预算内的全部记忆正文，排序 `project > feedback > user > reference`，放不下的降级为 `[memory:type:id] 标题`钩子、其余折叠计数（硬上限 `memoryIndex.maxChars`，默认 6000 字符；未展示的用 `evolve_recall` 读）。该 section 每会话只算一次并逐字节复用，system prompt 因此稳定、prompt cache 持续命中——会话中途写入的记忆下个会话生效。skill 仍以按相关性排序的目录索引出现（15 行封顶 + 折叠计数行），memory 不再列入。每次 memory 落盘同时刷新 store 目录下的可读 `MEMORY.md` 索引 + 单事实文件。`memoryIndex.guide` 关闭且 store 为空时 = 零注入 token。
 
@@ -86,15 +86,12 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | `autoReview` | `false` | 没有 `evolve/runtime.json` 时 Memory Agent 的初始默认；监听器始终注册，因此它不是注册门 |
 | `memoryMinUserWords` | `3` | ZCode 风格：单个直接用户文本至少包含的词数；使用 CJK 分词 |
 | `sessionCloseDrainMs` | `15000` | 会话关闭时在途提取的有界 drain（毫秒，`0` 立即 abort） |
-| `reviewIntervalTurns` | `6` | local-fate 的兼容节奏；成功回合 review 不再等待这个间隔 |
-| `maxReviewInputChars` | `40000` | 交给门禁的轨迹切片 |
-| `reviewBudgetTokens` | `4096` | 门禁调用输出预算 |
-| `notifyOnAutoReview` | `true` | 门禁应用后发可见跟进通知 |
+| `maxReviewInputChars` | `40000` | 交给提取器的轨迹切片 |
+| `reviewBudgetTokens` | `4096` | 提取 loop 输出预算 |
+| `notifyOnAutoReview` | `true` | goal 受阻时刻应用后发可见跟进回执（压缩与会话收尾只留审计） |
 | `requireGlobalApproval` | `true` | 全局与项目写入需明确批准 |
 | `recordLanguage` | `auto` | 记录**与弹窗**语言：`auto` 依次跟随 DSH 客户端偏好 → 会话自身用户文本 → `en`；`zh`/`en` 固定 |
-| `localFate` | `false` | 可选的本地条目晋升/归档 fate 评估；listener 以 memory-only 运行时不可达，只对直接/完整调用者生效 |
-| `fateIntervalTurns` | 跟随 `reviewIntervalTurns` | 归宿评估的最小回合间隔 |
-| `goalBlockedWrapupTurns` | `3` | 连续阻塞目标的门禁轮数触发一次归宿评估（`0` 关闭） |
+| `goalBlockedWrapupTurns` | `3` | 连续阻塞目标的 idle 探测轮数触发一次记忆提取（`0` 关闭） |
 | `promotionBlockPatterns` | POSIX 路径、session id、`~/.dsh` | 内容命中即判定项目专属，永不晋升全局 |
 | `promotionMinChars` | `100` | 低于此长度的整体晋升留在本地 |
 | `injectionDirectoryLines` | `15` | 每次构建的目录行数上限，超出折叠为计数行 |
@@ -108,7 +105,7 @@ dsh plugin add ZK-Andy/dsh-continual-evolve
 | `logToFile` / `logLevel` / `logMaxBytes` | `true` / `1` / 5 MiB | 插件自带 JSONL 文件日志带轮转 |
 | `autoRollbackOnReject` | `true` | benchmark 拒绝后自动确定性回滚 |
 | `autoCase` | `true` | 失败的进化尝试自动沉淀为 draft 回归用例（`auto_regression` 基准） |
-| `reviewModel` | agent 自身 | 专用 memory Agent 与 review 门禁可选更便宜的模型（`"provider/model"`） |
+| `reviewModel` | agent 自身 | 专用 memory 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` 尾行 |
@@ -119,16 +116,15 @@ profile patch 示例：
 - id: continual-evolve
   config:
     autoReview: true
-    reviewIntervalTurns: 6
 ```
 
-即使 `autoReview` 为 `false`，Memory Agent 监听器也会注册——`autoReview` 只提供初始默认值，装完即用，无需改 profile。使用 `/evolve resume` 立即开启成功回合 snapshot，使用 `/evolve pause` 抑制新 snapshot 与模型调用，使用 `/evolve status` 查看配置默认值与运行时状态。开关保存在 `evolve/runtime.json`；手动 `evolve_*` 工具和 `/evolve` 命令不受暂停影响。自动运行只有 Memory Agent：通用 review/planner、prompt/skill 写入与 local fate 都不由该 listener 触达。Memory 触发采用 ZCode 的轻量 eligibility：单个直接用户文本至少包含 `memoryMinUserWords` 个词（使用 CJK 分词）；空增量、内部 Agent、直接 memory 写入会跳过，压缩不会额外触发 memory-only 管线。每次提取都在 `reviews.jsonl` 留统一审计回执（`noop`/`applied`/`declined` + 耗时与轮次/检索统计）；只有实际沉淀才排队前台通知，关闭的会话让在途提取在 `sessionCloseDrainMs` 内收尾再 abort。
+即使 `autoReview` 为 `false`，Memory Agent 监听器也会注册——`autoReview` 只提供初始默认值，装完即用，无需改 profile。使用 `/evolve resume` 立即开启提取时刻，使用 `/evolve pause` 抑制新的模型调用，使用 `/evolve status` 查看配置默认值与运行时状态。开关保存在 `evolve/runtime.json`；手动 `evolve_*` 工具和 `/evolve` 命令不受暂停影响。提取时刻驱动：压缩、goal 连续受阻（`goalBlockedWrapupTurns` 次 idle 探测）、会话收尾 drain（`sessionCloseDrainMs`）与手动 `/evolve wrapup`——成功回合零 LLM 成本。Memory 触发采用 ZCode 的轻量 eligibility：单个直接用户文本至少包含 `memoryMinUserWords` 个词（使用 CJK 分词）；空增量、内部 Agent、直接 memory 写入会跳过。每次提取都在 `reviews.jsonl` 留统一审计回执（`noop`/`applied`/`declined` + 耗时与轮次/检索统计）；只有 goal 受阻时刻的实际沉淀才排队前台回执，关闭的会话让在途提取在 `sessionCloseDrainMs` 内收尾再 abort。
 
 ## 开发
 
 ```bash
 pnpm install && pnpm build   # 依赖 + tsc -> lib/
-pnpm test                    # vitest（1097 例）
+pnpm test                    # vitest（1020 例）
 pnpm test:coverage           # v8 覆盖率，CI 强制阈值
 pnpm coverage:gaps           # 定位各文件未覆盖行（只读）
 pnpm lint                    # oxlint src test
@@ -137,11 +133,11 @@ pnpm lint                    # oxlint src test
 目录结构：
 
 ```
-├── src/                   # 引擎、工具、命令、memory Agent、召回、投影、门禁、fate、benchmark、注入 + token 用量…
+├── src/                   # 引擎、工具、命令、memory Agent、召回、投影、benchmark、注入 + token 用量…
 ├── test/                  # vitest 测试套件（59 个文件）
 ├── lib/                   # 构建产物（tsc）
 ├── docs/
-│   ├── design.md          # 完整设计文档（硬化矩阵）
+│   ├── design.md          # 一条循环的设计叙事
 │   ├── FAQ.md             # 真实踩坑记录
 │   ├── gap-analysis.md    # 对照 prime-agent /refine + penguin-harness
 │   ├── research/pi-dsh-competitor-gap-analysis.md  # pi/dsh 生态竞品差距分析

package/lib/approval.d.ts

@@ -7,7 +7,8 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { Agent } from "@deepseek-ai/dsh-agent";
 import { type RecordLanguagePreference } from "./record-language.js";
-export type ScopeApprovalDecision = "approved" | "declined";
+export { type ScopeApprovalDecision } from "./types.js";
+import type { ScopeApprovalDecision } from "./types.js";
 /** Labels the approval dialog offers for each decision (parser contract). */
 export declare const APPROVE_LABELS: readonly ["批准", "Approve"];
 export declare const DECLINE_LABELS: readonly ["拒绝", "Decline"];

package/lib/audit-log.d.ts

@@ -0,0 +1,19 @@
+export interface ReviewAuditRow {
+    sessionId: string;
+    reason: string;
+    turnsSinceLastReview: number;
+    outcome: string;
+    rationale?: string;
+    [key: string]: unknown;
+}
+/** Resolve the shared audit trail path under `<baseDir>/evolve/`. */
+export declare function reviewsAuditPath(baseDir: string): string;
+/** Append one audit row and bound the trail at write time. Never throws. */
+export declare function appendReviewRecord(baseDir: string, entry: ReviewAuditRow, retain: number | undefined, onError?: (cause: unknown) => void): void;
+/**
+ * Boot-time diagnostic: the armed marker proves the listener was registered
+ * even when its runtime default is off, distinguishing "not registered"
+ * from "off". Never throws.
+ */
+export declare function writeArmedMarker(baseDir: string, rationale: string, onError?: (cause: unknown) => void): void;
+//# sourceMappingURL=audit-log.d.ts.map

package/lib/audit-log.js

@@ -0,0 +1,52 @@
+/**
+ * The shared `reviews.jsonl` audit trail: the only writer for extraction
+ * decisions, mechanical skips, and the boot armed marker. Writes are
+ * contained — a broken ledger must never break the extraction path that
+ * already made its decision.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_REVIEWS_RETAIN, pruneJsonlFile } from "./store.js";
+/** Resolve the shared audit trail path under `<baseDir>/evolve/`. */
+export function reviewsAuditPath(baseDir) {
+    return join(baseDir, "evolve", "reviews.jsonl");
+}
+/** Append one audit row and bound the trail at write time. Never throws. */
+export function appendReviewRecord(baseDir, entry, retain, onError) {
+    try {
+        mkdirSync(join(baseDir, "evolve"), { recursive: true });
+        appendFileSync(reviewsAuditPath(baseDir), `${JSON.stringify({ ...entry, timestamp: new Date().toISOString() })}\n`, "utf8");
+    }
+    catch (cause) {
+        onError?.(cause);
+        return;
+    }
+    try {
+        pruneJsonlFile(reviewsAuditPath(baseDir), retain ?? DEFAULT_REVIEWS_RETAIN);
+    }
+    catch {
+        // ignored — the next record retries
+    }
+}
+/**
+ * Boot-time diagnostic: the armed marker proves the listener was registered
+ * even when its runtime default is off, distinguishing "not registered"
+ * from "off". Never throws.
+ */
+export function writeArmedMarker(baseDir, rationale, onError) {
+    try {
+        mkdirSync(join(baseDir, "evolve"), { recursive: true });
+        appendFileSync(reviewsAuditPath(baseDir), `${JSON.stringify({
+            timestamp: new Date().toISOString(),
+            sessionId: "boot",
+            reason: "boot",
+            turnsSinceLastReview: 0,
+            outcome: "armed",
+            rationale,
+        })}\n`, "utf8");
+    }
+    catch (cause) {
+        onError?.(cause);
+    }
+}
+//# sourceMappingURL=audit-log.js.map

package/lib/benchmark-command.d.ts

@@ -4,6 +4,6 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { CommandInvocation, CommandResult } from "@deepseek-ai/dsh-commands";
 import type { EvolutionEngine } from "./service.js";
-import type { CommandRuntimeOptions } from "./command.js";
+import type { CommandRuntimeOptions } from "./command-util.js";
 export declare function executeBenchmarkCommand(ctx: Context, engine: EvolutionEngine, invocation: CommandInvocation, rest: string[], runtime: CommandRuntimeOptions): Promise<CommandResult>;
 //# sourceMappingURL=benchmark-command.d.ts.map

package/lib/benchmark-command.js

@@ -1,5 +1,5 @@
 import { formatHarnessStateForPrompt } from "./render.js";
-import { stripAngleBrackets } from "./command.js";
+import { stripAngleBrackets } from "./command-util.js";
 import { addCase, caseCheckProblems, createBenchmark, listBenchmarks, listCases, loadBenchmark, loadCaseMeta, loadScoreboard, rollbackRejectedCandidate, saveCaseMeta, saveScoreboard, transitionCaseStatus } from "./benchmark.js";
 import { AUTO_CASE_BENCHMARK_ID, captureAutoCase } from "./autocase.js";
 import { decide, decisionReport, entryFromCells, flagMaterialDrift } from "./score.js";

package/lib/command-util.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared command-surface utilities: pure input parsing, entry lookup, and
+ * result rendering used by the `/evolve` router and every sub-command file.
+ * Lives below the interface layer so sub-command files can import it without
+ * cycling through command.ts.
+ */
+import type { HarnessEntry, HarnessState, HarnessScope, RefinementKind, RefinementResult } from "./types.js";
+import type { CommandInvocation } from "@deepseek-ai/dsh-commands";
+import type { PromotionPolicy } from "./promotion.js";
+import type { RecordLanguagePreference } from "./record-language.js";
+export interface CommandGateOptions {
+    requireGlobalApproval: boolean;
+}
+export interface CommandRuntimeOptions {
+    rubricKey: Buffer;
+    /** When a benchmark decision rejects a candidate, roll the refinement back automatically. */
+    autoRollbackOnReject: boolean;
+    /** P1: capture failed evolution attempts as draft cases in the auto-regression benchmark. */
+    autoCase: boolean;
+    /** Mechanical promotion guards for wrapup (2026-08-22 policy). */
+    promotionPolicy: PromotionPolicy;
+    /**
+     * Initial Memory Agent default from plugin config. The listener is always
+     * registered; this is not a registration gate.
+     */
+    autoReview?: boolean;
+    /** Plugin `recordLanguage` preference for dialog copy (see `approval.ts`). */
+    recordLanguage?: RecordLanguagePreference;
+}
+/** Parse an optional leading scope token ("global" | "project") off the args. */
+export declare function scopeArg(tokens: string[]): {
+    scope: HarnessScope;
+    rest: string[];
+};
+/**
+ * The store id a scope reads/writes from the human command: live session id
+ * for local, derived project key for project, undefined for global. Throws
+ * for project when the session cwd is unavailable.
+ */
+export declare function storeIdForCommand(scope: HarnessScope, invocation: CommandInvocation): string | undefined;
+/**
+ * Tokenize a command's raw input with shell-like quoting:
+ * - a `#` outside quotes starts a comment (rest of the line is dropped);
+ * - whitespace separates tokens;
+ * - double or single quotes group words into one token and are stripped.
+ *
+ * This lets users paste help-text examples verbatim, e.g.
+ * `/evolve benchmark add-case <bid> "<title>" "<statement>" "<rubric>"`.
+ */
+export declare function tokenizeEvolveInput(rawInput: string): string[];
+/** Accept both `<id>` (help-text placeholder form) and bare `id`. */
+export declare function stripAngleBrackets(value: string): string;
+/**
+ * Locate an entry by id across every kind of a store. Ids are only unique
+ * within a kind, so the lookup scans all four and returns the first match
+ * (kind + entry) or undefined. Used by archive/unarchive, which take a bare
+ * id from the user.
+ */
+export declare function findEntryById(state: HarnessState, id: string): [RefinementKind, HarnessEntry] | undefined;
+export declare function parsePositiveInt(value: string, what: string): number;
+/** Structural stand-in for the host `CommandResult` (kind + text only). */
+export interface CommandTextResult {
+    kind: "success" | "error";
+    text: string;
+}
+export declare function success(text: string): CommandTextResult;
+export declare function error(text: string): CommandTextResult;
+/** Human-readable one-refinement rendering shared by every apply path. */
+export declare function renderResult(result: RefinementResult): string;
+//# sourceMappingURL=command-util.d.ts.map

package/lib/command-util.js

@@ -0,0 +1,123 @@
+import { projectKeyOf } from "./project.js";
+/** Parse an optional leading scope token ("global" | "project") off the args. */
+export function scopeArg(tokens) {
+    if (tokens[0] === "global") {
+        return { scope: "global", rest: tokens.slice(1) };
+    }
+    if (tokens[0] === "project") {
+        return { scope: "project", rest: tokens.slice(1) };
+    }
+    return { scope: "local", rest: tokens };
+}
+/**
+ * The store id a scope reads/writes from the human command: live session id
+ * for local, derived project key for project, undefined for global. Throws
+ * for project when the session cwd is unavailable.
+ */
+export function storeIdForCommand(scope, invocation) {
+    if (scope === "local") {
+        return invocation.agent.id;
+    }
+    if (scope === "project") {
+        const key = projectKeyOf(invocation.agent);
+        if (!key) {
+            throw new Error("project scope needs the session cwd (unavailable here) — use local or global instead");
+        }
+        return key;
+    }
+    return undefined;
+}
+/**
+ * Tokenize a command's raw input with shell-like quoting:
+ * - a `#` outside quotes starts a comment (rest of the line is dropped);
+ * - whitespace separates tokens;
+ * - double or single quotes group words into one token and are stripped.
+ *
+ * This lets users paste help-text examples verbatim, e.g.
+ * `/evolve benchmark add-case <bid> "<title>" "<statement>" "<rubric>"`.
+ */
+export function tokenizeEvolveInput(rawInput) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    for (const char of rawInput) {
+        if (quote !== null) {
+            if (char === quote) {
+                quote = null;
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === "#") {
+            break; // rest of the line is a comment
+        }
+        if (/\s/.test(char)) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += char;
+    }
+    if (current.length > 0) {
+        tokens.push(current);
+    }
+    return tokens;
+}
+/** Accept both `<id>` (help-text placeholder form) and bare `id`. */
+export function stripAngleBrackets(value) {
+    return value.replace(/^<|>$/g, "");
+}
+/**
+ * Locate an entry by id across every kind of a store. Ids are only unique
+ * within a kind, so the lookup scans all four and returns the first match
+ * (kind + entry) or undefined. Used by archive/unarchive, which take a bare
+ * id from the user.
+ */
+export function findEntryById(state, id) {
+    for (const kind of Object.keys(state.entries)) {
+        const entry = state.entries[kind][id];
+        if (entry) {
+            return [kind, entry];
+        }
+    }
+    return undefined;
+}
+export function parsePositiveInt(value, what) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`${what} must be a positive integer, got "${value}"`);
+    }
+    return n;
+}
+export function success(text) {
+    return { kind: "success", text };
+}
+export function error(text) {
+    return { kind: "error", text };
+}
+/** Human-readable one-refinement rendering shared by every apply path. */
+export function renderResult(result) {
+    const applied = result.appliedEdits.filter((e) => e.applied);
+    const failed = result.appliedEdits.filter((e) => !e.applied);
+    const lines = [
+        `refinement ${result.id}${result.rollbackOf ? ` (rollback of ${result.rollbackOf})` : ""}: ${applied.length} applied, ${failed.length} failed`,
+        `summary: ${result.summary}`,
+    ];
+    for (const e of applied) {
+        lines.push(`- ${e.action} ${e.kind}:${e.id} (v${(e.after?.version ?? e.before?.version) ?? "?"})`);
+    }
+    for (const e of failed) {
+        lines.push(`- failed ${e.action} ${e.kind}:${e.id ?? "(computed)"} — ${e.error ?? "unknown error"}`);
+    }
+    lines.push(`expected outcome: ${result.expectedOutcome}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=command-util.js.map

package/lib/command.d.ts

@@ -1,49 +1,13 @@
 /**
- * The human-facing `/evolve` command: inspect and drive the continual
- * harness from the chat UI without the model in between.
+ * The human-facing `/evolve` command router: parse the subcommand and hand
+ * off to its implementation file. Subcommand logic lives in the
+ * `*-command.ts` modules; this file owns only registration, help text, and
+ * the core inspect/rollback flows.
  */
 import type { Context } from "@deepseek-ai/cordis";
-import type { HarnessEntry, HarnessState, RefinementKind } from "./types.js";
 import type { EvolutionEngine } from "./service.js";
-import type { PromotionPolicy } from "./promotion.js";
-import type { RecordLanguagePreference } from "./record-language.js";
-export interface CommandGateOptions {
-    requireGlobalApproval: boolean;
-}
-export interface CommandRuntimeOptions {
-    rubricKey: Buffer;
-    /** When a benchmark decision rejects a candidate, roll the refinement back automatically. */
-    autoRollbackOnReject: boolean;
-    /** P1: capture failed evolution attempts as draft cases in the auto-regression benchmark. */
-    autoCase: boolean;
-    /** Mechanical promotion guards for wrapup/fate (2026-08-22 policy). */
-    promotionPolicy: PromotionPolicy;
-    /**
-     * Initial Memory Agent default from plugin config. The listener is always
-     * registered; this is not a registration gate.
-     */
-    autoReview?: boolean;
-    /** Plugin `recordLanguage` preference for dialog copy (see `approval.ts`). */
-    recordLanguage?: RecordLanguagePreference;
-}
+import { findEntryById, stripAngleBrackets, tokenizeEvolveInput, type CommandGateOptions, type CommandRuntimeOptions } from "./command-util.js";
+export { findEntryById, stripAngleBrackets, tokenizeEvolveInput };
+export type { CommandGateOptions, CommandRuntimeOptions };
 export declare function registerEvolveCommand(ctx: Context, engine: EvolutionEngine, opts: CommandGateOptions, runtime: CommandRuntimeOptions): void;
-/**
- * Tokenize a command's raw input with shell-like quoting:
- * - a `#` outside quotes starts a comment (rest of the line is dropped);
- * - whitespace separates tokens;
- * - double or single quotes group words into one token and are stripped.
- *
- * This lets users paste help-text examples verbatim, e.g.
- * `/evolve benchmark add-case <bid> "<title>" "<statement>" "<rubric>"`.
- */
-export declare function tokenizeEvolveInput(rawInput: string): string[];
-/** Accept both `<id>` (help-text placeholder form) and bare `id`. */
-export declare function stripAngleBrackets(value: string): string;
-/**
- * Locate an entry by id across every kind of a store. Ids are only unique
- * within a kind, so the lookup scans all four and returns the first match
- * (kind + entry) or undefined. Used by archive/unarchive, which take a bare
- * id from the user.
- */
-export declare function findEntryById(state: HarnessState, id: string): [RefinementKind, HarnessEntry] | undefined;
 //# sourceMappingURL=command.d.ts.map