@modusensus/dsh-mneme 0.13.0 → 0.14.0-beta.1

package/test/wiki-queries.test.js

@@ -275,3 +275,124 @@ test("outline：模块名 + 文件数 + 页状态 + 页相对路径，不读正
     rmTempBestEffort(root);
   }
 });
+// --- claim 粒度失效（Grounded Claims）:DB 索引 × git diff 的对账 --------------
+
+test("claimDrift：基线 == HEAD 说 clean:true，改了锚点所在行 → 只有那页那条进 atRisk", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    const page = store.choroPageBySlug(repo.id, "src");
+    store.saveChoroPageClaims(page.id, [
+      { statement: "a 依赖 b", kind: "architecture", sourcePath: "src/a.js", startLine: 3, endLine: 3, createdAt: FIXED_NOW() },
+      { statement: "b2 只是常量", kind: "architecture", sourcePath: "src/b2.js", startLine: 1, endLine: 1, createdAt: FIXED_NOW() },
+    ]);
+
+    const same = q.claimDrift(repo.id);
+    assert.equal(same.clean, true, "基线就是 HEAD：确实没变，可以说没事");
+    assert.equal(same.anchorStale, false);
+    assert.equal(same.totals.claims, 2);
+    assert.equal(same.totals.atRiskClaims, 0);
+
+    // 改掉 a.js 第 3 行（claim 的锚点）并提交 → 基线落后 HEAD。
+    writeFileSync(join(root, "src", "a.js"), 'import { b } from "./b.js";\nimport h from "left-pad";\nexport const a = () => b() + 1;\n', "utf8");
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-am", "change a", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+
+    const drift = q.claimDrift(repo.id);
+    assert.equal(drift.clean, false);
+    assert.notEqual(drift.baseline, drift.head, "基线落后了");
+    assert.equal(drift.totals.claims, 2);
+    assert.equal(drift.totals.atRiskClaims, 1, "只有锚在 a.js 第 3 行那条受影响");
+    const pageRisk = drift.pages.find((p) => p.slug === "src");
+    assert.equal(pageRisk.atRisk.length, 1);
+    assert.equal(pageRisk.atRisk[0].reason, "touched");
+    assert.equal(pageRisk.atRisk[0].sourcePath, "src/a.js");
+    // 排序契约：有风险的页排最前（面板直接顺着读，不再排一遍）。
+    assert.equal(drift.pages[0].slug, "src");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：基线认不出时说 anchorStale，不说「都还准」也不说「全失效」", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    // force-push / 浅克隆的形态：基线 sha 合法但对象不在库里的任何一棵树上。
+    store.db.prepare("UPDATE choro_repos SET git_baseline = ? WHERE id = ?").run("0123456789abcdef0123456789abcdef01234567", repo.id);
+    const drift = q.claimDrift(repo.id);
+    assert.equal(drift.clean, false);
+    assert.equal(drift.anchorStale, true);
+    assert.equal(drift.reason, "diff-failed");
+    assert.equal(drift.totals.atRiskClaims, 0, "算不出来不等于有风险——一条都不许判");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：验证过却没记下基线（verified_at 有、verified_baseline 空）→ 判不了，不回退全仓基线", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    const page = store.choroPageBySlug(repo.id, "src");
+    store.saveChoroPageClaims(page.id, [
+      { statement: "a 依赖 b", kind: "architecture", sourcePath: "src/a.js", startLine: 3, endLine: 3, createdAt: FIXED_NOW() },
+    ]);
+    // 后半段的验证没留下凭据：T1 写了 verified_at，却没写 verified_baseline。
+    store.db.prepare("UPDATE choro_pages SET verified_at = ?, verified_baseline = NULL WHERE id = ?").run(FIXED_NOW(), page.id);
+
+    const drift = q.claimDrift(repo.id);
+    const p = drift.pages.find((x) => x.slug === "src");
+    // 退到全仓基线会把「富化之后才发生」的改动当成「富化之前就有」而放过——漏报。
+    // 不知道起点就不装作知道：diffBaseline 必须为 null，且这一页判 baselineUnknown。
+    assert.equal(p.diffBaseline, null, "没有验证点就不许回退全仓基线");
+    assert.equal(p.baselineApprox, false, "这不是「老数据退而求其次」，别标成约等于");
+    assert.equal(p.baselineUnknown, true);
+    assert.equal(drift.totals.baselineUnknownPages, 1);
+    // 基线 == HEAD 时 clean 仍可为真：一条提交都没发生过，锚点不可能被碰到，
+    // 「验证点没记下」在这里不影响结论（影响的是「变了之后能不能判」）。
+    assert.equal(drift.clean, true, "没变就是没变，不必因为起点没记下而说不知道");
+
+    // 有提交之后就不一样了：起点认不出的页不许被那些提交的改动「顺带放过」。
+    writeFileSync(join(root, "src", "a.js"), 'import { b } from "./b.js";\nexport const a = () => b() + 1;\n', "utf8");
+    execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-am", "change a", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+    const after = q.claimDrift(repo.id);
+    assert.equal(after.clean, false, "有判不了的页，就不能说干净");
+    assert.equal(after.totals.baselineUnknownPages, 1);
+    assert.equal(after.totals.atRiskClaims, 0, "判不了不等于有风险，一条都不许判");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：repoAtHead 也不能掩盖 inconsistentPages（有语义段却没 claims 的页）", () => {
+  const { root, store, q } = setup();
+  try {
+    const repo = q.resolveRepo(undefined);
+    // 造一次「T1 落盘不完整」：页里有语义段，库里一条 claims 都没有。
+    // 仓库基线仍等于 HEAD，旧实现在这里会短路成 clean:true——把残局说成没事。
+    const pagePath = join(root, ".chorography", "modules", "src.md");
+    writeFileSync(pagePath, readFileSync(pagePath, "utf8") + "\n<!-- CHORO:T1:START -->\n## 架构\n\na.js 是入口。\n<!-- CHORO:T1:END -->\n", "utf8");
+
+    const drift = q.claimDrift(repo.id);
+    assert.equal(drift.baseline, drift.head, "前提：仓库基线就是 HEAD（走短路分支）");
+    assert.equal(drift.totals.inconsistentPages, 1, "有语义段、零 claims 的页要被数出来");
+    assert.equal(drift.totals.atRiskClaims, 0, "它一条结论都没有，谈不上有风险");
+    assert.equal(drift.clean, false, "残局不许被说成「全部干净」");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+test("claimDrift：未知仓库返回 null（调用方据此 404，不是空清单）", () => {
+  const { root, store, q } = setup();
+  try {
+    assert.equal(q.claimDrift(999999), null);
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});

package/test/wiki-t0.test.js

@@ -257,12 +257,86 @@ test("重跑 T0 覆盖已富化的页：必须先出声（t1Loss 清点 + warnin
   }
 });
 
+// 读不出来 ≠ 没有：清点靠读盘，读失败就先不知道那页有没有语义段。旧实现在 catch 里
+// 直接当「没有」，guard 于是放行，replaceChoroGraph 把读不到的页连同它可能有的语义段
+// 一起退回骨架、claims 清空——一次权限错误就能静默抹掉一整页富化成果。
+// 这条锁的是：读失败必须进 unreadable、必须拒绝刷新、必须在 receipt 里说出来。
+test("collectT1Loss 读页失败：进 unreadable，guard 拒绝刷新，绝不静默放行", () => {
+  const root = makeFixture();
+  const store = createStore(":memory:");
+  try {
+    runChoroT0({ repoRoot: root, store, apply: true, now: FIXED_NOW });
+    const pagePath = join(root, ".chorography", "modules", "src.md");
+    writeFileSync(pagePath,
+      `${readFileSync(pagePath, "utf8")}\n${T1_SECTION_START}\n## 架构\n\na.js 是入口。\n${T1_SECTION_END}\n`,
+      "utf8");
+    // 用「同名目录顶掉文件」制造真实的读失败：existsSync 为真（目录存在），
+    // readFileSync 抛 EISDIR。比 chmod 稳（Windows 上 chmod 不生效），也不依赖权限。
+    rmSync(pagePath, { force: true });
+    mkdirSync(pagePath, { recursive: true });
+
+    const dry = runChoroT0({ repoRoot: root, store, now: FIXED_NOW });
+    assert.ok(Array.isArray(dry.t1Loss.unreadable) && dry.t1Loss.unreadable.length > 0,
+      "读不出来的页必须被点名，不能当成「没有 T1 段」");
+    assert.equal(dry.t1Loss.unreadable[0].reason, "EISDIR", "记下读失败的原因，便于归因");
+    assert.ok(dry.warnings.some((w) => w.includes("读不出来")), "dry-run 也要如实说一声");
+
+    assert.throws(
+      () => runChoroT0({ repoRoot: root, store, apply: true, guardT1Loss: true, now: () => "2026-11-09T00:00:00.000Z" }),
+      (err) => err instanceof ChoroRefusal && err.code === "would-drop-t1" && /读不出来/.test(err.message),
+      "读不出内容时无法证明它没有语义段 → 拒绝刷新，而不是赌一把"
+    );
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
+// guardT1Loss（自动刷新专用）：读侧「顺手」重跑 T0 会在用户只点开一页的时候
+// 替他丢掉语义段与 claims——那是破坏性写盘，不是刷新。这条锁三件事：
+// ① 有 T1 段时 apply 整轮拒绝（would-drop-t1），一个字节都不写、claims 一条不少；
+// ② 拒绝发生在写盘之前，页里 T1 段还在（拒绝不能只拒一半）；
+// ③ 不传 guardT1Loss 的老路径行为不变（手动重建就是用户明确要的那次写）。
+test("guardT1Loss：自动刷新遇到已富化的页就整轮拒绝，不写字节也不清 claims", () => {
+  const root = makeFixture();
+  const store = createStore(":memory:");
+  try {
+    runChoroT0({ repoRoot: root, store, apply: true, now: FIXED_NOW });
+    const pagePath = join(root, ".chorography", "modules", "src.md");
+    writeFileSync(pagePath,
+      `${readFileSync(pagePath, "utf8")}\n${T1_SECTION_START}\n## 架构\n\na.js 是入口。\n${T1_SECTION_END}\n`,
+      "utf8");
+    // 库里也造一条 claim：拒绝必须让它原样躺着。
+    const repoRow = store.choroRepoByRoot(root);
+    const pageRow = store.choroPageBySlug(repoRow.id, "src");
+    store.saveChoroPageClaims(pageRow.id, [{ statement: "a.js 是入口", kind: "architecture", sourcePath: "src/a.js", startLine: 1, endLine: 4, createdAt: FIXED_NOW() }]);
+    const beforeBytes = readFileSync(pagePath, "utf8");
+
+    assert.throws(
+      () => runChoroT0({ repoRoot: root, store, apply: true, guardT1Loss: true, now: () => "2026-11-09T00:00:00.000Z" }),
+      (err) => err instanceof ChoroRefusal && err.code === "would-drop-t1" && /src/.test(err.message),
+      "有富化页时拒绝，且点名是哪一页"
+    );
+    assert.equal(readFileSync(pagePath, "utf8"), beforeBytes, "拒绝发生在写盘之前：页一字节未动");
+    assert.equal(store.db.prepare("SELECT COUNT(*) AS c FROM choro_claims").get().c, 1, "claims 一条不少");
+    assert.notEqual(store.choroPageBySlug(repoRow.id, "src").status, "enriched", "拒绝时不该顺手把页标成富化");
+
+    // 老路径（手动重建）行为不变：它照样退回骨架，只是回执里会说一声。
+    const manual = runChoroT0({ repoRoot: root, store, apply: true, now: () => "2026-11-10T00:00:00.000Z" });
+    assert.deepEqual(manual.t1Loss.pages, [".chorography/modules/src.md"], "手动路径仍按设计丢弃并清点");
+  } finally {
+    store.close();
+    rmTempBestEffort(root);
+  }
+});
+
 // CLI 的 --timeout 是「秒」，一路乘 1000 变成 spawn 的 timeoutMs。NaN 混进去不会
 // 报错，只会让墙钟上限静默失效——用户以为设了 60 秒，实际跑到 4 分钟默认值。
 test("CLI 解析：--t1 相关旗标取到值，--timeout 只收正数秒", () => {
   const { flags } = parseArgv([
     "D:/repo", "--t1", "--apply", "--module", "src", "--model", "xdpool/m",
-    "--timeout", "60", "--retry-failed", "--dsh-exe", "D:/Harness.exe", "--json",
+    "--timeout", "60", "--retry-failed", "--dsh-exe", "D:/Harness.exe",
+    "--dsh-cli", "D:/cli.js", "--json",
   ]);
   assert.equal(flags.t1, true);
   assert.equal(flags.apply, true);
@@ -271,6 +345,8 @@ test("CLI 解析：--t1 相关旗标取到值，--timeout 只收正数秒", () =
   assert.equal(flags.timeout, 60, "解析出来就是数字，接线处不再二次转换");
   assert.equal(flags.retryFailed, true);
   assert.equal(flags["dsh-exe"], "D:/Harness.exe");
+  // --dsh-cli 是 issue #578 的人工出口（探测不进 asar 时的唯一办法），必须能取到值
+  assert.equal(flags["dsh-cli"], "D:/cli.js");
   assert.throws(() => parseArgv(["--t1", "--timeout", "abc"]), /正数秒/);
   assert.throws(() => parseArgv(["--t1", "--timeout", "0"]), /正数秒/);
   assert.throws(() => parseArgv(["--t1", "--timeout"]), /需要一个秒数/);

package/test/wiki-t1.test.js

@@ -10,9 +10,10 @@ import { mkdtempSync, rmSync, writeFileSync, mkdirSync, readFileSync, existsSync
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
+import { EventEmitter } from "node:events";
 import { runChoroT0 } from "../src/wiki/t0.js";
 import { createStore } from "../src/store.js";
-import { createT1, T1Refusal, T1_SECTION_START, T1_SECTION_END } from "../src/wiki/t1.js";
+import { createT1, T1Refusal, T1_SECTION_START, T1_SECTION_END, makeHeadlessRunner, locateDshExe, resolveCliJs } from "../src/wiki/t1.js";
 
 const FIXED_NOW = () => "2026-11-05T12:00:00.000Z";
 
@@ -233,3 +234,227 @@ test("未登记仓库整轮拒绝（先跑 T0）", async () => {
     rmTempBestEffort(root);
   }
 });
+
+/* ------------------------- 定位层（issue #578） ------------------------- */
+//
+// 这一组锁的是「按安装布局写死路径」那类回归：exe 名、cli.js 位置、失败诊断三件事
+// 以前都只有一种答案，换一种安装布局（DSH NEXT）整档 T1 就起不来，而报错是
+// 「(无输出)」。全部用临时目录造假结构，不碰真 asar、不真开进程。
+
+/** 造一棵假的安装树：<root>/<exeName> + <root>/resources/app.asar/<rel> */
+function fakeInstall(exeName, cliRels) {
+  const root = mkdtempSync(join(tmpdir(), "choro-install-"));
+  const exe = join(root, exeName);
+  writeFileSync(exe, "", "utf8");
+  for (const rel of cliRels) {
+    const abs = join(root, "resources", "app.asar", ...rel.split("/"));
+    mkdirSync(join(abs, ".."), { recursive: true });
+    writeFileSync(abs, "// cli\n", "utf8");
+  }
+  return { root, exe };
+}
+
+test("resolveCliJs：DSH NEXT 布局优先于旧布局，且 DSH_CLI_JS 压过一切", () => {
+  // 两种布局同时在（老机器升级后可能留下旧目录），新布局必须赢——否则又一次
+  // 「升级了但还是按旧位置找」。
+  const both = fakeInstall("DSH NEXT.exe", [
+    "lib/desktop-cli.js",
+    "dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/cli.js",
+  ]);
+  try {
+    const picked = resolveCliJs(both.exe, {});
+    assert.equal(picked.verified, true);
+    assert.equal(picked.path, join(both.root, "resources", "app.asar", "lib", "desktop-cli.js"));
+  } finally {
+    rmTempBestEffort(both.root);
+  }
+
+  // 只有旧布局：仍要认（不能为了修新布局把老安装打坏）。
+  const legacy = fakeInstall("DeepSeek Harness.exe", ["dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/cli.js"]);
+  try {
+    const picked = resolveCliJs(legacy.exe, {});
+    assert.equal(picked.verified, true);
+    assert.ok(picked.path.includes("dsh-desktop-host"));
+  } finally {
+    rmTempBestEffort(legacy.root);
+  }
+
+  // DSH_CLI_JS：探测不进 asar 的进程（裸 node、远程布局）唯一的人工出口。
+  const manual = fakeInstall("DSH NEXT.exe", []);
+  try {
+    const custom = join(manual.root, "custom-cli.js");
+    writeFileSync(custom, "// cli\n", "utf8");
+    const picked = resolveCliJs(manual.exe, { DSH_CLI_JS: custom });
+    assert.equal(picked.path, custom);
+    assert.equal(picked.verified, true);
+  } finally {
+    rmTempBestEffort(manual.root);
+  }
+});
+
+test("resolveCliJs：DSH_CLI_JS 明确指定但路径不存在 → 直接失败，绝不回退到其它候选", () => {
+  const root = mkdtempSync(join(tmpdir(), "choro-t1-explicit-"));
+  try {
+    const exe = join(root, "DSH NEXT.exe");
+    writeFileSync(exe, "", "utf8");
+    // 这份「看起来能用」的布局候选真的存在：如果没有显式指定的短路，
+    // resolveCliJs 会安静地挑中它，用户以为自己的 DSH_CLI_JS 生效了。
+    const asarLib = join(root, "resources", "app.asar", "lib");
+    mkdirSync(asarLib, { recursive: true });
+    writeFileSync(join(asarLib, "desktop-cli.js"), "", "utf8");
+
+    const missing = join(root, "不存在的", "desktop-cli.js");
+    const picked = resolveCliJs(exe, { DSH_CLI_JS: missing });
+    assert.equal(picked.path, null, "显式指定失败就是失败：回退会让人以为设置生效了");
+    assert.equal(picked.verified, false);
+    assert.equal(picked.explicitMissing, missing, "把用户写的那个路径原样带回来，好让他改");
+    assert.ok(picked.candidates.includes(missing), "候选清单里仍是第一位");
+  } finally {
+    for (let i = 0; i < 5; i++) {
+      try { rmSync(root, { recursive: true, force: true }); break; } catch { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200); }
+    }
+  }
+});
+
+test("runner：DSH_CLI_JS 指定不存在的路径时，错误信息指向那个路径而不是布局", () => {
+  const run = makeHeadlessRunner({
+    locateExe: () => "D:\\fake\\DSH.exe",
+    resolveCli: () => ({ path: null, candidates: ["D:\\fake\\cli.js"], verified: false, explicitMissing: "D:\\my\\cli.js" }),
+  });
+  return run({ cwd: ".", task: "x", model: "p/m" }).then((res) => {
+    assert.equal(res.ok, false);
+    assert.equal(res.kind, "environment");
+    assert.ok(res.reason.includes("D:\\my\\cli.js"), "要点名用户写的路径");
+    assert.ok(res.reason.includes("不会回退"), "要说清它不会自动改用别的候选，否则用户会去查布局");
+  });
+});
+
+test("resolveCliJs：全都不在时交回旧布局路径但标 verified:false，候选清单完整", () => {
+  // verified:false 是失败信息里那句「这次没探测」的依据：宁可说清楚「我没看到」
+  // 也不假装自己确认过路径存在。
+  const empty = fakeInstall("DSH NEXT.exe", []);
+  try {
+    const picked = resolveCliJs(empty.exe, {});
+    assert.equal(picked.verified, false);
+    assert.ok(picked.path.endsWith(join("dsh-desktop-host", "lib", "cli.js")));
+    assert.equal(picked.candidates.length, 3); // DSH_CLI_JS 未设 → 不占位
+    assert.ok(picked.candidates.some((c) => c.endsWith(join("lib", "desktop-cli.js"))));
+  } finally {
+    rmTempBestEffort(empty.root);
+  }
+});
+
+test("locateDshExe：认 DSH NEXT.exe，也认标准安装位与 DSH_EXE", () => {
+  // 旧实现只认 basename === "deepseek harness.exe"：DSH NEXT 的 exe 名不匹配、
+  // 装在别处也不匹配 → 两个条件同时不满足，直接 environment 失败。
+  assert.equal(locateDshExe({}, "D:\\Apps\\DSH NEXT.exe"), "D:\\Apps\\DSH NEXT.exe");
+  assert.equal(locateDshExe({}, "D:\\Apps\\DeepSeek Harness.exe"), "D:\\Apps\\DeepSeek Harness.exe");
+  // 不认识的 exe 名不许瞎猜：装了两套宿主时按「同目录任意 exe」挑会挑错。
+  assert.equal(locateDshExe({ ProgramFiles: "Z:\\nope", "ProgramFiles(x86)": "Z:\\nope2" }, "D:\\Apps\\other.exe"), null);
+
+  const install = fakeInstall("DSH NEXT.exe", []);
+  try {
+    // 标准安装位探测：<root>/DSH NEXT/DSH NEXT.exe
+    const pf = join(install.root, "pf");
+    const dir = join(pf, "DSH NEXT");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "DSH NEXT.exe"), "", "utf8");
+    assert.equal(locateDshExe({ ProgramFiles: pf }, "D:\\Apps\\other.exe"), join(dir, "DSH NEXT.exe"));
+    // DSH_EXE 最高优先（显式指定永远赢过探测）。
+    assert.equal(locateDshExe({ DSH_EXE: install.exe, ProgramFiles: pf }, "D:\\Apps\\other.exe"), install.exe);
+  } finally {
+    rmTempBestEffort(install.root);
+  }
+});
+
+/** 假子进程：只实现 consumeHeadlessStream 用到的那几个面。 */
+function fakeProc({ stdout = [], stderr = [], code = 0 } = {}) {
+  const proc = new EventEmitter();
+  proc.stdout = new EventEmitter();
+  proc.stderr = new EventEmitter();
+  proc.killed = false;
+  proc.exitCode = null;
+  proc.signalCode = null;
+  proc.kill = () => { proc.killed = true; };
+  queueMicrotask(() => {
+    for (const chunk of stdout) proc.stdout.emit("data", Buffer.from(chunk));
+    for (const chunk of stderr) proc.stderr.emit("data", Buffer.from(chunk));
+    proc.emit("close", code);
+  });
+  return proc;
+}
+
+test("headless 起不来时，stderr 尾巴进 reason（不再是「(无输出)」）", async () => {
+  // issue #578 的直接症状：退出码 1 + stdout 空 → reason 只有「(无输出)」，用户
+  // 连是缺 credential 还是路径错都不知道。原因一直在 stderr 里。
+  const runner = makeHeadlessRunner({
+    locateExe: () => "D:\\fake\\DSH NEXT.exe",
+    resolveCli: () => ({ path: "D:\\fake\\cli.js", candidates: [], verified: true }),
+    spawn: () => fakeProc({ stderr: ["Error: Cannot find module 'D:\\fake\\cli.js'\n"], code: 1 }),
+  });
+  const result = await runner({ cwd: ".", task: "t", model: "p/m", timeoutMs: 5000, maxToolCalls: 3, maxOutputBytes: 4096 });
+  assert.equal(result.ok, false);
+  assert.equal(result.kind, "environment"); // "Cannot find" → 环境级
+  assert.ok(result.reason.includes("Cannot find module"));
+  assert.ok(!result.reason.includes("(无输出)"));
+});
+
+test("成功路径不追加「未经探测」的提示；探测失败且环境错时才追加", async () => {
+  // 成功时多说一句会让人以为哪里没配好；失败时这句是唯一的自查线索。
+  const okRunner = makeHeadlessRunner({
+    locateExe: () => "D:\\fake\\app.exe",
+    resolveCli: () => ({ path: "D:\\fake\\cli.js", candidates: [], verified: false }),
+    spawn: () => fakeProc({ stdout: ['{"type":"final","text":"ok"}\n'] }),
+  });
+  const ok = await okRunner({ cwd: ".", task: "t", model: "p/m", timeoutMs: 5000, maxToolCalls: 3, maxOutputBytes: 4096 });
+  assert.equal(ok.ok, true);
+  assert.ok(!ok.reason);
+
+  const badRunner = makeHeadlessRunner({
+    locateExe: () => "D:\\fake\\app.exe",
+    resolveCli: () => ({ path: "D:\\fake\\cli.js", candidates: [], verified: false }),
+    spawn: () => fakeProc({ stderr: ["MISSING_CREDENTIAL\n"], code: 1 }),
+  });
+  const bad = await badRunner({ cwd: ".", task: "t", model: "p/m", timeoutMs: 5000, maxToolCalls: 3, maxOutputBytes: 4096 });
+  assert.equal(bad.kind, "environment");
+  assert.ok(bad.reason.includes("DSH_CLI_JS")); // 提示指向唯一的人工出口
+});
+
+test("找不到 CLI 时 reason 列出全部候选路径", async () => {
+  const runner = makeHeadlessRunner({
+    locateExe: () => "D:\\fake\\DSH NEXT.exe",
+    resolveCli: () => ({ path: null, candidates: ["a/lib/desktop-cli.js", "b/dsh/lib/cli.js"], verified: false }),
+    spawn: () => { throw new Error("不该 spawn"); },
+  });
+  const result = await runner({ cwd: ".", task: "t", model: "p/m", timeoutMs: 5000, maxToolCalls: 3, maxOutputBytes: 4096 });
+  assert.equal(result.ok, false);
+  assert.equal(result.kind, "environment");
+  assert.ok(result.reason.includes("a/lib/desktop-cli.js"));
+  assert.ok(result.reason.includes("b/dsh/lib/cli.js"));
+});
+
+test("--dsh-exe 只影响这一轮：跑完 env 还原", async () => {
+  // 原来写进 process.env 就不还：同一进程里后续每次定位都继承旧值（面板切仓库
+  // 还是那个 exe），属于会记很久的脏状态。
+  const { root, store } = setup();
+  const saved = process.env.DSH_EXE;
+  try {
+    delete process.env.DSH_EXE;
+    let seen = null;
+    const t1 = createT1({
+      store,
+      runSession: async () => {
+        seen = process.env.DSH_EXE;
+        return { ok: true, text: GOOD_OUTPUT };
+      },
+      now: FIXED_NOW,
+    });
+    await t1.runT1({ repoRoot: root, moduleSlug: "src", dshExe: "D:\\Harness.exe" });
+    assert.equal(seen, "D:\\Harness.exe"); // 轮内可见
+    assert.equal(process.env.DSH_EXE, undefined); // 轮后还原
+  } finally {
+    if (saved !== undefined) process.env.DSH_EXE = saved;
+    store.close();
+    rmTempBestEffort(root);
+  }
+});