dsh-plugin-dev-kb 1.0.0

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

@@ -0,0 +1,388 @@
+---
+editSource: "docs/subsystems/persistence.md"
+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 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 two interchangeable backends 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 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)).
+
+## 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)).
+
+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.
+
+`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.
+
+## `SessionLocation` — optional per-session 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.
+
+```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.
+ */
+interface SessionLocation {
+  /** Backend-specific artifact kind, for example `jsonl`. */
+  readonly kind: string
+  /** Absolute path to this session's backend-owned artifact. */
+  readonly path: string
+}
+```
+
+<a id="sessionheader--metadata-beside-the-log"></a>
+
+## `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`.
+
+Source: [`packages/core/session/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/core/session/src/types.ts)
+
+```ts type-equiv
+/**
+ * Immutable validated storage metadata, kept outside the conversation event log.
+ */
+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).
+   */
+  readonly version: number
+  /** 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. */
+  readonly createdAt: number
+  /** Absolute working directory the session was created in (if any). */
+  readonly cwd?: string
+  /** 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.
+   */
+  readonly seedLength?: number
+  /**
+   * Coarse product classification for a session created as a subagent child.
+   * This is presentation metadata, not proof that the child is continuable.
+   */
+  readonly origin?: 'subagent'
+  /**
+   * Delegation depth: absent (zero) for a top-level session, parent depth + 1
+   * for a subagent child. Persisted so a recursion budget survives restart and
+   * resume — a runtime-only depth would reset a resumed child to top-level.
+   */
+  readonly delegationDepth?: number
+  /**
+   * Id of the agent preset this session's agent was composed from, when the
+   * deployment composes per session. Durable because the preset decides the
+   * session's tools and prompt: a resume that restored a different composition
+   * would replay history the model can no longer act on.
+   */
+  readonly agentPreset?: string
+}
+```
+
+## 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 vocabulary (`KNOWN_SESSION_EVENT_TYPES`, emitted by `gen-persistence-catalog`) refuses the same way unless the event's envelope carries `ignorable: true` — silently skipping an unrecognized required event 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 today's header shape 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 [session-log-version-mechanism note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md).
+
+## `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.
+
+```ts type-equiv
+/**
+ * Options for creating a {@link Session} via the store. `seed` replays/forks
+ * an existing event log; `meta` carries the caller-supplied storage fields the
+ * store folds into a {@link SessionHeader}.
+ */
+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.
+   */
+  readonly meta?: {
+    readonly cwd?: string
+    readonly parentSession?: SessionId
+    readonly createdAt?: number
+    readonly seedLength?: number
+    readonly origin?: 'subagent'
+    readonly delegationDepth?: number
+    readonly agentPreset?: string
+  }
+}
+```
+
+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
+}
+```
+
+## 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.
+
+```ts type-equiv
+/**
+ * Fresh storage values transferred to {@link SessionStore.prepare} without a
+ * second serialization copy. Callers retain no mutable aliases.
+ */
+interface RestoredSessionOptions {
+  /** Fresh detached storage events to validate and freeze in place. */
+  readonly seed: SessionEvent[]
+  /** Fresh detached storage metadata to validate and freeze in place. */
+  readonly meta: SessionHeader
+  /** Select the persistence ownership-transfer path. */
+  readonly seedSource: 'persistence'
+}
+```
+
+```ts type-equiv
+/** Inputs accepted while constructing an unpublished Session. */
+type PrepareSessionOptions =
+  | (CreateSessionOptions & { readonly seedSource?: undefined })
+  | RestoredSessionOptions
+```
+
+```ts type-equiv
+/** Options for a preparation whose provider retains unpublished state. */
+interface SessionPreparationOptions {
+  /** Release provider-owned state when the Session was not published. */
+  readonly release?: () => void
+}
+```
+
+```ts public-api
+/**
+ * One exact unpublished Session and the provider state that keeps it usable.
+ * Disposal is synchronous and idempotent. Providers decide whether release
+ * returns the Session to a cache or discards it; publication may consume that
+ * state before disposal, making the callback a no-op.
+ */
+declare class SessionPreparation implements Disposable {
+  /** The exact Session to use for setup and publication. */
+  readonly session: Session;
+  /**
+   * Wrap an unpublished Session in one preparation lifetime.
+   * @param session - exact unpublished Session.
+   * @param options - optional provider release behavior.
+   * @returns a preparation disposed after publication or rollback.
+   */
+  static create(session: Session, options?: SessionPreparationOptions): SessionPreparation;
+  /** Release provider state once when this preparation leaves its caller. */
+  [Symbol.dispose](): void;
+}
+```
+
+```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.
+
+```ts type-equiv
+/**
+ * Backend-owned token that identifies both one storage source and one revision
+ * of a persisted session log.
+ */
+type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'>
+```
+
+```ts type-equiv
+/** Lightweight immutable source identity returned without loading a full log. */
+interface SessionPersistenceSnapshot {
+  /** Detached metadata for one materialized session. */
+  header: SessionHeader
+  /** Opaque source-qualified token that changes whenever this stored log changes. */
+  revision: SessionPersistenceRevision
+}
+```
+
+## The backends
+
+Both 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:
+
+- **[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)** — `node:sqlite`, one row per `SessionEvent`. The row fields `(session_id, seq, type, time, data, source_event_seqs, surface_op)` map 1:1 onto the event, including optional surface metadata, so there is no parallel persisted schema to keep in sync.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
+
+### `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>
+
+/**
+ * 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>
+
+/**
+ * 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>
+
+/**
+ * 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>
+
+/**
+ * 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.
+ */
+abstract inspect(id: SessionId, signal?: AbortSignal): Promise<SessionInspection>
+
+/**
+ * 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`.
+ */
+abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
+
+/**
+ * Lightweight listing from metadata, without a full-log parse.
+ * @param signal - optional cancellation for backend listing work.
+ * @returns one header per materialized session.
+ */
+abstract list(signal?: AbortSignal): Promise<SessionHeader[]>
+
+/**
+ * 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.
+ */
+abstract listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>
+```
+
+Types: [SessionEvent](./session.md) · [SessionId](./core.md)
+
+Source: [`packages/session/session-persistence/src/index.ts:84`](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

@@ -0,0 +1,90 @@
+---
+editSource: "docs/subsystems/plan.md"
+outline: [2,3]
+---
+
+# Plan Mode
+
+Plan mode is logged per-agent collaboration state owned by [dsh-plan-mode](https://github.com/deepseek-ai/deepseek-harness/tree/master/packages/plan/plan-mode) (`ctx.planMode`, `PlanModeController`): while active, a deployment-owned guidance section is included in each model request. Plan mode is **soft guidance**. [Sandbox mode](./sandbox.md) and [approval policy](./approval.md) enforce restrictions independently; neither reads or writes plan state, so deployments configure them separately. The package is optional, and the agent loop does not depend on it. It contributes the `plan:policy` prompt section and registers the `exit_plan_mode` tool and `/plan` command. The [design note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/simplification/2026-07-22-plan-specific-collaboration-state.md) owns the rationale; the [package README](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/plan/plan-mode/README.md) owns the model-experience and limitation detail.
+
+Source: [`packages/plan/plan-mode/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/plan/plan-mode/src/index.ts)
+
+## 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).
+
+## Pending selections and the pre-step append
+
+Because every session event is turn-enclosed, a user selection remains pending until the next accepted in-turn pre-step appends it before request derivation, in whichever turn that occurs. A selection never forces continuation, so one made after a turn's final accepted pre-step is appended in a later turn. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }`: the logged state used to assemble the current step plus the selected state waiting to be appended.
+
+The only append point while an agent is running is a prepended `agent/pre-step` listener. It observes every proposed request step, including turn 1 step 1 and request-recovery retries, calls downstream listeners first, and appends only after they accept the step. Prompt admission happens before a turn and cannot append `plan/mode`, so a selection made at the prompt is appended by the first accepted in-turn pre-step of the turn it starts. An append failure cannot block the turn, and the selection remains pending for a later accepted in-turn pre-step. An appended user selection also records one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A selection made after a turn's final accepted pre-step remains process-local and is lost if the process exits before another accepted in-turn pre-step ([README limitation](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
+
+## Configuration
+
+```ts type-equiv
+/** Deployment-owned plan guidance. */
+interface PlanModeConfig {
+  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
+  section: string
+}
+```
+
+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
+
+[`exit_plan_mode`](../tool-catalog.md#deepseek-aidsh-plan-mode) stays registered while plan mode is inactive, so entering or leaving plan mode changes only the prompt section, never the request tool catalog; execution outside plan mode fails. In plan mode it requires a complete markdown plan starting with a `#` heading and presents it for review through the [user-questions seam](./user-questions.md). Approval returns `{ approved: true }` and records a silent (non-narrated) pending exit that is appended at the next accepted in-turn pre-step. Plan guidance therefore remains active for the rest of the assistant's current tool batch, and the tool result itself reports the transition. Keep-planning is a failed call carrying the user's feedback, so the model revises and presents again; a missing interaction channel and a service reload during review also fail the call rather than silently leaving plan mode.
+
+When [`ctx.commands`](./commands.md) is composed, the plugin registers `/plan [off|message]`: bare `/plan` selects plan mode, any other non-empty message selects it and then submits the text through `agent.steer()` so it becomes the next step's ordinary logged user message under plan guidance, and the exact argument `off` selects inactive, which also cancels a pending entry before it is appended and becomes visible to a request.
+
+## The service
+
+`ctx.planMode` owns the logged plan state, applies and narrates selected state at step start, and owns the `plan:policy` section, the `/plan` command, and the stable exit tool; `get`/`set` signatures are in the generated [service catalog](#ctxplanmode--planmodecontroller).
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxplanmode--planmodecontroller"></a>
+
+### `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.
+
+```ts cordis-catalog
+/**
+ * Read the logged plan state and any selected state awaiting the next
+ * accepted in-turn pre-step.
+ *
+ * @param agent The agent to read.
+ * @returns Current logged state plus a pending selection, when present.
+ */
+get(agent: Agent): { active: boolean; pending?: boolean }
+
+/**
+ * Select whether plan mode should be active. Between turns the method
+ * appends the change immediately because no in-turn pre-step will run until
+ * another prompt starts a turn. The open-turn fold is the idle signal:
+ * agent status stays `running` through post-turn checkpointing, when no
+ * further in-turn pre-step runs. During an open turn the selection remains
+ * pending until the next accepted in-turn pre-step. Repeated selection of
+ * the current or already-pending state is a no-op.
+ *
+ * @param agent The agent to switch.
+ * @param active Whether plan mode should be active.
+ * @returns what happened: `committed` (logged now), `queued` (awaiting the
+ * next accepted in-turn pre-step), `cancelled` (an opposite pending selection
+ * was cleared; the logged state already matches), or `noop` (already in that
+ * state).
+ */
+set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
+```
+
+Types: [Agent](./core.md)
+
+Source: [`packages/plan/plan-mode/src/index.ts:184`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/plan/plan-mode/src/index.ts)
+<!-- END GENERATED cordis-surface -->