ChatGPTClaudeGrok / X / CursorGemini

DSH plugin SessionHandle: flush barriers and crash recovery

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessSessionHandlePersistenceCrash recovery
DSH plugin session handle semantics: read slicing, append versus flush, two visibility layers, crash recovery closers, and format rejection paths.

"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:

  1. You cannot read or write events by id while bypassing a handle;
  2. One handle type serves both reading and writing; the access field separates them rather than two classes;
  3. 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/open inside this process from the moment create resolves;
  • 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:

  • stat and list classify by highest canonical generation and convert supported historical headers without reading or changing the body;
  • historical open shares 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)

  1. create a write handle, append a turn/start plus a few events, skip flush, and hard-kill the process.
  2. After restart, stat the id and assert the session may exist while the last batch is missing — this proves append is not durability.
  3. Repeat, calling flush() before the kill, and assert all events are present after restart.
  4. Build a log with only turn/start and no turn/end, recover it with resume, and assert a synthetic interrupted end reason was appended.
  5. Attempt open(id, 'write') during recovery and assert SessionAlreadyOwnedError.
  6. 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can a DSH plugin open a running session with write access?

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.

Does a resolved DSH plugin append mean the data is on disk?

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.

Does DSH plugin persistence auto-repair a crashed log?

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.

Is a DSH plugin format-unsupported error data corruption?

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