@modusensus/dsh-mneme 0.8.16 → 0.9.0

package/src/tools.js

@@ -7,6 +7,7 @@ import { matchesPlatform } from "./runtime/closure.js";
 import { verifyPayload } from "./runtime/verify.js";
 import { TOOL_GUIDE, CONTINUITY_TOOL_RULE } from "./guide.js";
 import { injectChildEnabled } from "./config.js";
+import { lastUserQuery } from "./inject.js";
 
 const TEXT_OUTPUT = (text) => [{ type: "text", text }];
 // Per-registry tool-name registry: guards against duplicate registration on
@@ -381,6 +382,14 @@ export function createTools(ctx, service, config, embedder) {
         render: (_args, value) => TEXT_OUTPUT(`Updated memory ${value.memory.id}: ${value.memory.title}`)
       },
       async execute(args) {
+        // v0.9.0：失败表的 query 是「当时到底想干什么」唯一的落点，而 service
+        // 层看不到会话（它只认 ctx.query，见 src/service.js 的 saveFailure 注释）。
+        // 工具层是唯一同时握着改写动作与本轮会话的入口：没给 reason 就退回当轮用户
+        // 原话，取法与注入侧共用同一份实现（src/inject.js 的 lastUserQuery），不复制
+        // 第二份。两边都取不到时仍然写 NULL——空串会假装「有意图」，NULL 才说实话。
+        const exec = arguments[1];
+        const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+        const query = reason || lastUserQuery(exec) || undefined;
         const memory = service.update(args.id, {
           title: args.title,
           content: args.content,
@@ -389,10 +398,10 @@ export function createTools(ctx, service, config, embedder) {
           importance: args.importance,
           // 复核项 4（#170）：strictScope 下他 scope 的行按「不存在」处理（与 get 对齐），
           // 展开恒为 undefined，仅承担写入前校验。
-          ...(assertVisibleForTool(args.id, arguments[1])),
+          ...(assertVisibleForTool(args.id, exec)),
           ...(args.agent_scope !== undefined ? { agent_scope: args.agent_scope } : {}),
           ...(args.workspace_scope !== undefined ? { workspace_scope: args.workspace_scope } : {})
-        }, { query: args.reason });
+        }, { query });
         return { memory: { id: memory.id, title: memory.title, content: memory.content } };
       }
     }),

package/test/api.test.js

@@ -680,7 +680,11 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   // #135 成本审计派生新增 dreamMaxMergePerRun（单轮 merge 决策上限））
   // issue #399 新增 distillRecords.enabled/distillRecords.retentionDays（蒸馏原文留存 +
   // 溯源：开关与保留期都在嵌套对象里，两个都进 NESTED_FLAG_PATHS））
-  assert.equal(Object.keys(data.effective).length, 59 + 3 + 2 + 1 + 2 + 2 + 2 + 1 + 1 + 1 + 2 + 1 + 2 + 1 + 3 + 2 + 2 + 1 + 1 + 1 + 1 + 2 + 1 + 2);
+  // v0.9.0 新增 actionPipelineEnabled（M.O. beta 门控；顶层扁平键，
+  // 走 configFlagValue 默认分支，不需要 NESTED_FLAG_PATHS 条目）。
+  // 计数锁钉的是「白名单键 ↔ config schema 成对」：schema 加了键而漏了白名单
+  // （或反过来）时，effective 会静默少键/多键，面板读不到也报不出来。
+  assert.equal(Object.keys(data.effective).length, 59 + 3 + 2 + 1 + 2 + 2 + 2 + 1 + 1 + 1 + 2 + 1 + 2 + 1 + 3 + 2 + 2 + 1 + 1 + 1 + 1 + 2 + 1 + 2 + 1);
   assert.equal(data.effective.dreamSkipInvalid, true);
   assert.equal(data.effective.allowCrossTypeMerge, false);
   assert.equal(data.effective.dreamMergeGuard, true);
@@ -714,6 +718,9 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   // 保留期默认 90 天（与 llmAudit.retentionDays 同款）。
   assert.equal(data.effective["distillRecords.enabled"], false);
   assert.equal(data.effective["distillRecords.retentionDays"], 90);
+  // v0.9.0：M.O. beta 门控默认关——客户端 GET /features 必须能读到这个键
+  // （读不到就静默不注册任何座位），且默认值必须是 false（beta opt-in）。
+  assert.equal(data.effective.actionPipelineEnabled, false);
   // 新增字符串 / URL / 枚举键
   assert.equal(data.effective.localEmbedModel, "Xenova/bge-small-zh-v1.5");
   assert.equal(data.effective.ollamaBaseUrl, "http://localhost:11434");
@@ -746,14 +753,16 @@ test("PUT /api/dsh-mneme/features round-trips, overrides effective and persists"
   const { routes, settings } = setup(undefined, "", FLAGS_CFG);
   const route = routes.find((r) => r.path === "/api/dsh-mneme/features");
   const res = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/features", "PUT", { autoDream: false, distillMaxChars: 48000 }), res);
+  await route.handler(req("/api/dsh-mneme/features", "PUT", { autoDream: false, distillMaxChars: 48000, actionPipelineEnabled: true }), res);
   assert.equal(res.statusCode, 200);
   const data = JSON.parse(res.body);
-  assert.deepEqual(data.overrides, { autoDream: false, distillMaxChars: 48000 });
+  assert.deepEqual(data.overrides, { autoDream: false, distillMaxChars: 48000, actionPipelineEnabled: true });
   assert.equal(data.effective.autoDream, false, "override wins over config default");
   assert.equal(data.effective.distillMaxChars, 48000);
+  // v0.9.0：默认关的键也能被 PUT 打开并读回（beta 功能的启用路径）。
+  assert.equal(data.effective.actionPipelineEnabled, true, "override flips the beta gate on");
   assert.equal(data.effective.autoInject, true, "keys not in the patch still report config");
-  assert.deepEqual(settings.getFeatureFlags(), { autoDream: false, distillMaxChars: 48000 });
+  assert.deepEqual(settings.getFeatureFlags(), { autoDream: false, distillMaxChars: 48000, actionPipelineEnabled: true });
 });
 
 test("PUT /api/dsh-mneme/features round-trips nested, string, url and enum keys", async () => {
@@ -1435,8 +1444,12 @@ const MOCK_LLM = {
     if (provider === "broken") throw new Error("provider not reachable");
     return [{ id: "deepseek-chat", name: "DeepSeek Chat" }, { id: "deepseek-reasoner", name: "DeepSeek Reasoner" }];
   },
+  // 每次 stream 的 options 留档：既给「字段省略 / 透传」的断言用，也让「档位被拒
+  // 后重试一次」能数出调用次数（降级必须恰好两次，多一次就是盲重试）。
+  streamCalls: [],
   async *stream(options) {
     MOCK_LLM.lastOptions = options;
+    MOCK_LLM.streamCalls.push(options);
     if (options.model === "bad-model") {
       yield {
         type: "finish",
@@ -1444,6 +1457,26 @@ const MOCK_LLM = {
       };
       return;
     }
+    // 流级档位拒收：rc.1 起的适配器把 provider 的拒收折叠成终止 error finish
+    // chunk（不抛错），这条路径曾让 withEffortFallback 的重试形同死代码。
+    if (options.model === "stream-reject" && options.reasoningEffort) {
+      yield {
+        type: "finish",
+        reason: {
+          kind: "error",
+          failure: {
+            code: "UNSUPPORTED_REASONING_EFFORT",
+            message: `provider "mock" model "mock-model" does not support reasoning effort "${options.reasoningEffort}"`
+          }
+        }
+      };
+      return;
+    }
+    // 抛错型真失败（网络中断 / provider 崩溃）：错误以异常形式冒到 catch 路径，
+    // 必须原样上报——「档位被拒才重试」不能退化成「见到错误就重试」。
+    if (options.model === "crash-model") {
+      throw new Error("socket hang up");
+    }
     if (options.reasoningEffort === "reject") {
       throw new Error('UNSUPPORTED_REASONING_EFFORT: provider "mock" model "mock-model" does not support reasoning effort "reject"');
     }
@@ -1517,15 +1550,122 @@ test("POST /api/dsh-mneme/test-model reports stream-level failure with 502", asy
   assert.match(data.error, /AUTH_FAILED/, "stream failure reason surfaced like audit rows");
 });
 
-test("POST /api/dsh-mneme/test-model reports thrown failure with 502", async () => {
+// issue #215 的后续：探针是仓里唯一「接受并转发调用方档位、却此前没有兜底」的
+// LLM 调用面（直调 llm.stream 的其余各面要么在 withEffortFallback 之内，要么
+// 是 src/index.js 的手写版兜底，要么像 pre-inject-gate 的判定池那样不转发档位），
+// 档位被拒则丢掉字段重试一次，于是同一份配置「后台跑得通、点测试报红」，用户被
+// 引向「换哪家 Provider 都失败」。探针必须与真实 run 同语义：降级跑通 → 200 +
+// effortDropped:true（不是 502）。
+test("POST /api/dsh-mneme/test-model degrades on a rejected effort instead of failing (issue #215 follow-up)", async () => {
+  const { routes } = setupLlm(MOCK_LLM);
+  const route = routes.find((r) => r.path === "/api/dsh-mneme/test-model");
+  const before = MOCK_LLM.streamCalls.length;
+  const res = new FakeRes();
+  await route.handler(
+    req("/api/dsh-mneme/test-model", "POST", { provider: "mock", model: "mock-model", reasoningEffort: "reject" }),
+    res
+  );
+  assert.equal(res.statusCode, 200, "a rejected effort is a downgrade, not a connectivity failure");
+  const data = JSON.parse(res.body);
+  assert.equal(data.ok, true);
+  assert.equal(data.reply, "ok", "the no-effort retry actually answered");
+  assert.equal(data.effortDropped, true, "the caller must be able to tell 'connected, effort dropped' from 'connected as configured'");
+  const calls = MOCK_LLM.streamCalls.slice(before);
+  assert.equal(calls.length, 2, "exactly one retry: attempt with the effort, then once without");
+  assert.equal(calls[0].reasoningEffort, "reject", "first attempt carries the configured effort");
+  assert.equal("reasoningEffort" in calls[1], false, "the retry omits the field entirely");
+});
+
+test("POST /api/dsh-mneme/test-model degrades on a STREAM-level effort rejection too", async () => {
+  // rc.1 起适配器不抛错，把 provider 的拒收折叠成终止 error finish chunk——只在
+  // catch 里做兜底的话这条路径就是死的，探针会照旧 502。
+  const { routes } = setupLlm(MOCK_LLM);
+  const route = routes.find((r) => r.path === "/api/dsh-mneme/test-model");
+  const before = MOCK_LLM.streamCalls.length;
+  const res = new FakeRes();
+  await route.handler(
+    req("/api/dsh-mneme/test-model", "POST", { provider: "mock", model: "stream-reject", reasoningEffort: "high" }),
+    res
+  );
+  assert.equal(res.statusCode, 200, "stream-level rejection also downgrades");
+  const data = JSON.parse(res.body);
+  assert.equal(data.ok, true);
+  assert.equal(data.effortDropped, true);
+  const calls = MOCK_LLM.streamCalls.slice(before);
+  assert.equal(calls.length, 2, "stream rejection retries once without the effort");
+  assert.equal("reasoningEffort" in calls[1], false);
+});
+
+test("POST /api/dsh-mneme/test-model keeps real failures red and never reports a phantom downgrade", async () => {
+  // 非档位原因的失败绝不能被兜底吞掉：真连不上还得是 502、还得带原始原因。
   const { routes } = setupLlm(MOCK_LLM);
   const route = routes.find((r) => r.path === "/api/dsh-mneme/test-model");
+  const before = MOCK_LLM.streamCalls.length;
   const res = new FakeRes();
-  await route.handler(req("/api/dsh-mneme/test-model", "POST", { provider: "mock", model: "mock-model", reasoningEffort: "reject" }), res);
+  await route.handler(
+    req("/api/dsh-mneme/test-model", "POST", { provider: "deepseek", model: "bad-model", reasoningEffort: "low" }),
+    res
+  );
   assert.equal(res.statusCode, 502);
   const data = JSON.parse(res.body);
   assert.equal(data.ok, false);
-  assert.match(data.error, /UNSUPPORTED_REASONING_EFFORT/, "throw path surfaces the harness rejection");
+  assert.match(data.error, /AUTH_FAILED/);
+  assert.equal(data.effortDropped, undefined, "a genuine failure is not a downgrade");
+  assert.equal(MOCK_LLM.streamCalls.length - before, 1, "non-effort failures are not retried blindly");
+});
+
+test("POST /api/dsh-mneme/test-model reports a thrown transport failure as-is (catch path)", async () => {
+  // 错误以异常形式到达时（socket 断开 / provider 崩溃）走 catch 路径：谎报成功不行，
+  // 拿 without-effort 的裸奔重试去掩盖真故障更不行——「档位被拒才重试」不能退化成
+  // 「见到错误就重试」，否则真故障会被一次盲重试糊住（还多烧一次配额）。
+  const { routes } = setupLlm(MOCK_LLM);
+  const route = routes.find((r) => r.path === "/api/dsh-mneme/test-model");
+  const before = MOCK_LLM.streamCalls.length;
+  const res = new FakeRes();
+  await route.handler(
+    req("/api/dsh-mneme/test-model", "POST", { provider: "deepseek", model: "crash-model", reasoningEffort: "low" }),
+    res
+  );
+  assert.equal(res.statusCode, 502);
+  const data = JSON.parse(res.body);
+  assert.equal(data.ok, false);
+  assert.match(data.error, /socket hang up/, "the thrown cause reaches the panel verbatim");
+  assert.equal(data.effortDropped, undefined, "a thrown failure is not a downgrade");
+  assert.equal(MOCK_LLM.streamCalls.length - before, 1, "a thrown failure is not retried blindly either");
+});
+
+test("POST /api/dsh-mneme/test-model omits effortDropped when no effort was configured", async () => {
+  const { routes } = setupLlm(MOCK_LLM);
+  const route = routes.find((r) => r.path === "/api/dsh-mneme/test-model");
+  const res = new FakeRes();
+  await route.handler(req("/api/dsh-mneme/test-model", "POST", { provider: "deepseek", model: "deepseek-chat" }), res);
+  assert.equal(res.statusCode, 200);
+  const data = JSON.parse(res.body);
+  assert.equal(data.effortDropped, undefined, "no effort configured -> nothing was dropped");
+});
+
+// 防分叉静态锁（与 #405 的归一逻辑同款）：档位拒收的判据与降级语义全仓只有一份
+// ——dream.js 的 EFFORT_REJECT_RE + withEffortFallback。api.js 手写正则或自己做
+// 重试，两条路必然漂移（漂移方向就是「探针与服务端行为不一致」，本次修的就是这个）。
+test("api.js reuses the single effort-rejection source instead of forking it", () => {
+  const src = readFileSync(new URL("../src/api.js", import.meta.url), "utf8");
+  assert.match(
+    src,
+    /import \{[^}]*withEffortFallback[^}]*\} from "\.\/dream\.js"/,
+    "the probe must reuse dream.js's withEffortFallback instead of hand-rolling a retry"
+  );
+  assert.match(
+    src,
+    /import \{[^}]*EFFORT_REJECT_RE[^}]*\} from "\.\/dream\.js"/,
+    "the rejection predicate must come from dream.js (single source), not a local regex"
+  );
+  assert.ok(
+    !/\/reasoning\[/.test(src),
+    "api.js must not carry its own copy of the effort-rejection pattern"
+  );
+  // 降级语义只能有一处：探针内不得再出现第二个「无档位重试」判据。
+  const attempts = src.split("withEffortFallback(").length - 1;
+  assert.equal(attempts, 1, `the probe must route through withEffortFallback exactly once (got ${attempts})`);
 });
 
 test("POST /api/dsh-mneme/test-model resolves empty body against the consolidation route", async () => {

package/test/candidates.test.js

@@ -0,0 +1,345 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  decideDetour,
+  scanIrreversible,
+  projectKey,
+  candidateDir,
+  candidateId,
+  validateCandidate,
+  loadCandidates,
+  saveCandidate,
+  recordDetour,
+  maybePropose,
+  archiveStale,
+  promoteCandidate,
+  summarizeCandidate,
+  readCandidateDoc,
+  removeCandidate,
+  IRREVERSIBLE_PATTERNS,
+  PROMOTE_MIN_SEEN,
+  STALE_AFTER_DAYS
+} from "../src/candidates.js";
+
+// 这一组守的是 M.O. 的**候选层与绕行判定**——这一版解决的是「刻板的图会让 agent 失去自主性」。
+// 核心规则一句话：自主性住在 R0/R1，刚性只住在它必须住的地方。
+// 里面有几条是**踩过坑才写下的**（子命令误拦、requires/forbids 语义搞反），
+// 所以那些用例不是举例子，是回归锁。
+
+function withDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), "mo-cand-"));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const STEPS = [
+  { title: "看仓库干不干净", when: "发版前", do: "git status", done: "无未提交", risk: "R0" },
+  { title: "跳过 release-prep", when: "上一次已 bump", do: "手工改版本号", done: "版本号对", risk: "R1" }
+];
+
+const okCandidate = (over = {}) => ({
+  id: "cand-abcdef123456",
+  origin: "detour",
+  steps: STEPS,
+  reason: "仓库干净，release-prep 这步多余",
+  counterfactual: null,
+  seen: [],
+  status: "collecting",
+  createdAt: new Date().toISOString(),
+  ...over
+});
+
+// ── 分档：B 档的核心规则 ────────────────────────────────────────────────────
+
+test("R0/R1 且不跨闸门、兜底未命中 → 记账先走（自主性住在这里）", () => {
+  assert.equal(decideDetour({ risk: "R0", actions: ["gh pr view 438", "ls"] }).decidedBy, "model");
+  assert.equal(decideDetour({ risk: "R1", actions: ["npm test", "git status"] }).decidedBy, "model");
+  assert.equal(decideDetour({ risk: "R1", actions: [] }).decidedBy, "model");
+});
+
+test("R2/R3 → 停下等点头（刚性只住在这里）", () => {
+  assert.equal(decideDetour({ risk: "R2", actions: [] }).decidedBy, "human");
+  assert.equal(decideDetour({ risk: "R3", actions: [] }).decidedBy, "human");
+});
+
+test("兜底清单不看自报：自报 R0 但命令里有对外动作，照样拦", () => {
+  // 这条是「模型在自己上下文里给自己打分不可靠」的直接应用——不给单点判断。
+  const r = decideDetour({ risk: "R0", actions: ["git push origin main"] });
+  assert.equal(r.decidedBy, "human");
+  assert.equal(r.risk, "R2", "命中兜底时风险档要按较高者记，结算卡上才看得准");
+  assert.deepEqual(r.scan.matches.map((m) => m.id), ["git-push"]);
+});
+
+test("自报非法风险档 → 按最保守处理，不是放行", () => {
+  // 一个模型说「我的风险是 R9」时，正确的反应是别信它，而不是当成没风险。
+  assert.equal(decideDetour({ risk: "R9", actions: [] }).decidedBy, "human");
+  assert.equal(decideDetour({ risk: undefined, actions: [] }).decidedBy, "model");
+});
+
+test("闸门保护与风险档无关：纯只读绕行只要跨闸门也停下", () => {
+  // 闸门本来就放在「错了很难撤」的地方，绕开它等于把安全阀绕掉——
+  // 哪怕这条绕行本身全是只读动作。
+  const r = decideDetour({ risk: "R0", actions: ["ls"], crossesGate: true });
+  assert.equal(r.decidedBy, "human");
+  assert.match(r.reason, /闸门/);
+});
+
+// ── 兜底清单：子命令必须分得开 ──────────────────────────────────────────────
+
+test("兜底清单分得清只读与写：同一工具的子命令，性质相反", () => {
+  // 回归锁：第一版把工具名整条当动作，`gh pr view`（只看一眼 PR）也被拦下了，
+  // 直接毁掉「自主性住在 R0/R1」。工具名 + 子命令才是动作。
+  const readOnly = [
+    "gh pr view 438", "gh pr list", "gh pr checks", "gh pr diff",
+    "gh issue view 12", "gh release view v1", "gh auth status",
+    "gh api repos/x/y", "gh repo view", "gh run list",
+    "git tag -l", "git status", "npm test",
+    "curl https://example.com", "Remove-Item x.txt"
+  ];
+  for (const cmd of readOnly) {
+    assert.equal(scanIrreversible([cmd]).hit, false, `只读的 ${cmd} 不该被拦`);
+  }
+  const writes = [
+    "git push origin main", "git tag v1.0.0", "git tag -d v1",
+    "gh pr create --title x", "gh pr merge 438", "gh pr close 438",
+    "gh issue create -t x", "gh release create v1",
+    "gh api -X POST /repos/x/y", "gh api -f name=v",
+    "gh auth login", "gh secret set FOO", "gh repo edit", "gh workflow run ci.yml",
+    "npm publish", "yarn publish", "pnpm publish",
+    "curl -X POST https://x.com", "curl --data a=1 https://x.com",
+    "Remove-Item -Recurse -Force x", "rm -rf build", "drop table memories"
+  ];
+  for (const cmd of writes) {
+    assert.equal(scanIrreversible([cmd]).hit, true, `要写的 ${cmd} 必须被拦`);
+  }
+});
+
+test("requires 与 forbids 的语义不能混：默认安全的动作只能用 requires", () => {
+  // 回归锁：`gh api` 不写方法时是 GET（安全），只有显式写方法与字段才危险。
+  // 用 forbids 表达「默认安全」是错的——不写方法时两个特征都不出现，
+  // forbids 不成立、规则照样命中，于是只读调用被误拦。
+  const api = IRREVERSIBLE_PATTERNS.find((p) => p.id === "gh-api-write");
+  assert.ok(api && Array.isArray(api.requires), "gh api 那条必须用 requires");
+  assert.equal(api.forbids, undefined, "同一语义不能既用 requires 又用 forbids");
+  // 而「默认危险、列出只读例外」的动作用 forbids。
+  const pr = IRREVERSIBLE_PATTERNS.find((p) => p.id === "gh-pr-write");
+  assert.ok(pr && Array.isArray(pr.forbids));
+});
+
+test("扫多条动作：任一命中即算命中，同一条不重复算", () => {
+  const r = scanIrreversible(["ls", "git push", "git push --tags"]);
+  assert.equal(r.hit, true);
+  assert.equal(r.matches.filter((m) => m.id === "git-push").length, 1);
+  assert.equal(scanIrreversible([]).hit, false);
+  assert.equal(scanIrreversible(null).hit, false);
+});
+
+// ── 候选的住址与身份 ───────────────────────────────────────────────────────
+
+test("项目键稳定、不含绝对路径（文件名里不能有本机用户名）", () => {
+  const a = projectKey("C:\\Users\\someone\\Desktop\\dsh-mneme");
+  const b = projectKey("C:\\Users\\someone\\Desktop\\dsh-mneme");
+  const other = projectKey("C:\\Users\\someone\\Desktop\\another-project");
+  assert.equal(a, b, "同一个项目每次算到同一个键");
+  assert.notEqual(a, other, "不同项目必须分开");
+  assert.equal(a.includes("someone"), false, "不能把用户名带进文件名");
+  assert.ok(a.startsWith("dsh-mneme-"), "保留目录名便于人读");
+  assert.equal(projectKey(""), null);
+  assert.equal(projectKey(null), null);
+});
+
+test("项目键对两种分隔符一视同仁：Windows 路径不得退化成整条路径", () => {
+  // 回归锁，指向一个**只在 posix 上现形**的缺陷：原实现借 path.basename() 取目录名，
+  // 它跟着运行平台走——Linux 上 `C:\Users\someone\Desktop\dsh-mneme` 整条被当成
+  // 文件名，清洗后 C--Users-someone-Desktop-dsh-mne，用户名的残片进了目录名。
+  // 这正是 PR #439 里 ubuntu 四腿全红、windows 两腿全绿的那条。
+  //
+  // **这条锁在 Windows 上是绿的，且永远抓不住回退**：win32.basename 两种分隔符都认，
+  // 旧实现在本机结果就是对的。它的杀伤力只在 ubuntu 矩阵腿上——别删了它以为没事。
+  const nameOf = (key) => key.replace(/-[0-9a-f]{8}$/, "");
+  const bs = projectKey("C:\\Users\\someone\\Desktop\\dsh-mneme");
+  const fwd = projectKey("C:/Users/someone/Desktop/dsh-mneme");
+  const trail = projectKey("C:\\Users\\someone\\Desktop\\dsh-mneme\\");
+  assert.equal(nameOf(bs), "dsh-mneme", "反斜杠路径要取到目录名");
+  assert.equal(nameOf(fwd), "dsh-mneme", "正斜杠路径要取到目录名");
+  assert.equal(nameOf(trail), "dsh-mneme", "尾随分隔符不改变结果");
+  assert.equal(bs.includes("someone"), false, "用户名不得进目录名");
+  assert.equal(bs.includes("-Users-"), false, "整条路径不得被清洗成目录名");
+  assert.match(bs, /^[A-Za-z0-9._-]+$/, "目录名只许出现安全字符");
+});
+
+
+test("候选的家在 memoryDir 下、按项目分桶；拿不到项目根就没有家", () => {
+  const dir = candidateDir({ memoryDir: "~/.dsh/memory", projectRoot: "C:\\x\\y" });
+  assert.ok(dir && dir.includes("candidates"), "落在 candidates/ 下");
+  assert.equal(dir.includes("C:\\x\\y"), false, "路径不进字符串");
+  assert.equal(candidateDir({ memoryDir: "/tmp/m", projectRoot: null }), null);
+});
+
+test("候选 id 由步骤形状决定：同一段路走两次会落到同一条上", () => {
+  // 这正是「复用第二次才算类型，第一次只是实例」的落点——
+  // 如果每次绕行都生成新 id，第二次永远并不到第一次上，门槛就永远够不着。
+  const id1 = candidateId(STEPS);
+  const id2 = candidateId(STEPS.map((s) => ({ ...s })));
+  const id3 = candidateId([STEPS[0], { ...STEPS[1], title: "换了个做法" }]);
+  assert.equal(id1, id2);
+  assert.notEqual(id1, id3);
+  assert.match(id1, /^cand-[0-9a-f]{12}$/);
+});
+
+// ── 校验：候选松，但 reason 一个都不能少 ────────────────────────────────────
+
+test("候选比定稿松，但「写不出理由就不许绕」是硬要求", () => {
+  assert.equal(validateCandidate(okCandidate()).ok, true);
+  // 定稿要求 id/name/project/version/status/done/trigger 一个不缺；候选只要这四样。
+  const minimal = { id: "cand-abcdef123456", origin: "manual", steps: STEPS, reason: "为什么", seen: [], status: "collecting" };
+  assert.equal(validateCandidate(minimal).ok, true, "候选不该要求定稿那一整套字段");
+
+  const noReason = validateCandidate(okCandidate({ reason: "   " }));
+  assert.equal(noReason.ok, false);
+  assert.ok(noReason.problems.some((p) => p.includes("reason 必填")));
+
+  assert.equal(validateCandidate(okCandidate({ id: "bad-id" })).ok, false);
+  assert.equal(validateCandidate(okCandidate({ origin: "telepathy" })).ok, false);
+  assert.equal(validateCandidate(okCandidate({ status: "whatever" })).ok, false);
+  assert.equal(validateCandidate(okCandidate({ steps: [] })).ok, false);
+  assert.equal(validateCandidate(okCandidate({ steps: [{ title: "x" }] })).ok, false, "步骤缺字段要报出来");
+  assert.equal(validateCandidate(null).ok, false);
+});
+
+test("坏文件不静默跳过：与定稿同一纪律", () => {
+  withDir((dir) => {
+    saveCandidate(dir, okCandidate());
+    assert.equal(loadCandidates(dir).length, 1);
+    rmSync(join(dir, "cand-abcdef123456.json"));
+    writeFileSync(join(dir, "broken.json"), "{ not json", "utf8");
+    assert.throws(() => loadCandidates(dir), /broken\.json: JSON 解析失败/);
+  });
+});
+
+// ── 绕行 → 候选：两次才算数 ─────────────────────────────────────────────────
+
+test("第一次绕行：落成候选，但还够不着提议", () => {
+  withDir((dir) => {
+    const r = recordDetour(dir, { steps: STEPS, reason: "仓库干净，这步多余", outcome: "worked", evidence: ["测试全绿"], runId: "r1" });
+    assert.equal(r.created, true);
+    assert.equal(r.promotedNow, false);
+    assert.equal(r.candidate.status, "collecting");
+    assert.equal(r.candidate.seen.length, 1);
+    assert.equal(readdirSync(dir).filter((f) => f.endsWith(".json")).length, 1);
+  });
+});
+
+test(`第二次走同一段路：并进同一条，翻成 proposed（门槛 ${PROMOTE_MIN_SEEN} 次）`, () => {
+  withDir((dir) => {
+    recordDetour(dir, { steps: STEPS, reason: "同上", outcome: "worked", evidence: ["绿"], runId: "r1" });
+    const b = recordDetour(dir, { steps: STEPS, reason: "同上", outcome: "worked", evidence: ["又绿"], runId: "r2" });
+    assert.equal(b.created, false, "不该新建——同一段路只有一条候选");
+    assert.equal(b.promotedNow, true);
+    assert.equal(b.candidate.status, "proposed");
+    assert.equal(b.candidate.seen.length, 2);
+    assert.equal(readdirSync(dir).filter((f) => f.endsWith(".json")).length, 1);
+  });
+});
+
+test("两次里只要有一次没跑通，就够不着提议", () => {
+  // 「复用第二次才算类型」的前提是**那次真的走通了**；两次都失败的路不该被提议进图。
+  const c = okCandidate({ seen: [{ outcome: "failed" }, { outcome: "unknown" }] });
+  assert.equal(maybePropose(c), false);
+  assert.equal(c.status, "collecting");
+  const d = okCandidate({ seen: [{ outcome: "failed" }, { outcome: "worked" }] });
+  assert.equal(maybePropose(d), true, "有一次跑通就算走通了这条路");
+});
+
+test("失败也留痕：走不通是知识，不是垃圾", () => {
+  withDir((dir) => {
+    recordDetour(dir, { steps: STEPS, reason: "试试", outcome: "failed", evidence: ["C2 直接报错"] });
+    const [c] = loadCandidates(dir);
+    assert.equal(c.seen[0].outcome, "failed");
+    assert.deepEqual(c.seen[0].evidence, ["C2 直接报错"]);
+    const row = summarizeCandidate(c);
+    assert.equal(row.failed, 1);
+    assert.equal(row.worked, 0);
+  });
+});
+
+// ── 归档与升格 ─────────────────────────────────────────────────────────────
+
+test(`只走过一次、${STALE_AFTER_DAYS} 天没再被走到 → 归档；归档不删文件`, () => {
+  withDir((dir) => {
+    const old = okCandidate({
+      seen: [{ outcome: "worked", at: new Date(Date.now() - (STALE_AFTER_DAYS + 10) * 86400000).toISOString() }]
+    });
+    saveCandidate(dir, old);
+    const archived = archiveStale(dir, {});
+    assert.deepEqual(archived, [old.id]);
+    const after = loadCandidates(dir).find((c) => c.id === old.id);
+    assert.equal(after.status, "dropped");
+    assert.match(after.droppedReason, /没再被走到/);
+    assert.ok(readdirSync(dir).some((f) => f.startsWith(old.id)), "文件还在——留着当负清单的邻居");
+  });
+});
+
+test("归档只碰 collecting：够格的和已归档的都不动", () => {
+  withDir((dir) => {
+    const proposed = okCandidate({ id: "cand-proposed0001", status: "proposed", seen: [{ outcome: "worked", at: new Date(Date.now() - 100 * 86400000).toISOString() }] });
+    const fresh = okCandidate({ id: "cand-fresh0000001", seen: [{ outcome: "worked", at: new Date().toISOString() }] });
+    saveCandidate(dir, proposed);
+    saveCandidate(dir, fresh);
+    assert.deepEqual(archiveStale(dir, {}), []);
+  });
+});
+
+test("升格：补齐字段后必须过定稿的 validatePipeline", () => {
+  const cand = okCandidate();
+  const good = promoteCandidate(cand, { name: "发版（绕开 release-prep）", project: "slow-stack/mneme", done: "发出去且 registry 对得上" });
+  assert.equal(good.ok, true);
+  assert.equal(typeof good.pipeline.id, "string");
+  assert.equal(good.pipeline.id.startsWith("cand-"), false, "句柄要去掉 cand- 前缀");
+  assert.deepEqual(good.pipeline.steps[1].needs, ["S1"], "needs 要串成链，否则定稿那边会报图不连通");
+  assert.equal(good.pipeline.version, 0);
+  // 升格不是降低标准，是补齐标准：缺 project 照样过不了。
+  const bad = promoteCandidate(cand, { name: "缺 project" });
+  assert.equal(bad.ok, false);
+  assert.ok(bad.problems.some((p) => p.includes("project")));
+});
+
+test("升格带上候选的反事实——它是准入判据，不是备注", () => {
+  const cand = okCandidate({ counterfactual: "没有它，C 阶段会拿旧版本号发出去" });
+  const r = promoteCandidate(cand, { name: "x", project: "a/b" });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.pipeline.steps[0].evidence, ["没有它，C 阶段会拿旧版本号发出去"]);
+});
+
+// ── 投影与契约 ─────────────────────────────────────────────────────────────
+
+test("清单行取整段路里最高的风险档（最坏情况才是它该被看待的档位）", () => {
+  const row = summarizeCandidate(okCandidate({ steps: [STEPS[0], STEPS[1], { title: "问人", when: "w", do: "d", done: "x", risk: "R2" }] }));
+  assert.equal(row.risk, "R2");
+  assert.equal(row.steps, 3);
+});
+
+test("契约把「这一刀不做的事」也写进去，免得以后有人以为忘了做", () => {
+  withDir((dir) => {
+    const doc = readCandidateDoc({ memoryDir: dir, projectRoot: "C:\\x\\y" });
+    assert.equal(doc.contract, "mneme.candidates/v1");
+    assert.deepEqual(doc.boundaries, { autoPromote: false, autoApprove: false, injectIntoMemory: false });
+    assert.deepEqual(doc.counts, { collecting: 0, proposed: 0, promoted: 0, dropped: 0 });
+  });
+});
+
+test("removeCandidate 只删指定的那条", () => {
+  withDir((dir) => {
+    saveCandidate(dir, okCandidate());
+    saveCandidate(dir, okCandidate({ id: "cand-second000001" }));
+    assert.equal(removeCandidate(dir, "cand-abcdef123456"), true);
+    assert.equal(loadCandidates(dir).length, 1);
+    assert.equal(removeCandidate(dir, "cand-nope00000000"), false);
+  });
+});