@argszero/cordis-plugin-session-audit

A proactive session-log completeness audit for the deepseek-harness (dsh) agent harness. It never fixes a log — it diagnoses the full corruption surface and prints a report before replay crashes or silently drops history.

Why this exists

The dsh harness persists every agent interaction to an append-only JSONL session log. Two in-tree mechanisms already exist, but neither is a full diagnostic:

• repair.ts (interruptedTurnClosers) is narrow — it only synthesizes replay-time closers for a crash tail (open-turn truncation), one mechanism.
• validateStoredEvents (storage-contract) is a fail-closed load-time check — it refuses an unrecognized/structurally-invalid log outright, but tells you only "this log is bad", not which of the many corruption classes is present.

Upstream, the session-log corruption family has produced 14+ distinct bug reports (seq gaps, index-reuse, format-version drift, empty-id duplicates, orphan tool_calls, turn-reason loss). This plugin audits for all of them at once and classifies each finding as error (replay would fail / needs manual) vs warn (data may have silently dropped) vs info (recoverable — e.g. the open-turn tail the in-tree repair already handles).

Detection surface

| Code | Severity | What it means | |------|----------|---------------| | HEADER_MISSING | error | First line is not a session header; log unusable | | FORMAT_VERSION_DRIFT | error | Log format vN differs from the harness's SESSION_FORMAT_VERSION (written by newer/older harness) | | UNPARSABLE_LINE | error | A committed line is not a decodeable session record | | SEQ_GAP | error | Events are missing between seqs (contiguity break) | | SEQ_DUPLICATE | warn | Same seq appears twice (index reuse) | | SEQ_REORDERED | warn | An event appears below the contiguous watermark (out-of-order / reused seq) | | UNKNOWN_REQUIRED_TYPE | error | A type outside the known vocabulary and not marked ignorable. The harness read path refuses a log containing an unmarked unknown type (SessionFormatUnsupportedError), so a reload of this session will hard-fail — this is the #5769 failure mode (a plugin wrote a custom event type that the log then rejects). Fix: mark the event ignorable, or the session may be unrecoverable. | | TOOL_CALL_NO_ID / TOOL_RESULT_NO_ID | warn | tool/call or tool/result carries no usable call identity | | ORPHAN_TOOL_CALL | info | A tool was requested (tool/call) but its outcome was never durably recorded (tool/result) | | OPEN_TURN | info | A turn opened but never closed (crash interruption; the in-tree repair synthesizes closers for this) | | EMPTY_TEXT_BLOCK | warn | A persisted assistant/message carries an empty/whitespace-only {type:'text', text:''} content block. Harmless under lenient models (GLM/Gemini), but a strict provider (Claude) refuses it and the session becomes permanently unusable after a model switch (#5773). Strip these blocks before replaying at a new provider. | | UNREADABLE_ARTIFACT | error | The artifact is a Zstandard container whose structure is broken — a bad frame magic, a reserved frame-header bit, a reserved block type. This is the class that takes the whole application down: the harness's artifact listing aborts on it, so dsh cannot boot at all until the file is moved out of the sessions root (#7161). The finding names the byte offset, in the harness's own wording. | | UNDECODABLE_FRAME | error | The container structure is intact, so the frames can be located, but a frame's content failed validation (checksum or entropy decode). The session cannot be read; unlike UNREADABLE_ARTIFACT this does not abort a boot, because the failure happens after the listing. | | TORN_FINAL_FRAME | info | The final Zstandard frame is incomplete — a crash tail from a process killed mid-append. The harness tolerates this class while listing and repairs what it can, so it is reported as info and never as needs-manual. The tail's plaintext is recovered on a best-effort basis and reported separately; it is never folded into the audited content, which covers the complete frames only. | | SESSION_PATH_MISMATCH | error | The artifact does not sit in the directory its own header names. The backend re-derives the path from the header on every read (assertStoredIdentity, session-persistence-jsonl) and refuses the read — corrupt session log "…": header id "…" and cwd identify "…" — and that refusal escapes the artifact listing, so it aborts the boot exactly like UNREADABLE_ARTIFACT (#7161, the renamed-directory row). It fires when a session directory was renamed or moved by hand. The session directory must be the header id under the backend's lossless path encoding; the check reports a path shape, so if both names resolve to one file (a symlink or hard link) the backend accepts the artifact and the finding is advisory. | | PROJECT_PATH_MISMATCH | warn | The artifact sits under a project directory that the header's recorded cwd does not derive. The backend's project naming is deliberately lossy (separator runs collapse to one -, the slug is truncated to fit a filesystem component), so a disagreement is advisory — it usually means the layout predates a naming revision, not that the read is refused. A header with no cwd is compared against the _no-cwd bucket, which is where the backend puts such a session. | | EMPTY_ARTIFACT | info | Zero bytes. The harness skips an empty artifact rather than refusing it, so this is not corruption. | | REPETITIVE_STREAM | warn | A run of many identical consecutive assistant/chunk deltas within one stream — the signature of a degenerate decode loop (the model emits the same short token(s) repeatedly with no tool call between them, e.g. '\n' × 701). No tool-call repeat guard can see this because no tool call is made; the harness itself places no turn-length bound. |

Usage

As a mounted Cordis plugin (slash command)

Add it to a cordis.yml resolution manifest:

- insert:
    - id: session-audit
      name: '@argszero/cordis-plugin-session-audit'

Then /session-audit audits every stored session artifact — .jsonl and the compressed .jsonl.zstd container — under the JSONL root, and /session-audit id=<substring> narrows to matching session ids. Configure the root via plugin config:

- insert:
    - id: session-audit
      name: '@argszero/cordis-plugin-session-audit'
      config:
        root: !!js dshHomePath('sessions')

As a one-shot CLI (no harness needed)

The package ships a session-audit bin that runs under plain Node and needs zero dsh runtime:

# audit a whole sessions root
npx @argszero/cordis-plugin-session-audit /path/to/sessions

# narrow to one session id
npx @argszero/cordis-plugin-session-audit /path/to/sessions --id <substring>

# default root from DSH_HOME
DSH_HOME=/path/to/home npx @argszero/cordis-plugin-session-audit

Exit code. The CLI exits 1 when any artifact needs manual attention, 0 otherwise — so it can gate a launch:

npx @argszero/cordis-plugin-session-audit "$DSH_HOME/sessions" && dsh web

Notes

• Both containers are read. .jsonl and .jsonl.zstd are audited alike, so a machine with compression enabled gets the same findings as one without. The container is chosen by artifact name, which is how the harness chooses it — a .jsonl.zstd file whose bytes are not Zstandard is reported as the structural defect it is, not as a malformed header.
• Per-frame, deliberately. Node's zstdDecompressSync accepts a concatenated container and decodes only the first frame, with no error. The harness's container is concatenated frames, one per durable batch, so a one-shot decode silently returns the first batch and drops the rest — which would make a badly truncated session read as clean. This tool scans the frame structure first and decodes each frame, which is also what lets it tell a torn crash tail apart from a structural defect.
• Two-phase, so the important verdict survives a weak runtime. The structural scan is plain Buffer arithmetic and needs no node:zlib; decompression is the optional second phase. On a Node without zstdDecompressSync the audit still reports whether an artifact would abort a boot.
• Non-mutating. This plugin never appends to, truncates, or rewrites a session log.
• It is a diagnostic companion, not a replacement for repair.ts or a fix. Use it to understand what is wrong, then decide whether the in-tree repair or a manual migration is appropriate.

License

MIT