@modusensus/dsh-mneme 0.9.1 → 0.9.3

package/test/embed-text-reasons.test.js

@@ -0,0 +1,112 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { embedText, embedTextDetailed, createEmbedder } from "../src/embedding.js";
+
+// distill-tx-embed-gap 的"坏了为什么看不出来"半边：embedText 此前把「配置缺」
+// 「网络挂」「超时」「HTTP 4xx/5xx」「响应不是 JSON」「响应没有向量」全部压成
+// null，回执账本只能统一写 embedding-request-returned-no-vector——分诊不可能。
+// embedTextDetailed 把失败模式拆开；embedText 保留旧 null 契约（调用方不变）。
+
+const FULL = {
+  enabled: true,
+  baseUrl: "https://api.example.com/v1",
+  apiKey: "sk-test",
+  model: "text-embedding-3-small"
+};
+
+async function withFetch(impl, fn) {
+  const original = globalThis.fetch;
+  globalThis.fetch = impl;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = original;
+  }
+}
+
+test("detailed: 成功时 reason 为 null，vector 与旧契约一致", async () => {
+  await withFetch(async () => ({ ok: true, json: async () => ({ data: [{ embedding: [1, 2, 3] }] }) }), async () => {
+    const out = await embedTextDetailed(FULL, "猫咪");
+    assert.deepEqual(out.vector, [1, 2, 3]);
+    assert.equal(out.reason, null);
+    // 旧包装的 null 契约不变
+    assert.deepEqual(await embedText(FULL, "猫咪"), [1, 2, 3]);
+  });
+});
+
+test("detailed: 配置缺失时逐字段点名，不伪装成网络故障", async () => {
+  assert.match((await embedTextDetailed({ ...FULL, model: "" }, "x")).reason, /^config-incomplete:model$/);
+  assert.match((await embedTextDetailed({ ...FULL, apiKey: "" }, "x")).reason, /^config-incomplete:apiKey$/);
+  assert.match((await embedTextDetailed({ ...FULL, baseUrl: "" }, "x")).reason, /^config-incomplete:baseUrl$/);
+  assert.match(await embedTextDetailed(FULL, "").then((o) => o.reason), /config-incomplete:text/);
+});
+
+test("detailed: HTTP 状态码进 reason（401 钥匙 / 404 路径 / 429 限流）", async () => {
+  await withFetch(async () => ({ ok: false, status: 404, text: async () => "Not Found" }), async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.equal(out.vector, null);
+    assert.equal(out.reason, "http-404:Not Found");
+  });
+  await withFetch(async () => ({ ok: false, status: 429, text: async () => "" }), async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.equal(out.reason, "http-429", "空响应体不拼尾巴");
+  });
+  // 旧包装在这些场景全部 null，不抛
+  await withFetch(async () => ({ ok: false, status: 401, text: async () => "denied" }), async () => {
+    assert.equal(await embedText(FULL, "x"), null);
+  });
+});
+
+test("detailed: 超时与网络错误分型，不混为一谈", async () => {
+  await withFetch(async () => {
+    const err = new Error("socket hang up");
+    err.name = "TypeError";
+    throw err;
+  }, async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.match(out.reason, /^request-failed:network:socket hang up/);
+  });
+  await withFetch(async () => {
+    const err = new Error("The operation was aborted");
+    err.name = "TimeoutError";
+    throw err;
+  }, async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.match(out.reason, /^request-failed:timeout:/, "慢和不通是两种病");
+  });
+});
+
+test("detailed: 响应不是 JSON 与响应没有向量各自有名", async () => {
+  await withFetch(async () => ({ ok: true, json: async () => { throw new Error("bad"); } }), async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.equal(out.reason, "response-not-json");
+  });
+  await withFetch(async () => ({ ok: true, json: async () => ({ data: [] }) }), async () => {
+    const out = await embedTextDetailed(FULL, "x");
+    assert.equal(out.reason, "response-no-vector");
+  });
+});
+
+test("embedFor 回执账本带上可区分 reason（不再是统一的 no-vector）", async () => {
+  const receipts = [];
+  const embedder = createEmbedder({
+    store: { setEmbedding() {} },
+    settings: { getVectorConfig: () => FULL },
+    logger: { info() {}, warn() {} }
+  });
+  // embedReceipts 在账本上；rejection 已在 schedule() 内消化，这里直接等 schedule promise。
+  await withFetch(async () => ({ ok: false, status: 404, text: async () => "no route" }), async () => {
+    const r = await embedder.schedule({ id: "m1", title: "t", content: "c" });
+    assert.equal(r.status, "failed");
+    assert.equal(r.reason, "http-404:no route");
+  });
+  await withFetch(async () => ({ ok: true, json: async () => ({ data: [{ embedding: [1, 2, 3] }] }) }), async () => {
+    const r = await embedder.schedule({ id: "m2", title: "t", content: "c" });
+    assert.equal(r.status, "ok");
+    assert.equal(r.dim, 3);
+  });
+  const snap = embedder.embedReceipts();
+  assert.equal(snap.totals.failed, 1);
+  assert.equal(snap.totals.ok, 1);
+  assert.equal(snap.lastFailReason, "http-404:no route", "账本记的是分诊后的原因");
+});

package/test/pipeline-nudge-auto.test.js

@@ -0,0 +1,224 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createNudgeAutoRun } from "../src/pipeline-nudge-auto.js";
+
+// 这组守的是**触发侧**（v0.9.3）：什么时候跑、跑几次、跑挂了怎么办。
+// 挖掘算法本身在 pipeline-nudge.test.js 里守，这里只守接线，所以 runNudge 全部用假的。
+
+/** 一个假 ctx：只提供 session/event 的订阅面（真宿主用同一个口）。 */
+function fakeCtx() {
+  const listeners = [];
+  return {
+    logger: { info() {}, warn() {} },
+    on(name, fn) {
+      if (name !== "session/event") throw new Error("unexpected event: " + name);
+      listeners.push(fn);
+      return () => {
+        const i = listeners.indexOf(fn);
+        if (i >= 0) listeners.splice(i, 1);
+      };
+    },
+    emit(session, event) {
+      for (const fn of listeners.slice()) fn(session, event);
+    },
+    count: () => listeners.length
+  };
+}
+
+function sessionAt(cwd) {
+  return { header: { cwd } };
+}
+
+/** 把 setTimeout(0) 排的活跑完：本模块刻意不用同步跑（见文件头）。 */
+function tick(ms = 5) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * 等到条件成立。队列是**链式**排程（跑完一个再 defer 下一个），所以「两个项目都跑完」
+ * 至少要等两个宏任务;固定 tick(30) 在满载的 CI 上会假阴性——全量跑时其它测试文件
+ * 同时解压 zstd，一次 setTimeout(0) 被拉长就可能超过 30ms。这里只等该等的东西。
+ */
+async function waitFor(predicate, timeout = 2000) {
+  const started = Date.now();
+  while (!predicate()) {
+    if (Date.now() - started > timeout) return false;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  return true;
+}
+
+test("自动沉淀只认 turn/end：中途事件不排队、不预跑", async () => {
+  const ctx = fakeCtx();
+  const calls = [];
+  const auto = createNudgeAutoRun({
+    ctx,
+    runNudge: (args) => { calls.push(args); return { counts: { savedProposals: 0 } }; },
+    now: () => 1_000_000
+  });
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/start" });
+  ctx.emit(sessionAt("D:/proj"), { type: "message" });
+  await tick();
+  assert.deepEqual(calls, [], "一轮没结束就不是观测窗口");
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  await tick();
+  assert.equal(calls.length, 1);
+  auto();
+});
+
+test("自动跑永远是「只落提议、不落草稿」：materialize 恒 false", async () => {
+  const ctx = fakeCtx();
+  const calls = [];
+  const auto = createNudgeAutoRun({
+    ctx,
+    memoryDir: "D:/memory",
+    runNudge: (args) => { calls.push(args); return { counts: { savedProposals: 0 } }; },
+    now: () => 1_000_000
+  });
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  await tick();
+  assert.equal(calls.length, 1);
+  // 这三条是边界，不是偏好：往别人仓库里塞文件必须是人的显式动作。
+  assert.equal(calls[0].materialize, false, "自动跑不许落草稿");
+  assert.equal(calls[0].persistProposals, true, "提议要落进记忆库");
+  assert.equal(calls[0].memoryDir, "D:/memory");
+  auto();
+});
+
+test("同一个项目在冷却期内不重跑（观测新鲜度，不是防重复写盘）", async () => {
+  const ctx = fakeCtx();
+  const calls = [];
+  let clock = 1_000_000;
+  const auto = createNudgeAutoRun({
+    ctx,
+    runNudge: (args) => { calls.push(args); return { counts: { savedProposals: 0 } }; },
+    now: () => clock,
+    minIntervalMs: 10_000
+  });
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  await tick();
+  assert.equal(calls.length, 1);
+  // 冷却期内：再来几轮也不跑。
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  await tick();
+  assert.equal(calls.length, 1, "十分钟内同一个项目只跑一次");
+  // 过了冷却就该跑。
+  clock += 20_000;
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  await tick();
+  assert.equal(calls.length, 2);
+  auto();
+});
+
+test("冷却按项目分账：另一个项目不受影响，也不许并成一次", async () => {
+  const ctx = fakeCtx();
+  const roots = [];
+  const auto = createNudgeAutoRun({
+    ctx,
+    runNudge: (args) => { roots.push(args.projectRoot); return { counts: { savedProposals: 0 } }; },
+    now: () => 1_000_000,
+    minIntervalMs: 10_000
+  });
+  ctx.emit(sessionAt("D:/a"), { type: "turn/end" });
+  ctx.emit(sessionAt("D:/b"), { type: "turn/end" });
+  assert.ok(await waitFor(() => roots.length === 2), "两个项目都该被跑到");
+  assert.deepEqual(roots.sort(), ["D:/a", "D:/b"], "两个项目各跑一次，跨项目不并账");
+  auto();
+});
+
+test("冷却键不区分大小写与尾斜杠（Windows 同一个项目别算成两个）", async () => {
+  const ctx = fakeCtx();
+  const calls = [];
+  let clock = 1_000_000;
+  const auto = createNudgeAutoRun({
+    ctx,
+    runNudge: (args) => { calls.push(args); return { counts: { savedProposals: 0 } }; },
+    now: () => clock,
+    minIntervalMs: 10_000
+  });
+  ctx.emit(sessionAt("D:/Proj"), { type: "turn/end" });
+  await tick();
+  ctx.emit(sessionAt("d:\\proj\\"), { type: "turn/end" });
+  await tick();
+  assert.equal(calls.length, 1, "同一个项目换个写法不该被当成新项目");
+  auto();
+});
+
+test("挖挂了不许冒泡：session/event 那条链上还挂着摘要与续期", async () => {
+  const ctx = fakeCtx();
+  let ran = 0;
+  const auto = createNudgeAutoRun({
+    ctx,
+    logger: { info() {}, warn() {} },
+    runNudge: () => { ran += 1; throw new Error("boom"); },
+    now: () => 1_000_000
+  });
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  await assert.doesNotReject(tick().then(() => {}), "定时回调里的异常不许掀翻宿主");
+  assert.equal(ran, 1);
+  auto();
+});
+
+test("没有 cwd 的会话不排队（归属不明就别猜）", async () => {
+  const ctx = fakeCtx();
+  const calls = [];
+  const auto = createNudgeAutoRun({
+    ctx,
+    runNudge: (args) => { calls.push(args); return { counts: { savedProposals: 0 } }; },
+    now: () => 1_000_000
+  });
+  ctx.emit({ header: {} }, { type: "turn/end" });
+  ctx.emit(null, { type: "turn/end" });
+  await tick();
+  assert.deepEqual(calls, []);
+  assert.equal(auto.pendingCount(), 0);
+  auto();
+});
+
+test("dispose 之后：取消订阅、清掉排队的活，runNow 也不再跑", async () => {
+  const ctx = fakeCtx();
+  const calls = [];
+  const auto = createNudgeAutoRun({
+    ctx,
+    runNudge: (args) => { calls.push(args); return { counts: { savedProposals: 0 } }; },
+    now: () => 1_000_000
+  });
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  auto();
+  assert.equal(ctx.count(), 0, "订阅必须被摘掉");
+  assert.equal(auto.pendingCount(), 0, "排队的活必须被清掉");
+  await tick();
+  // 关键：dispose 之前排进 timer 的那一次也不许再跑（否则卸载后还会写盘）。
+  assert.deepEqual(calls, [], "卸载之后不许还有一次偷偷的写盘");
+  assert.equal(auto.runNow("D:/proj"), null);
+  assert.deepEqual(calls, []);
+  // 再发事件也不排队了。
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  await tick();
+  assert.deepEqual(calls, []);
+});
+
+test("runNow 绕开冷却与 timer，手动入口可以直接驱动一次", () => {
+  const ctx = fakeCtx();
+  const calls = [];
+  const auto = createNudgeAutoRun({
+    ctx,
+    runNudge: (args) => { calls.push(args); return { counts: { savedProposals: 0 } }; },
+    now: () => 1_000_000,
+    minIntervalMs: 10_000
+  });
+  const doc = auto.runNow("D:/proj");
+  assert.ok(doc, "手动入口要有同步回执");
+  assert.equal(calls.length, 1);
+  // runNow 刻意**不走冷却**：它是人显式要的一次跑，人比定时器知道自己要什么。
+  assert.ok(auto.runNow("D:/proj"));
+  assert.equal(calls.length, 2);
+  // 但它要把时间记上——否则紧接着的自动跑会立刻再来一次。
+  assert.equal(typeof auto.lastRunAt("D:/proj"), "number");
+  ctx.emit(sessionAt("D:/proj"), { type: "turn/end" });
+  return tick().then(() => {
+    assert.equal(calls.length, 2, "runNow 之后冷却生效，自动跑不许立刻重跑");
+    auto();
+  });
+});

package/test/pipeline-nudge.test.js

@@ -33,10 +33,12 @@ import {
   loadProposals,
   summarizeProposal,
   retirementProposals,
-  nudgeFromSessions
+  nudgeFromSessions,
+  nudgeForProject,
+  resolveProjectSessionDir
 } from "../src/pipeline-nudge.js";
 
-// 这组测试守的是 M.O. 的**沉淀链**：一条手法能不能从真实数据里自己长出来。
+// 这组测试守的是 M.O. 的**沉淀链**：一条工作流能不能从真实数据里自己长出来。
 // 三条不许越的分界线（见 src/pipeline-nudge.js 文件头），测试逐条守：
 //   1. 机器只写它真观察到的东西（措辞里不许出现编出来的判据，也不许漏本机路径）；
 //   2. 反事实判据的结论**永远不由机器给**（verdict 必须是 null，问题必须带着选项）；
@@ -210,7 +212,7 @@ test("挖掘：至少两个不同会话才算候选；同一段路出现两次
   });
 });
 
-test("默认只挖能力级：内置工具的通用动作不算手法（本机 520 份日志实测那是噪音）", () => {
+test("默认只挖能力级：内置工具的通用动作不算工作流（本机 520 份日志实测那是噪音）", () => {
   withDir((dir) => {
     const sessions = join(dir, "sessions");
     for (const id of ["sess-a", "sess-b", "sess-c"]) {
@@ -221,7 +223,7 @@ test("默认只挖能力级：内置工具的通用动作不算手法（本机 5
     const read = readSessionObservations({ sessionDir: sessions });
     const segments = segmentObservations(read.observations);
     assert.deepEqual(DEFAULT_NUDGE_KINDS, ["skill", "mcp"]);
-    // 三个会话都出现了 read → pwsh，支持度足够高，但它是通用动作习惯，不是项目手法。
+    // 三个会话都出现了 read → pwsh，支持度足够高，但它是通用动作习惯，不是项目工作流。
     assert.deepEqual(mineRepeatedPatterns(segments), [], "默认口径下这类序列不该冒出来");
     // 显式开工具级才挖得到——而且要把「同一步连着走」重新折叠起来。
     const toolLevel = mineRepeatedPatterns(segments, { kinds: null });
@@ -522,7 +524,7 @@ test("清单行：反事实覆盖率与风险下限照实投影", () => {
     counterfactual: { verdict: null }
   };
   const row = summarizeProposal(proposal);
-  // 19/19 与 6/19 是两条不同的手法，清单上就该看得出来。
+  // 19/19 与 6/19 是两条不同的工作流，清单上就该看得出来。
   assert.deepEqual(row.contrast, { answered: 1, total: 2 });
   assert.equal(row.riskFloor, "R2", "整条的风险取下限里的最高档");
   assert.equal(row.verdict, null, "判据没有结论时清单里也是 null，不显示一个假结论");
@@ -729,7 +731,7 @@ test("回归·空回答不算「已答」：一条都没接受就不许推进状
   assert.equal(ok.applied.length, 1);
 });
 
-test("回归·跨工作区不并账：两个桶各一次不是「支持度 2 的同一手法」", () => {
+test("回归·跨工作区不并账：两个桶各一次不是「支持度 2 的同一工作流」", () => {
   withDir((dir) => {
     const sessions = join(dir, "sessions");
     const seq = [[sessionLine({ turn: 1, calls: [skill("alpha"), skill("beta")] })]];
@@ -1034,3 +1036,156 @@ test("回归·文件上限按排序截断，不按遍历顺序（选择偏差要
     assert.equal(read.scannedFiles, 2);
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// nudgeForProject：把「归属解析」和「挖掘」绑成一次调用（v0.9.3 接线的入口）。
+// 守两件事：没有归属就**不许跑**（不能退化成无归属普查），预览不许写盘。
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 造一个假 DSH_HOME：sessions/<桶>/<会话>/session.v4.jsonl.zstd，头行带 cwd。 */
+function fakeDshHome(dir, { bucket = "ws-bucket", cwd = null, sessions = ["sess-a"] } = {}) {
+  const home = join(dir, "dsh-home");
+  for (const id of sessions) {
+    const sub = join(home, "sessions", bucket, id);
+    mkdirSync(sub, { recursive: true });
+    const head = JSON.stringify({ time: 1700000000000, cwd });
+    const body = sessionLine({ turn: 1, calls: [skill("alpha"), skill("beta"), pwsh("npm test")] });
+    writeFileSync(join(sub, "session.v4.jsonl.zstd"), zlib.zstdCompressSync(Buffer.from([head, body].join("\n"), "utf8")));
+  }
+  return home;
+}
+
+test("nudgeForProject：归属解析不到就整跑跳过，绝不退化成「无归属普查」", () => {
+  withDir((dir) => {
+    const projectRoot = join(dir, "proj");
+    mkdirSync(projectRoot, { recursive: true });
+    const dshHome = fakeDshHome(dir, { cwd: join(dir, "somewhere-else") });
+    const doc = nudgeForProject({ projectRoot, dshHome, memoryDir: join(dir, "memory"), persistProposals: true });
+    assert.equal(doc.skipped, true);
+    assert.equal(doc.skippedReason, "no-session-attribution");
+    assert.equal(doc.attribution.reason, "no-bucket");
+    assert.equal(doc.counts.candidates, 0);
+    assert.equal(doc.counts.savedProposals, 0);
+    // 边界话术：跳过与跑完必须是同一句（同一个 NUDGE_BOUNDARIES 常量）。
+    assert.equal(doc.boundaries.autoActivate, false);
+    assert.equal(doc.boundaries.writesOnlyDrafts, true);
+    assert.equal(existsSync(join(dir, "memory", "proposals")), false, "没归属就不该建提议桶");
+  });
+});
+
+test("nudgeForProject：命中归属就真跑，预览（persistProposals:false）一个文件都不写", () => {
+  withDir((dir) => {
+    const projectRoot = join(dir, "proj");
+    mkdirSync(projectRoot, { recursive: true });
+    const memoryDir = join(dir, "memory");
+    const dshHome = fakeDshHome(dir, { cwd: projectRoot });
+    // 两个会话走同一段序列才够 NUDGE_MIN_SUPPORT=2（support 数的是**会话**，不是次数）。
+    fakeDshHome(dir, { cwd: projectRoot, sessions: ["sess-b"] });
+
+    const preview = nudgeForProject({ projectRoot, dshHome, memoryDir, persistProposals: false });
+    assert.equal(preview.skipped, false);
+    assert.equal(preview.attribution.reason, "matched");
+    assert.ok(preview.counts.candidates >= 1, "真数据里必须挖得出候选");
+    // 这一条是接线的关键：面板每刷一次就 GET 一次，预览绝不能往 memoryDir 里塞文件。
+    assert.equal(preview.counts.savedProposals, 0);
+    assert.equal(existsSync(join(memoryDir, "proposals")), false, "预览不落盘");
+
+    const real = nudgeForProject({ projectRoot, dshHome, memoryDir, persistProposals: true });
+    assert.equal(real.counts.savedProposals, real.counts.candidates);
+    assert.ok(existsSync(real.proposalsDir));
+    // 自动跑永不落草稿：materialize 默认 false，项目里不该多出 pipelines 目录。
+    assert.equal(real.counts.draftsWritten, 0);
+    assert.equal(existsSync(projectPipelineDir(projectRoot)), false);
+  });
+});
+
+test("nudgeForProject：「读不到」与「确实没有」必须分开报", () => {
+  withDir((dir) => {
+    const projectRoot = join(dir, "proj");
+    mkdirSync(projectRoot, { recursive: true });
+    // 桶在，但里面一个会话文件都没有 → 读不出任何 cwd → unreadable（故障），不是 no-bucket。
+    const homeEmpty = join(dir, "home-empty");
+    mkdirSync(join(homeEmpty, "sessions", "ws-bucket"), { recursive: true });
+    assert.equal(resolveProjectSessionDir({ dshHome: homeEmpty, projectRoot }).reason, "unreadable");
+    // 会话根根本不存在 → no-sessions-dir（新机器），同样是故障侧。
+    const homeMissing = join(dir, "home-missing");
+    assert.equal(resolveProjectSessionDir({ dshHome: homeMissing, projectRoot }).reason, "no-sessions-dir");
+  });
+});
+
+test("归属解析也吃 budgetMs：预算用光报 budget-exceeded，不冒充 no-bucket", () => {
+  // 评审抓出：resolveProjectSessionDir 最多同步扫 500 个桶 × 3 个文件，原先完全不看
+  // budgetMs，于是 PR 正文那句「真卡就调 budgetMs」对这段路径是空话。
+  // 这里用「截止点已经过去」来构造，不依赖真实耗时，确定性。
+  withDir((dir) => {
+    const projectRoot = join(dir, "proj");
+    mkdirSync(projectRoot, { recursive: true });
+    const home = fakeDshHome(dir, { cwd: projectRoot });
+    // 已经过期的截止点 → 连一个桶都不该扫。
+    const stalled = resolveProjectSessionDir({ dshHome: home, projectRoot, deadline: Date.now() - 1 });
+    assert.equal(stalled.reason, "budget-exceeded");
+    assert.equal(stalled.sessionDir, null);
+    assert.equal(stalled.filesRead, 0, "超预算时一个会话文件都不该读");
+    // 不给 deadline = 扫到底，行为与改动前一致（测试与离线批处理要完整结果）。
+    assert.equal(resolveProjectSessionDir({ dshHome: home, projectRoot }).reason, "matched");
+  });
+});
+
+test("nudgeForProject：归属解析超预算时 skipped 并如实带 budget-exceeded", () => {
+  withDir((dir) => {
+    const projectRoot = join(dir, "proj");
+    mkdirSync(projectRoot, { recursive: true });
+    const home = fakeDshHome(dir, { cwd: projectRoot });
+    // now 往前推 10s + budget 4s → 截止点在过去，模拟「预算已经被前面的活花掉了」。
+    const doc = nudgeForProject({
+      projectRoot,
+      dshHome: home,
+      memoryDir: join(dir, "memory"),
+      now: Date.now() - 10000,
+      budgetMs: 4000,
+      persistProposals: false
+    });
+    assert.equal(doc.skipped, true);
+    assert.equal(doc.skippedReason, "no-session-attribution");
+    // 关键：原因必须能区别于「这个项目确实没跑过会话」（no-bucket）——否则一次
+    // 扫不完会被读成「这个项目很干净」。
+    assert.equal(doc.attribution.reason, "budget-exceeded");
+    assert.equal(doc.counts.candidates, 0);
+  });
+});
+
+test("桶数超过 maxBuckets：先排序再截断，截断没命中报 bucket-limit 而不是 no-bucket", () => {
+  // 评审抓出的第二个「读不到装成确实没有」：早前是边收边截（到 500 个就 break、
+  // 然后才 sort），留下哪 500 个由文件系统遍历顺序决定；目标项目的桶一旦落在被
+  // 截掉的那部分，就返回 no-bucket —— 一次截断被报成「这个项目没有会话」。
+  withDir((dir) => {
+    const projectRoot = join(dir, "proj");
+    mkdirSync(projectRoot, { recursive: true });
+    const elsewhere = join(dir, "somewhere-else");
+    mkdirSync(elsewhere, { recursive: true });
+    // 四个桶：字母序 aaa-1, aaa-2, ws-bucket, zz-1。目标在 ws-bucket。
+    // 无关桶里也放**真会话**（cwd 指向别处），这样 bucketsWithCwd > 0，
+    // 唯一剩下的原因就是截断本身——否则会先命中 unreadable，测不到这条。
+    const home = fakeDshHome(dir, { bucket: "ws-bucket", cwd: projectRoot });
+    fakeDshHome(dir, { bucket: "aaa-1", cwd: elsewhere });
+    fakeDshHome(dir, { bucket: "aaa-2", cwd: elsewhere });
+    fakeDshHome(dir, { bucket: "zz-1", cwd: elsewhere });
+
+    // 只扫前 2 个（aaa-1、aaa-2）：目标被挤出，且这不是「它没有会话」。
+    const miss = resolveProjectSessionDir({ dshHome: home, projectRoot, maxBuckets: 2 });
+    assert.equal(miss.reason, "bucket-limit", "被截断 ≠ 这个项目没有会话");
+    assert.notEqual(miss.reason, "no-bucket");
+    assert.equal(miss.bucketsTruncated, true);
+    assert.equal(miss.bucketsScanned, 2);
+    assert.equal(miss.bucketsTotal, 4, "总数与扫描数都要报，截断才看得见");
+
+    // 放宽到 3 个：字母序把 ws-bucket 包进来 → 命中。
+    const hit = resolveProjectSessionDir({ dshHome: home, projectRoot, maxBuckets: 3 });
+    assert.equal(hit.reason, "matched", "留下谁由字母序决定，不由遍历序决定");
+
+    // 不截断时依然是真答案那套，且 truncated 明确为 false。
+    const full = resolveProjectSessionDir({ dshHome: home, projectRoot, maxBuckets: 999 });
+    assert.equal(full.reason, "matched");
+    assert.equal(full.bucketsTruncated, false);
+  });
+});

package/test/readme-claims.test.js

@@ -0,0 +1,68 @@
+// 两份 README 曾经都写着「默认全离线」「offline by default」「默认零网络依赖」——
+// 这与代码默认值相反：autoDream 与 autoSummarize 默认开（src/config.js），
+// 两者都把记忆正文交给 ctx.llm.stream(...)（src/dream.js / src/summarize.js）；
+// embedProvider 默认还是 "openai"，只有显式改成 "local"（ONNX）才真正离线。
+// 一句假话比不写更坏：读者会据此以为装完就能断网用，而它默认会把正文发给宿主模型。
+// 所以这里锁两件事：一、绝对离线声明不许回来；二、隐私节必须写出「巩固走宿主模型」这个出站事实——
+// 删掉假话后如果什么都不说，误导是一样的。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync, existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+const repoRoot = path.dirname(pkgRoot);
+const rootReadmePath = path.join(repoRoot, "README.md");
+
+// npm 的 files 清单把整个 test/ 打进包里，所以在 packed / installed 包里跑 npm test 时，
+// 这个文件照样会被执行——但那里没有仓库根 README（只有包内 dsh-mneme/README.md）。
+// 直接 readFileSync 会让整个测试文件在加载阶段 ENOENT 崩掉，把「不是这个仓」报成「断言失败」。
+// 所以仓库根不在时显式 skip：这条守卫的适用面本来就只是仓库，不该在包内假红。
+const hasRepoRoot = existsSync(rootReadmePath);
+const rootReadme = hasRepoRoot ? readFileSync(rootReadmePath, "utf8") : "";
+const pkgReadme = readFileSync(path.join(pkgRoot, "README.md"), "utf8");
+const outsideRepo = hasRepoRoot ? {} : { skip: "not a repo checkout: 仓库根 README 不存在（包内安装态）" };
+
+// 只锁「默认 / 无条件」的说法。带条件的离线表述（把 embedProvider 改成 local、离线巩固论文、
+// 运行时离线取件）都是真话，不在这个列表里，否则守卫会把正确写法也判红。
+const ABSOLUTE_CLAIMS = [
+  "默认全离线",
+  "默认零网络依赖",
+  "offline by default",
+  "Zero network dependency by default",
+  "完全离线的语义记忆引擎",
+];
+
+function section(text, heading) {
+  const start = text.indexOf(heading);
+  assert.ok(start >= 0, `README 里应有「${heading}」一节`);
+  const rest = text.slice(start + heading.length);
+  const next = rest.search(/\r?\n## /);
+  return next === -1 ? rest : rest.slice(0, next);
+}
+
+test("两份 README 都不许再把「离线」写成默认行为", outsideRepo, () => {
+  for (const [name, text] of [
+    ["README.md", rootReadme],
+    ["dsh-mneme/README.md", pkgReadme],
+  ]) {
+    for (const claim of ABSOLUTE_CLAIMS) {
+      assert.ok(!text.includes(claim), `${name} 仍含绝对离线声明：${claim}`);
+    }
+  }
+});
+
+test("隐私节必须写出「巩固与摘要走宿主模型」这个出站事实", outsideRepo, () => {
+  const zh = section(rootReadme, "## 隐私承诺");
+  assert.ok(zh.includes("宿主模型"), "中文隐私节应说明巩固与摘要走宿主模型");
+  assert.ok(
+    zh.includes("autoDream") || zh.includes("autoSummarize"),
+    "中文隐私节应点名 autoDream / autoSummarize，否则读者不知道是谁在出站",
+  );
+  const en = section(rootReadme, "## Privacy");
+  assert.ok(
+    en.includes("host model"),
+    "English Privacy section should disclose that consolidation uses the host model",
+  );
+});