What dsh-why is, and when to use it

dsh (DeepSeek Harness) has two ways to fail, and they leave completely different evidence behind. dsh-why answers both, from local files, read-only.

• npx dsh-whydsh will not start. A plugin's client bundle called require() on a module the shell does not provide, and the loader materialized the whole client plugin tree — so one plugin takes every plugin down. dsh-why reads your actual install and names the plugin, the module, and the fix.
• npx dsh-why rundsh starts fine, but a run died. The turn is over, you have a symptom, and nothing said why. dsh-why reads your own session logs and turns turn/end.reason into a verdict — plus a health view that separates chronic noise from a real incident.

A diagnostic that guesses is worse than one that admits it does not know. Every dsh-why verdict lands on one of these, and a blind spot is never turned into a red card:

That last row is the reason to trust the other three.

The failure vocabulary is closed, which is what makes attribution possible at all. Across a measured corpus of 2,006 turns every failure carried one of these, and they split into two families that need opposite advice — the network family usually clears on its own, the configuration family never does:

Loader failures — dsh will not start

• client-modules: require("…") missed the module table
• client-modules: cannot resolve "…"
• client-modules: bundle script … failed to load
• Failed to load plugins

Run failures — dsh started, a run died

• DeepSeek API request to https://api.deepseek.com failedthe API call never completed
• 401: The API Key appears to be invalid or may have expiredthe key was rejected
• llm-deepseek: no API key for provider route "deepseek-official"no key for this route
• Insufficient Balanceout of credit
• 503 "pricing not configured for provider/model"no pricing for this model
• 400 "unsupported model"the route cannot serve it
• 502 status code (no body)a 5xx from the provider
• DeepSeek stream idle timeout after 300000msthe stream went idle

dsh does not let your client bundle require() arbitrary npm packages — it resolves against a module table baked into each shell build. dsh ships several times a day. Nothing in your repo tells you when an upstream change would break yours, until your users do.

npx dsh-why --package . is that check, and it works as a CI gate:

npx dsh-why --package . && npm publish   # any non-zero must block the release

Exit 1 is a real crash. Exit 3 means it could not check at all — almost always an unbuilt checkout, since the client bundle is a build artifact. It is deliberately not 0: a gate that passes when it verified nothing is worse than no gate.

Field-tested against 13 popular published plugins: zero false positives, and no plugin was found broken. This gate is quiet on healthy plugins — it is a regression guard against upstream, not a cleanup tool.

Full integration guide: CI recipes, exit codes, and the seed-safe fix pattern →

• Never modifies a file.It diagnoses. Fixing is yours, or your agent's — --prompt produces a paste-ready instruction.
• Never uploads anything.No account, no telemetry, no session content leaves the machine. --offline skips even the read-only data fetches.
• Never calls a model.Zero dependencies, no API key, no per-run cost. The whole rule base is local.
• Never turns "I could not tell" into a failure.It reports it as unclassified and gives it a distinct exit code.

• the full error and module reference — every failure class, and every module with its per-shell history
• run failures, all of them — the eight classes dsh-why run can name
• the plugin-author gate guide — CI recipes and the seed-safe fix pattern