Introduction¶
The DeepSeek Harness plugin dsh-deadend is a “refutation ledger” designed for coding agents. It solves the problem of agents repeatedly trying known-failed approaches in each session, because existing memory systems usually only record “what works” and rarely record “what does not work.” dsh-deadend records “tried and failed” approaches into the repository and validates them before the next attempt.
Core Features¶
The plugin mainly includes the following capabilities:
- Anchor tracking: Each record carries anchors (file hashes). When the code that a record depends on changes, the record is automatically invalidated.
- Automatic expiration: When anchors remain unchanged, the record remains in an “authoritative” state; when anchors change, it is automatically downgraded to a “suspect” state.
- Command normalization: When hashing logs, noise such as line numbers, paths, and timestamps is ignored, ensuring that cross-session and cross-machine failure patterns are correctly identified.
- Exit codes: Standardized exit codes are provided for CI workflows: 3 (blocked/authoritative failure), 4 (suspect/retest needed), 5 (record rejected).
- Repository ledger: Data is stored in the repository’s
.deadend/ledger.jsonl, not in a local cache, supporting multi-person collaboration and historical traceability. - Mergeability: Content-generated identities (ID) support deduplication and merging.
Installation and Enablement¶
Installing the plugin requires a DeepSeek Harness environment and Node.js >= 20. The installation process does not require a build step.
dsh plugin --profile web add github:liyixuan201211/dsh-deadend
Typical Usage¶
Before use, ensure the environment meets the requirements. The plugin provides commands such as check, record, and verify.
Check known failures:
Before performing expensive operations, first check whether an authoritative failure record already exists.
deadend check --cmd "npm install sharp" --log /tmp/last-install.log
Record a failure:
Record a failure case and specify its anchor files.
deadend record --title "npm install sharp fails: no prebuilt binary for darwin-arm64" --cmd "npm install sharp" --exit 1 --log /tmp/last-install.log --why "sharp ships prebuilt binaries and publishes none for this platform/arch" --retry "npm rebuild sharp --build-from-source (needs libvips)" --anchor package.json --anchor package-lock.json --evidence /tmp/last-install.log --tag native
Verify a result:
When you suspect a record may no longer apply, verify it.
deadend verify dd_50e127c7d9c5 --still-fails --log <new-output>
Notes¶
- Unanchored entries: If no anchors are specified (
--unanchored), the record will block permanently and will not expire automatically. - Storage location: The ledger is located in the repository directory, rather than in a machine cache, ensuring data shareability and auditability.
- Dependency requirements: Ensure that the runtime environment has Node.js version >= 20 installed.
Summary¶
dsh-deadend addresses the difficulty of automatically invalidating negative knowledge by introducing an “anchor” mechanism. It turns failure experience into a repository asset, ensuring that agents do not infinitely retry along known erroneous paths.