dsh-session-integrity

English | 简体中文

Session integrity diagnosis and non-destructive recovery for DeepSeek Harness.

A single internal scheduler exception can turn an ordinary tool failure into a durable transcript defect that makes every later model request fail before the model can answer.

The problem

The provider invariant

When an assistant message requests tools, every provider-visible tool call id must be followed by its matching tool result. A normal tool failure is safe for the conversation because Harness serializes the failure as that result and the model can decide what to do next.

The broken case is different: Harness persists the assistant request and the execution start, but no result reaches the model-visible Session surface.

assistant/message  tool-call c1
tool/call          c1
scheduler.prepare  throws
step/end
turn/end           error

# Missing: tool/result c1

The next request replays the assistant tool call without a result. DeepSeek rejects the request before inference with a protocol error such as:

An assistant message with 'tool_calls' must be followed by tool messages
responding to each 'tool_call_id'.

This is why sending another user message does not recover the Session. The invalid history is durable and is sent again on every turn.

sequenceDiagram
    participant M as Model
    participant H as Harness
    participant S as Tool scheduler
    participant P as Provider
    M-->>H: assistant tool-call c1
    H->>H: persist assistant/message and tool/call
    H->>S: prepare(c1)
    S--xH: throws
    H->>H: persist turn/end(error), no tool/result
    H->>P: later request replays unmatched c1
    P--xH: HTTP 400 before inference

Why one error becomes permanent

There are three separate layers:

1. Trigger: prepare() or another internal scheduler boundary throws. A duplicated runtime package and mismatched symbol can cause this, but it is only one possible trigger.
2. Persistence defect: tool/call has already been recorded, while the only path that appends tool/result is never reached.
3. Replay amplification: the turn still receives turn/end, so open-tail crash recovery does not repair it. Every later provider request contains the same unmatched tool call and fails again.

The structural bug therefore exists independently of the original trigger. Any exception in the vulnerable interval can poison a previously healthy Session.

Why blindly adding a generic error is unsafe

If failure happens before dispatch, the tool definitely did not run and a retry is safe when still needed. If dispatch started but its result was not durably committed, external side effects may already exist. That outcome must be marked unknown and verified before retrying a write, payment, deployment, or other non-idempotent operation.

What this project does

• The Cordis plugin scans live Sessions at load and after turn/end.
• The offline CLI checks exported JSON or uncompressed JSONL without starting a model request.
• Provider-visible defects are separated from raw execution gaps already shadowed by compaction.
• Reports use hashed references and omit prompts, tool arguments, and tool results.
• The recovery planner finds the latest completed prefix that is still safe to send to a provider.
• The Web plugin adds Continue from here to historical assistant turns. It creates and opens a fork while retaining the original Session.
• The analyzer and planner are read-only. Recovery uses Harness's public fork operation rather than rewriting durable history.

The issue was reproduced on a clean dsh-v0.1.0-rc.8 / master baseline: the unpatched regression recorded one tool/call and zero tool/result events. The tested prevention patch in the linked fork closes undispatched calls with TOOL_SCHEDULER_FAILED_BEFORE_DISPATCH and dispatched calls with TOOL_SCHEDULER_OUTCOME_UNKNOWN, without rerunning dispatch or finalizers. It is a proposal for upstream review, not a change already merged by DeepSeek.

• Upstream incident and reproduction
• Proposed core prevention patch (fork)
• Plugin showcase in the upstream Discussions

DeepSeek Harness currently routes external contributions through Discussions, plugins, guides, and community support rather than external Pull Requests; see the official contribution policy. The fork keeps the complete patch reviewable until maintainers invite or reopen the PR path.

Safety contract

• Never mutates, repairs, deletes, or replaces events in the source Session.
• Recovery creates a child Session through Harness's fork API. It never retries tools and never claims that external side effects were rolled back.
• Never logs prompt text, tool arguments, tool output, raw Session ids, or raw tool call ids.
• Separates provider-visible transcript defects from shadowed execution-log warnings.
• Does not implement hard deletion. The current public persistence service has no backend-independent Session deletion operation.

Install from GitHub

dsh plugin --profile web add github:DON738110198/dsh-session-integrity#v0.2.1
dsh --profile web --dump-config
dsh --profile web

The package ships built JavaScript, so a Git install does not need a build allowance. The Host plugin scans already-live Sessions when it loads and checks a Session again at turn/end. Each distinct defect is logged once.

In the Web UI, finalized assistant messages that have later conversation history receive a branch icon. Pressing it creates a child through the official Session fork API and opens that child. It refuses while the source turn is running, retains the original Session, and does not archive it automatically.

Offline check

Use an uncompressed session.jsonl artifact or an exported JSON document with an events array:

dsh plugin --profile web exec dsh-session-integrity ./session.jsonl
dsh plugin --profile web exec dsh-session-integrity ./session.jsonl --json > integrity-report.json
dsh plugin --profile web exec dsh-session-integrity recover ./session.jsonl --json > recovery-plan.json
dsh plugin --profile web exec dsh-session-integrity recover ./session.jsonl --at 42

From a repository checkout, use node ./cli.js ./session.jsonl instead. The package is not published to npm yet, so a bare npx dsh-session-integrity command is intentionally not documented as an available install path.

recover interprets --at as a Session event anchor. It first considers the completed turn at or after that anchor, then walks backward until the prefix has no provider-blocking defect. The output is a plan only: it does not modify the artifact or a live Session.

For scan, exit codes are 0 for no provider-blocking defect, 1 for an input error, and 2 for a critical defect. For recover, 0 means a safe fork boundary was found and 2 means a fresh Session is required. Zstandard logs are intentionally not decoded independently; use a Harness export or an uncompressed backend.

Why recovery is a fork, not rollback

Harness Sessions are append-only event logs. Removing a visible message can also remove tool calls, request headers, compaction provenance, or evidence of an external side effect. Continue from here therefore creates a new lineage from a completed turn instead of pretending the old events never happened.

Permanent deletion is a separate core capability: it must coordinate the live agent, JSONL and SQLite backends, workspace accounting, projections, cached indexes, and attachment retention. A frontend-only delete button or direct file removal would not provide that contract, so this plugin deliberately does not offer one.

What it checks

• assistant tool requests missing matching provider-visible tool results
• unexpected or mismatched tool results
• duplicate assistant call ids and duplicate execution events
• unsettled tool/call records hidden from the current surface
• malformed or invalid surface operations
• non-monotonic event sequences

Development

npm test
npm run check
npm run pack:check

The fixture suite covers healthy and poisoned recovery boundaries, a prepare()-style failure, synthetic cancellation, an open crash tail, a compaction-shadowed orphan, packed JSONL rows, browser fork orchestration, plugin warning deduplication, and CLI exit behavior.

Status

0.2.x targets DeepSeek Harness dsh-v0.1.0-rc.8. Harness is a developer preview, so compatibility is tested per release rather than assumed.

License

MIT