@modusensus/dsh-mneme 0.11.0 → 0.13.0

package/test/wiki-cli-hint.test.js

@@ -0,0 +1,118 @@
+// dsh-mneme/test/wiki-cli-hint.test.js
+// issue #607 的回归锁：提示里那条命令必须真能粘贴就跑。
+//
+// 这条 issue 的病因不是「文案不好看」，是**给了一条跑不起来的命令**：插件装在
+// profile 依赖里，npm 只为全局安装把 shim 放进 PATH，用户照抄 dsh-mneme-choro
+// 必然 command not found。所以真正要锁的不是字符串长相，而是三件事：
+//   1) 推导出的入口在这个仓库里真实存在（下面的 existsSync 与实跑验证）；
+//   2) 推导不依赖调用方在第几层目录（src/ 与 lib/ 同层、src/wiki/ 在第二层、
+//      bin/ 在第一层）——写死层数会悄悄算错，而算错的表现正是又给一条跑不起来的命令；
+//   3) 找不到入口时返回 null 让调用方降级，而不是硬编一个假路径。
+//
+// 引号部分单独锁：安装路径带空格是常态（Windows 的 C:\Program Files\），
+// POSIX 路径带单引号也必须转义成 '\''，否则「带引号的命令」照样跑不起来。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { choroCliCommand, choroCliCommandFrom, choroCliEntry } from "../src/wiki/cli-hint.js";
+
+const ENTRY_TAIL = join("bin", "dsh-mneme-choro.mjs");
+
+test("从包内任意深度都能推出同一个 CLI 入口（不按固定层数）", () => {
+  // 四个不同深度、且真实存在于本仓的模块位置；写死 dirname 次数的实现只会有
+  // 其中一部分对，这条断言就会红。
+  const froms = [
+    new URL("../package.json", import.meta.url), // test/  -> 1 层
+    new URL("../src/tools.js", import.meta.url), // src/   -> 1 层
+    new URL("../src/wiki/t1.js", import.meta.url), // src/wiki/ -> 2 层
+    new URL("../bin/dsh-mneme-choro.mjs", import.meta.url) // bin/ -> 0 层
+  ];
+  const entries = froms.map((u) => choroCliEntry(u.href));
+  for (const [i, entry] of entries.entries()) {
+    assert.equal(typeof entry, "string", "caller #" + i + " must resolve an entry");
+    assert.ok(existsSync(entry), "caller #" + i + " resolved a path that does not exist: " + entry);
+    assert.ok(entry.endsWith(ENTRY_TAIL), entry);
+  }
+  // 四条路径必须收敛到同一个入口，否则「同一份代码在不同文件里给出不同命令」
+  assert.equal(new Set(entries).size, 1);
+});
+
+test("推出来的入口是这个包自己的 bin（不是同名外来目录）", () => {
+  const entry = choroCliEntry(new URL("../src/wiki/t1.js", import.meta.url).href);
+  assert.ok(entry);
+  // 包根必须同时有 bin/ 与 package.json —— 这正是推导的两个条件，反过来验一遍
+  const pkgRoot = entry.slice(0, entry.length - ENTRY_TAIL.length - 1);
+  assert.ok(existsSync(join(pkgRoot, "package.json")), pkgRoot);
+  assert.equal(join(pkgRoot, ENTRY_TAIL), entry);
+});
+
+test("源码树被裁剪（找不到 bin 或 package.json）时返回 null，不硬编假路径", () => {
+  const dir = mkdtempSync(join(tmpdir(), "mneme-cli-hint-"));
+  try {
+    // 只有 bin/ 没有 package.json：可能是别人的同名 bin，不能认
+    mkdirSync(join(dir, "bin"), { recursive: true });
+    writeFileSync(join(dir, "bin", "dsh-mneme-choro.mjs"), "");
+    assert.equal(choroCliEntry(pathToFileURL(join(dir, "bin", "dsh-mneme-choro.mjs")).href), null);
+
+    // 补齐 package.json 就该认出来（证明上一条的红不是「永远返回 null」）
+    writeFileSync(join(dir, "package.json"), "{}");
+    assert.equal(
+      choroCliEntry(pathToFileURL(join(dir, "bin", "dsh-mneme-choro.mjs")).href),
+      join(dir, "bin", "dsh-mneme-choro.mjs")
+    );
+
+    // 只有 package.json 没有 bin/：`files` 少了 bin 的裁剪树，同样不能认
+    const bare = mkdtempSync(join(tmpdir(), "mneme-cli-hint-bare-"));
+    try {
+      writeFileSync(join(bare, "package.json"), "{}");
+      mkdirSync(join(bare, "src"), { recursive: true });
+      assert.equal(choroCliEntry(pathToFileURL(join(bare, "src", "tools.js")).href), null);
+    } finally {
+      rmSync(bare, { recursive: true, force: true });
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("命令带引号：Windows 双引号，POSIX 单引号（路径含空格与单引号都要能跑）", () => {
+  // Windows：安装路径带空格是常态，不加引号那条命令在 cmd 里会被拆成两段
+  assert.equal(
+    choroCliCommand("C:\\Program Files\\mneme\\bin\\dsh-mneme-choro.mjs", "<repo>", "win32"),
+    'node "C:\\Program Files\\mneme\\bin\\dsh-mneme-choro.mjs" <repo> --apply'
+  );
+  // POSIX：无空格时也加引号（统一形态，便于用户照着改）
+  assert.equal(
+    choroCliCommand("/opt/mneme/bin/dsh-mneme-choro.mjs", "<repo>", "linux"),
+    "node '/opt/mneme/bin/dsh-mneme-choro.mjs' <repo> --apply"
+  );
+  // POSIX：路径里有单引号，必须转成 '\''，否则 shell 把命令截断在引号处
+  assert.equal(
+    choroCliCommand("/opt/it's here/bin/dsh-mneme-choro.mjs", "<repo>", "linux"),
+    "node '/opt/it'\\''s here/bin/dsh-mneme-choro.mjs' <repo> --apply"
+  );
+  // 占位符原样保留（面板给 <仓库路径>，工具报错给 <repo>），不被引号逻辑吞掉
+  assert.equal(
+    choroCliCommandFrom(new URL("../src/tools.js", import.meta.url).href, "<仓库路径>", "win32").endsWith(" <仓库路径> --apply"),
+    true
+  );
+  // 入口缺失时整体返回 null —— 调用方据此降级，绝不输出半条命令
+  assert.equal(choroCliCommand(null, "<repo>", "win32"), null);
+  assert.equal(choroCliCommandFrom("not a url", "<repo>", "win32"), null);
+});
+
+test("真的能跑：用推导出的入口执行一次 --help（issue 的验收就是「用户能跑起来」）", () => {
+  const entry = choroCliEntry(new URL("../src/wiki/t1.js", import.meta.url).href);
+  assert.ok(entry);
+  // 用真实入口起一次进程：issue 的验收标准就是「用户照着这条命令能跑起来」，
+  const res = spawnSync(process.execPath, [entry, "--help"], { encoding: "utf8", timeout: 30000 });
+  assert.equal(res.status, 0, entry + " --help failed: " + (res.stderr || res.stdout));
+  assert.match(res.stdout, /--apply/);
+});
+  // 用真实入口起一次进程：issue 的验收标准就是「用户照着这条命令能跑起来」，
+  // 字符串层面的断言证明不了这件事。

package/test/wiki-queries.test.js

@@ -4,7 +4,7 @@
 // 盘上缺页如实报 page-missing、检索分节与行号、repo 解析的歧义处理。
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, unlinkSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
@@ -46,6 +46,89 @@ function setup() {
   return { root, store, q: createChoroQueries({ store }) };
 }
 
+// stub embedder：文本含 "src" → [1,0]，否则 [0,1]（固定二维，可断言方向与失配）
+function stubEmbedder(model = "stub-1") {
+  return {
+    model,
+    embedSingle: async (text) => (/src/.test(text) ? [1, 0] : [0, 1]),
+    embed: async (text) => (/src/.test(text) ? [1, 0] : [0, 1]),
+  };
+}
+
+// --- 收尾档 P37–P39：向量惰性物化与检索 -------------------------------------
+
+test("embedPageVectors：首次全嵌，generated_at 没变就跳过，变了重嵌（staleness 两维之一）", async () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    const emb = stubEmbedder();
+    const r1 = await q.embedPageVectors(repo.id, emb);
+    assert.equal(r1.embedded, 2, "两页全嵌");
+    const r2 = await q.embedPageVectors(repo.id, emb);
+    assert.equal(r2.embedded, 0);
+    assert.equal(r2.skipped, 2, "generated_at 没变 → 全跳过");
+    // 页面内容变了（generated_at 推进）→ 只重嵌变的那页
+    const pagePath = join(root, ".chorography", "modules", "src.md");
+    const before = readFileSync(pagePath, "utf8");
+    writeFileSync(pagePath, `${before}<!-- CHORO:HUMAN:START -->\n人工补充\n<!-- CHORO:HUMAN:END -->\n`, "utf8");
+    store.db.prepare(
+      "UPDATE choro_pages SET generated_at = ? WHERE generated_at IS NOT NULL AND id IN (SELECT p.id FROM choro_pages p JOIN choro_modules m ON p.module_id = m.id WHERE m.slug = 'src')"
+    ).run("2026-11-06T00:00:00.000Z");
+    const r3 = await q.embedPageVectors(repo.id, emb);
+    assert.equal(r3.embedded, 1, "只有 src 页重嵌");
+    assert.equal(r3.stale, 1, "旧向量按 stale 记账");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("dim 失配（换 embedder 模型）→ 惰性全量重嵌（P38：不锁死，代价只是几十页）", async () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    await q.embedPageVectors(repo.id, stubEmbedder("stub-1"));
+    // 换模型：维度从 2 → 3。expectDim 来自查询向量（路由先嵌查询再物化）
+    const emb3 = {
+      model: "stub-2",
+      embedSingle: async () => [1, 0, 0],
+      embed: async () => [1, 0, 0],
+    };
+    const r = await q.embedPageVectors(repo.id, emb3, { expectDim: 3 });
+    assert.equal(r.embedded, 2, "维度变了 → 全部重嵌（fresh 检查被 dimDrift 压过）");
+    assert.equal(r.dimMismatch, true, "失配被记账");
+    const rows = store.getChoroPageVectors(repo.id);
+    assert.ok(rows.every((row) => row.dim === 3 && row.model === "stub-2"), "旧维度行不复存");
+    // 不给 expectDim（无查询场景）→ fresh 行照旧跳过
+    const r2 = await q.embedPageVectors(repo.id, emb3);
+    assert.equal(r2.embedded, 0);
+    assert.equal(r2.skipped, 2);
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("searchSemantic：cosine 排序 + dim 失配行被过滤 + embedder 缺席返回 null", async () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    await q.embedPageVectors(repo.id, stubEmbedder("stub-1"));
+    const hits = await q.searchSemantic(repo.id, stubEmbedder("stub-1"), "src 相关的页");
+    assert.ok(Array.isArray(hits) && hits.length >= 1);
+    assert.equal(hits[0].slug, "src", "查询向量 [1,0] 与 src 页同向 → 排前");
+    // 查询向量三维：与所有行 dim 失配 → 无可比行，返回空数组而不是抛
+    const dim3 = { embedSingle: async () => [1, 0, 0], embed: async () => [1, 0, 0] };
+    const empty = await q.searchSemantic(repo.id, dim3, "x");
+    assert.deepEqual(empty, []);
+    assert.equal(await q.searchSemantic(repo.id, null, "x"), null);
+    assert.deepEqual(await q.searchSemantic(repo.id, stubEmbedder(), "  "), [], "空查询不嵌入、返回空数组");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
 test("listRepos / resolveRepo：单仓自动收敛，多仓歧义要显式给键", () => {
   const { root, store, q } = setup();
   try {
@@ -82,6 +165,13 @@ test("moduleMap：模块、页面状态与跨模块边同源返回", () => {
     assert.deepEqual(slugs, ["root", "src"]);
     const src = modules.find((m) => m.slug === "src");
     assert.equal(src.page_status, "skeleton");
+    // 面板从地志页导入知识点时读的是 mod.relPath（契约 §3.6）；SQL 行里只有
+    // page_rel_path，缺这层映射会让「选完模块点导入」永远提示请先选模块（#607）。
+    // 同时锁住原 snake_case 字段还在——choro_module_map 的 render 与 CLI 都在用。
+    assert.equal(typeof src.relPath, "string", "relPath 必须与 page_rel_path 同值");
+    assert.equal(src.relPath, src.page_rel_path);
+    assert.ok(src.relPath.endsWith(".md"), "页相对路径是磁盘上真实存在的 .md");
+    assert.equal(typeof src.file_count, "number", "file_count 原字段必须保留（choro_module_map 的 render 在吃）");
     // fixture 的引用全在 src 模块内部（a→b→b2），left-pad 是外部依赖，root 只有
     // package.json 没有代码——跨模块边应为空集。跨模块聚erge本身由 wiki-store 的
     // 整仓替换用例与 t0 的 moduleEdges 排序覆盖。

package/test/wiki-t1-jobs.test.js

@@ -0,0 +1,125 @@
+// T1 面板后台任务状态机的回归锁（契约 §3.2）。
+//
+// **绝不真起进程**：T1 一次要花模型额度，测试里注入假 spawn 就够——这一层要证明的
+// 是「记账与状态迁移对不对」，不是「模型跑得通不通」（那是 CLI 的 e2e 地盘）。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { createT1Jobs } from "../src/wiki/t1-jobs.js";
+
+// 假子进程：stdout/stderr 是 EventEmitter，close/error 也走事件——形状贴着真
+// ChildProcess，但一个字节都不会真跑出去。
+function fakeSpawn() {
+  const calls = [];
+  const spawn = (cmd, args, opts) => {
+    const child = new EventEmitter();
+    child.stdout = new EventEmitter();
+    child.stderr = new EventEmitter();
+    child.stdout.setEncoding = () => {};
+    child.stderr.setEncoding = () => {};
+    child.killed = false;
+    child.kill = () => { child.killed = true; };
+    child.cmd = cmd;
+    child.args = args;
+    child.opts = opts;
+    calls.push(child);
+    return child;
+  };
+  return { spawn, calls };
+}
+
+function makeJobs(overrides = {}) {
+  const fake = fakeSpawn();
+  const jobs = createT1Jobs({
+    spawn: fake.spawn,
+    nodePath: "node",
+    scriptPath: "/pkg/bin/dsh-mneme-choro.mjs",
+    dbPath: "/mem/memory.db",
+    now: (() => { let i = 0; return () => `T${++i}`; })(),
+    ...overrides
+  });
+  return { jobs, calls: fake.calls };
+}
+
+const repo = { id: 1, name: "r", root_path: "/repo" };
+
+test("start：起的是 CLI 的 --t1 --apply --json（面板必须带 apply，否则 CLI 只列候选不写）", () => {
+  const { jobs, calls } = makeJobs();
+  const r = jobs.start({ repo, module: "src", retryFailed: true });
+  assert.equal(r.started, true);
+  assert.ok(r.jobId);
+  assert.equal(calls.length, 1);
+  const [cmd, args, opts] = [calls[0].cmd, calls[0].args, calls[0].opts];
+  assert.equal(cmd, "node");
+  assert.deepEqual(args.slice(0, 5), ["/pkg/bin/dsh-mneme-choro.mjs", "/repo", "--t1", "--apply", "--json"]);
+  assert.ok(args.includes("--module") && args.includes("src"));
+  assert.ok(args.includes("--retry-failed"));
+  assert.ok(args.includes("--db") && args.includes("/mem/memory.db"));
+  // Electron 宿主里不设这个变量会去开窗口而不是跑脚本——这条是踩过的坑。
+  assert.equal(opts.env.ELECTRON_RUN_AS_NODE, "1");
+  assert.deepEqual(opts.stdio, ["ignore", "pipe", "pipe"]);
+  jobs.dispose();
+});
+
+test("同一仓库并发 → job-running 且带回在跑的 jobId（面板据此继续轮询而不是重起）", () => {
+  const { jobs } = makeJobs();
+  const first = jobs.start({ repo });
+  const second = jobs.start({ repo });
+  assert.equal(second.started, false);
+  assert.equal(second.code, "job-running");
+  assert.equal(second.jobId, first.jobId);
+
+  // 不同仓库互不影响：并发闸是按仓库的，不是全局的。
+  const other = jobs.start({ repo: { id: 2, name: "o", root_path: "/repo2" } });
+  assert.equal(other.started, true);
+  jobs.dispose();
+});
+
+test("stdout 逐行进 logTail（封顶 200 行），chunk 切在一行中间也不丢字", async () => {
+  const { jobs, calls } = makeJobs();
+  const { jobId } = jobs.start({ repo });
+  const child = calls[0];
+  // 故意把一行拆成两个 chunk：不做余量拼接的实现会把它切成两条假日志。
+  child.stdout.emit("data", "第一行\n第二");
+  child.stdout.emit("data", "行\n");
+  let view = jobs.status(jobId);
+  assert.deepEqual(view.logTail, ["第一行", "第二行"]);
+
+  for (let i = 0; i < 300; i += 1) child.stdout.emit("data", `l${i}\n`);
+  view = jobs.status(jobId);
+  assert.equal(view.logTail.length, 200, "ring buffer 封顶：长任务 stdout 不封顶就是内存泄漏");
+  assert.equal(view.logTail[199], "l299", "留下的是最新的尾巴（面板要看的是当前在干嘛）");
+  jobs.dispose();
+});
+
+test("退出码 0 → done 且从回执读出进度；非 0 → failed 且带 stderr 尾巴", () => {
+  const { jobs, calls } = makeJobs();
+  const ok = jobs.start({ repo });
+  // CLI --json 输出的是多行 JSON（不是 NDJSON）：按行收日志、按全文解析回执，两条路
+  // 各走各的，才不会互相牺牲。
+  calls[0].stdout.emit("data", JSON.stringify({ dryRun: false, enriched: [{ slug: "a" }], failed: [{ slug: "b" }] }, null, 2));
+  calls[0].emit("close", 0);
+  const done = jobs.status(ok.jobId);
+  assert.equal(done.state, "done");
+  assert.deepEqual(done.modules, { total: 2, done: 1, failed: 1 });
+  assert.ok(done.finishedAt);
+
+  const bad = jobs.start({ repo: { id: 2, name: "o", root_path: "/repo2" } });
+  calls[1].stderr.emit("data", "拒绝运行（not-registered）：仓库没登记\n");
+  calls[1].emit("close", 1);
+  const failed = jobs.status(bad.jobId);
+  assert.equal(failed.state, "failed");
+  // 只报 exit code 等于让面板说「失败了，不知道为啥」——stderr 尾巴才是人话。
+  assert.match(failed.error, /not-registered/);
+  jobs.dispose();
+});
+
+test("未知 jobId → null；dispose 杀掉在跑的进程并清账", () => {
+  const { jobs, calls } = makeJobs();
+  assert.equal(jobs.status("nope"), null);
+  const { jobId } = jobs.start({ repo });
+  assert.equal(jobs.status(jobId).state, "running");
+  jobs.dispose();
+  assert.equal(calls[0].killed, true, "宿主卸载时要带走子进程，不留孤儿");
+  assert.equal(jobs.status(jobId), null);
+});

package/test/wiki-tools.test.js

@@ -1,41 +1,45 @@
-// chorography 只读工具的回归锁（M1）。锁四件事：
-// 1. 默认配置下三个 choro_* 工具根本不注册（模型连名字都看不到，与 memory_organize
-//    同款反向语义）——tools.test.js 的 11 工具清单锁管默认面，这里管开启面；
-// 2. chorographyEnabled 开 + queries 装配 → 三工具在场；
-// 3. 开了开关但 queries 缺装配（null）→ 同样不在场（「开了没装配」与「没开」
-//    对模型都不可见，可区分性由面板路由的 409/503 负责）；
-// 4. execute 的错误形状：多仓歧义带回可选清单、未知 slug 报 page-not-found。
+// #579：从宿主的工具执行入口验证，绕过 schema 校验直调 execute 会漏掉原故障。
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, unlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
+import { Context } from "@deepseek-ai/cordis";
+import SystemPrompt from "@deepseek-ai/dsh-system-prompt";
+import ToolRuntime from "@deepseek-ai/dsh-tools";
 import { createStore } from "../src/store.js";
 import { createService } from "../src/service.js";
 import { createTools } from "../src/tools.js";
 import { createChoroQueries } from "../src/wiki/queries.js";
 import { runChoroT0 } from "../src/wiki/t0.js";
 
-function setup(config = {}, choro) {
+const choroArgs = {
+  choro_module_map: {},
+  choro_read_page: { slug: "src" },
+  choro_search: { query: "b.js" }
+};
+
+async function setup(t, config = {}, withChoro = false) {
   const store = createStore(":memory:");
+  t.after(() => store.close());
+  const ctx = new Context();
+  const prompt = await ctx.plugin(SystemPrompt);
+  const runtime = await ctx.plugin(ToolRuntime);
+  t.after(() => { runtime.dispose(); prompt.dispose(); });
+  const tools = ctx.get("tools");
   const service = createService({ store, mirror: null, config: {} });
-  const registered = [];
-  const ctx = {
-    tools: {
-      register(def) {
-        registered.push(def);
-        return () => {};
-      }
-    }
-  };
-  createTools(ctx, service, config, null, null, choro);
-  return { registered, store };
+  createTools({ tools }, service, config, null, null, withChoro ? createChoroQueries({ store }) : null);
+  const call = (name, args = {}) => tools.execute({
+    name, callId: name, arguments: args, signal: new AbortController().signal
+  });
+  return { tools, store, call };
 }
 
-function makeRepo(store) {
+function makeRepo(t, store, name = "toolfix") {
   const root = mkdtempSync(join(tmpdir(), "choro-tools-"));
-  writeFileSync(join(root, "package.json"), JSON.stringify({ name: "toolfix", scripts: { test: "node --test" } }, null, 2) + "\n", "utf8");
+  t.after(() => rmTempBestEffort(root));
+  writeFileSync(join(root, "package.json"), JSON.stringify({ name, scripts: { test: "node --test" } }, null, 2) + "\n", "utf8");
   mkdirSync(join(root, "src"), { recursive: true });
   writeFileSync(join(root, "src", "a.js"), 'import { b } from "./b.js";\nexport const a = () => b();\n', "utf8");
   writeFileSync(join(root, "src", "b.js"), "export const b = () => 1;\n", "utf8");
@@ -55,67 +59,118 @@ function rmTempBestEffort(dir) {
   }
 }
 
-test("默认配置下三个 choro 工具不注册（模型看不到就不会调）", () => {
-  const { registered } = setup();
-  const names = registered.map((t) => t.name);
-  for (const name of ["choro_module_map", "choro_read_page", "choro_search"]) {
-    assert.ok(!names.includes(name), `${name} 默认缺席`);
+function expectToolError(result, pattern) {
+  const message = result.content[0]?.text ?? "";
+  assert.equal(result.isError, true, message);
+  assert.match(message, pattern);
+}
+
+test("默认配置下三个 choro 工具不注册（模型看不到就不会调）", async (t) => {
+  const { tools } = await setup(t, {}, true);
+  for (const name of Object.keys(choroArgs)) {
+    assert.ok(!tools.get(name), `${name} 默认缺席`);
   }
 });
 
-test("开关关但 queries 缺装配 → 同样缺席（可区分性归路由层）", () => {
-  const { registered } = setup({ chorographyEnabled: true }, null);
-  const names = registered.map((t) => t.name);
-  assert.ok(!names.includes("choro_search"));
+test("开关开但 queries 缺装配 → 同样缺席（可区分性归路由层）", async (t) => {
+  const { tools } = await setup(t, { chorographyEnabled: true });
+  for (const name of Object.keys(choroArgs)) assert.ok(!tools.get(name));
 });
 
-test("开启后三工具在场，execute 走通读侧三件套", async () => {
-  const store = createStore(":memory:");
-  const root = makeRepo(store);
-  try {
-    const choro = createChoroQueries({ store });
-    const { registered } = setup({ chorographyEnabled: true }, choro);
-    const names = registered.map((t) => t.name);
-    for (const name of ["choro_module_map", "choro_read_page", "choro_search"]) {
-      assert.ok(names.includes(name), `${name} 在场`);
-    }
-    const byName = Object.fromEntries(registered.map((t) => [t.name, t]));
-
-    const map = await byName.choro_module_map.execute({});
-    assert.ok(map.modules.length >= 2);
-    assert.equal(map.repo, "toolfix");
-
-    const page = await byName.choro_read_page.execute({ slug: "src" });
-    assert.equal(page.slug, "src");
-    assert.ok(page.content.includes("## 文件清单"));
-
-    const missing = await byName.choro_read_page.execute({ slug: "nope" });
-    assert.equal(missing.error, "page-not-found");
-
-    const hits = await byName.choro_search.execute({ query: "b.js" });
-    assert.ok(hits.hits.length >= 1);
-  } finally {
-    store.close();
-    rmTempBestEffort(root);
+test("开启后三个只读工具的成功结果通过宿主校验", async (t) => {
+  const { call, store } = await setup(t, { chorographyEnabled: true }, true);
+  makeRepo(t, store);
+  const map = await call("choro_module_map");
+  assert.equal(map.isError, false);
+  assert.equal(map.value.repo, "toolfix");
+  assert.ok(map.value.modules.length >= 2);
+  const page = await call("choro_read_page", { slug: "src" });
+  assert.equal(page.isError, false);
+  assert.equal(page.value.slug, "src");
+  assert.match(page.value.content, /## 文件清单/);
+  const search = await call("choro_search", { query: "b.js" });
+  assert.equal(search.isError, false);
+  assert.ok(search.value.hits.length >= 1);
+  assert.equal(search.value.unreadablePages, undefined);
+});
+
+test("未登记或找不到指定仓库时，三个工具都返回可操作的错误", async (t) => {
+  const { call, store } = await setup(t, { chorographyEnabled: true }, true);
+  for (const [name, args] of Object.entries(choroArgs)) {
+    expectToolError(await call(name, args), /No repository is registered.*dsh-mneme-choro/);
+  }
+  makeRepo(t, store);
+  const [{ id }] = createChoroQueries({ store }).listRepos();
+  const unknownId = String(id + 1);
+  for (const [name, args] of Object.entries(choroArgs)) {
+    expectToolError(await call(name, { ...args, repo: unknownId }), /Repository "\d+" is not registered/);
   }
 });
 
-test("多仓歧义：execute 返回可选清单而不是猜一个", async () => {
-  const store = createStore(":memory:");
-  const root1 = makeRepo(store);
-  const root2 = makeRepo(store);
-  try {
-    const choro = createChoroQueries({ store });
-    const { registered } = setup({ chorographyEnabled: true }, choro);
-    const map = registered.find((t) => t.name === "choro_module_map");
-    const result = await map.execute({});
-    assert.equal(result.error, "repo-ambiguous");
-    assert.equal(result.repos.length, 2);
-    const named = await map.execute({ repo: "toolfix" });
-    assert.ok(named.modules, "显式给名后解析成功（fixture 同名仓按 id 序取先者）");
-  } finally {
-    store.close();
-    rmTempBestEffort(root1);
-    rmTempBestEffort(root2);
+test("多仓歧义提示可选 id，按 id 重试可读到对应仓库", async (t) => {
+  const { call, store } = await setup(t, { chorographyEnabled: true }, true);
+  makeRepo(t, store);
+  makeRepo(t, store, "other");
+  const repos = createChoroQueries({ store }).listRepos();
+  for (const [name, args] of Object.entries(choroArgs)) {
+    const result = await call(name, args);
+    expectToolError(result, /More than one repository is registered/);
+    for (const { id, name } of repos) assert.ok(result.content[0].text.includes(`${id} (${name})`));
   }
+  const selected = await call("choro_module_map", { repo: String(repos[1].id) });
+  assert.equal(selected.isError, false);
+  assert.equal(selected.value.repo, "other");
+});
+
+test("读页错误区分未知 slug、缺失文件和不可读文件", async (t) => {
+  const { call, store } = await setup(t, { chorographyEnabled: true }, true);
+  const root = makeRepo(t, store);
+  expectToolError(await call("choro_read_page", { slug: "nope" }), /Page "nope" was not found.*choro_module_map/);
+  const path = join(root, ".chorography", "modules", "src.md");
+  unlinkSync(path);
+  expectToolError(await call("choro_read_page", { slug: "src" }), /Page "src" is missing from disk.*dsh-mneme-choro/);
+  mkdirSync(path);
+  const unreadable = await call("choro_read_page", { slug: "src" });
+  expectToolError(unreadable, /Page "src" could not be read.*permissions/);
+  assert.ok(!unreadable.content[0].text.includes(root), "工具错误不暴露仓库绝对路径");
+});
+
+test("共享库中本机不可达的仓库仍有模块图，读页和检索报告文件访问失败", async (t) => {
+  const { call, store } = await setup(t, { chorographyEnabled: true }, true);
+  const root = makeRepo(t, store);
+  const [{ id }] = createChoroQueries({ store }).listRepos();
+  store.db.prepare("UPDATE choro_repos SET root_path = ? WHERE id = ?")
+    .run(join(root, "unavailable-checkout"), id);
+  const repo = String(id);
+
+  const map = await call("choro_module_map", { repo });
+  assert.equal(map.isError, false);
+  assert.equal(map.value.repo, "toolfix");
+  assert.ok(map.value.modules.some(({ slug }) => slug === "src"));
+  expectToolError(await call("choro_read_page", { repo, slug: "src" }), /missing from disk.*local checkout/);
+  expectToolError(await call("choro_search", { repo, query: "b.js" }), /Search was incomplete.*src.*local checkout/);
+});
+
+test("检索报告不可读的页，保留已读到的命中", async (t) => {
+  const { call, store } = await setup(t, { chorographyEnabled: true }, true);
+  const root = makeRepo(t, store);
+  const rootPage = join(root, ".chorography", "modules", "root.md");
+  unlinkSync(rootPage);
+  const partial = await call("choro_search", { query: "b.js" });
+  assert.equal(partial.isError, false);
+  assert.ok(partial.value.hits.length >= 1);
+  assert.deepEqual(partial.value.unreadablePages, ["root"]);
+  assert.match(partial.content[0].text, /Search was incomplete.*root/);
+
+  const empty = await call("choro_search", { query: "not present", module: "src" });
+  assert.equal(empty.isError, false);
+  assert.deepEqual(empty.value, { hits: [] });
+  assert.equal(empty.content[0].text, "0 hits.");
+
+  const incomplete = await call("choro_search", { query: "not present" });
+  expectToolError(incomplete, /Search was incomplete.*root/);
+  const srcPage = join(root, ".chorography", "modules", "src.md");
+  unlinkSync(srcPage);
+  mkdirSync(srcPage);
+  expectToolError(await call("choro_search", { query: "b.js" }), /Search was incomplete.*root.*src/);
 });