DSH plugin SessionHandle: flush barriers and crash recovery
"The write succeeded, but a chunk vanished after restart" is almost never a broken backend — it is append being mistaken for flush. DSH plugin's session persistence is a capability seam, and the durability promise hangs on flush alone. Understanding the handle's boundaries is more effective than switching backends.
The handle is the only entry, not an id-addressed service
Every log read and write flows through a handle, the single entry guarded by a cross-process write lease.(source)
Three consequences follow immediately:
- You cannot read or write events by id while bypassing a handle;
- One handle type serves both reading and writing; the
accessfield separates them rather than two classes; - Mutating through a read handle is a runtime
SessionReadOnlyError, not a type-level split.
Write ownership is in-process single-writer semantics: when an active holder exists, a second open(id, 'write') is rejected with SessionAlreadyOwnedError. That is not a flexibility limit; it protects a running turn, because otherwise repair logic would collide with active writes.
The service itself exposes only create, open, stat, and list, with no parallel persistence event types. create and open return a per-session SessionHandle, and the handle provides read, append, flush, and close.
read slicing and close semantics
read returns only a valid contiguous prefix; a torn tail is never handed to you.(source)
read(offset?, length?, options?) returns SessionHandleReadResult with two parts: eventState and events. events is an outer array owned exclusively by the caller; eventState says whether values are fully exclusive (detached) or shared only after deep freezing (shared-frozen). A slice preserves the producer's state even when it is empty.
Three read guarantees belong in your debugging checklist:
- a slice is a valid log prefix segment, and a torn physical tail is never returned;
- repeated reads on the same handle never observe state older than a prior read;
- a write handle can read what it has successfully appended.
close() is the only teardown: idempotent, asynchronous, deliberately not cancellable, with Symbol.asyncDispose delegating to it. Any operation on a closed handle is rejected with SessionHandleClosedError. So do not reuse a handle for "one last read" after closing — that is guaranteed to fail.
append is best effort, flush is the durability barrier
append settles order and visibility; only flush settles crash survival.(source)
append(events) requires a contiguous batch whose first seq equals the stored next-seq, and committed events are never rewritten. On resolve it promises exactly this: the batch was accepted, ordered, and visible to reads on this backend instance. Nothing more — a backend may buffer or batch physical writes after append.
flush() is the durability barrier: on resolve, every acknowledged append is durable and the session is materialized for other processes; an empty created session becomes persistently listable at that moment. Callers that must survive a crash have to flush. A backend that already persists on append resolve can treat flush as on-demand materialization.
Visibility has two layers that are often confused:
- a created session is observable via
stat/list/openinside this process from the momentcreateresolves; - other processes see only materialized sessions, and a session never materialized before a crash effectively never existed.
That explains "the log is right here on my machine but gone on another": nothing was lost — it was never materialized.
Crash recovery hands open turns to the reader
Persistence does not repair open turns; it only guarantees physical validity, leaving closers to resume.(source)
A log that crashes mid-turn ends with an open turn/start and no turn/end. Persistence does not truncate or repair it, because a single turn of a long-running task can be enormous and those events were durably appended before the crash. It only discards incomplete fragments of a torn physical tail — the JSONL backend partially decodes a torn Zstandard frame and durably rewrites the recovered complete records before the handle's first new append.
Repair is the reader's job. resume (agent-loop) reads the stored log through a write handle, computes interruptedTurnClosers — missing tool errors, any unclosed step/end, and a synthetic turn/end { reason: { kind: 'interrupted' } } — and appends them as an ordinary batch through the same handle before publishing the Session.
Two corollaries: repair writes only under write ownership, so a concurrent open(id, 'write') is rejected rather than racing the active turn; read-only observers such as session-query balance a cold log in memory with the same closers and write nothing back. interrupted is also the only TurnEndReason the loop never emits itself.
SessionHeader and SessionLocation: metadata is not the log
Neither the header nor the location enters the event log or reaches deriveMessages().(source)
SessionHeader is stored separately from the event log and carries version, id, createdAt, optional cwd, parentSession, isSeeded, origin, delegationDepth, and agentPreset. The logical header attaches as session.header, while the exact fork-inherited prefix length is exposed as inheritedEventCount and is not ordinary header metadata.
Two fields invite misuse: origin: 'subagent' is only a display classification and does not prove the child can continue; and delegationDepth is persisted so recursion budgets survive restart and resume — track depth only at runtime and a recovered child looks like a top-level agent.
SessionLocation is narrower still: a backend-resolved per-session artifact path for diagnostics and snapshot export. It grants no read access and is not persisted content. JSONL provides the absolute transcript path inside the project/session directory; backends without per-session artifacts provide none.
Format rejection: data intact, this build cannot read it
Failure needs two names — unreadable and corrupt — because the handling differs completely.(source)
A backend rejects logs it cannot interpret reliably with SessionFormatUnsupportedError, which is distinct from SessionPersistenceCorruptionError because the data is not damaged. The specific rules:
statandlistclassify by highest canonical generation and convert supported historical headers without reading or changing the body;- historical
openshares one migration preparation per session, keeping every source path, byte, and inode unchanged; - a JSONL read open returns a handle from the in-memory result without publishing; a write open reuses that preparation while holding the single-writer claim and file lease, then exclusively publishes the final current generation;
- the highest future generation causes rejection even when older readable generations remain.
Current-format restore keeps installed extensions and unknown events carrying ignorable: true; historical v0/v1/v2 migration rejects unknown types even with that marker. That difference is part of migration safety — do not infer that ancient formats accept your ignorable flag.
Verification: hard-kill, then restart
Recovery verification requires a real hard kill; graceful exit cannot produce an open turn.(source)
createa write handle,appendaturn/startplus a few events, skipflush, and hard-kill the process.- After restart,
statthe id and assert the session may exist while the last batch is missing — this proves append is not durability. - Repeat, calling
flush()before the kill, and assert all events are present after restart. - Build a log with only
turn/startand noturn/end, recover it withresume, and assert a syntheticinterruptedend reason was appended. - Attempt
open(id, 'write')during recovery and assertSessionAlreadyOwnedError. - Open a log with a future generation and assert
SessionFormatUnsupportedError, not a corruption error.
For how the handle relates to the agent above it, see the persistence seam overview; for "sessions will not open after an upgrade," see session migration after update.
One line to close: all access goes through the handle, append settles order and visibility while flush settles crashes, open turns close in resume, and unreadable is not the same as corrupt.
FAQ
No. DSH plugin rejects it with SessionAlreadyOwnedError. In-process single-writer ownership protects the active session, so a second write open fails instead of racing an active turn.
No. DSH plugin's append is best effort: resolving promises the batch was accepted, ordered, and visible to reads on this backend instance. Only flush promises survival across a crash.
No. It only discards incomplete fragments of a torn physical tail. DSH plugin returns the open turn/start as-is; resume in agent-loop computes interruptedTurnClosers and appends them before publishing the Session.
No. DSH plugin separates the two with distinct errors. SessionFormatUnsupportedError means this build cannot interpret the log reliably while the data is intact; SessionPersistenceCorruptionError means real damage.
Related Terms
- SessionHandle
- SessionHandle is one open channel to a stored session, carrying all log access plus single-writer ownership, with read, append, flush, and close.— packages/session/session-persistence/src/index.ts
- SessionLocation
- SessionLocation is a backend-resolved per-session artifact path for diagnostics and snapshot export; it grants no read access and is not persisted content.— packages/session/session-persistence/src/index.ts
- SessionFormatUnsupportedError
- SessionFormatUnsupportedError signals that this build cannot interpret the log reliably, kept distinct from genuine data corruption.— DeepSeek Harness reference - Session persistence
- interruptedTurnClosers
- interruptedTurnClosers is the closing batch resume computes: missing tool errors, unclosed step/end events, and a synthetic interrupted turn/end.— DeepSeek Harness reference - Session persistence
Sources
- DeepSeek Harness reference - Session persistence· deepseek-ai
- packages/session/session-persistence/src/index.ts· deepseek-ai