dsh-session-integrity

Readme

# dsh-session-integrity

[English](README.md) | [简体中文](README.zh-CN.md)

Session integrity diagnosis and non-destructive recovery for
[DeepSeek Harness](https://github.com/deepseek-ai/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.

```text
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:

```text
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.

```mermaid
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](https://github.com/deepseek-ai/deepseek-harness/discussions/3524#discussioncomment-18089302)
- [Proposed core prevention patch (fork)](https://github.com/DON738110198/deepseek-harness/tree/fix/scheduler-failure-tool-results)
- [Plugin showcase in the upstream Discussions](https://github.com/deepseek-ai/deepseek-harness/discussions/3555)

DeepSeek Harness currently routes external contributions through Discussions,
plugins, guides, and community support rather than external Pull Requests; see
the official [contribution policy](https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.md).
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

```sh
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:

```sh
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

```sh
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