[Bug] 0.1.5-rc.2 桌面端 prepare:dsh 必然失败：payload smoke 断言已被移除的 fs-ext，无法产出 resources/dsh

[379061296]

环境

• 提交：master @ c291e796（@deepseek-ai/dsh-desktop 与根包版本均为 0.1.5-rc.2）
• 平台：Windows 10 x64；Node v24.17.0（仓库固定的 desktop runtime）
• 命令链：prepare:runtime → prepare:packages → prepare:dsh

现象

prepare:dsh 在 bundled-runtime payload smoke 处中止，生产 payload 无法产出。本机在每次全新 temp project + 全新 pnpm store 下连续三次运行，都在同一处失败：

desktop native payload smoke failed: node:internal/modules/cjs/loader:1500
Error: Cannot find module 'fs-ext'
  at checkFsExt (.../apps/desktop/tests/fixtures/runtime-payload-smoke.mjs:69)
  at .../runtime-payload-smoke.mjs:124

该错误由 apps/desktop/scripts/prepare-dsh.ts 里 smoke 子进程的回调抛出并终止整个脚本，因此 resources/dsh 闭包不会生成；后续 electron-builder 打包会以
ENOENT ...\resources\dsh\desktop-runtime.json 失败（verifyDesktopRuntime / afterPack）。

根因：fs-ext 已不是任何包的依赖，但 smoke 仍在断言它

fs-ext（安装期编译的 NAN addon）已在之前的迁移中被移除：

• 全树没有任何 package.json 声明 fs-ext：git grep -n 'fs-ext' -- '*package.json' 无匹配；
• pnpm-lock.yaml 中也没有 fs-ext 条目（只有 fs-extra）；
• 会话写入租约现在走 @deepseek-ai/node-addon-system/flock：
  packages/session/session-persistence-jsonl/src/lease.ts:34
  （import { tryLockExclusive } from '@deepseek-ai/node-addon-system/flock'），
  即 .agents/notes/implemented/architecture/2026-09-07-prebuilt-system-primitives.md
  描述的「用预构建 Node-API system addon 取代安装期编译的 NAN fs-ext」；
• 全树唯一还在引用 fs-ext / seekSync 的代码，就是这个 fixture 自己
  （apps/desktop/tests/fixtures/runtime-payload-smoke.mjs:69）。

也就是说，payload 的 pnpm install --prod --frozen-lockfile 永远不会装上 fs-ext，
checkFsExt() 在任何平台都不可能通过，而 prepare-dsh.ts 把它当硬失败。

（同一迁移的残留还有 apps/desktop/scripts/runtime-file-policy.ts 里的
fs-ext/build/** 排除规则与 project-manager.ts 的 allowBuilds: fs-ext: true；
它们不影响构建，但语义上已经是死代码。）

建议的最小修复

删除 fixture 中已失效的 fs-ext 断言：checkFsExt() 函数、它的调用、汇总 JSON 里的
fsExt: true，以及因此不再使用的 node:fs 导入（closeSync / openSync / readSync）。
其余 koffi / sharp / turndown+gfm / node-pty 断言针对的模块都在 package set 中真实存在，保持不变。

针对 c291e796 的完整补丁（单文件，+2/−19）：

--- a/apps/desktop/tests/fixtures/runtime-payload-smoke.mjs
+++ b/apps/desktop/tests/fixtures/runtime-payload-smoke.mjs
@@ -1,7 +1,7 @@
 /** Exercise filtered Desktop native and HTML dependencies under its bundled Node. */
 
 import assert from 'node:assert/strict'
-import { closeSync, mkdtempSync, openSync, readFileSync, readSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
@@ -64,22 +64,6 @@ async function checkPty() {
   }
 }
 
-/** fs-ext implements seek on Windows through SetFilePointerEx and on POSIX through lseek. */
-function checkFsExt() {
-  const fsExt = requireRuntime('fs-ext')
-  const file = join(scratch, 'seek.txt')
-  writeFileSync(file, 'abcdef', { flag: 'wx', mode: 0o600 })
-  const fd = openSync(file, 'r')
-  try {
-    assert.equal(fsExt.seekSync(fd, 2, fsExt.constants.SEEK_SET), 2)
-    const bytes = Buffer.alloc(4)
-    assert.equal(readSync(fd, bytes, 0, bytes.length, null), 4)
-    assert.equal(bytes.toString(), 'cdef')
-  } finally {
-    closeSync(fd)
-  }
-}
-
 /** Resolve one system function through Koffi's packaged native module. */
 function checkKoffi() {
   const koffi = requireRuntime('koffi')
@@ -121,7 +105,6 @@ function checkHtml() {
 }
 
 try {
-  checkFsExt()
   checkKoffi()
   await checkSharp()
   checkHtml()
@@ -134,5 +117,5 @@ try {
 // Natural event-loop drain includes node-pty's worker and console-list helper teardown.
 process.once('beforeExit', () => {
   console.log(JSON.stringify({ node: process.versions.node, platform: process.platform, arch: process.arch,
-    fsExt: true, koffi: true, sharp: true, html: true, pty: true }))
+    koffi: true, sharp: true, html: true, pty: true }))
 })

CONTRIBUTING.md 说明暂不接受外部 PR、Issues 已关闭，因此把报告发在这里；若需要其他形式（例如单独的 patch 文件）我再补充。

[argszero]

You are right on both halves, including the tempting one to get wrong: fs-ext is gone, and koffi must stay. I re-checked from the anchor rather than taking the patch on trust, and I have three additions — the second one is about the payload rather than the fixture.

Independent confirmation

• No package.json in the tree declares fs-ext, and pnpm-lock.yaml has no entry. The only remaining references are the fixture itself (apps/desktop/tests/fixtures/runtime-payload-smoke.mjs:69/124/137), the file-policy rules (apps/desktop/scripts/runtime-file-policy.ts:26/30), the allowBuilds block (apps/desktop/src/project-manager.ts:109), and one stale comment (vitest.config.ts:98).
• checkFsExt() is indeed unreachable-successful: requireRuntime resolves inside the installed payload, and the payload's pnpm install --prod --frozen-lockfile cannot produce a package that no manifest and no lockfile entry mentions.
• Your call to leave checkKoffi() alone is right, and the reason is worth stating explicitly because the migration note reads like a removal list: the note retains koffi on purpose. Its rejected-alternatives table records "use koffi for the POSIX call" as a rejected replacement for fs-ext — i.e. the accepted direction was the prebuilt Node-API addon — and one of the accepted sections keeps the Windows lock on the existing koffi semaphore. koffi is declared in six manifests here. Deleting it would have traded a correct removal for a false one.

1. A passing run cannot show which checks ran

This one is about the fixture's own shape, and it is the reason this bug was able to sit here.

The fixture computes a summary line — {node, platform, arch, fsExt, koffi, sharp, html, pty} — and prepare-dsh.ts:145 writes the child's stdout straight to the console without parsing it. There is no consumer for those keys anywhere in the tree; I grepped. So the keys are a report nobody reads, which means deleting any single check* call from the fixture is indistinguishable from a run where it passed. The fsExt key is the proof: it kept reporting true for a check that could no longer succeed, and nothing anywhere disagreed.

The failure path is fine — prepare-dsh.ts:144 rejects on any non-zero exit and wraps stderr, so an applied-but-broken change fails loudly, and DESKTOP_HOST_RUNTIME_FILES is existence-checked with a throw. The unverified part is success: a green prepare:dsh currently asserts only "the child exited 0", not "these six checks ran". Printing or parsing that summary costs one line and turns the next removal of a check into a visible diff instead of a silent one. I would treat that as part of this fix rather than a follow-up, because it is the property that would have caught it.

2. The payload's other removed-native dependency has no coverage at all

You listed the residue of the fs-ext removal; the same migration also introduced an addition, and it is the one this smoke exists to protect:

• The lease imports @deepseek-ai/node-addon-system/flock (packages/session/session-persistence-jsonl/src/lease.ts:34) — verified — and the family ships test files including test/flock.test.js. That is the source-tree trust model, the mode the note says was already covered before.
• The payload side has no counterpart: the fixture asserts pty, koffi, sharp and html, and nothing loads node-addon-system or resolves its platform package.

That matters because the failure mode this fixture guards is precisely "the install produced a different native layout than the source tree", and the platform-package contract is the newest and least exercised part of it. So:

• From the note, bundling alone would still be unsound — no prebuilt binary is portable across OS, CPU, libc and Node ABI, which is why the family is split into per-platform packages.
• A missing platform package surfaces on a bare require of the subpath, so a payload check is cheap and needs no new fixture machinery.
• Cold-run hardening and module coverage are orthogonal; a fix that asserts the same names one layer up should at minimum record what it did not make stricter, otherwise the impression is that this payload now has fewer unverified spots than it does.

3. Runtime-file-policy: removal is right, but it is not free

To my point above — the fs-ext rules at runtime-file-policy.ts:26/30 are not inert residue. apps/desktop/tests/runtime-file-policy.spec.ts exercises them with seven vectors including a positive case at line 73. Removing the rules turns that spec red, so they should be kept or removed as one change rather than judged at the same time as the smoke fix, which is why I agree with your sequencing.

Likewise, allowBuilds already contains a positive entry for every intentionally built native dependency (node-pty, koffi, fs-ext), so it is a small declaration set rather than a general allow-list. An entry naming a package that cannot be installed is self-consistent but no longer meaningful, and stale entries here are exactly what made this bug expensive. Worth folding into the policy cleanup rather than leaving for later.

Summary

The diagnosis and the minimal patch for the fixture are both correct, and the interesting parts are the boundary cases: the always-false assert, the retained koffi, and the fact that the summary line reports a true nobody reads. If it is useful, I can prepare the second and third items above as separate minimal patches — they touch packaging scripts, not the product — so they stay reviewable independently of your fixture change. I realise external PRs are not being accepted at the moment, so treat this as notes placed where they are easy to find.

[379061296]

Thanks — this is exactly the review the report needed. Points 1 and 2 are both fair: the fixture reports a true that nobody reads, and the migration's addition has no payload coverage at all. I folded both into an updated patch. Point 3 I agree to take as you framed it — the policy rules and the spec vectors have to move as one change, so they stay out of this one.

What I re-checked on c291e796

• prepare-dsh.ts:145 writes the child's stdout straight through, and the only producer of those keys is the fixture itself (git grep finds no consumer anywhere), so any dropped check* call is invisible in a green run. Confirmed — that is the property that let this sit here.
• koffi is declared in six manifests (fs-local, directory-picker-native, sandbox-windows-acl, session-persistence-jsonl, subprocess-local, win32-process), so leaving checkKoffi() alone was deliberate on the note's terms: the rejected alternative was using koffi for the POSIX call, not removing koffi.
• runtime-file-policy.spec.ts really does exercise the fs-ext rules (the keep-vectors at lines 20–24 and 38, the nested-path negative at line 73). Calling them "inert residue" was my error in the original report; they can only go together with the spec, which is why your sequencing is the right one. Same for the allowBuilds entry.
• @deepseek-ai/node-addon-system is part of the desktop package set (desktop-packages.json → deepseek-ai-node-addon-system-0.1.2.tgz) and session-persistence-jsonl depends on it, so a payload check is meaningful rather than aspirational.

Updated patch (both files against c291e796)

--- a/apps/desktop/tests/fixtures/runtime-payload-smoke.mjs
+++ b/apps/desktop/tests/fixtures/runtime-payload-smoke.mjs
@@ -1,7 +1,7 @@
 /** Exercise filtered Desktop native and HTML dependencies under its bundled Node. */
 
 import assert from 'node:assert/strict'
-import { closeSync, mkdtempSync, openSync, readFileSync, readSync, writeFileSync } from 'node:fs'
+import { closeSync, mkdtempSync, openSync, readFileSync, writeFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import { tmpdir } from 'node:os'
@@ -17,6 +17,9 @@ assert.equal(process.arch, descriptor.arch)
 const requireRuntime = createRequire(join(root, 'package.json'))
 const scratch = mkdtempSync(join(tmpdir(), 'dsh-runtime-payload-'))
 
+/** Prefix of the summary line prepare-dsh.ts parses; keep both copies in sync. */
+const SUMMARY_PREFIX = 'desktop-runtime-payload-smoke '
+
 /** Spawn only a fixed Node program and await the terminal's drained exit event. */
 async function checkPty() {
   const pty = requireRuntime('node-pty')
@@ -64,17 +67,19 @@ async function checkPty() {
   }
 }
 
-/** fs-ext implements seek on Windows through SetFilePointerEx and on POSIX through lseek. */
-function checkFsExt() {
-  const fsExt = requireRuntime('fs-ext')
-  const file = join(scratch, 'seek.txt')
-  writeFileSync(file, 'abcdef', { flag: 'wx', mode: 0o600 })
+/**
+ * The prebuilt Node-API system addon replaced fs-ext on POSIX. Windows keeps its
+ * koffi semaphore, so only the `./flock` subpath has to resolve there.
+ */
+async function checkSystemFlock() {
+  const flock = requireRuntime('@deepseek-ai/node-addon-system/flock')
+  assert.equal(typeof flock.tryLockExclusive, 'function')
+  if (process.platform === 'win32') return
+  const file = join(scratch, 'flock.txt')
+  writeFileSync(file, '', { flag: 'wx', mode: 0o600 })
   const fd = openSync(file, 'r')
   try {
-    assert.equal(fsExt.seekSync(fd, 2, fsExt.constants.SEEK_SET), 2)
-    const bytes = Buffer.alloc(4)
-    assert.equal(readSync(fd, bytes, 0, bytes.length, null), 4)
-    assert.equal(bytes.toString(), 'cdef')
+    await flock.tryLockExclusive(fd)
   } finally {
     closeSync(fd)
   }
@@ -121,7 +126,7 @@ function checkHtml() {
 }
 
 try {
-  checkFsExt()
+  await checkSystemFlock()
   checkKoffi()
   await checkSharp()
   checkHtml()
@@ -132,7 +137,9 @@ try {
 }
 
 // Natural event-loop drain includes node-pty's worker and console-list helper teardown.
+// prepare-dsh.ts asserts this summary, so a dropped check cannot pass as a green run.
 process.once('beforeExit', () => {
-  console.log(JSON.stringify({ node: process.versions.node, platform: process.platform, arch: process.arch,
-    fsExt: true, koffi: true, sharp: true, html: true, pty: true }))
+  console.log(`${SUMMARY_PREFIX}${JSON.stringify({ runtime: { node: process.versions.node,
+    platform: process.platform, arch: process.arch },
+    checks: { systemFlock: true, koffi: true, sharp: true, html: true, pty: true } })}`)
 })

--- a/apps/desktop/scripts/prepare-dsh.ts
+++ b/apps/desktop/scripts/prepare-dsh.ts
@@ -38,6 +38,11 @@ const PACKAGE_SET_ROOT = BUILD_PATHS.packageSet
 const NODE = join(RUNTIME_ROOT, 'node', process.platform === 'win32' ? 'node.exe' : 'node')
 const PNPM = join(RUNTIME_ROOT, 'pnpm', 'bin', 'pnpm.mjs')
 
+/** Must match the summary prefix in tests/fixtures/runtime-payload-smoke.mjs. */
+const PAYLOAD_SMOKE_SUMMARY_PREFIX = 'desktop-runtime-payload-smoke '
+/** Native checks the bundled payload must report; a silent removal must not look like a pass. */
+const EXPECTED_PAYLOAD_SMOKE_CHECKS: readonly string[] = ['systemFlock', 'koffi', 'sharp', 'html', 'pty']
+
 function manifestVersion(path: string, subject: string): string {
   const manifest = JSON.parse(readFileSync(path, 'utf8')) as { version?: unknown }
   if (typeof manifest.version !== 'string') throw new Error(`desktop runtime: ${subject} has no version`)
@@ -100,6 +105,17 @@ function runPnpm(args: readonly string[]): Promise<void> {
   })
 }
 
+function verifyPayloadSmokeSummary(stdout: string): void {
+  const line = stdout.split(/\r?\n/u).filter(entry => entry.startsWith(PAYLOAD_SMOKE_SUMMARY_PREFIX)).at(-1)
+  if (line === undefined) throw new Error('desktop runtime: payload smoke printed no summary line')
+  const summary = JSON.parse(line.slice(PAYLOAD_SMOKE_SUMMARY_PREFIX.length)) as { checks?: Record<string, unknown> }
+  const checks = Object.entries(summary.checks ?? {})
+  if (checks.length !== EXPECTED_PAYLOAD_SMOKE_CHECKS.length
+    || checks.some(([name, value]) => value !== true || !EXPECTED_PAYLOAD_SMOKE_CHECKS.includes(name))) {
+    throw new Error(`desktop runtime: payload smoke reported ${JSON.stringify(summary.checks ?? null)}`)
+  }
+}
+
 async function main(): Promise<void> {
   rmSync(DSH_OUTPUT_ROOT, { recursive: true, force: true })
   rmSync(PNPM_BUILD_STATE, { recursive: true, force: true })
@@ -142,7 +158,15 @@ async function main(): Promise<void> {
       execFile(NODE, [join(APP_ROOT, 'tests/fixtures/runtime-payload-smoke.mjs'), DSH_OUTPUT_ROOT],
         { timeout: 120_000, env: { ...process.env, NODE_OPTIONS: '' } }, (error, stdout, stderr) => {
           if (error !== null) reject(new Error(`desktop native payload smoke failed: ${stderr}`, { cause: error }))
-          else { process.stdout.write(stdout); accept() }
+          else {
+            try {
+              verifyPayloadSmokeSummary(stdout)
+              process.stdout.write(stdout)
+              accept()
+            } catch (cause) {
+              reject(cause instanceof Error ? cause : new Error(String(cause)))
+            }
+          }
         })
     })
     await smokeDesktopRuntime(DSH_OUTPUT_ROOT, NODE, descriptor)

Two decisions inside it worth stating, because they are where I would expect pushback:

The summary is now a contract instead of a report. The fixture emits one prefixed line, desktop-runtime-payload-smoke {"runtime":…,"checks":…}, and prepare-dsh.ts parses the last matching line and rejects unless the reported check set equals the expected set and every value is true. I used set equality rather than "all expected keys present" so that a check added to the fixture but not to the expectation list also fails — otherwise the gate only closes one of the two directions. One trap for whoever touches this next: the parse error is converted to reject on purpose, because a throw inside that execFile callback would leave the promise pending forever and hang the prepare instead of failing it.

checkSystemFlock() replaces checkFsExt() — but only on POSIX does it exercise the addon. On Linux/macOS it resolves the platform package and calls tryLockExclusive(fd) for real, which is the coverage the payload was missing. On Windows there is nothing to load: native/system/packages/entry/package.json declares optional dependencies for darwin-* and linux-* only, flock.js is lazily loaded by design, and tryLockExclusive rejects with ERR_FLOCK_UNSUPPORTED_PLATFORM; the Windows lock is the koffi semaphore that checkKoffi() already covers. So the Windows branch asserts only that the ./flock subpath resolves inside the payload, and the system.node bytes are verified on the POSIX lanes. Worth making explicit so a Windows pass is not later read as platform-package coverage.

What is not verified

I have not run prepare:dsh end-to-end with this patch. This machine would need the whole prepare:runtime → prepare:packages chain to produce a 0.1.5-rc.2 package set, and I would rather hand you a real run than a plausible one. What I did check: exact anchors against c291e796, node --check on the fixture, and a TypeScript parse of prepare-dsh.ts. If it is useful I can push the run through and report the summary line that comes out; otherwise your lane is the better judge.

On point 3: agreed — please take it as your separate patch. Stale allowBuilds entry plus the fs-ext policy rules plus their spec vectors should move together, and I would not object to the vitest.config.ts:98 comment riding along.

[379061296]

Ran the patch through end to end on Windows 10 x64, so here is the summary line you asked about (the new prepare-dsh.ts check is what consumes it):

desktop-runtime-payload-smoke {"runtime":{"node":"24.17.0","platform":"win32","arch":"x64"},"checks":{"systemFlock":true,"koffi":true,"sharp":true,"html":true,"pty":true}}

prepare:packages and prepare:dsh both exited 0, and the gates that follow the fixture in the same process — smokeDesktopRuntime (boots the Host with an external plugin and fetches dsh-app://app/) and the final verifyDesktopRuntime — passed too, so the recorded inventory matches the materialized tree on this target. resources/dsh came out at 114.1 MB across 188 top-level packages.

Three notes from the run, in case they are useful on your side:

• Windows does resolve the ./flock subpath inside the payload, which is all the new check asserts there. The system.node bytes still only get exercised on the POSIX lanes, since the entry package has no win32-* optional dependency — worth keeping in mind if the check is ever tightened.
• prepare:runtime exits 13 on this machine (Detected unsettled top-level await in prepare-runtime.ts; the archive itself verifies). That is a pre-existing local quirk, unrelated to this patch: the runtime tree it had already materialized was complete (node v24.17.0, pnpm 11.7.0), so I resumed with prepare:packages + prepare:dsh.
• I also carried the result through the downstream packaging path to make sure nothing after prepare:dsh depended on the removed check: electron-builder copies resources/dsh/node_modules (node-pty's ConPTY helpers, ripgrep), the afterPack verifyDesktopRuntime gate passes on the packaged tree, and an extracted-copy smoke creates 241 junctions from the profile into app/resources/dsh with the window up in about ten seconds. That part is my local unsigned route, not something that belongs upstream — the fixture and prepare-dsh.ts change is the whole upstream-facing delta.