docs: decide what to take from DeepSeek Harness, and what not to

[oratis]

Research on deepseek-ai/deepseek-harness@47f9438 and the decisions that follow from it.

What this is

Two documents, following the precedent set by the Floatboat round:

• docs/research/deepseek-harness.md — the research, with every claim graded A/B/C. A = read the source, B = their docs say so but I did not run it, C = hearsay and inadmissible.
• docs/DSH_ADOPTION_PLAN.md — each candidate argued proponent / opponent / verdict, so the implementation PRs execute a decision rather than reopen one.

I cloned the repo and read its package tree, docs/architecture.md, docs/capability-seams.md, and the READMEs of every subsystem I judged. I did not run dsh (needs a key and a full build), so every claim about its runtime behaviour is marked B and none of it is copied without redesign.

Why it is worth comparing at all

dsh is the closest thing we have to a direct comparison: another DeepSeek-powered coding agent facing the same constraints. Half of what Claude Code and Codex do (cloud tasks, teams, MDM) is worthless at DeepCode's positioning; dsh's trade-offs are made against our own.

The comparison is not one-directional. DeepCode is ahead on governance (File Contract, Change Ledger, sandbox network allowlist) and on pricing awareness (cache-hit tiers, /cost hit rate). dsh is ahead on context economy and on execution shape, and a generation ahead on frontend extensibility.

Two defects it surfaced in our own code

Both verified against our source, not inferred:

1. WebFetch returns the entire response body to the model. web-fetch.ts:149 does content: body; the only ceiling upstream is 5 MiB of bytes. A 5 MiB HTML page is roughly 1.5M tokens — one call destroys the session.
2. Bash truncation is destruction. bash.ts:43-52 slices at 30 KB and appends a marker. The remainder is written nowhere. The tail of a failing test run is exactly where the useful part lives.

One capability fixes both, and it is the first implementation PR.

Verdicts

Adopt	tool-output spill · repeat-call guard · per-tool timeout · persistent shell sessions · session search · tool render intent · model-free result pruning
Defer	job registry unification · goal domain · Ralph loop · UI package split
Reject	Cordis-style rewrite · workflow engine · the three-package seam convention

The rejection is the load-bearing one. dsh spends 219 packages expressing what DeepCode expresses in 4, and that ratio is not waste — it is what shipping a third-party plugin ecosystem costs. We do not ship one, so we would pay the cost and collect none of the benefit. It also self-describes as a developer preview that will break compatibility, while we have 0.3.0 out with npm, VSIX, DMG, and an update feed downstream. Take the discipline, not the framework.

Three adoptions were narrowed by their own opponent case rather than waved through:

• Persistent shell without PTY. node-pty is a native dependency needing a build per Tauri target. 90% of the value (surviving cd, export, source venv/bin/activate; reading incremental output) needs no PTY, so this uses a marker protocol over pipes and says plainly in the tool description that full-screen TUIs are out of scope.
• Session search is workspace-scoped by default. Cross-session retrieval is a privacy surface: project A's session should not leak credentials or another client's code into project B's context.
• Spill previews keep head and tail. dsh only requires a bounded preview. Stack traces and assertion failures live at the end, which is precisely what our current truncation throws away.

Verification

pnpm docs:check passes; prettier clean. Docs-only — no code touched.