dsh-plugin-dev-kb 1.0.9 → 1.1.0

package/kb/site/en/reference/subsystems/persistence.md

@@ -5,31 +5,114 @@ outline: [2,3]
 
 # Session Persistence
 
-The **durability seam** for the event log. [session.md](./session.md) describes the in-memory `Session` — the append-only `SessionEvent` log that is the source of truth. This page describes how that log is made durable: the abstract `SessionPersistence` service, its backends, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated [persistence log event catalog](../persistence-catalog.md).
+The **durability seam** for the event log. [session.md](./session.md) describes the in-memory `Session` — the append-only `SessionEvent` log that is the source of truth. This page describes how that log is made durable: the abstract `SessionPersistence` service, its provider model and shipped JSONL backend, the flush checkpoint, crash recovery, and the metadata header that travels alongside the log. The event vocabulary the log carries is enumerated, member by member, in the generated [persistence log event catalog](../persistence-catalog.md).
 
-The seam is a [capability seam](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session/session-persistence), `ctx.sessionPersistence`) defining locate/create/append, reusable Session preparation, logical load/inspect, physical suffix reads, and lightweight list/snapshot observation over the existing `SessionEvent` — **no parallel persisted event type** — and three interchangeable providers implementing the same contract. See the [session-persistence Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
+The seam is a [capability seam](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-06-13-capability-seams.md): one abstract service ([dsh-session-persistence](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session/session-persistence), `ctx.sessionPersistence`) exposing `create`/`open`/`stat`/`list` over the existing `SessionEvent` — **no parallel persisted event type** — where `create` and `open` return a per-session `SessionHandle` (`read`/`append`/`flush`/`close`) that carries all log access and single-writer ownership. The repository ships [dsh-session-persistence-jsonl](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session/session-persistence-jsonl) as its provider; out-of-tree providers may implement the same service contract. See the [handle-based persistence Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md) and the [session-persistence Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-06-14-session-persistence.md).
+
+## `SessionHandle` — one open channel onto a stored session
+
+Every log read and write flows through a handle, never through id-addressed service methods: the handle is the single door the cross-process write lease guards. One handle type serves both accesses — a mutation on a `read` handle is a runtime `SessionReadOnlyError` rather than a typed split — and in-process single-writer ownership makes a second `open(id, 'write')` reject with `SessionAlreadyOwnedError` while an owner is active.
+
+```ts type-equiv
+/**
+ * One open channel onto a stored session. A handle is single-owner state, not
+ * a shared service: `read` never backtracks below what this handle already
+ * observed, a `write` handle reads its own successful appends, and `close()`
+ * is the one teardown (idempotent, uncancellable; `Symbol.asyncDispose`
+ * delegates to it). Every operation on a closed handle rejects with
+ * `SessionHandleClosedError`.
+ *
+ * Freshness across handles: once an `append` or `flush` resolves on a write
+ * handle, every read STARTED afterwards on the same backend instance — on any
+ * handle, or through `stat`/`list` — observes at least that prefix.
+ * Reads concurrent with a mutation carry no ordering promise beyond the valid
+ * contiguous prefix.
+ */
+interface SessionHandle extends AsyncDisposable {
+  /** The stored session this handle addresses. */
+  readonly id: SessionId
+  /** The immutable stored header, fixed at `create`/`open`. */
+  readonly header: SessionHeader
+  /**
+   * Exact fork-inherited prefix length stored with the log; `0` when
+   * `header.isSeeded` is false. Storage metadata paired with the header for
+   * every body read, never part of the replayable event log.
+   */
+  readonly inheritedEventCount: SessionLogOffset
+  /** Whether this handle may mutate the log. */
+  readonly access: SessionAccess
+
+  /**
+   * Read a slice of the valid contiguous logical log. The slice is a legal log
+   * prefix segment: a torn physical tail is never returned, and repeated reads
+   * on this handle never observe an older state than a prior read.
+   * @param offset - first logical event seq to include; defaults to `0`.
+   * @param length - maximum number of events to return; defaults to the rest
+   *   of the log. An offset at or past the end returns an empty list.
+   * @param options - optional cancellation.
+   * @returns the events with `seq >= offset`, at most `length` of them.
+   */
+  read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<readonly SessionEvent[]>
+
+  /**
+   * Append a contiguous batch continuing the current logical end. The first
+   * event's `seq` MUST equal the stored next-seq; committed events are never
+   * rewritten. Persistence is best-effort: on resolution the batch is
+   * accepted, ordered, and visible to reads on this backend instance, but
+   * only a resolved {@link flush} promises it survives a crash — a backend
+   * may buffer or batch physical writes behind append. Rejects with
+   * `SessionReadOnlyError` on a read handle and `SessionOwnershipLostError`
+   * when write ownership is gone.
+   * @param events - the contiguous batch, in seq order.
+   * @param options - optional cancellation observed before the write starts.
+   */
+  append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>
+
+  /**
+   * The durability barrier — the one operation that promises storage: on
+   * resolution every acknowledged append is durable and the session is
+   * materialized for other processes; an empty created session becomes
+   * durably listable here. Callers that must survive a crash flush; a backend
+   * whose `append` already persists on resolution treats this as
+   * materialize-if-needed. Rejects with `SessionReadOnlyError` on a read
+   * handle.
+   * @param options - optional cancellation observed before the barrier starts.
+   */
+  flush(options?: SessionHandleFlushOptions): Promise<void>
+
+  /**
+   * Release the handle: a read handle frees local resources; a write handle
+   * completes pending durability and releases write ownership. Idempotent,
+   * asynchronous, and deliberately not cancellable.
+   */
+  close(): Promise<void>
+}
+```
+
+A created session is observable in this process from the moment `create` resolves, while a backend may defer physical materialization (a pure optimization) until the first `append` or `flush`; other processes see only materialized sessions, and a session that never materialized before a crash never existed.
 
 ## The flush checkpoint
 
-`session/event` is a *synchronous* notification; persistence plugins copy the event into a per-session controller without blocking the producer. The first pending event starts a fixed batching window, and later events join without resetting its deadline. Expiry starts one durable batch; events admitted during that write receive their own deadline and form a follow-up batch. `session/flush` cancels the wait and drains through quiescence, so the loop still uses it as the ordering and error-observation checkpoint before claiming the next ordinary turn. A rejected background write retains its events and pauses automatic retry; a new event starts a fresh window, while explicit flush retries immediately and reports failure through `agent/error` and the logger, never as a session event past the closed turn. Disposal performs the same final drain. The configured maximum bounds only intentional batching wait, not event-loop scheduling or backend durability latency ([decision](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
+`session/event` is a *synchronous* notification; the mounted backend routes it by session id into the active write handle's bounded write-behind window without blocking the producer (the backend installs these listeners once, because persistence already enforces one active write handle per id). The first pending event starts a fixed internal batching window, and later events join without resetting its deadline. Expiry starts one durable `append` through the session's write handle; events admitted during that write receive their own deadline and form a follow-up batch. `session/flush` cancels the wait and drains through quiescence, so the loop still uses it as the ordering and error-observation checkpoint before claiming the next ordinary turn. A rejected background write retains its events in order, pauses the automatic path, and is reported through the logger; the next explicit flush retries and rejects loudly to its caller. `session/disposed` performs the same final drain and closes the handle, and `close()` itself drains the routed buffer through the still-open storage, so backend teardown's close sweep loses nothing. The window bounds only intentional batching wait, not event-loop scheduling or backend durability latency ([decision](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)).
 
 ## Crash recovery preserves an interrupted turn
 
-A backend that reloads a log crashed mid-turn finds an open `turn/start` with no `turn/end`. It does **not** truncate — a single turn can be huge in a long-horizon task (many steps, large tool output), and those events were durably appended before the crash. Instead it closes the orphaned turn with a synthetic `turn/end { reason: { kind: 'interrupted' } }`, keeping the interrupted execution balanced without changing any standalone events before or after it. `interrupted` is the one `TurnEndReason` no loop emits (see [session.md](./session.md#why-a-turn-ended-turnendreasonmap)).
+A log crashed mid-turn ends with an open `turn/start` and no `turn/end`. Persistence does **not** truncate or repair it — a single turn can be huge in a long-horizon task (many steps, large tool output), and those events were durably appended before the crash. It returns the physically valid contiguous log; only the incomplete fragment of a torn physical tail, belonging to an append that never resolved, is discarded — complete records recovered from it (the JSONL backend partially decodes a torn Zstandard frame) are durably rewritten by the write path before the handle's first new append. Repair is the reader's job: resume (agent-loop) reads the stored log through its write handle, computes `interruptedTurnClosers` — missing tool errors, any open `step/end`, and a synthetic `turn/end { reason: { kind: 'interrupted' } }` — and appends them through the same handle as an ordinary batch before publishing the Session. `interrupted` is the one `TurnEndReason` no loop emits (see [session.md](./session.md#why-a-turn-ended-turnendreasonmap)).
 
-Repair applies only to cold sessions. For a live id, `SessionPersistence.load(id)` waits until the authoritative in-memory snapshot is durable and returns it only when balanced; an open live turn rejects rather than receiving synthetic interruption boundaries. HMR adopts a live prefix without closing its active turn.
+Repair therefore writes only under write ownership: a live session's write handle is held by its lifecycle owner, so a concurrent `open(id, 'write')` rejects with `SessionAlreadyOwnedError` instead of racing repair against a live turn. Read-only observers (session-query) balance an interrupted cold log with the same closers in memory only, writing nothing back.
 
-`SessionPersistence.inspect(id)` constructs an immutable logical Session without publishing it or writing recovery. Cold inspection balances an interrupted turn in memory while leaving torn physical tails untouched; inspection of an already-live Session borrows its current immutable snapshot and may therefore contain an open turn. Coordinator-backed implementations retain the exact cold unpublished Session in a bounded LRU, so repeated history reads and a later `prepare(id)` share one read, decompression, validation, freeze, and Session construction. `prepare(id)` reserves the Session, commits pending repair, and returns a disposable publication handle; `load(id)` uses the same machinery to commit repair without publication. The [Session preparation decision](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md) owns this lifecycle.
+Read-only observation is `open(id, 'read')`: the handle serves validated contiguous prefix slices, never a torn tail, and repeated reads on one handle never observe an older state than a prior read. There is no persistence-side prepared-Session cache: session-query owns its cold-read cache, keying one balanced cold Session per id on the `stat().revision` change token and re-reading only when the token changes. The [handle-based persistence Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.md) owns this lifecycle; the [Session preparation decision](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-05-session-preparation.md) records the publication-boundary `SessionPreparation` that remains.
 
-## `SessionLocation` — optional per-session artifact target
+## `SessionLocation` — refusal-diagnostics artifact target
 
-`SessionPersistence.locate(meta)` synchronously resolves a backend-owned independent artifact without reading, creating, or flushing it. JSONL returns the absolute transcript path inside its project/session directory; SQLite returns `undefined` because sessions share one database. A returned path can therefore name a file that does not yet exist or lacks the current unflushed turn; it is a location hint, not authorization or a freshness guarantee.
+`SessionLocation` is not a consumer-facing query: log access goes through a session handle's `read`. It survives only as refusal diagnostics, letting a `SessionFormatUnsupportedError` name the raw log a build refused to interpret. JSONL supplies the absolute transcript path inside its project/session directory; a backend without one artifact per session supplies nothing.
 
 ```ts type-equiv
 /**
- * A backend-resolved, per-session local artifact location. The path is an
- * absolute target path and can name an artifact that has not materialized yet.
- * Consumers must treat it as a location hint, never as an authorization token.
+ * A backend-resolved, per-session local artifact location. Carried only by
+ * refusal diagnostics ({@link SessionFormatUnsupportedError}) so a user can
+ * find the raw log a build refused to interpret; it is not a consumer-facing
+ * query — log access goes through a session handle's `read`.
  */
 interface SessionLocation {
   /** Backend-specific artifact kind, for example `jsonl`. */
@@ -43,7 +126,7 @@ interface SessionLocation {
 
 ## `SessionHeader` — metadata beside the log
 
-Per-session metadata travels **separately** from the event log: format version, cwd, lineage, and the seed boundary are storage concerns, not conversation events, so they stay out of `SessionEventMap` and never reach `deriveMessages()`. The header is attached to a `Session` via `session.header`.
+Per-session metadata travels **separately** from the event log: the header carries format version, cwd, and the `isSeeded` lineage bit, while body-bearing storage values carry the exact inherited cut beside it. Neither belongs to `SessionEventMap` or reaches `deriveMessages()`. The logical header is attached through `session.header`; the Session exposes its cut as `inheritedEventCount`.
 
 Source: [`packages/core/session/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/session/src/types.ts)
 
@@ -53,11 +136,10 @@ Source: [`packages/core/session/src/types.ts`](https://github.com/deepseek-ai/de
  */
 interface SessionHeader {
   /**
-   * On-disk format version, stamped from {@link SESSION_FORMAT_VERSION} when the
-   * session is created. A persistence backend rejects any other version on load
-   * (no migration — see the constant).
+   * Current logical format version, stamped from {@link SESSION_FORMAT_VERSION}.
+   * Historical physical headers are translated before entering this interface.
    */
-  readonly version: number
+  readonly version: typeof SESSION_FORMAT_VERSION
   /** The session's id (mirrors the {@link Session}'s id). */
   readonly id: SessionId
   /** Non-negative safe-integer Unix epoch milliseconds when the session was created. */
@@ -67,10 +149,10 @@ interface SessionHeader {
   /** The session this one was forked from (seed lineage), if any. */
   readonly parentSession?: SessionId
   /**
-   * How many leading events were inherited through a seed. Persisting this
-   * boundary lets resume and replay distinguish parent history from child work.
+   * Whether this Session contains a fork-inherited event prefix. The exact prefix
+   * length is Session state rather than ordinary header metadata.
    */
-  readonly seedLength?: number
+  readonly isSeeded: boolean
   /**
    * Coarse product classification for a session created as a subagent child.
    * This is presentation metadata, not proof that the child is continuable.
@@ -94,11 +176,11 @@ interface SessionHeader {
 
 ## Format refusal — logs a build cannot faithfully read
 
-A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupportedError`, distinct from `SessionPersistenceCorruptionError` because nothing is damaged. A header `version` ahead of `SESSION_FORMAT_VERSION` names the direction ("written by a newer harness — upgrade the harness to open it"); one behind it states that this build ships no upgrade path. After legacy-shape normalization, an event type outside this build's generated set (`KNOWN_SESSION_EVENT_TYPES`, emitted by `gen-persistence-catalog`) also refuses reconstruction because silently skipping it could change how the rest of the log must be read. The message appends the raw log path when the backend keeps one artifact per session, so the refused text stays reachable. The JSONL backend refuses a foreign version straight from the raw header line, before validating this format version's header fields or decoding any event row — a structurally different future format still reports the upgrade direction, never "corrupt"; SQLite gates whole-file structure through its own `SCHEMA_VERSION` pragma first. Design rationale and the deferred upgrader chain live in the [fail-closed event-vocabulary note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/simplification/2026-08-25-fail-closed-session-event-vocabulary.md).
+A backend refuses a log it cannot faithfully interpret with `SessionFormatUnsupportedError`, distinct from `SessionPersistenceCorruptionError` because nothing is damaged. `stat` and `list` classify the highest canonical generation and translate a supported historical header without reading or mutating its body. `open` runs the build-static adjacent migration chain under per-id serialization before returning a handle, leaves every source path, byte, and inode unchanged, and exclusively publishes only the final current generation. A future highest generation refuses even when an older readable generation remains. Current v2 restoration retains installed extensions and unknown events carrying `ignorable: true`; historical v0/v1 migration refuses an unknown type even when marked ignorable. The message appends the selected raw log path when the backend keeps one artifact per session. The JSONL backend migrates released v0 or v1 to current v2 and refuses a future version before interpreting its version-specific fields or event rows. An out-of-tree backend must enforce equivalent current-only handle values and direction-aware refusals at its physical-format entry. The [released-format migration decision](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.md) owns the chain and immutable-publication rules.
 
 ## `CreateSessionOptions` — seeding and metadata
 
-Creating a `Session` through the store takes a `seed` (initial replay or fork history) and `meta` (the storage-level fields the store folds into a `SessionHeader`). The store fills in `version`/`id` and defaults `createdAt`; the caller may supply the validated absolute `cwd`, the `parentSession` lineage, the `seedLength` seed boundary, the optional coarse `origin`, the `delegationDepth`, the `agentPreset` the agent was composed from, and an existing `createdAt`. `origin: 'subagent'` lets product navigation hide duplicate child rows; it does not prove that a descriptor is valid or that the child can resume.
+Creating a `Session` through the store takes a `seed` (initial replay or fork history), an optional exact `inheritedEventCount`, and `meta` (the storage-level fields the store folds into a `SessionHeader`). The store fills in `version`/`id` and defaults `createdAt`; the caller may supply the validated absolute `cwd`, `parentSession` lineage, `isSeeded` lineage bit, optional coarse `origin`, `delegationDepth`, `agentPreset`, and an existing `createdAt`. A seeded creation requires an explicit seed equal to its inherited prefix and an exact cut; the constructor appends the child-owned tagged end-seed marker at that cut before setup adds child-owned events. `origin: 'subagent'` lets product navigation hide duplicate child rows; it does not prove that a descriptor is valid or that the child can resume.
 
 ```ts type-equiv
 /**
@@ -110,14 +192,20 @@ interface CreateSessionOptions {
   /** Initial replay or fork history supplied at construction. */
   readonly seed?: readonly SessionEvent[]
   /**
-   * Storage metadata read once before publication. `seedLength` is explicit
-   * because a resumed seed contains the full stored log, not only its inherited prefix.
+   * Exact fork-inherited prefix length when `meta.isSeeded` is true. In v2 the
+   * constructor seed is exactly this inherited prefix; the constructor
+   * appends the child-owned tagged marker at the cut.
+   */
+  readonly inheritedEventCount?: SessionLogOffset
+  /**
+   * Storage metadata read once before publication. `isSeeded` marks fork
+   * lineage; supplying replay history alone does not make it inherited.
    */
   readonly meta?: {
     readonly cwd?: string
     readonly parentSession?: SessionId
     readonly createdAt?: number
-    readonly seedLength?: number
+    readonly isSeeded?: boolean
     readonly origin?: 'subagent'
     readonly delegationDepth?: number
     readonly agentPreset?: string
@@ -125,27 +213,11 @@ interface CreateSessionOptions {
 }
 ```
 
-Replay/fork is therefore `ctx.sessions.create(id, { seed: seedEvents })`; resuming a *persisted* session into a live agent is `ctx.agents.resume({ resumeSessionId })`.
-
-## `SessionRawArtifact` — verbatim stored artifact text
-
-A backend's own artifact text for one session, byte-identical to what it durably wrote (decoded from its physical encoding). `readRaw` returns it without reconstructing from parsed events, so backend-specific serialization (chunk packing, key order, line breaks) survives. Consumers first test `supportsRawArtifacts`: `false` means the backend does not provide this capability (for example SQLite), while `readRaw(...) === undefined` means a supported backend has no materialized artifact for that session.
-
-```ts type-equiv
-/** A backend's own raw artifact text for one session, verbatim. */
-interface SessionRawArtifact {
-  /** The session header parsed from the artifact's own first line. */
-  readonly meta: SessionHeader
-  /** The artifact's base filename on disk, without any physical encoding suffix. */
-  readonly filename: string
-  /** The artifact's full text content, decoded from the backend's physical encoding. */
-  readonly content: string
-}
-```
+Replay/fork is therefore `ctx.agents.create({ sessionId, seed, meta })` — a fork additionally supplies `inheritedEventCount` with `meta.isSeeded: true`, and only agent-loop-published sessions persist, and the loop stores the seed through the new session's write handle before publication; resuming a *persisted* session into a live agent is `ctx.agents.resume({ resumeSessionId })`.
 
 ## Preparation and restoration ownership
 
-`SessionStore.prepare()` accepts ordinary creation options or fresh persistence graphs transferred through `RestoredSessionOptions`. The restoration branch validates and freezes the transferred header and events in place, so callers must retain no mutable aliases. `SessionPreparation` then owns the exact unpublished Session until publication or rollback; disposal is synchronous and idempotent. Persistence inspection exposes only `SessionInspection`, an immutable logical view borrowed from the same prepared Session.
+`SessionStore.prepare()` accepts ordinary creation options or fresh persistence graphs transferred through `RestoredSessionOptions`. The restoration branch validates and freezes the transferred header and events in place, so callers must retain no mutable aliases. `SessionPreparation` then owns the exact unpublished Session until publication or rollback; disposal is synchronous and idempotent. agent-loop's resume builds these graphs by reading the stored log through the session's write handle and appending any needed `interruptedTurnClosers` before preparation.
 
 ```ts type-equiv
 /**
@@ -157,6 +229,8 @@ interface RestoredSessionOptions {
   readonly seed: SessionEvent[]
   /** Fresh detached storage metadata to validate and freeze in place. */
   readonly meta: SessionHeader
+  /** Exact number of fork-inherited leading events decoded from storage. */
+  readonly inheritedEventCount: SessionLogOffset
   /** Select the persistence ownership-transfer path. */
   readonly seedSource: 'persistence'
 }
@@ -199,19 +273,9 @@ declare class SessionPreparation implements Disposable {
 }
 ```
 
-```ts type-equiv
-/** Immutable logical session prepared from persistence or a live owner. */
-interface SessionInspection {
-  /** Validated immutable session metadata. */
-  readonly meta: SessionHeader
-  /** Validated contiguous logical event log. */
-  readonly events: readonly SessionEvent[]
-}
-```
-
 ## Lightweight source revisions
 
-Consumers of derived state compare a cheap opaque revision before loading a full event log. The persistence backend owns its representation and changes it transactionally with append or mutating load repair; callers compare it only for equality.
+Consumers of derived read models compare a cheap opaque revision before loading a full event log. The revision is a per-backend-instance change token from `stat`/`list`: equal revisions may be treated as an unchanged log; unequal revisions promise nothing, and write-ownership churn never changes one. session-query keys its cold-read cache on it; the token plays no part in open, read, or resume.
 
 ```ts type-equiv
 /**
@@ -222,21 +286,29 @@ type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>
 ```
 
 ```ts type-equiv
-/** Lightweight immutable source identity returned without loading a full log. */
+/**
+ * Lightweight stored-session observation returned by {@link SessionPersistence.stat}
+ * and {@link SessionPersistence.list} without reading the full event log.
+ */
 interface SessionPersistenceSnapshot {
-  /** Detached metadata for one materialized session. */
-  header: SessionHeader
-  /** Opaque source-qualified token that changes whenever this stored log changes. */
-  revision: SessionPersistenceRevision
+  /** Detached metadata for one stored session. */
+  readonly header: SessionHeader
+  /** Opaque change token; see {@link SessionPersistence.stat}. */
+  readonly revision: SessionPersistenceRevision
+  /** Logical event count, when the backend can provide it cheaply from metadata; otherwise absent. */
+  readonly eventCount?: number
+  /** Physical artifact byte size, when the backend can provide it cheaply (JSONL); otherwise absent. */
+  readonly sizeBytes?: number
 }
 ```
 
-## The backends
+The optional `eventCount`/`sizeBytes` fields remain cheap backend observations for consumers that explicitly need them. Session listing does not use either field to open cold logs: it reads headers plus identity-checked projection-cache hints only, so a cache or Session-format upgrade never turns startup into a body scan.
 
-All implement the same abstract `SessionPersistence` (locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots over `SessionEvent`, with optional cancellation on observation methods) and pass the shared `runPersistenceContract` suite:
+## The backend
 
-- **[dsh-session-persistence-jsonl](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic writes, interrupted-turn recovery, and a read/replay path.
-- **[dsh-session-persistence-sqlite](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session/session-persistence-sqlite)** — an opt-in `node:sqlite` backend using schema 19 to store exact same-block delta runs in bounded physical `text-chunks`, `reasoning-chunks`, and `tool-call-chunks` rows. It reconstructs the complete logical event stream before returning it, packs only newly durable batches, and rejects older schemas rather than migrating them.
+The shipped provider implements the abstract `SessionPersistence` contract (`create`/`open`/`stat`/`list`, with per-session `SessionHandle`s carrying `read`/`append`/`flush`/`close` and optional cancellation throughout) and passes the shared persistence contract suite:
+
+- **[dsh-session-persistence-jsonl](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/session/session-persistence-jsonl)** — an append-only logical JSONL log per session, stored as checksummed concatenated Zstandard frames by default or raw lines by configuration, with crash-safe atomic materialization, per-batch `fsync` appends, and torn-tail truncation before the first new append. `stat`/`list` carry `sizeBytes` and a best-effort `fs.stat`-derived revision.
 
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
@@ -250,158 +322,77 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
 
-Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events.
-
-```ts cordis-catalog
-/**
- * Resolve this backend's independent local artifact for a session without
- * reading, creating, flushing, or otherwise materializing it. Backends such
- * as SQLite that do not own one artifact per session return `undefined`.
- * @param meta - the immutable session header whose artifact is requested.
- * @returns the backend-specific absolute location, when one exists.
- */
-abstract locate(meta: SessionHeader): SessionLocation | undefined
-
-/**
- * Read a session's backend-owned artifact text verbatim — the exact durable
- * bytes the backend wrote (decoded from its physical encoding, e.g. a
- * decompressed JSONL). The returned `content` is the raw text, not a
- * reconstruction from parsed events, so it preserves backend-specific
- * serialization (chunk packing, key order, line breaks). Callers first test
- * {@link supportsRawArtifacts}; `undefined` then means only that the requested
- * session has no materialized artifact.
- * @param _id - the persisted session to read (unused by the default: no
- * per-session artifact).
- * @param signal - optional cancellation for backend read work.
- * @returns the raw artifact plus its parsed header, or `undefined` when the
- * session is absent.
- * @throws when this backend does not expose per-session raw artifacts.
- */
-readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>
-
-/**
- * Register a new session's metadata. A backend MAY defer the physical write
- * until the first {@link append} (lazy materialization), in which case a
- * created-but-never-appended session is absent from {@link list}
- * — abandoned sessions leave nothing behind.
- * @param meta - the immutable header (id, version, cwd, lineage) to record.
- */
-abstract create(meta: SessionHeader): Promise<void>
-
-/**
- * Ensure a live session has a durable header even when it has no events.
- * Ordinary sessions remain lazily materialized; lifecycle frontends call
- * this only when an empty session itself is a durable resumable resource.
- * @param _session - exact live session whose registered header is materialized.
- */
-ensureMaterialized(_session: Session): Promise<void>
+Durable append-only session storage addressed through per-session handles.
 
-/**
- * Durably persist a batch of events. Honors the append-only and contiguous-
- * seq contracts: the first event's `seq` MUST equal the stored next-seq
- * (after `load` has durably closed any interrupted turn). Rejects non-JSON-
- * serializable `event.data` with an error naming the offending event type.
- * @param id - the session the batch belongs to.
- * @param events - the contiguous batch to persist, in seq order.
- */
-abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
+Storage semantics shared by every backend: events are contiguous from seq 0 and never rewritten; a torn physical tail is never returned to a reader and is truncated by the write path before its first append; reads validate current-format records only and refuse unknown vocabulary fail-closed. `append` persists best-effort; `flush` — per handle or service-wide — is the durability barrier.
 
-/**
- * Prepare the exact unpublished Session used by resume. Implementations may
- * reuse object graphs retained by an earlier {@link inspect} after confirming
- * their durable revision is still current; disposal releases an unpublished
- * reservation. Revision retries require the durable log to remain unchanged
- * for one read/check round trip; continuous external writers may delay completion.
- * @param id - persisted session to prepare.
- * @param signal - optional cancellation for preparation work.
- * @returns one owned unpublished Session preparation.
- */
-async prepare(id: SessionId, signal?: AbortSignal): Promise<SessionPreparation>
+Visibility: a created session is observable through `stat`/`list`/`open` in this process from the moment `create` resolves, even while a backend defers physical materialization (a pure optimization); other processes see the session only once it materializes, and a session that never materialized before a crash never existed. `SessionHandle.flush` forces materialization.
 
-/**
- * Load an immutable balanced logical view and commit any required cold
- * recovery. A complete interrupted final turn is preserved and durably
- * closed with missing tool errors plus any open step and turn boundaries;
- * only a torn final record is discarded. Unknown versions and corruption in
- * the committed prefix reject. Implementations MUST NOT crash-repair an
- * identity still bound to a live Session: a balanced live log may return as a
- * durable snapshot, while an open live turn rejects. Returned values may be
- * shared with immutable live or prepared state and must not be mutated.
- * Revision-based implementations may wait for one stable read/check round trip.
- * @param id - the persisted session to reload.
- * @returns the header and a log ending on a balanced `turn/end`.
- */
-abstract load(id: SessionId): Promise<SessionInspection>
+Freshness: once an `append` or `flush` resolves, reads started afterwards on this backend instance observe at least that prefix.
 
+```ts cordis-catalog
 /**
- * Inspect an immutable logical session without committing recovery or
- * publishing it. A cold complete interrupted turn receives synthetic closers
- * in memory and a torn physical tail remains untouched. An already-live
- * Session instead yields its current immutable snapshot, which may contain an
- * open turn and its `session/end-seed` boundary. Coordinator-backed
- * implementations retain the exact cold unpublished Session for bounded
- * reuse by a later {@link prepare}. A stale ready source is reloaded; a source
- * already committing or reserved for resume remains exclusive, and inspection
- * may borrow its immutable view. Callers borrow only the immutable header and
- * log. Continuous external writers may delay revision convergence.
- * @param id - the persisted session to inspect.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns the validated header and current logical event log.
+ * Create a new stored session and take its write ownership.
+ * @param header - the immutable header (id, version, cwd, lineage) to store.
+ * @param options - optional cancellation.
+ * @returns a `write` handle owned by the caller; close it to release ownership.
+ * @throws {SessionAlreadyExistsError} when the id already exists.
  */
-abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
+abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>
 
 /**
- * Borrow one exact inspection while retaining any reusable prepared source.
- * A cold observation must pin the exact prepared Session that a later
- * {@link prepare} reserves. Implementations must not degrade this operation
- * to a detached {@link inspect} result.
- * @param id - persisted session to observe.
- * @param signal - optional cancellation for preparation work.
- * @returns a disposable immutable observation.
+ * Open an existing stored session.
+ *
+ * `read` never takes ownership and works while another handle (or process)
+ * holds write ownership. `write` atomically claims single-writer ownership;
+ * an existing active owner rejects.
+ * @param id - the stored session to open.
+ * @param access - `read` or `write`.
+ * @param options - optional cancellation.
+ * @returns the open handle.
+ * @throws {SessionPersistenceNotFoundError} when the session does not exist.
+ * @throws {SessionAlreadyOwnedError} for `write` when ownership is taken.
  */
-abstract borrowSession(id: SessionId, signal?: AbortSignal): Promise<BorrowedSessionSource>
+abstract open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>
 
 /**
- * Read the stored events from `fromSeq` onward — the read-from-seq
- * primitive for read models that resume from a watermark (e.g. a persisted
- * projection cache folding only the tail past its checkpoint). Unlike
- * {@link inspect}, it is a detached physical suffix read: no preparation
- * cache, torn-tail truncation, synthetic closers, or coordinator-state
- * publication. Only events from the valid contiguous stored prefix are
- * returned, so a torn fragment never reaches the caller. `fromSeq` at or
- * beyond the stored prefix returns an empty event list (never an error).
- * Backends whose medium can seek by seq
- * (SQLite) read only the suffix; sequential media (JSONL, both encodings)
- * still parse the whole artifact and skip forward — the primitive bounds
- * what is RETURNED and refolded, not every backend's physical read.
- * @param id - the persisted session to read.
- * @param fromSeq - first event seq to include; a non-negative safe integer.
- * @param signal - optional cancellation for queued and backend read work.
- * @returns the header and the stored events with `seq >= fromSeq`.
+ * Flush every active write handle owned by this service instance in one
+ * durability barrier: each handle's routed live events drain durably and
+ * its session materializes, exactly as that handle's own
+ * `SessionHandle.flush` would. Read handles buffer nothing and are
+ * untouched. A handle closed concurrently counts as flushed — close itself
+ * drains durably.
+ * @returns resolution once every write handle active at the call has flushed.
+ * @throws {AggregateError} naming each session whose flush failed; the
+ *   remaining handles still flush.
  */
-abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+abstract flush(): Promise<void>
 
 /**
- * Lightweight listing from metadata, without a full-log parse.
- * @param signal - optional cancellation for backend listing work.
- * @returns one header per materialized session.
+ * Observe one stored session without reading its event log or taking
+ * ownership.
+ *
+ * The snapshot's `revision` is an opaque change token comparable only
+ * against revisions from the same service instance and session id: equal
+ * revisions may be treated as an unchanged log; unequal revisions promise
+ * nothing. Write-ownership churn does not change a revision. It exists for
+ * derived read-model caches keyed off `stat`/`list`; it plays no part in
+ * open, read, or resume.
+ * @param id - the stored session to observe.
+ * @param options - optional cancellation.
+ * @returns the snapshot, or `undefined` when the session does not exist.
  */
-abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
+abstract stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>
 
 /**
- * List materialized sessions with cheap per-log change tokens.
- *
- * Repeated observations of an unchanged log return the same revision. A
- * successful mutating {@link load} repair changes the next listed revision.
- * Revisions also distinguish independently backed stores so backend-local
- * counters cannot compare equal across different persistence sources.
- * @param signal - optional cancellation for backend snapshot-listing work.
- * @returns one header and opaque revision per materialized session without loading full logs.
+ * List every stored session visible to this process, in no promised order.
+ * @param options - optional cancellation.
+ * @returns one snapshot per stored session.
  */
-abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
+abstract list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>
 ```
 
-Types: [Session](./session.md) · [SessionEvent](./session.md) · [SessionId](./core.md)
+Types: [SessionId](./core.md)
 
 Source: [`packages/session/session-persistence/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/session/session-persistence/src/index.ts)
 <!-- END GENERATED cordis-surface -->

package/kb/site/en/reference/subsystems/plan.md

@@ -11,7 +11,7 @@ Source: [`packages/plan/plan-mode/src/index.ts`](https://github.com/deepseek-ai/
 
 ## Logged state and recovery
 
-`plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace [session event](./session.md): durable and replayable, never in the model transcript. `foldPlanMode(events, end?)` returns the last logged value in the prefix, or `false` when there is none — the state in force is always a pure fold of the session log, so resume, fork, and compaction recover it with no live mirror, and UIs observe committed flips through `session/event`. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md).
+`plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace [session event](./session.md): durable and replayable, never in the model transcript. The optionally registered `plan` unit folds committed mode, command settlement, and the mode recorded at the latest request header. `ctx.planMode` reads that state through `stateOf()`; the first dependent access fails if the registry, `plan` key, or `turnBoundary` key is absent. Clients receive only `{ active, pending }`; resume, fork, and compaction recover both from the log. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md).
 
 ## Pending selections and the pre-step append
 
@@ -29,7 +29,7 @@ interface PlanModeConfig {
 }
 ```
 
-A missing, blank, or non-string `section` and any unknown key fail at plugin load rather than being ignored. While plan mode is active, the exact `section` text renders as the `plan:policy` [system-prompt section](./system-prompt.md) at first-party order 500; inactive plan mode contributes no text.
+A missing, blank, or non-string `section` and any unknown key fail at plugin load rather than being ignored. While plan mode is active, the exact `section` text renders as the `plan:policy` [system-prompt section](./system-prompt.md) at order 50; inactive plan mode contributes no text.
 
 ## The exit tool and the `/plan` command
 
@@ -53,7 +53,7 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 
 ### `ctx.planMode` — `PlanModeController`
 
-`ctx.planMode`: owns logged plan state, applies and narrates selected state at step start, the `plan:policy` section, the `/plan` command, and the stable exit tool. UIs observe committed flips through `session/event`; there is no live mirror.
+`ctx.planMode`: owns logged plan state, applies and narrates selected state at step start, the `plan:policy` section, the `/plan` command, and the stable exit tool. Client carriers expose the projection's cropped `{ active, pending }` view.
 
 ```ts cordis-catalog
 /**

package/kb/site/en/reference/subsystems/sandbox.md

@@ -96,6 +96,8 @@ interface SandboxPolicy extends SandboxExecutionPolicy {
 }
 ```
 
+<a id="wrapped-argv-and-classification-dialects"></a>
+
 ## Wrapped argv and classification dialects
 
 `RunnerFailureRule` combines evidence that a runner failed before executing the command. A consumer requires a nonzero exit, the optional allowed-exit-code gate, and a case-insensitive fatal signature within one remaining stderr line. Case-insensitive exact full-line informational exclusions are removed first, so a benign runner notice cannot prove failure by itself. The matched line remains available as error detail; classification does not rewrite stderr.