dsh-doctor: an offline diagnostic for the failure classes this community keeps reporting

[moonquake2004]

dsh-doctor: an offline diagnostic for the failure classes this community keeps reporting

Show-and-tell + community asset. A small, dependency-free CLI that checks a profile's env / profile / session state before you boot or install — 19 checks mapped to 18 discussions, each one a failure this community has hit and traced.

TL;DR

Over the last few days this community produced a cluster of reproducible failure reports around the plugin/profile/session surfaces. Almost all of them are detectable offline — the broken state lives in local files (package.json, cordis.patch.yml, node_modules, session logs, PATH) long before boot or the next install. I mined the discussions, grouped them into checkable classes, and built a single zero-dependency CLI (dsh-doctor.mjs) that catches them ahead of time.

1. Method

For each of the ~15 candidate discussions, asked one question: is the failure state visible in local state that an offline script can inspect? If yes → turned into a check. If it needs a live host (e.g. runtime registry collisions like #1415) → out of scope, noted.

2. The failure-class catalog (what the checks map to)

#	Check	Discussion	What it detects
E1	tool availability	#1270	node/pnpm/zstd missing from PATH (session creation / dsh plugin / log decode)
E2	.env type	#71	.env is a directory → failed to load .env: EISDIR
E3	node version	#113, #1313	--expose-internals-dependent boot paths (HMR/headless)
P1	bundle entry resolvable	#917, #1377, #880	dsh.profile.bundles entries that can't resolve (failed remove leftovers, silently disabled bundles, boot fail-fast)
P2	bundle vs user-patch id collision	#1404	duplicate loader entry id → boot crash
P3	patch insert name: resolvable	#1197, #880	unresolvable cordis.patch.yml insert names (asymmetric resolution)
P4	file: deps intact	#1197	dangling file: links (vanished node_modules link)
P5	no top-level @deepseek-ai/* duplication	#1486	duplicate module instances → Symbol mismatch → tool layer crash
S1	orphan tool_call	#1363	assistant tool_calls without tool results → INVALID_REQUEST on resume
S2	unclosed turns	#466, #1265	session stuck "running" after an abnormal host kill

Known out of scope (need a live host): #1415 (runtime registry collision), #1486's runtime manifestation (we only detect the condition), IME issues (#1051/#629/#1417/#1281).

3. The tool

• File: dsh-doctor.mjs (~14 KB, zero npm dependencies; uses node:fs/node:child_process, shells out to zstd only for .zstd session logs)
• Usage:

  node dsh-doctor.mjs                      # everything
  node dsh-doctor.mjs --profile web        # profile checks only
  node dsh-doctor.mjs --session <path>     # session checks (default: latest session)
  node dsh-doctor.mjs --env                # env checks
  node dsh-doctor.mjs --json               # machine-readable output
  

• Exit codes: 0 = all pass · 1 = fixable problems found · 2 = usage/environment error
• Verified:
  • Healthy profile (web, 0.1.0-rc.6): all 10 checks pass, exit 0
  • Negative tests: the pre-fix broken profile from dsh plugin add promotes pre-existing bundle-declaring deps into the bundle stack and breaks the next boot with "duplicate loader entry id" #1404 correctly flags modlens, better-sidebar under P2; a synthetic orphan fixture correctly flags S1
  • --json round-trip works

4. Where this fits

This community already has several doctor proposals — #649 (one-command env doctor), #432 (surface silent patch failures), #1380 (plugin doctor), #1518 (session doctor + migrations), #738 (Windows doctor). This one is intentionally the offline, zero-dependency, three-surface (env/profile/session) slice — a stopgap that runs anywhere node exists, and a seed the official dsh doctor (per the advisory in #1496) can absorb.

It complements the user-side security checklist in the dsh-handbook chapter 13 (which already lists our earlier check-dsh-profile.mjs).

5. Call to action

• Try it — if you've hit any of the 18 discussions above, run the matching check and confirm it catches your case (or add the missing one);
• Extend it — the structure is "one function per check"; natural next candidates: port-in-use (【BUG】 端口被占用会报错 #602), interrupted plugin-creation leftovers (创建插件中断后无法启动 #1131), pnpm-lock vs file: consistency;
• Adopt it — happy to hand this over as the seed for an official dsh doctor implementation.

Author note: built while chasing #1404/#1197/#1486/#1363 in a real profile; the catalog is from the discussions above (2026-08-14 era, 0.1.0-rc.6).

---

---

---

---

Source & maintenance

The tool's canonical home is the public repo: https://github.com/moonquake2004/dsh-doctor (MIT).

# latest, no clone needed (node + zstd on PATH)
npx --yes github:moonquake2004/dsh-doctor
# or clone
git clone https://github.com/moonquake2004/dsh-doctor

The repo README keeps the current check↔discussion table, the S11 materialization-metric calibration (measured heap model + DSH_DOCTOR_HEAP_MB), and Windows-compat notes. This post intentionally no longer embeds the full source — an embedded copy goes stale as the tool evolves with the threads (it already did twice); the discussion history here is the design/verification log, the repo is the code.

[argszero]

This is exactly the consolidation the community needed — I've been involved in several of the threads you mapped (#1377, #1404, #1452, #1473, #1497), and the offline-check framing is right: nearly all of these failure states are visible in local files before boot.

Three failure classes from today's reports that would strengthen the catalog — all offline-detectable:

S-class (session log) additions

S6 — seq discontinuity / duplicated segment (#1333, #1452): scan session.jsonl / .zstd event seqs for non-monotonic jumps or duplicated ranges. This is the single most-reported session corruption today (two independent byte-level repros). Detection: decode frames (zstd), assert seq == index contiguity per session — same check the loader runs, offline.

S7 — replayed committed tail after end-seed (#1497): events appearing after a session/end-seed with seqs lower than the seed's last seq. Distinct signature from S6 (single-process unclean-exit replay vs concurrent writers) — worth its own check so the repair advice differs.

S8 — unknown-type events without ignorable (#1538, posted today): a session log containing an out-of-repo plugin event type that isn't marked ignorable: true will be refused wholesale. Offline check: cross-reference event types against KNOWN_SESSION_EVENT_TYPES + the ignorable flag. This one is extensibility-induced corruption — the plugin wrote valid events, the harness can't read them.

P-class addition

P6 — dsh plugin Windows arg-quoting (#1420): absolute path args containing spaces break under shell: true. Offline-detectable? Partially — you can't repro the spawn without running it, but you can flag profile package.json dependencies with file:/absolute specs containing spaces on win32, which is the precondition. A lint-style warning is cheap.

Method note

Your "is it visible in local state?" filter is the right one. For the S-class checks, the zstd decode is the only non-trivial dependency — if you want to stay zero-dependency, a minimal zstd frame scan (magic + frame header skip, like the loader's scanZstdFrames) suffices for seq-level checks without full decompression.

Happy to contribute the S6/S7/S8 check logic (I have the exact corruption shapes and source line refs from the four threads) if you want to fold them in.

[moonquake2004]

Great additions — and thanks for pulling the exact thread refs. S6/S7/S8 are exactly the kind of byte-level session corruption that deserves offline checks, and P6 is a cheap lint worth having.

On your method note: agreed on the zstd frame scan — right now I shell out to the zstd CLI (E1 already checks for it), and a minimal frame scan would remove even that dependency for the seq-level checks. Happy to adopt it.

Re: folding S6/S7/S8 in — yes please. Concretely:

1. If you can share the check logic (corruption shapes + line refs), I'll integrate them into dsh-doctor.mjs as S6/S7/S8 (keeping the S-section numbering), add P6 as a win32 lint, and test against your repro shapes;
2. or if you'd rather open a PR against the repo — either works; I'll verify with synthetic fixtures (seq gap, duplicated range, post-end-seed tail, unknown-type event) and report results back here.

The catalog is yours to extend too — I've kept the "one function per check" structure precisely so contributions like this are drop-in.

[boyin111-1]

v0.2.0 更新 —— 已落地 #1496 建议清单里的 (a)+(b) 两个离线检测项

工具迭代到 0.2.0 并已推仓库（https://github.com/boyin111-1/dsh-doctor，npx --yes github:boyin111-1/dsh-doctor）。本次聚焦把 #1496 的 dsh doctor 建议项 (a) id 冲突与 (b) 可解析性补成离线检测：

• dsh.profile.bundles 完整性（check 6）：清单里每个 bundle 必须能从 dsh 安装或 profile 目录双锚点解析、声明 dsh.bundle.patch、且补丁文件存在——直接命中 [Bug Report] `dsh plugin remove` 失败后残留 `dsh.profile.bundles` 条目，profile 永久无法启动且官方提示的修复命令无效 #917 的"残留 bundle 永久启动失败"与 profile.ts:resolveBundleDir 的显式抛错路径。
• bundle ↔ 用户 patch id 碰撞（check 7）：用户 cordis.patch.yml 插入的 entry id 若与某个 bundle 的 patch id 相同 → duplicate loader entry id（dsh plugin add promotes pre-existing bundle-declaring deps into the bundle stack and breaks the next boot with "duplicate loader entry id" #1404/两个不同插件拥有同一个id，导致dsh web启动错误 #1479 场景）；bundle 既在 dsh.profile.bundles 又在用户 patch 同名 insert → reconcile 未清理的冗余提升。
• --fix：对 target 存在但未链接的 file: 依赖，自动在 profile 目录执行 pnpm add file:<target> 重链；其余项只给"先备份再删"配方，不动你配置文件。
• 读 $DSH_HOME（默认 ~/.dsh），可对临时 home 演练不碰真实环境。
• 破坏性测试 test/destructive.test.mjs（10 个断言）：每个检测"坏 profile 必报、好 profile 不误报"，当前真实 ~/.dsh/profiles/web 全绿（18 ✓ / 0 ⚠ / 0 ✗）。

新增检测逻辑都镜像 packages/boot/app-boot/src/profile.ts（resolveBundleDir 安装优先双锚点 + dsh.bundle.patch 契约），保证离线结论与真实启动一致。欢迎在真机上跑一遍确认覆盖你的 case。

[moonquake2004]

v0.2.0 verified ✅ — I re-ran it against the exact broken state that the previous version missed (#1404: a user patch with 4 inserts + the promoted bundles):

• check 7 now hits correctly: reports user patch inserts "better-sidebar" = dsh-better-sidebar's bundle entry id (and the same for modlens), plus a "redundant insert" warning — the blind spot from Issue #1 is closed;
• Healthy profile: 12 ✓ / 0 ⚠ / 0 ✗, no false positives; --fix, $DSH_HOME, and the destructive tests are all solid additions, and mirroring the profile.ts contract is the right approach.

One small observation (non-blocking): when DSH_HOME points at a temp home (dry-run scenario), the in-box bundles (@deepseek-ai/dsh-base, dsh-web-app) get flagged as "dangling" — the install-anchor discovery doesn't cover npx/PATH-style installs. Our implementation solves the same problem by finding dsh's node_modules via PATH (same idea as E1/P1) — worth a look.

Also: the S6/S7 checks argszero proposed in this thread are now implemented locally (position monotonicity/no-duplicates, and post-end-seed replay detection); once he shares the corruption shapes I'll cross-verify and sync back here. Happy to keep the two tools cross-referencing.

[boyin111-1]

v0.3.0 update — added the --session dangling-tool_call scan, straight from forum feedback

The loop ran the way the advisory intended: community report #1544 (a tool crash leaves an unmatched tool/call; every later request fails 400 insufficient tool messages, permanently) — same family as #1363 — turned out to be offline-detectable from the session log. So:

dsh-doctor --session <session.jsonl.zstd>

pairs tool/call ids (packages/core/session/src/types.ts:279) against
tool/result message.source.callId (types.ts:291, tools/index.ts:315).
A call whose completed turn is still unmatched → hard error (poisons future requests,
#1544/#1363). A dangling call in the latest still-active turn → warning (in-flight),
so scanning a live session never false-positives. Destructive test D10 locks in
"bad synthetic log flagged, identical log with the result → clean".

Repo: https://github.com/boyin111-1/dsh-doctor (npx --yes github:boyin111-1/dsh-doctor)

[moonquake2004]

v0.3.0 --session verified ✅ — ran it against our live session (0.1.0-rc.6 web): it correctly reports only the in-flight call in the current active turn as a warning (0 ✓ / 1 ⚠ / 0 ✗), matching our S1 result (no real orphans — only the trailing in-flight call). Good cross-confirmation, and #1544 being the same #1363 family keeps validating the catalog.

One note: your turn-based in-flight discrimination (completed vs still-active turn) is cleaner than my seq-position heuristic — worth aligning mine to it. Also, the tool/call → tool/result pairing you cite (types.ts:279/291) matches how I parse content blocks, so the two implementations agree on the same log.

Three independent implementations of the same offline checks now agree on real data — the loop is working.

[moonquake2004]

All of argszero's S-class proposals are now implemented in dsh-doctor.mjs (17 checks total, all passing on a healthy live 0.1.0-rc.6 session; each check also has a synthetic negative fixture):

• S6 — seq==index contiguity, official semantics: instead of a monotonic heuristic, I replicated the harness's exact check — decodeStorageRecord/expandRow (chunk rows expand to seq0+k events) then assert event.seq === events.length. Verified: 343k expanded events on the live session with 0 violations; a synthetic seq gap (expected 6, got 7) is flagged.
• S7 — post-end-seed replay: events after the last session/end-seed with lower seqs → flagged (seed@11274, 20k following records all higher on the live log).
• S8 — unknown types without ignorable: the official KNOWN_SESSION_EVENT_TYPES (44 entries) is parsed at runtime from the installed dsh-session (baked 0.1.0-rc.6 fallback when the install isn't on PATH); storage row types and the header are excluded; ignorable: true exempts. Synthetic my-plugin/fancy-event flagged, ignorable-marked one passes.
• Bonus, same family: S9 (zstd container frame count — single-frame logs are the 单个会话日志损坏时 session.list 整体 500,Web 侧边栏全部会话消失 #1043 "session.list 500 / all sessions disappear" signature), S10 (sourceEventSeqs must reference earlier events — the other half of [Bug] 强制上下文压缩会损坏会话日志：seq 空洞 + 悬空 sourceEventSeqs 导致历史永久无法加载 #1469), E4 (node-pty native binary present, npm 全局安装后 dsh web 启动失败：node-pty 原生模块 pty.node 缺失 #1219), E5 (storage JSON strict-UTF-8 + parse, [BUG] 多个 dsh 实例并发写 workspace.json 导致非 ASCII 路径乱码、工作区会话列表消失 #1357).

Cross-verification invite: if you share the exact corruption shapes / line refs from #1333/#1452/#1497/#1538, I'll run them against these implementations and report back here (the tool's "one function per check" structure makes additions drop-in). Also happy to align S7's repair advice with the distinct single-process-replay vs concurrent-writer signatures you mentioned.

[boyin111-1]

v0.3.1 update — --verify-anchors now checks the dsh you actually run

After a review flagging that the first anti-rot draft verfied a source checkout, --verify-anchors was reworked to align with what dsh-doctor itself resolves at check time.

npm users run the compiled build (node_modules/**/lib/*.js), which can differ from the GitHub source in version or patch level — so verifying a source repo checks a build nobody is running. Now:

• dsh-doctor --verify-anchors (no arg) → parses your installed dsh and greps its compiled lib/ artifacts (dsh-session, dsh-tools, dsh-app-boot).
• dsh-doctor --verify-anchors <dir> → checks that dir alone, never falls back to the local install (so a deliberately broken tree is reported broken, not masked).

The 5 anchors: tool/call + tool/result event literals, ToolResultMessage.callId, the bundle two-anchor install-first order, and the dsh.bundle.patch contract. Confirmed 5/5 against a normal npm install. Exit code 1 on any missing anchor, so an upstream behavior change surfaces instead of a stale verdict.

Honest caveat: this catches anchors whose tokens vanish; a change that keeps the same field name but alters semantics still needs a human re-check (it's a tripwire, not a guarantee).

Repo: https://github.com/boyin111-1/dsh-doctor (npx --yes github:boyin111-1/dsh-doctor)

[moonquake2004]

Update: the tool is now at 18 checks — added S11 (whole-session scan) after #1550's field report: it enumerates every session under $DSH_HOME/sessions, flags corrupt ones (S6/S7/S8/zstd failures) with a quarantine suggestion, and oversized ones (decoded >10MB or >10k frames — the Session B class) as a cold-open materialization-risk warning. Details + the N → N-4 signature verification are in my #1550 reply.

Full check inventory (18): env E1-E5 (node/pnpm/zstd, .env, node version, node-pty #1219, storages #1357), profile P2-P5 (bundle resolvability, id collisions #1404, insert resolvability #1197, file: links, dual @deepseek-ai #1486), session S1 (#1363), S2 (#466), S6 (seq==index, #1333/#1452/#1469), S7 (end-seed replay #1497), S8 (unknown types #1538), S9 (zstd frames #1043), S10 (sourceEventSeqs #1469), S11 (#1550).

[moonquake2004]

v0.3.1 --verify-anchors verified ✅ — with an explicit dir it passes 5/5 against our npx install (0.1.0-rc.6), including the compiled-lib path detection. Nice anti-rot tripwire, and the honest "catches vanished tokens, not semantic drift" caveat is the right framing.

Two notes:

1. The no-arg auto-discovery still misses npx/PATH-style installs (we run from the npx cache): --verify-anchors without an arg reports "找不到 dsh 安装" here, which slightly undercuts "checks the dsh you actually run" for npx users — the same discovery gap as before. Worth a PATH-based fallback (find dsh in node_modules/.bin on PATH).
2. The idea maps directly to our implementation: S6 replicates expandRow's seq0+k semantics by hand, S7 depends on the session/end-seed literal, S8 self-adjusts by re-parsing KNOWN_SESSION_EVENT_TYPES. If upstream changes any of those, our verdicts rot silently too. I'll add an analogous anchor check (verify seq0, session/end-seed, sourceEventSeqs exist in the installed dsh-session) as a meta-check in our tool — the same tripwire philosophy.

Nice work — this closes a real gap in the "offline verdict" trust model.

[moonquake2004]

The promised tripwire is in — E6 (anchor meta-check) added to dsh-doctor.mjs (19 checks now): it verifies the installed dsh-session still contains the three contracts our session checks depend on — expandRow's row.seq0 usage (S6), the "session/end-seed" literal (S7), and the sourceEventSeqs field (S10). Missing anchor → hard failure with a "verdicts need re-review" hint; dsh-session not locatable → informational fallback. Verified 3/3 on our install, and a synthetic lib with row.seq0 replaced by row.base correctly trips the wire.

Same tripwire philosophy as your --verify-anchors, applied to our three hand-replicated contracts.

[moonquake2004]

The tool now has a proper home: https://github.com/moonquake2004/dsh-doctor (public, MIT). It mirrors the current 19-check source in this thread's body — the repo is the cloneable/issue-trackable copy (README has the full check ↔ discussion mapping). Issues/PRs welcome there; I'll keep this thread as the design/verification log.

[moonquake2004]

Update: the tool is now also installable as a dsh plugin. The repo (moonquake2004/dsh-doctor) ships a plugin/ bundle — install with dsh plugin --profile web add file:<checkout>/plugin (npm publish pending), which gives you:

• a Settings → Doctor panel running all 19 checks from the UI;
• an HTTP API GET /dsh-doctor/run (JSON, same checks; ?profile=/?session= narrow the scope).

Same single source as the CLI (plugin/dsh-doctor.mjs); the server route shells out to it — the checks are offline/filesystem-based by design, so nothing is lost by running them in a child process. Tested in a scratch profile and installed in our live web profile: panel renders, API returns 19/19 ✓.

Also worth noting while publishing: the bare npm name dsh-doctor is already taken (by a fourth independent implementation, astra3294/dsh-doctor — the offline-check niche is crowded now, which is a good sign). We'll publish under a scoped name.