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

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-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-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);
+  }
+});