@modusensus/dsh-mneme 0.12.0 → 0.13.0

package/test/vector-index.test.js

@@ -88,7 +88,7 @@ test("deleteEmbedding clears the cached vector; getEmbedding reflects it", () =>
   assert.deepEqual(vectorIndex.getEmbedding(m.id), [0, 0, 1]);
 });
 
-test("rebuildIndex embeds only rows missing an embedding and marks the model", async () => {
+test("rebuildIndex re-embeds rows with no vector and rows with no provenance", async () => {
   const { store, vectorIndex } = setup();
   // One memory already embedded, two missing.
   addMemory(store, { title: "已有向量", content: "A", vector: [0, 1, 0] });
@@ -101,21 +101,60 @@ test("rebuildIndex embeds only rows missing an embedding and marks the model", a
   embedder.embedSingle = async (text) => { seen.push(text); return [1, 0, 0]; };
 
   const result = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
-  assert.equal(result.indexed, 2, "two missing embeddings written");
+  // #604: the selector is model-aware, so the row that already carried a vector
+  // but no fingerprint (embedding_model NULL) is selected too — without this it
+  // stayed permanently unattributed and the boot sweep re-embedded it forever.
+  assert.equal(result.indexed, 3, "all three rows written with provenance");
+  assert.equal(result.failed, 0);
   assert.equal(result.skipped, 0);
+  assert.equal(result.remaining, 0, "nothing left for this model");
   assert.equal(vectorIndex.getStats().embeddedCount, 3, "all rows embedded after rebuild");
-  assert.equal(seen.length, 2, "embedSingle called once per missing row");
+  assert.equal(seen.length, 3, "embedSingle called once per selected row");
+  assert.equal(store.needsEmbeddingFor("mock#rebuild").length, 0, "provenance recorded, nothing stale");
 
-  // Rebuild is a no-op once everything is embedded.
+  // Rebuild is a no-op once everything carries this model's fingerprint.
   const again = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
   assert.equal(again.indexed, 0);
   assert.equal(again.skipped, 0);
+  assert.equal(again.remaining, 0);
 
   // Model fingerprint marked from the rebuild embedder.
   assert.equal(vectorIndex.modelHash(), "mock#rebuild");
   assert.equal(vectorIndex.dimension(), 3);
 });
 
+test("rebuildIndex picks up rows embedded by a previous model (#604)", async () => {
+  const { store, vectorIndex } = setup();
+  // Every row already has a vector — from modelA. needsEmbedding() (the old
+  // selector) matches only empty vectors, so it would select nothing here and
+  // report a successful no-op.
+  const a = addMemory(store, { title: "旧模型1", content: "A" });
+  const b = addMemory(store, { title: "旧模型2", content: "B" });
+  store.setEmbedding(a.id, [0, 1, 0], "modelA#aaa");
+  store.setEmbedding(b.id, [0, 1, 0], "modelA#aaa");
+  assert.equal(store.needsEmbedding().length, 0, "no row is missing a vector");
+  assert.equal(store.needsEmbeddingFor("modelB#bbb").length, 2, "both rows belong to modelA");
+
+  const embedder = rebuildEmbedder({ vector: [1, 0, 0], modelHash: "modelB#bbb", dimension: 3 });
+  const result = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
+
+  assert.equal(result.indexed, 2, "model switch is what reindex is for");
+  assert.equal(result.remaining, 0);
+  assert.equal(store.needsEmbeddingFor("modelB#bbb").length, 0, "provenance now says modelB");
+  assert.equal(store.needsEmbeddingFor("modelA#aaa").length, 2, "modelA's vectors are the stale ones now");
+});
+
+test("rebuildIndex reports remaining work when the limit truncates the batch", async () => {
+  const { store, vectorIndex } = setup();
+  for (let i = 0; i < 5; i++) addMemory(store, { title: `行${i}`, content: `C${i}` });
+
+  const embedder = rebuildEmbedder({ vector: [1, 0, 0], modelHash: "mock#limit", dimension: 3 });
+  const result = await vectorIndex.rebuildIndex(embedder, { limit: 2 });
+
+  assert.equal(result.indexed, 2, "limit bounds the batch");
+  assert.equal(result.remaining, 3, "remaining counts what the same predicate still selects");
+});
+
 test("rebuildIndex handles a throwing embedder without failing the batch", async () => {
   const { store, vectorIndex } = setup();
   addMemory(store, { title: "好行", content: "A" });
@@ -133,7 +172,11 @@ test("rebuildIndex handles a throwing embedder without failing the batch", async
 
   const result = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
   assert.equal(result.indexed, 1, "only the successful row is indexed");
-  assert.equal(result.skipped, 2, "thrown + empty rows count as skipped");
+  // #604: a thrown embed and an empty vector are failures, not "skipped" — the
+  // old single bucket made them indistinguishable from "did not fit the limit".
+  assert.equal(result.failed, 2, "thrown + empty rows count as failures");
+  assert.equal(result.skipped, 0, "nothing was skipped for lack of room");
+  assert.equal(result.remaining, 2, "failed rows stay selected");
   assert.equal(vectorIndex.getStats().embeddedCount, 1);
 });
 
@@ -142,7 +185,11 @@ test("rebuildIndex guard: embedder with no embed method at all is ignored", asyn
   addMemory(store, { title: "缺向量", content: "A" });
   const bare = { modelHash: "mock#bare", dimension: 3 };
   const result = await vectorIndex.rebuildIndex(bare, { limit: 100 });
-  assert.deepEqual(result, { indexed: 0, skipped: 0 }, "guard returns early when neither embed nor embedSingle is available");
+  assert.deepEqual(
+    result,
+    { indexed: 0, failed: 0, skipped: 0, remaining: 0, error: "no-embedder" },
+    "guard returns early when neither embed nor embedSingle is available"
+  );
   assert.equal(vectorIndex.modelHash(), undefined, "no model marked");
 });
 
@@ -219,3 +266,70 @@ test("search returns empty when nothing is embedded", () => {
   addMemory(store, { title: "也无向量", content: "B" });
   assert.deepEqual(vectorIndex.search([1, 0, 0], { limit: 10 }), []);
 });
+
+test("rebuildIndex prefers a detailed adapter so a provider outage is not reported as a dead row (#604)", async () => {
+  const { store, vectorIndex } = setup();
+  addMemory(store, { title: "甲", content: "A" });
+  addMemory(store, { title: "乙", content: "B" });
+
+  let detailedCalls = 0;
+  let plainCalls = 0;
+  const embedder = {
+    // A 503 from the provider: transient, and only the detailed path can say so.
+    embedSingleDetailed: async () => {
+      detailedCalls++;
+      return { vector: null, reason: "http-503" };
+    },
+    embedSingle: async () => {
+      plainCalls++;
+      return null;
+    },
+    modelHash: "mock#detailed",
+    dimension: 3
+  };
+
+  const result = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
+  assert.equal(detailedCalls, 2, "every row went through the detailed entry point");
+  assert.equal(plainCalls, 0, "the reason-dropping path was not used");
+  assert.equal(result.indexed, 0);
+  assert.equal(result.failed, 2);
+  assert.deepEqual(
+    result.failureReasons,
+    { "error:http-503": 2 },
+    "the button path keeps the provider reason instead of flattening it"
+  );
+});
+
+test("rebuildIndex separates a permanent row from a transient one on the same run (#604)", async () => {
+  const { store, vectorIndex } = setup();
+  addMemory(store, { title: "甲", content: "A" });
+  addMemory(store, { title: "乙", content: "B" });
+
+  let calls = 0;
+  const embedder = {
+    embedSingleDetailed: async () => {
+      calls++;
+      // First row cannot ever embed; second row is a provider hiccup.
+      return calls === 1 ? { vector: null, reason: "response-no-vector" } : { vector: null, reason: "http-503" };
+    },
+    modelHash: "mock#mixed",
+    dimension: 3
+  };
+
+  const result = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
+  assert.equal(result.failed, 2);
+  assert.deepEqual(result.failureReasons, {
+    "error:response-no-vector": 1,
+    "error:http-503": 1
+  });
+});
+
+test("rebuildIndex still names the plain path's failure when no detailed adapter exists (#604)", async () => {
+  const { store, vectorIndex } = setup();
+  addMemory(store, { title: "甲", content: "A" });
+
+  const embedder = { embedSingle: async () => null, modelHash: "mock#plain", dimension: 3 };
+  const result = await vectorIndex.rebuildIndex(embedder, { limit: 100 });
+  assert.equal(result.failed, 1);
+  assert.deepEqual(result.failureReasons, { "empty-vector": 1 });
+});

package/test/wiki-api.test.js

@@ -120,6 +120,11 @@ test("快乐路径：repos / modules / page / search 全通", async () => {
     assert.equal(modules.status, 200);
     assert.ok(modules.body.modules.length >= 2);
     assert.ok(Array.isArray(modules.body.edges));
+    // 面板的地志页导入要把「根路径 + 页相对路径」拼成磁盘绝对路径（契约 §3.6），
+    // 回执里缺 relPath 时它会静默回落到「请先选模块」——这条锁的就是那个真机 bug。
+    const withPage = modules.body.modules.filter((m) => m.page_rel_path);
+    assert.ok(withPage.length >= 1, "fixture 里至少一个模块有骨架页");
+    for (const m of withPage) assert.equal(m.relPath, m.page_rel_path);
 
     const page = await invoke(handler(routes, "/api/dsh-mneme/choro/page"), `/api/dsh-mneme/choro/page?repo=${repoId}&slug=src`);
     assert.equal(page.status, 200);
@@ -271,3 +276,353 @@ test("/choro/search：embedder 在场 → 惰性物化 + semantic 数组；缺
     rmTempBestEffort(root);
   }
 });
+
+// ---------------------------------------------------------------------------
+// 契约 §3.2（kb-qoder parity）：面板闭环要的新字段与新入口
+// ---------------------------------------------------------------------------
+
+test("/choro/repos：契约字段齐备，git 漂移 → stale/git，plan 漂移 → stale/plan", async () => {
+  const store = createStore(":memory:");
+  const root = makeRepo(store);
+  try {
+    const { routes } = setup({ config: { chorographyEnabled: true }, choro: createChoroQueries({ store }) });
+    const url = "/api/dsh-mneme/choro/repos";
+
+    // 刚重建完：不该有任何过期信号——否则面板会对着一个刚生成的地志喊「代码已变」，
+    // 用户第一次用就学会不信任那个标记。
+    const fresh = await invoke(handler(routes, url), url);
+    assert.equal(fresh.status, 200);
+    const a = fresh.body.repos[0];
+    for (const key of ["id", "name", "rootPath", "modules", "pages", "claims", "legacy", "stale", "staleReason", "lastRunAt"]) {
+      assert.ok(key in a, `契约字段 ${key} 必须在场（面板按它渲染）`);
+    }
+    assert.equal(a.stale, false);
+    assert.equal(a.staleReason, null);
+    assert.equal(a.legacy, false);
+    assert.equal(typeof a.lastRunAt, "string");
+    assert.ok(a.modules >= 2 && a.pages >= 2, "modules/pages 是契约字段名（不是行里的 module_count）");
+
+    // 代码变了（新 commit）→ 说过期，理由必须是 git：面板那句话是「代码已变」。
+    writeFileSync(join(root, "src", "c.js"), "export const c = () => 2;\n", "utf8");
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "add", "-A"], { cwd: root, stdio: "pipe" });
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", "drift", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+    const drifted = await invoke(handler(routes, url), url);
+    assert.equal(drifted.body.repos[0].stale, true);
+    assert.equal(drifted.body.repos[0].staleReason, "git");
+
+    // 先重建一次把 git 基线推平（否则 git 那一路永远优先，plan 判据根本轮不到），
+    // 再只改 plan.yaml（HEAD 不动）→ 理由必须是 plan：这条判据不依赖 git，不能被
+    // git 那一路掩盖掉，否则「改了模板配置但没提交」的仓库永远显示干净。
+    runChoroT0({ repoRoot: root, store, apply: true });
+    const cleaned = await invoke(handler(routes, url), url);
+    assert.equal(cleaned.body.repos[0].stale, false, "重建后 git 基线推平，过期信号应清掉");
+    writeFileSync(join(root, ".chorography", "plan.yaml"), "pages: []\n", "utf8");
+    const planDrift = await invoke(handler(routes, url), url);
+    assert.equal(planDrift.body.repos[0].stale, true);
+    assert.equal(planDrift.body.repos[0].staleReason, "plan");
+  } finally {
+    rmTempBestEffort(root);
+  }
+});
+
+test("/choro/run：空态按绝对路径登记新仓库，重复路径复用同一 id", async () => {
+  const store = createStore(":memory:");
+  // 只把仓库目录准备好但不登记：这就是面板「一个仓库都没登记」的真实起点。
+  const root = mkdtempSync(join(tmpdir(), "choro-empty-"));
+  writeFileSync(join(root, "package.json"), JSON.stringify({ name: "emptyfix" }, null, 2) + "\n", "utf8");
+  mkdirSync(join(root, "src"), { recursive: true });
+  writeFileSync(join(root, "src", "a.js"), "export const a = 1;\n", "utf8");
+  execFileSync("git", ["init", "-b", "main"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "add", "-A"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", "init", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+  try {
+    const { routes } = setup({
+      config: { chorographyEnabled: true },
+      choro: { ...createChoroQueries({ store }), runT0Apply: ({ repoRoot }) => runChoroT0({ repoRoot, store, apply: true }) }
+    });
+    const route = handler(routes, "/api/dsh-mneme/choro/run");
+    const reposUrl = "/api/dsh-mneme/choro/repos";
+    const before = await invoke(handler(routes, reposUrl), reposUrl);
+    assert.equal(before.body.repos.length, 0, "起点确实是一个仓库都没登记");
+
+    const first = await invokePost(route, "/api/dsh-mneme/choro/run", { path: root });
+    assert.equal(first.status, 200);
+    assert.equal(first.body.ok, true);
+    assert.ok(first.body.receipt.moduleCount >= 1, "走的是真 T0（有划分回执）");
+    const after = await invoke(handler(routes, reposUrl), reposUrl);
+    assert.equal(after.body.repos.length, 1, "空态 + 路径 → 自动登记");
+
+    // 第二次同一路径：不能变成两条记录，也不能报错——面板按钮会被连点。
+    const again = await invokePost(route, "/api/dsh-mneme/choro/run", { rootPath: root, refresh: true });
+    assert.equal(again.status, 200);
+    assert.equal(again.body.refresh, true, "refresh 原样回显，面板据此区分「我要求过重跑」");
+    assert.equal((await invoke(handler(routes, reposUrl), reposUrl)).body.repos.length, 1, "同一路径复用既有 id");
+  } finally {
+    rmTempBestEffort(root);
+  }
+});
+
+test("/choro/run：路径给错时结构化报错，不落 500 一锅烩", async () => {
+  const store = createStore(":memory:");
+  const notGit = mkdtempSync(join(tmpdir(), "choro-notgit-"));
+  try {
+    const { routes } = setup({
+      config: { chorographyEnabled: true },
+      choro: { ...createChoroQueries({ store }), runT0Apply: ({ repoRoot }) => runChoroT0({ repoRoot, store, apply: true }) }
+    });
+    const route = handler(routes, "/api/dsh-mneme/choro/run");
+
+    const rel = await invokePost(route, "/api/dsh-mneme/choro/run", { path: "some/rel/dir" });
+    assert.equal(rel.status, 400);
+    assert.equal(rel.body.error, "path-not-absolute", "相对路径的语义取决于宿主 cwd，必须挡");
+
+    const missing = await invokePost(route, "/api/dsh-mneme/choro/run", { path: join(notGit, "nope") });
+    assert.equal(missing.status, 400);
+    assert.equal(missing.body.error, "path-not-found");
+
+    const plain = await invokePost(route, "/api/dsh-mneme/choro/run", { path: notGit });
+    assert.equal(plain.status, 409);
+    assert.equal(plain.body.error, "not-a-git-repo", "目录在但不是 git 仓库 → 409，不是 500");
+  } finally {
+    rmTempBestEffort(notGit);
+  }
+});
+
+// T1 会真花钱（模型调用），所以这里注入假的 startT1Job / t1JobStatus：
+// 路由层要锁的只是闸门与 200/409/404 的分叉形状，不是进程本身。
+function withT1({ startT1Job, t1JobStatus } = {}) {
+  const store = createStore(":memory:");
+  const root = makeRepo(store);
+  const choro = { ...createChoroQueries({ store }) };
+  if (startT1Job) choro.startT1Job = startT1Job;
+  if (t1JobStatus) choro.t1JobStatus = t1JobStatus;
+  return { store, root, choro };
+}
+
+test("/choro/t1：缺装配 503 / 面板闸关 409 / 同仓并发 409 job-running / 缺省 404", async () => {
+  const a = withT1({});
+  try {
+    const noJobs = setup({ config: { chorographyEnabled: true, chorographyT1FromPanel: true }, choro: a.choro });
+    const missing = await invokePost(handler(noJobs.routes, "/api/dsh-mneme/choro/t1"), "/api/dsh-mneme/choro/t1", { repo: 1 });
+    assert.equal(missing.status, 503, "没装配任务账 → 503 环境缺件");
+    assert.equal(missing.body.error, "unavailable");
+  } finally {
+    rmTempBestEffort(a.root);
+  }
+
+  const b = withT1({ startT1Job: () => ({ started: true, jobId: "j-1" }) });
+  try {
+    const off = setup({
+      config: { chorographyEnabled: true, chorographyT1FromPanel: false },
+      choro: b.choro
+    });
+    const disabled = await invokePost(handler(off.routes, "/api/dsh-mneme/choro/t1"), "/api/dsh-mneme/choro/t1", { repo: 1 });
+    assert.equal(disabled.status, 409, "T1 花模型额度，面板闸关着就不许起");
+    assert.equal(disabled.body.error, "disabled");
+
+    const on = setup({ config: { chorographyEnabled: true, chorographyT1FromPanel: true }, choro: b.choro });
+    const t1Route = handler(on.routes, "/api/dsh-mneme/choro/t1");
+    assert.equal(t1Route.policy, "token-write", "起一个会写页面/claims 的后台任务属数据面写");
+
+    const ok = await invokePost(t1Route, "/api/dsh-mneme/choro/t1", { repo: 1, module: "src", retryFailed: true });
+    assert.equal(ok.status, 200);
+    assert.deepEqual(ok.body, { jobId: "j-1", started: true });
+
+    const unknown = await invokePost(t1Route, "/api/dsh-mneme/choro/t1", { repo: 99 });
+    assert.equal(unknown.status, 404);
+
+    const busy = withT1({ startT1Job: () => ({ started: false, code: "job-running", jobId: "j-2" }) });
+    try {
+      const busySetup = setup({ config: { chorographyEnabled: true, chorographyT1FromPanel: true }, choro: busy.choro });
+      const running = await invokePost(handler(busySetup.routes, "/api/dsh-mneme/choro/t1"), "/api/dsh-mneme/choro/t1", { repo: 1 });
+      assert.equal(running.status, 409);
+      assert.equal(running.body.error, "job-running");
+      assert.equal(running.body.jobId, "j-2", "把在跑的那个 jobId 带回给面板，好让它接着轮询而不是重起");
+    } finally {
+      rmTempBestEffort(busy.root);
+    }
+  } finally {
+    rmTempBestEffort(b.root);
+  }
+});
+
+test("/choro/t1/status：jobId 缺 400、未知 404、已知 200 带契约字段", async () => {
+  const job = {
+    jobId: "j-9",
+    repo: { id: 1, name: "x", rootPath: "/x" },
+    state: "running",
+    startedAt: "T0",
+    modules: { total: 2, done: 1, failed: 0 },
+    logTail: ["line"]
+  };
+  const f = withT1({ startT1Job: () => ({ started: true, jobId: "j-9" }), t1JobStatus: (id) => (id === "j-9" ? job : null) });
+  try {
+    const { routes } = setup({ config: { chorographyEnabled: true }, choro: f.choro });
+    const route = handler(routes, "/api/dsh-mneme/choro/t1/status");
+
+    const noId = await invoke(route, "/api/dsh-mneme/choro/t1/status");
+    assert.equal(noId.status, 400);
+    assert.equal(noId.body.error, "jobId-required");
+
+    const gone = await invoke(route, "/api/dsh-mneme/choro/t1/status?jobId=nope");
+    assert.equal(gone.status, 404, "宿主重启后旧 jobId 必然查不到，面板据此回到「没有在跑的任务」");
+
+    const found = await invoke(route, "/api/dsh-mneme/choro/t1/status?jobId=j-9");
+    assert.equal(found.status, 200);
+    assert.equal(found.body.state, "running");
+    assert.equal(found.body.modules.total, 2);
+    assert.deepEqual(found.body.logTail, ["line"]);
+  } finally {
+    rmTempBestEffort(f.root);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// chorographyAutoRefresh：读侧自动重跑 T0（面板文案已经把它当契约写死了：
+// 「读地志页时如果发现仓库代码变了，自动重跑一次 T0 骨架」）。
+// 这一批同时锁「开关关着绝不偷偷改用户工作区」与「开关开着真的会刷」——只锁一端
+// 的测试在实现成「永远不刷」或「永远刷」时都会绿，等于没锁。
+// ---------------------------------------------------------------------------
+
+// 计数外壳：真实 queries + 包一层的 runT0Apply（记调用次数、可注入失败）。
+// 不造一个假 T0——「刷了但基线没推进」这种 bug 只有真 T0 才照得出来。
+function countingChoro(store, { throwOnRun = false } = {}) {
+  const calls = [];
+  const base = createChoroQueries({ store });
+  return {
+    calls,
+    choro: {
+      ...base,
+      runT0Apply: ({ repoRoot }) => {
+        calls.push(repoRoot);
+        if (throwOnRun) throw new Error("磁盘只读（模拟）");
+        return runChoroT0({ repoRoot, store, apply: true });
+      }
+    }
+  };
+}
+
+// 造一个「代码已变」的仓库：登记时的 git_baseline 与当前 HEAD 不同。
+function driftRepo(store) {
+  const root = makeRepo(store);
+  writeFileSync(join(root, "src", "c.js"), "export const c = () => 2;\n", "utf8");
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "add", "-A"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", "drift", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+  return root;
+}
+
+test("/choro/repos 自动重跑：开关关着时即使过期也一次都不刷（默认行为逐字节不变）", async () => {
+  const store = createStore(":memory:");
+  const root = driftRepo(store);
+  try {
+    const { calls, choro } = countingChoro(store);
+    const { routes } = setup({ config: { chorographyEnabled: true }, choro });
+    const url = "/api/dsh-mneme/choro/repos?repo=1";
+    const REPOS_PATH = "/api/dsh-mneme/choro/repos";
+    const res = await invoke(handler(routes, REPOS_PATH), url);
+    assert.equal(res.status, 200);
+    assert.equal(res.body.repos[0].staleReason, "git", "前提：这个仓库确实是过期的");
+    assert.equal(calls.length, 0, "开关缺省 false 时读侧一个字节都不许动用户的工作区");
+    assert.equal(res.body.autoRefreshed, false);
+  } finally {
+    rmTempBestEffort(root);
+  }
+});
+
+test("/choro/repos 自动重跑：开关开 + ?repo= 点名且 git 过期 → 刷一次，回执按新基线说话", async () => {
+  const store = createStore(":memory:");
+  const root = driftRepo(store);
+  try {
+    const { calls, choro } = countingChoro(store);
+    const { routes } = setup({ config: { chorographyEnabled: true, chorographyAutoRefresh: true }, choro });
+    const url = "/api/dsh-mneme/choro/repos?repo=1";
+    const REPOS_PATH = "/api/dsh-mneme/choro/repos";
+    const res = await invoke(handler(routes, REPOS_PATH), url);
+    assert.equal(res.status, 200);
+    assert.equal(calls.length, 1, "开关开 + 指名 + git 过期 = 恰好刷这一个仓库");
+    assert.equal(res.body.autoRefreshed, true);
+    // 刷完必须改成不 stale：否则面板刚刷完就显示「代码已变」，等于谎报一次失败。
+    assert.equal(res.body.repos[0].stale, false);
+    assert.equal(res.body.repos[0].staleReason, null);
+  } finally {
+    rmTempBestEffort(root);
+  }
+});
+
+test("/choro/repos 自动重跑：不 stale 或没点名 ?repo= 时都不刷（一次面板加载不能扫全库）", async () => {
+  const store = createStore(":memory:");
+  const cleanRoot = makeRepo(store);
+  try {
+    const { calls, choro } = countingChoro(store);
+    const { routes } = setup({ config: { chorographyEnabled: true, chorographyAutoRefresh: true }, choro });
+    const plain = "/api/dsh-mneme/choro/repos";
+    const clean = await invoke(handler(routes, plain), plain);
+    assert.equal(clean.status, 200);
+    assert.equal(calls.length, 0, "staleReason 为 null → 没有刷的理由");
+
+    // 造第二个过期仓库，但请求不带 ?repo=：列表路径一个都不许刷。
+    const drifted = driftRepo(store);
+    try {
+      const listed = await invoke(handler(routes, plain), plain);
+      assert.equal(listed.body.repos.length, 2);
+      assert.equal(calls.length, 0, "没点名就不刷：否则打开面板要付 N 次全仓扫描");
+      assert.equal(listed.body.autoRefreshed, false);
+      assert.ok(listed.body.repos.some((r) => r.staleReason === "git"), "过期信号照常回，只是不顺手刷");
+    } finally {
+      rmTempBestEffort(drifted);
+    }
+  } finally {
+    rmTempBestEffort(cleanRoot);
+  }
+});
+
+test("/choro/repos 自动重跑失败：读照常 200、数据在、错误进 autoRefreshError", async () => {
+  const store = createStore(":memory:");
+  const root = driftRepo(store);
+  try {
+    const { calls, choro } = countingChoro(store, { throwOnRun: true });
+    const { routes } = setup({ config: { chorographyEnabled: true, chorographyAutoRefresh: true }, choro });
+    const url = "/api/dsh-mneme/choro/repos?repo=1";
+    const REPOS_PATH = "/api/dsh-mneme/choro/repos";
+    const res = await invoke(handler(routes, REPOS_PATH), url);
+    // 读是主诉求、刷新是附赠：打成 500 等于「顺手的事没办成，正事也不给办」。
+    assert.equal(res.status, 200, "刷新失败不许把读请求打成 500");
+    assert.equal(calls.length, 1);
+    assert.equal(res.body.autoRefreshed, false);
+    assert.match(res.body.autoRefreshError, /磁盘只读/);
+    assert.equal(res.body.repos.length, 1, "数据必须还在");
+    assert.equal(res.body.repos[0].staleReason, "git", "没刷成功就照实说过期");
+  } finally {
+    rmTempBestEffort(root);
+  }
+});
+
+// /choro/page 是面板主路径，也是「读地志页时发现代码变了」那句文案的真正时刻。
+// 顶栏「代码已变」徽章读 state.repo.stale —— 回执里没有 repo 这份数据，徽章永远不亮。
+test("/choro/page 回执带 repo.stale/staleReason，并在这条读路径上自动重跑", async () => {
+  const store = createStore(":memory:");
+  const root = driftRepo(store);
+  try {
+    const { calls, choro } = countingChoro(store);
+    const url = "/api/dsh-mneme/choro/page?repo=1&slug=src";
+    const PAGE_PATH = "/api/dsh-mneme/choro/page";
+
+    const offSetup = setup({ config: { chorographyEnabled: true }, choro });
+    const off = await invoke(handler(offSetup.routes, PAGE_PATH), url);
+    assert.equal(off.status, 200);
+    assert.equal(off.body.repo.stale, true, "徽章的数据源：开关关着也要照实报过期");
+    assert.equal(off.body.repo.staleReason, "git");
+    assert.equal(off.body.autoRefreshed, false);
+    assert.equal(calls.length, 0);
+
+    const onSetup = setup({ config: { chorographyEnabled: true, chorographyAutoRefresh: true }, choro });
+    const on = await invoke(handler(onSetup.routes, PAGE_PATH), url);
+    assert.equal(on.status, 200);
+    assert.equal(calls.length, 1, "页读路径点名的就是这一个仓库");
+    assert.equal(on.body.autoRefreshed, true);
+    assert.equal(on.body.repo.stale, false, "刷完页面与 repo 徽章必须同一时刻一致");
+    assert.ok(on.body.page.content.includes("## 文件清单"), "页正文照常回");
+  } finally {
+    rmTempBestEffort(root);
+  }
+});

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 的验收标准就是「用户照着这条命令能跑起来」，
+  // 字符串层面的断言证明不了这件事。