[Bug] Source launch (pnpm dsh) on 0.1.6-alpha.2: every tool call fails with "Cannot read properties of undefined (reading 'prepare')"

[PerryLink]

Summary

On dsh-v0.1.6-alpha.2 (ddefc45fbc, current master tip), a source launch through tsx — the vector the repo's own dsh script uses — fails on every tool call:

dsh: UNKNOWN: Cannot read properties of undefined (reading 'prepare')

The built launch (node apps/cli/lib/bin.js) is unaffected at the same commit. The two module instances are created by the launcher itself from a single package directory: no duplicate package on disk, no community plugin involved.

This trigger is new in 0.1.6-alpha.2, but the symptom is not — it is the same reading 'prepare' crash that has been reported since August under two other triggers. I have tried to collect everything into this one post, including material from the other threads, so the next person starts from one place instead of five.

Most of the depth below is not mine. Credit to #6967 (LLKernel) and the macOS probe in its comments (DreamStan), #6974 (TRAVI5TY), and the August threads by leether (#2078, #2130) and zoahdev.

Flagging a few people who may have context, since the failure mode makes this hard to diagnose from the error alone:

• @imccyu — this bisects to 9ddef327a4 ("feat: resolution mode link to runtime"), which is yours; you also committed the release(dsh): 0.1.6-alpha.2 commit.
• @CreatixChu — you authored the dsh-v0.1.6-alpha.2 release commit (PR Bug: "Fetch available models" returns stale bundled catalog for built-in providers (e.g. OpenRouter) instead of querying the live endpoint #4469), the version this regressed in.
• @tianyicui — 7c9bb5914c ("refactor(ptc): align runtime packages and services with PTC naming") shaped the scheduler and service contract that now throws, so you may have a view on the intended direction.

No blame intended — the split is subtle and the error message points at the wrong thing entirely. What I'd most like to know is which fix direction you'd prefer.

If you are hitting this right now

• Source checkout? Edit apps/cli/src/profile-boot.ts:263 to ?? 'link' (§ Workarounds). Takes effect immediately under tsx; no rebuild.
• Can you use the built launcher? node apps/cli/lib/bin.js web is unaffected.
• Is your session already broken? Patching the resolution will not revive it. A session that died this way cannot be resumed — see § Consequence. Repair the log first.
• Non-source install (npm/pnpm global, desktop)? This particular trigger is specific to tsx source launches. If you see the same message there, you are probably in the other trigger family — a second physical copy of @deepseek-ai/dsh-tools.

Environment matrix

The same crash at the same commit, reported on three platforms by three people:

report	OS / arch	Node	pnpm	launch
this post	Windows 11 x64	v22.22.3	11.7.0	tsx source + built
#6967 comment (DreamStan)	macOS arm64	v25.2.1	11.7.0	tsx source
#6974 (TRAVI5TY)	Linux x86_64	v26.7.0	—	tsx source

Not platform-specific.

Reproduction, and the A/B that isolates it

Verified here on a pristine checkout at ddefc45fbc — zero local modifications, git status --porcelain empty. Same tree, same command each time; the only variable is apps/cli/src/profile-boot.ts:263:

-  const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'runtime'
+  const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'link'

node --import tsx/esm apps/cli/src/bin.ts --profile headless \
  "Read package.json and reply with only the value of its name field. Do nothing else."

That task needs exactly one read call. (If the headless profile does not exist yet, initialize it from the shipped template with --from-default-profile headless.)

launch	resolutionMode	result
source via tsx	runtime (new default)	exit 1 — dsh: UNKNOWN: Cannot read properties of undefined (reading 'prepare')
source via tsx	link (previous default)	exit 0 — tool ran, @deepseek-ai/dsh-root printed
node apps/cli/lib/bin.js (same task)	runtime	exit 0 — unaffected

So runtime is not broken in itself — it is fine whenever the whole graph comes from lib/. It is the tsx + runtime pairing that splits the package, and it splits it deterministically.

On the boundary: every session log on my install back to 2026-09-13 had zero occurrences of this message; after the 0d1f50007f → ddefc45fbc move, 8 of 8 attempted tool calls failed — across both read and pwsh, including a brand-new session dying on its very first tool call at turn 1, step 1. Not tool-specific, not tied to pre-existing session state.

The raw evidence

A crashed turn, straight out of session.v3.jsonl.zstd (ids trimmed):

tool/call   seq 2098  turn 15 step 1  name=read  args={"file_path":"…\\DSH…md"}
step/end    seq 2099  turn 15 step 1
turn/end    seq 2100  reason={"kind":"error",
                        "error":{"message":"Cannot read properties of undefined
                                          (reading 'prepare')","code":"UNKNOWN"}}

Two details are worth reading off this:

• The tool/call is durably recorded before the throw, and step/end closes the step anyway. The events line up exactly with tool-calls.ts: appendToolCall (line 168) runs, then .prepare() (line 170) throws. The turn/end records the failure and nothing else.
• No tool/result follows — which is what poisons the session (§ Consequence).

(If you are reading logs yourself: these files are concatenated zstd frames, and zlib.zstdDecompressSync silently returns only the first frame — 254 bytes out of 1.35 MB in my case. Decode with scanZstdFrames from packages/session/session-persistence-jsonl/src/zstd.ts, or every crash looks like it never happened.)

The two probes — seconds, no model request

Both from #6974, and both worth running before anything else. They show the two planes independently:

# source plane: what every tsx-loaded file sees
node --import tsx/esm -e "console.log(import.meta.resolve('@deepseek-ai/dsh-tools'))"
# -> file:///…/packages/core/tools/src/index.ts

// artifact plane: what the profile generation routes plugin rows to.
// Save as probe.mts in the checkout root, then: node --import tsx/esm probe.mts
import { createRequire } from 'node:module'
import { createProfileResolutionGeneration, loadProfileDirectory } from '@deepseek-ai/dsh-app-boot'

const anchor = new URL('./apps/cli/package.json', import.meta.url).pathname
const home = process.env.DSH_HOME ?? `${process.env.HOME}/.dsh`
const profile = loadProfileDirectory('dsh', `${home}/profiles/web`, anchor, { userLayer: true })
const generation = await createProfileResolutionGeneration({ installAnchor: anchor, profile })
for (const entry of generation.entries) {
  if (entry.name !== '@deepseek-ai/dsh-tools') continue
  console.log(entry.name, createRequire(entry.declarer).resolve(entry.name))
}
// -> @deepseek-ai/dsh-tools /…/packages/core/tools/lib/index.js

Two planes, one process. This is also a ready-made smoke test — see § Questions.

Where it throws, and why the message misleads

packages/core/agent-loop/src/tool-calls.ts:170:

const prepared = await ctx.tools[TOOL_RUNTIME_SCHEDULER].prepare(call.exec)

ctx.tools resolves, but ctx.tools[TOOL_RUNTIME_SCHEDULER] is undefined. That key is a module-private symbol, not a string:

packages/core/tools/src/index.ts:463

/** Scheduler entry point omitted from the generated named service API. @internal */
export const TOOL_RUNTIME_SCHEDULER: unique symbol = Symbol('@deepseek-ai/dsh-tools.scheduler')

Symbol() is not Symbol.for(), so it is only equal across a process while the package is loaded exactly once. Two instances produce two symbols, the lookup is silently undefined, and the property read is what throws.

The message is why this family has been re-diagnosed five times. Nothing checks that the scheduler exists, so what surfaces is Cannot read properties of undefined (reading 'prepare') — naming a method on a value that was never there, and pointing at agent-loop when the fault is in module identity. Every reporter so far has had to rediscover that the real question is "how many copies of dsh-tools are alive in this process". #2130's "Diagnosis" row calls this the third unclosed feedback loop, and I think that is exactly right.

For reference, the build output does contain two independent definitions of the symbol:

• packages/core/tools/lib/index.js:2526 — const TOOL_RUNTIME_SCHEDULER = Symbol("@deepseek-ai/dsh-tools.scheduler");
• packages/core/tools/lib/types/index.js:51 — export const TOOL_RUNTIME_SCHEDULER = Symbol('@deepseek-ai/dsh-tools.scheduler');
• packages/core/tools/lib/types/ptc.js:13 imports it from ./index.js, so that subtree is internally consistent

The change that introduced it

9ddef327a4 "feat: resolution mode link to runtime" flipped the non-packaged default in apps/cli/src/profile-boot.ts and apps/desktop-host/src/index.ts:

-  const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'link'
+  const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'runtime'

link materialised junctions on disk and left resolution to tsx; runtime installs an in-process resolver (it reaches Node's internal ESM/CJS loader through node-addon-require-builtin; see packages/boot/app-boot/src/profile-resolution/resolver.ts) and mounts the plugin tree from lib/. Both planes are then live in one process, and tsx keeps re-projecting workspace imports to src.

The tool-call code itself did not change. Between dsh-v0.1.6-alpha.1 (where tool calls worked) and dsh-v0.1.6-alpha.2, the only changes inside packages/core/agent-loop/src and packages/core/tools/src are inbox.ts (−5/+2, inbox projection registration dedup) and agent-loop/src/index.ts (+2). tool-calls.ts and tools/src/index.ts are byte-identical between the two tags. This is a module-identity regression, not a logic one.

Nor is the phenomenon new in kind: #2091 already documented source launches loading workspace packages twice, splitting a different registry. What is new is that it now reaches a Symbol()-keyed contract, which turns a previously silent split into a fatal one.

Independent confirmations of the split

• LLKernel captured it directly ([Bug] 0.1.6-alpha.2 source launch (pnpm dsh) splits @deepseek-ai/dsh-tools across src/lib — every tool call fails with "Cannot read properties of undefined (reading 'prepare')" #6967), with module.register load hooks in a single boot:

  LOAD tools packages/core/tools/src/index.ts
  LOAD tools packages/core/tools/lib/index.js
  LOAD loop  packages/core/agent-loop/lib/index.js
  

• DreamStan confirmed the symbol identity in-process on macOS ([Bug] 0.1.6-alpha.2 source launch (pnpm dsh) splits @deepseek-ai/dsh-tools across src/lib — every tool call fails with "Cannot read properties of undefined (reading 'prepare')" #6967 comment): ctx.tools[<lib-plane symbol>] is defined, ctx.tools[<src-plane symbol>] is not, and srcSymbol === libSymbol is false. No model involved, so it cannot be a provider-protocol artifact. Their resolution matrix shows tsx projecting the bare specifier to src from every parent, while the runtime generation mounts from lib — the split is in the process, not in any one importer.

• TRAVI5TY measured both planes on Linux (0.1.6-alpha.2 regression: a source checkout now loads harness packages from both src/ and lib/, crashing the first tool call and leaving the session unresumable #6974): both probes above, plus the conclusion that the packages are single copies on disk — the duplicate is the module instance, not a directory. That is why none of the plugin-side remedies in Pitfall map for DSH plugin authors: the 'reading prepare' crash is a duplicate @deepseek-ai/* copy — three guards that would catch it #2130 apply to this trigger.

Three platforms, same commit, same one-line cause.

The report family — same symptom, three different triggers

Worth separating, because the remedies differ:

#	date	trigger
#1337	08-14	community plugin resolves a second physical copy
#2078	08-15	same; one-line fix proposal
#2091	08-15	source launch loads workspace packages twice (different registry)
#2130	08-15	pitfall map for the copy family
#4508	08-25	web mode, mechanism unconfirmed
#6416, #6529	09-12/13	profile-local copy (any pnpm install in the profile, e.g. via the plugin-manager UI)
#6967, #6974, this post	09-17	source launch splits the package across src/ and lib/ — new
#6971	09-17	the same thing seen from the user side

The existing remedies for the plugin/profile-copy family (#2130's guidance) do not apply here — this trigger has no duplicate on disk and no third-party plugin involved.

Consequence: the session is left unresumable

This deserves its own heading, because it is easy to miss and it is what confuses users most.

When the dispatch fails, the assistant message and its tool/call events are already durably recorded, and no results are ever written. Every later turn replays that history, and the provider protocol rejects it during serialization — before any HTTP request:

DeepSeek Messages tool calls need immediate results      (INVALID_REQUEST)

packages/llm/llm-deepseek/src/protocols/messages/serialize.ts:117

So the damage is two-stage: one failed turn, then a session that can never continue. #6971 is exactly this seen from the UI — a new session reports reading 'prepare', an old session reports tool calls need immediate results, which reads like "even downgrading doesn't help".

As TRAVI5TY points out (#6974), this is by construction rather than bad luck: agent-loop drains dispatches on a scheduler failure without committing synthetic recovery results, whereas cancellation writes ABORTED_BEFORE_DISPATCH pairs. Any dispatch failure therefore poisons the session, not just this one. A synthetic result pair for a failed dispatch would reduce this entire class to a single failed turn — separately worth doing, whatever happens to the resolution question.

LLKernel also worked out a repair for already-damaged logs (#6967 comment): truncate each log after the last tool/call of the damaged step, so the built-in crash repair closes that turn on the next resume. Verified against the real serializer there: the original log is rejected with history ends with unresolved tools, the repaired log serializes clean with every tool call paired to a result; only the failed turn's own artifacts are lost.

There is no escape hatch

Also from #6974, and worth knowing before you go looking: parseDshArgs has no resolution-mode flag, runCli calls runProfile without resolutionMode, and nothing reads an environment variable for it. A source-checkout user cannot select link without editing source. It also makes pnpm run build mandatory after every pull, because the packaged rows read lib/.

Workarounds

1. One line, source launches only — verified above:

   -  const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'runtime'
   +  const resolutionMode = packaged ? 'runtime' : options.resolutionMode ?? 'link'

   Under tsx this takes effect immediately; no rebuild needed.

2. Run the built launcher: node apps/cli/lib/bin.js web. Works on Windows and macOS (confirmed in [Bug] 0.1.6-alpha.2 source launch (pnpm dsh) splits @deepseek-ai/dsh-tools across src/lib — every tool call fails with "Cannot read properties of undefined (reading 'prepare')" #6967's comments), including with third-party bundles — at the cost of rebuilding after every source change.

3. A branch already exists: Honghe linked fix/resolution-mode-link-default on [BUG] 更新不能太积极，又不能用了！ #6971, which is the same direction.

4. Make the symbol global — Symbol.for() instead of Symbol() (Fix: `reading 'prepare'` crash from duplicate `@deepseek-ai/dsh-tools` copies (Symbol-key mismatch) — a one-line `Symbol.for` fix #2078, branch leether/deepseek-harness → fix/tool-runtime-scheduler-symbol). See the trade-offs below; both the original proposer and zoahdev now treat it as a local unblocker.

5. Damaged sessions need separate repair — patching the resolution does not revive them.

Prior proposals, and why they were not adopted

This part matters for anyone thinking about the fix, because the obvious one-liner has already been round-tripped once.

#2078 — Symbol.for(). The standard dual-package-hazard remedy: the key becomes identical across all module instances while staying a Symbol, preserving the @internal intent. Verified there against duplicate copies on 0.1.0-rc.6.

The gap zoahdev raised in #2078's comments — version skew. Symbol.for makes the key identical but not the value's protocol. If two copies come from different trains (say the host's and an older one hoisted from a plugin), the global key means one copy now reads the other copy's scheduler. If their protocol shapes differ, that is a silent cross-wire — which "works" until it doesn't, and is harder to attribute than the original undefined. Their branch adds a TOOL_RUNTIME_SCHEDULER_PROTOCOL_VERSION guard on top.

#2130 — the proposer's own revised position. Symbol.for is a defensive stopgap with side effects, not the fix, because it: makes the key semi-public (breaking @internal), freezes the key string forever, silently cross-wires across versions, and removes the only signal we have (a loud undefined becomes a silent success or a silent cross-wire). "In a single-instance world preserved by relink + a check, Symbol() is strictly better."

That thread also frames the whole family as two reasonable defaults colliding — a private-identity Symbol() on one side, npm's "import X → dependencies" default on the other — with three feedback loops never closed: documentation (publish.md never says host packages must be peerDependencies), an install-time check (dsh plugin is a bare pnpm forwarder that silently accepts a plain @deepseek-ai/* dependency), and diagnosis (the crash reports undefined, not "two physical copies, one from the host and one from plugin X"). It maps five ways a duplicate appears with rough frequency shares — note those are estimates from discussion frequency, not measurements.

I find that framing convincing, and it applies to this trigger too: the source-launch split is a sixth path, and none of the three loops would have caught it either.

Two constraints on the fix space

Both come from the other threads, and are worth not rediscovering:

• "Route everything to lib/" does not work. DreamStan tried TSX_TSCONFIG_PATH pointed at a paths-less tsconfig; the plugin tree and the launcher graph then do agree on lib, but the source launch dies at import time with SyntaxError: The requested module '@deepseek-ai/cordis' does not provide an export named 'FiberState'. FiberState is a const enum (vendor/cordis/src/fiber.ts:147) that tsc inlines, so vendor/cordis/lib/index.js carries no runtime enum object. A source launch must therefore keep the src plane for the launcher's own graph — which rules out "everything to lib" and supports the "source → link, built → runtime" direction.
• Globalising the symbol is the other axis, with the trade-offs above.

Questions

1. Is the tsx source-launch path covered by CI? If not, that would explain how this reached a release tag while the built path stayed green. Both probes in § The two probes reproduce it in seconds with no model request, so a smoke test looks inexpensive.
2. Which direction do you want — keep source launches on a single module plane, or make the collision fail loud and name both copies, rather than throwing at .prepare?
3. Separate from the resolution question: should a dispatch failure write synthetic results, so that it cannot poison a session at all?

[zhang-guo-wen]

已把这批 0.1.6-alpha.2 源码启动故障的共同根因和完整修复方案汇总到 #7011 的这条回复。

本帖属于其中的 tsx src + runtime lib 混载路径。建议上游同时落地四项，而不是只选其中一个 workaround：

1. TypeScript 源码启动默认 link，构建产物/pkg 保持 runtime；
2. TOOL_RUNTIME_SCHEDULER 改用 Symbol.for(...)；
3. profile/plugin 安装后检测同名核心包的多个 realpath/版本；
4. 在写入 tool/call 前取得并验证 scheduler，避免失败后留下无法配对的持久事件。

本地 CLI 聚焦测试 16/16、tools scheduler key 测试和 CLI/tools/agent-loop TypeScript build 已通过。详细补丁、用户恢复步骤、会话处理和回归门禁见上面的集中回复。