[Bug + fix] Node 24 + tsx 下 build 静默跳过，导致 Web profile 缺少运行时产物

[hytime]

Summary

On 2026-08-20, with Node v24.0.0 and pnpm 11.7.0, starting the web profile failed with loader fibers failed.

The loader reported that @deepseek-ai/dsh-session-reference could not import lib/typert.host.js, and that four client bundles were missing:

• packages/client/ui-renderer/lib/client.js
• packages/client/ui-brand-official/lib/client.js
• packages/client/ui-attachment/lib/client.js
• packages/client/ui-reference/lib/client.js

Root cause

pnpm run build returned exit code 0 but did no work. scripts/build.ts ended with:

if (import.meta.main) main()

In the Node v24.0.0 + tsx execution path, import.meta.main is undefined, so main() was never called. The build therefore created neither the host/client artifacts nor .dsh-build/client-build-environment.json, while still appearing successful to the caller.

Fix

Keep the native import.meta.main check and fall back to comparing the launched script path with the current module path:

import { fileURLToPath } from "node:url"

if (import.meta.main ?? (
  process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
)) main()

A regression test was added in scripts/build.spec.ts; it launches the build script through the tsx ESM loader and verifies that invalid arguments produce an error instead of a silent successful exit.

Verification

• pnpm exec vitest run scripts/build.spec.ts — 1 test passed
• pnpm run build — exit code 0; recorded 200 client artifacts
• Required lib/typert.host.js, client bundles, and .dsh-build/client-build-environment.json were generated
• pnpm dsh --profile web --help — exit code 0; web profile booted without loader fibers failed

The fix is currently verified in the local checkout and has not yet been committed or merged.

[argszero]

Verified the root cause at rc.8 (141eb6fef8), and the fix is sound — but this is a 5-script family, not a build.ts-only bug. Worth sweeping before merging.

1. Root cause confirmed, and Node 24 is officially supported. scripts/build.ts:55 ends with if (import.meta.main) main(); root package.json declares "engines": { "node": "^22.19.0 || >=24.0.0" } — so the failing combination is inside the supported engine range, not an edge-of-support case.

2. Four more entry scripts share the exact guard (repo-wide sweep found these are the only import.meta.main call sites in scripts/):

• scripts/run-gates.ts:88 — launched by pnpm run doc-sync (tsx scripts/run-gates.ts doc-sync)
• scripts/verify-cordis-config.ts:61
• scripts/verify-doc-site-fragments.ts:157
• scripts/verify-runtime-closure.ts:101

All are invoked through the same tsx scripts/<name>.ts path per package.json, so under the Node 24 + tsx combination that produced your loader fibers failed, each of them silently no-ops too.

3. This makes the silent-skip class worse than the build case. A skipped build fails loudly at runtime (loader fibers failed — you found it immediately). A skipped gate fails invisibly: doc-sync, verify-cordis-config, verify-runtime-closure and verify-doc-site-fragments are CI gates wired through run-gates.ts — if import.meta.main is undefined, CI reports green while the checks never ran. That is a vacuous-green failure mode that can sit unnoticed until a doc/config/runtime regression slips through.

4. Suggested fix shape. Your argv[1] fallback is correct (both arms normalize through resolve() vs fileURLToPath(), and process.argv[1] === undefined cleanly keeps the import path non-firing). Rather than a one-off in build.ts, I'd extract a tiny shared helper — scripts/ already has small shared modules (cordis-walk.ts, package-graph.ts, jsdoc.ts) — e.g.:

import { fileURLToPath } from 'node:url'
export const isEntryModule = (): boolean =>
  import.meta.main ?? (process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url))

and apply it to all five entries in the same PR. The regression-test shape you added (scripts/build.spec.ts, launching through the tsx ESM loader and asserting non-silent behavior) generalizes well — one spec per entry, asserting that invalid args produce an error rather than exit 0.

One deliberate non-goal: making the guard fail loudly when the fallback also fails would break importing these modules (e.g. run-gates.spec.ts imports functions from run-gates.ts). The process.argv[1] discriminator is what keeps CLI invocation separate from import; keep that condition as-is.

Fix stands as PR-ready; happy to co-verify the sweep if you'd like.

[denial123789]

I traced this against the rc.8 source boundary and turned it into an operator-facing recovery path. The key diagnostic addition is to treat exit status as insufficient evidence: a complete root build must also print build: recorded … client artifact(s), create .dsh-build/client-build-environment.json, and produce the selected profile's host/client exports.

The resulting failure chain is: direct tsx scripts/build.ts → import.meta.main is undefined → normal status-0 module exit → neither build:lib nor build:web runs → missing exports are only discovered later inside the loader fibers failed aggregate. That distinguishes this incident from a genuine nested build failure or a single plugin packaging problem.

I also documented the safe repair contract: preserve import-without-side-effects, prove direct execution on Node 22 and 24, make invalid direct arguments fail nonzero, and require the artifact record plus Web boot as acceptance gates.

Source-backed runbook and visual trace: https://sandbaseai.github.io/deepseek-harness-handbook/node24-tsx-silent-build.html
Canonical guide: https://github.com/sandbaseai/deepseek-harness-handbook/blob/main/docs/en/troubleshooting/node24-tsx-silent-build.md

[Liyuk]

I prepared a complete patch for this issue on a public fork, including the five-script sweep identified by @argszero.

Root cause and impact

Under the affected Node 24 + tsx ESM-loader path, import.meta.main is undefined. Guards such as if (import.meta.main) main() therefore skip the command and return status 0.

The same failure mode affected all five direct TypeScript entrypoints in scripts/:

• scripts/build.ts
• scripts/run-gates.ts
• scripts/verify-cordis-config.ts
• scripts/verify-doc-site-fragments.ts
• scripts/verify-runtime-closure.ts

For build.ts, the result is missing host/client artifacts and .dsh-build/client-build-environment.json. For the verification scripts, the more dangerous result is a vacuous-green gate: the command exits successfully without running its checks.

Patch

The patch adds a shared scripts/entry-module.ts helper:

• use the native import.meta.main result when Node provides it;
• otherwise compare the resolved process.argv[1] path with fileURLToPath(import.meta.url);
• preserve false from native entry detection so imported modules remain inert.

All five scripts use this helper. Coverage includes:

• helper tests for native true/false, loader fallback matching, and an absent launched path;
• a subprocess regression test that launches the real scripts/build.ts through node --import tsx/esm and requires an unknown argument to fail instead of exiting silently.

Patch links

• Complete comparison: master...Liyuk:fix/build-entrypoint-node24
• Fork branch: https://github.com/Liyuk/deepseek-harness/tree/fix/build-entrypoint-node24
• Commit range to cherry-pick: e35e48671c74449e4da4e47593f66461ecd60c56^..219cc44
• Final commit: Liyuk@219cc44

External pull requests are currently disabled by the repository, so I am posting the ready-to-cherry-pick branch here.

Local verification

Passed on Node v24.18.0:

• shared helper behavior check using native type stripping;
• node --experimental-strip-types scripts/build.ts --unexpected returned nonzero with ERR_PARSE_ARGS_UNKNOWN_OPTION;
• node --experimental-strip-types scripts/run-gates.ts unexpected returned nonzero with the expected mode diagnostic;
• syntax checks for all five affected scripts;
• git diff --check.

I could not complete the focused Vitest run locally because installing this checkout’s dependencies repeatedly timed out against the npm registry. The test files are included for CI/maintainer execution.