[Feature]: Add partial DeepSeek Harness session-evidence adapter

[Cobb04]

Preflight

• I searched existing issues for a similar request.

What problem are you trying to solve?

Better Harness currently has no session-evidence adapter for DeepSeek Harness (dsh), so persisted DSH runs cannot be consumed by Better Harness's existing session-based analysis.

DSH's current base composition persists structured session records with session identity, workspace metadata, ordered user/assistant activity, correlated tool calls and results, and explicit turn outcomes. This leaves an integration gap between evidence DSH produces and evidence Better Harness can analyze after a run.

DSH is also highly configurable and plugin-oriented. Combined with its persisted execution evidence, that could make Better Harness findings a useful foundation for future harness-level iteration. This is only motivation for the adapter: a session log does not establish plugin ownership, root cause, or an automatic repair.

What would success look like?

A first contribution lands as a partial session-evidence adapter, with a support claim limited to:

DSH persisted JSONL session → workspace qualification → supported event normalization → Better Harness session evidence

For the currently observed DSH dsh-v0.1.0-rc.7 / session-format-v0 contract, the adapter would:

• discover JSONL-backend session artifacts from an explicitly resolved DSH session root, including the current default .jsonl.zstd encoding and raw .jsonl mode;
• validate the session header, identity, physical/logical record shape, and contiguous event sequence before using the evidence;
• qualify sessions against the requested workspace using the header's absolute cwd, not the intentionally lossy project-directory name;
• normalize an allowlisted subset of user, assistant, tool-call/result, and turn-outcome events into Better Harness's existing session contracts;
• retain user-message source distinctions, native call/result correlation, and existing privacy/content gates;
• keep missing, incomplete, and known-but-unsupported evidence explicit;
• refuse unsupported or malformed session-format versions and unknown required events rather than guessing;
• treat an open trailing turn as incomplete evidence and never repair or rewrite DSH artifacts;
• include deterministic synthetic fixtures for supported encodings, workspace matching and rejection, event correlation, terminal outcomes, unknown events, malformed records, deduplication, and privacy boundaries;
• document JSONL-only partial support and leave SQLite or custom persistence providers unavailable.

This first slice would not claim native installation, configured-asset discovery, plugin lifecycle integration, packaging integration, or Quickstart readiness.

Where would this be used?

The initial use case is post-run analysis of a project that has been worked on with DeepSeek Harness:

DSH run → persisted session evidence → Better Harness qualification/normalization → existing Better Harness analysis

Better Harness would analyze durable evidence after the run; it would not run natively inside DSH or infer live terminal/process state in this first slice.

Examples or evidence

Current upstream DSH sources at dsh-v0.1.0-rc.7:

• Developer-preview status, compatibility warning, and plugin-oriented positioning
• Base profile composition of JSONL persistence under the DSH-home sessions route
• Session header, format version, event vocabulary, correlation fields, and turn-end reasons
• JSONL layout, default Zstandard encoding, packed records, identity checks, and discovery constraints
• SQLite's separate persistence and discovery contract

Anything else?

DSH describes itself as a rapidly changing developer preview, and its current session format is version 0 with no compatibility promise. A narrow, version-aware adapter therefore seems safer than a general “DeepSeek Harness support” claim. Same-version structural drift should also fail closed when it does not match the explicitly supported fixtures.

I am interested in implementing this contribution. I would use PR #56 as a reference for Better Harness's ownership, evidence, synthetic-fixture, privacy, and validation conventions, while treating the current contribution guide as authoritative.

Explicit non-goals for this first contribution are full first-class DSH support, native Better Harness installation inside DSH, configured-asset or Skill discovery, DSH plugin lifecycle or packaging integration, public Quickstart status, automatic harness optimization, and automatic identification of faulty plugins.

Maintainer feedback would be welcome on whether session-evidence-only partial support, limited initially to the current JSONL contract, is the right first boundary.

[phodal]

@Cobb04 Thanks for the detailed proposal — the session-evidence boundary looks like a solid first slice.

That said, given how much of the DSH persistence/discovery model you’ve already investigated, we’d also welcome a somewhat broader contribution if you’re interested. In particular, automatic discovery of the default DSH session location, explicit adapter capability/version metadata, and preserving enough DSH provenance for future harness/plugin-level integration would all be useful.

So: JSONL session evidence is a good minimum scope, but it doesn’t have to be the maximum scope for the PR. We’d be happy to see the integration taken one step further.

[Cobb04]

Thanks — I dug into the three extensions you suggested, and they still look like they fit cleanly within one focused, read-only sessionAnalysis PR.

The revised scope I’m planning is:

• automatic default discovery via explicit --dsh-home → inherited DSH_HOME → ~/.dsh, with sessions under <home>/sessions;
• explicit partial capability/version boundaries: sessionAnalysis only, Better Harness adapter version dsh-v1, initially supporting DSH SESSION_FORMAT_VERSION = 0;
• bounded DSH provenance for lineage/subagent context, user-message source, turn/step position, and tool call/result correlation, without mirroring arbitrary raw events or making causal or plugin-ownership claims;
• support for both the default session.jsonl.zstd artifact and uncompressed session.jsonl.

I also ran a small feasibility probe for the Zstd path. Better Harness’s tested Node 22.20 and Node 24 lanes can read the default DSH format using Node’s public Zstd API, so this requires no new runtime dependency or packaging integration.

One important detail surfaced: DSH writes a concatenation of independently checksummed Zstd frames. On the tested Node 22.20/24 runtimes, passing the complete artifact to a single decompression call silently returns only the first frame. The adapter therefore needs to scan and validate frame boundaries, decode each complete frame individually, concatenate the resulting bytes, and only then parse the logical JSONL.

There is one runtime-policy edge where I’d appreciate your preference before locking the spec. Better Harness currently declares Node >=22.20.0 <25.0.0, but the Node 23 line did not gain the public Zstd APIs until 23.8.0. That leaves Node 23.0–23.7 inside the declared engine range but unable to read compressed DSH evidence natively.

My preference is to keep #93 focused: feature-detect the API and report compressed DSH evidence as unavailable on those runtimes, while continuing to support raw session.jsonl. This avoids changing the global engine range or adding a fallback dependency solely for that gap. If Node 23.0–23.7 were never intended to be part of the supported runtime contract, I can instead reflect that policy in the spec.

The broader non-goals remain unchanged: no native DSH installation or invocation, configured-asset/Skill discovery, plugin lifecycle integration, SQLite/custom persistence, Quickstart promotion, or live PTY/process-state support.

If this boundary looks right, I’ll capture it in the dated spec and proceed with fixtures and tests.

[phodal]

@Cobb04 Looks good. Please proceed with the spec and implementation using the proposed feature-detection approach.

[phodal]

Closed after merging PR #94.

[Cobb04]

Thanks for reopening #93 — could you clarify why you reopened it?

[phodal]

@Cobb04 Sorry again for the earlier mistake. Could you check whether the latest PR aligns with your idea?

[Cobb04]

@Cobb04 Sorry again for the earlier mistake. Could you check whether the latest PR aligns with your idea?

Thanks — I’ll review the latest implementation against the #93 scope and the pinned DSH behavior, and report back with any concrete mismatches I can reproduce.

[Cobb04]

@Cobb04 Sorry again for the earlier mistake. Could you check whether the latest PR aligns with your idea?

Yes — the overall product slice in PR #94 aligns with the scope agreed in #93.

I also completed an independent validation against pinned DSH rc.7 and existing Better Harness evidence contracts. I found a few reproducible implementation mismatches:

recoverable raw/Zstd crash tails currently discard committed prefixes;
inherited seedLength history is counted as child activity;
a missing tool-result isError is normalized as success: true;
reused callIds can collapse distinct downstream tool traces;
directory symlinks can escape the declared DSH sessions root.

These look like focused follow-up fixes against current main; they don’t change the overall scope-alignment conclusion. I’m happy to work through them as narrow follow-ups.