Merge origin/master into codex/skill-system

packages/core/README.md

@@ -15,4 +15,4 @@ The packages every harness build is assembled from: the session log, the system-
 
 `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; everything else in `core/` is interface/vocabulary. Plugins depend on the `agent` vocabulary, never on `agent-loop` directly, so the loop stays swappable.
 
-`agent-core` is the composition counterpart: one bundle plugin that loads the whole providerless spine (`timer` + `llm` + sessions + system-prompt + tools + skills + agents + invariants + `tool-bash` + `tool-skill` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. App packages (`ui/stdio-agent`, `ui/acp-agent`) consume it and add only a front door; a leaf adds only the swappable backends. It lives in `core/` because it composes exclusively `core/` + interface packages and ships no provider, executor, or UI of its own.
+`agent-core` is the composition counterpart: one bundle plugin that loads the whole providerless spine (`timer` + `llm` + sessions + system-prompt + tools + skills + agents + invariants + `tool-bash` + `tool-skill` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. App packages (`ui/stdio-agent`, `ui/acp-agent`) consume it and add only a front door; a leaf adds the swappable backends plus any optional product tools it wants to expose. It lives in `core/` because it composes exclusively `core/` + interface packages and ships no provider, executor, or UI of its own.

packages/core/agent-loop/README.md

@@ -12,10 +12,10 @@ This is the only package in the harness that contains concrete loop logic. Every
 
 `AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface):
 
-- `ctx.agents.create({ agentId, sessionId, meta?, agentOptions? }): AgentHandle` — programmatic create on a caller-supplied `sessionId` (e.g. an ACP-generated id), NOT `${id}-session`. Returns an [`AgentHandle`](../agent/README.md) — the owner disposes it to tear down exactly this agent (stop loop + await quiescence + unregister + remove session).
+- `ctx.agents.create({ agentId, sessionId, meta?, seed?, agentOptions? }): AgentHandle` — programmatic create on a caller-supplied `sessionId` (e.g. an ACP-generated id), NOT `${id}-session`; `meta` carries cwd/lineage/seed-boundary metadata and `seed` reconstructs a forked child prefix. Returns an [`AgentHandle`](../agent/README.md) — the owner disposes it to tear down exactly this agent (stop loop + await quiescence + unregister + remove session).
 - `ctx.agents.resume({ agentId, resumeSessionId, agentOptions? }): Promise<AgentHandle>` — load a persisted session via `ctx.sessionPersistence` ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)) and resume an agent on it. The live session id is the resumed id; turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent). Returns an `AgentHandle`.
 
-The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loop fiber (it discards the handle) — only the programmatic factory callers (the ACP bridge) hold a handle and own per-agent teardown.
+The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loop fiber (it discards the handle) — only the programmatic factory callers (the ACP bridge and in-process subagent backends) hold a handle and own per-agent teardown.
 
 ### Injected services
 
@@ -77,6 +77,6 @@ Everything that goes beyond "call the model, run the tools, repeat" belongs to p
 - Hooks: `agent/request`, `agent/step-result`, `tools/execute`, `agent/turn-continuation`
 - Compaction: `agent/request`
 - Sandbox, permission, plan mode: `tools/execute`
-- Sub-agents: TODO seam on `AgentLoop.create()`
+- Sub-agents: implemented outside the loop as `ctx.subagents` providers; in-process providers use `ctx.agents.create()` and owned `AgentHandle` teardown, while child streaming/progress and background/poll collection remain deferred.
 - Persistence: `session/event` + `session/flush`
 - UI: `agent/stream-chunk` + `agent/*` events

packages/core/agent-loop/src/agent.ts

@@ -126,7 +126,7 @@ export class ReactLoopAgent implements Agent {
       // A turn is open in the LOG (decided from the log, not agent status —
       // status can be `running` with no turn open): the context/message is
       // turn-enclosed by that turn, so append it directly.
-      this.session.append('context/message', { content, source })
+      this.session.append('context/message', { content, source }, { surfaceOp: 'append' })
       return
     }
     // No turn open: wrap the injection in a one-shot turn so every event stays
@@ -143,7 +143,7 @@ export class ReactLoopAgent implements Agent {
     // can't happen for our fixed trigger — no turn was opened and none is owed.)
     try {
       this.session.append('turn/start', { turn, trigger: { kind: 'injection', source } })
-      this.session.append('context/message', { content, source })
+      this.session.append('context/message', { content, source }, { surfaceOp: 'append' })
     } finally {
       // Close the turn if turn/start made it into the log. Contain a throwing
       // turn/end listener: Session.append pushes before notifying, so a throw

packages/core/agent-loop/src/loop.ts

@@ -375,7 +375,7 @@ async function runTurn(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle,
     // every event in the log is turn-enclosed. turn/end is now owed, so a throw
     // while appending these is caught below and the turn is still closed.
     for (const message of queued) {
-      session.append('user/message', { content: message.content, source: message.source })
+      session.append('user/message', { content: message.content, source: message.source }, { surfaceOp: 'append' })
     }
     ctx.emit('agent/turn-start', agent, turn)
 
@@ -543,7 +543,7 @@ async function runTurn(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle,
 function drainSteering(ctx: Context, agent: ReactLoopAgent, turn: number): boolean {
   const messages = agent.inbox.drainSteering()
   for (const message of messages) {
-    agent.session.append('steering/message', { turn, content: message.content, source: message.source })
+    agent.session.append('steering/message', { turn, content: message.content, source: message.source }, { surfaceOp: 'append' })
     ctx.emit('agent/steering', agent, turn, message.content, message.source)
   }
   return messages.length > 0
@@ -580,10 +580,12 @@ async function runStep(
 
   // --- Model call (streaming-first; raw chunks are the replay record) ---
   const assembler = new BlockAssembler()
+  const chunkSeqs: number[] = []
   for await (const chunk of ctx.llm.stream(request)) {
     /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
     if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
-    session.append('assistant/chunk', { turn, step, chunk })
+    const chunkEvent = session.append('assistant/chunk', { turn, step, chunk })
+    chunkSeqs.push(chunkEvent.seq)
     ctx.emit('agent/stream-chunk', agent, turn, step, chunk)
     assembler.push(chunk)
   }
@@ -606,7 +608,13 @@ async function runStep(
     // deriveMessages(), so hosting usage on it never injects a spurious assistant
     // turn into derived history.
     if (message.content.length > 0 || assembler.usage) {
-      session.append('assistant/message', { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) })
+      // A max-tokens finish is itself a streamed `finish` chunk, so chunkSeqs is
+      // never empty here — pass the provenance unconditionally.
+      session.append(
+        'assistant/message',
+        { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
+        { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
+      )
     }
     return { hadToolCalls: false, finish: assembler.finish }
   }
@@ -622,8 +630,15 @@ async function runStep(
   // streamed nothing) records no assistant/message — an empty-content message
   // exists only to host usage, and deriveMessages() skips it either way, so
   // appending one with no usage would be a pure trace-only row.
+  //
+  // sourceEventSeqs records the assistant/chunk provenance, but is omitted when
+  // no chunks streamed (the surface invariant rejects an empty sourceEventSeqs).
   if (message.content.length > 0 || assembler.usage) {
-    session.append('assistant/message', { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) })
+    session.append(
+      'assistant/message',
+      { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
+      { surfaceOp: 'append', ...(chunkSeqs.length > 0 ? { sourceEventSeqs: chunkSeqs } : {}) },
+    )
   }
 
   // --- Tool execution (sequential; parallel execution is a TODO) ---
@@ -633,7 +648,7 @@ async function runStep(
   for (const call of toolCalls) {
     /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
     if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
-    session.append('tool/call', { turn, step, callId: call.id, name: call.name, arguments: call.arguments })
+    const callEvent = session.append('tool/call', { turn, step, callId: call.id, name: call.name, arguments: call.arguments })
     let parsedArguments: unknown
     try {
       parsedArguments = call.arguments ? JSON.parse(call.arguments) : {}
@@ -659,7 +674,7 @@ async function runStep(
       content: result.content,
       isError: result.isError,
       ...result.error ? { error: result.error } : {},
-    })
+    }, { surfaceOp: 'append', sourceEventSeqs: [callEvent.seq] })
     // signal CAN flip during the await above (abort() inside a tool);
     // the analyzer can't see through the await boundary.
     /* v8 ignore start -- signal.reason default unreachable: cancel()/disposal always set it */

packages/core/agent-loop/tests/review-fixes.spec.ts

@@ -1018,3 +1018,32 @@ describe('P1-7: tool/result is logged under the originating call.id, not result.
     }
   })
 })
+
+describe('surface: assistant/message omits sourceEventSeqs when no chunks streamed', () => {
+  it('a step-result listener injecting content over an empty stream appends with surfaceOp but no sourceEventSeqs', async () => {
+    // An empty stream yields zero assistant/chunk events (finish defaults to
+    // `stop`), so chunkSeqs is empty. A step-result listener injects content, so
+    // the content-or-usage guard fires and an assistant/message is appended. Its
+    // sourceEventSeqs MUST be omitted (not `[]`) — the surface invariant rejects
+    // an empty sourceEventSeqs, and the dev invariants plugin would throw on it.
+    const adapter = new MockAdapter([[]])
+    const ctx = await harness(adapter)
+    await ctx.plugin(Invariants)
+    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+
+    ctx.on('agent/step-result', async (_agent, _turn, _step, _message, _next) => ({
+      role: 'assistant' as const,
+      content: [{ type: 'text' as const, text: 'injected' }],
+    }))
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    const recorded = agent.session.events.find(e => e.type === 'assistant/message')!
+    expect(recorded.type).toBe('assistant/message')
+    expect(recorded.surfaceOp).toBe('append')
+    expect(recorded.sourceEventSeqs).toBeUndefined()
+    // The injected content reaches derived history.
+    expect(JSON.stringify(agent.session.deriveMessages())).toContain('injected')
+  })
+})

packages/core/agent/README.md

@@ -17,10 +17,10 @@ Tracks live agents so UI, hook, and orchestrator plugins can find them without i
 Agent *creation* is provided by whichever plugin implements `AgentFactory` (phase 1: `dsh-agent-loop`), registered via `setFactory`. This keeps creation on the `dsh-agent` interface so consumers (UI, the ACP bridge) program against `ctx.agents` without depending on the concrete loop package.
 
 - `ctx.agents.setFactory(factory: AgentFactory): () => void` — register the creation factory (the loop calls this on construction). Throws on a second factory; the slot clears on dispose.
-- `ctx.agents.create(options: CreateAgentOptions): AgentHandle` — construct, start, AND register a new agent on a caller-supplied `sessionId` (with optional `meta.cwd`). Distinct from `register` (which only records). Throws if no factory is registered.
+- `ctx.agents.create(options: CreateAgentOptions): AgentHandle` — construct, start, AND register a new agent on a caller-supplied `sessionId` (with optional `meta.cwd`/`meta.parentSession`/`meta.seedLength` and optional `seed` events for forked children). Distinct from `register` (which only records). Throws if no factory is registered.
 - `ctx.agents.resume(options: ResumeAgentOptions): Promise<AgentHandle>` — load a persisted session ([session persistence](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md)) and resume an agent on it. Async; rejects if no factory is registered, or if the factory finds session persistence unconfigured.
 
-`AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **capability** — only the holder can tear this agent down. `dispose()` stops the loop, `await`s its exit (quiescence — NOT just the `disposed` status flip), unregisters the agent, and removes its session from the store, in an order that captures the loop's final `session/flush` before the session is detached. `ctx.agents.get(id)` still returns a bare `Agent` — the handle is only for the OWNER that created it. The ACP bridge is the production consumer (one handle per session, disposed on disconnect/teardown); config-created agents are owned by the loop fiber and never need a handle.
+`AgentHandle = { agent: Agent; dispose(): Promise<void> }`. The disposer is a **capability** — only the holder can tear this agent down. `dispose()` stops the loop, `await`s its exit (quiescence — NOT just the `disposed` status flip), unregisters the agent, and removes its session from the store, in an order that captures the loop's final `session/flush` before the session is detached. `ctx.agents.get(id)` still returns a bare `Agent` — the handle is only for the OWNER that created it. The ACP bridge and in-process subagent backends are production consumers; config-created agents are owned by the loop fiber and never need a handle.
 
 ### Events
 
@@ -62,9 +62,10 @@ The handle every plugin programs against:
 
 ### Extension points
 
-- Agent creation: `AgentLoop.create()` is the concrete implementation (in `dsh-agent-loop`). Replace the loop by implementing `Agent` and registering via `ctx.agents.register()`.
+- Agent creation: `AgentLoop.create()` is the concrete config-path implementation (in `dsh-agent-loop`), while programmatic consumers create/resume owned agents through `ctx.agents.create()` / `ctx.agents.resume()`. Replace the loop by implementing `Agent` and registering via `ctx.agents.register()`.
 - Event listeners: all `agent/*` events are declared here — no dependency on the loop package needed.
+- Subagent delegation: implemented by `@deepseek-ai/dsh-subagent`, not by a method on `Agent`; providers create or drive ordinary `Agent` handles through the factory seam, so spawn/fork/ACP transports stay outside the core agent interface.
 
 ### What is NOT here (TODO)
 
-- **Sub-agent spawn/fork** — seam on `AgentLoop.create()`, semantics deferred.
+- **Inter-agent channels beyond delegation** — shared state, streaming child output, and background/poll semantics remain outside the current synchronous `ctx.subagents` seam.

packages/core/session/README.md

@@ -1,6 +1,6 @@
 # dsh-session
 
-Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it.
+Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (a linked list of message-producing events) is maintained on top of the raw log for efficient derivation and compaction.
 
 ## Service: `SessionStore` (ctx key: `sessions`)
 
@@ -8,7 +8,7 @@ Creates and holds event-sourced `Session` instances. Persistence is intentionall
 
 ### Public API
 
-- `ctx.sessions.create(id?: SessionId, options?: { seed?: SessionEvent[]; meta?: { cwd?: string; parentSession?: SessionId; createdAt?: number } }): Session` — Create a session. `options.seed` replays/forks an existing event log; `options.meta` attaches creation metadata (validated absolute `cwd`, `parentSession` lineage) as the immutable `SessionHeader`. The store fills `version`/`id` and defaults `createdAt` to now; a caller reconstructing a persisted session passes the original `createdAt` to preserve it. Disposed with the calling fiber.
+- `ctx.sessions.create(id?: SessionId, options?: { seed?: SessionEvent[]; meta?: { cwd?: string; parentSession?: SessionId; createdAt?: number; seedLength?: number } }): Session` — Create a session. `options.seed` replays/forks an existing event log; `options.meta` attaches creation metadata (validated absolute `cwd`, `parentSession` lineage, seed boundary) as the immutable `SessionHeader`. The store fills `version`/`id` and defaults `createdAt` to now; a caller reconstructing a persisted session passes the original `createdAt` and persisted `seedLength` to preserve them. Disposed with the calling fiber.
 - `ctx.sessions.get(id: SessionId): Session | undefined`
 - `ctx.sessions.list(): Session[]`
 
@@ -34,28 +34,42 @@ Creates and holds event-sourced `Session` instances. Persistence is intentionall
 
 Plain class (not a Cordis Service). Create via `ctx.sessions.create()`.
 
-- `session.append(type, data): SessionEvent` — synchronous, never blocks on I/O. **Throws** if `data` is not losslessly JSON-serializable (BigInt, function, symbol, undefined, non-finite number, circular ref, or an exotic object like Map/Set/Date) — the event log is the durable source of truth, so this invariant is enforced at the source (exported as `isJsonValue` for backends to reuse on their replay/fork entry points).
-- `session.deriveMessages(): Message[]` — derive the LLM message history from the event log. Raw `assistant/chunk` events are skipped; `context/message` and `steering/message` render as tagged synthetic user messages.
+- `session.append(type, data, opts?): SessionEvent` — synchronous, never blocks on I/O. **Throws** if `data` is not losslessly JSON-serializable (BigInt, function, symbol, undefined, non-finite number, circular ref, or an exotic object like Map/Set/Date) — the event log is the durable source of truth, so this invariant is enforced at the source (exported as `isJsonValue` for backends to reuse on their replay/fork entry points). A third parameter `opts: SurfaceIntent` carries surface metadata: `surfaceOp` controls how the event enters the surface linked list, and `sourceEventSeqs` records provenance (the seq numbers of events this one derives from). It is **required** for the five `SurfaceEventType` events (every message-producing event must declare how it joins the surface) and rejected by the compiler for non-surface types. The marker requirement is enforced two ways: the typed overload makes `opts` mandatory when `type` is a specific `SurfaceEventType` literal, AND `append` **throws** at runtime if a surface-eligible event arrives with no `surfaceOp` — covering the case where `type` widens to the `SessionEventType` union (a caller iterating raw events, where the conditional overload collapses to optional) so a marker-less message event can never silently land in the log and vanish from `deriveMessages()`.
+- `session.deriveMessages(): Message[]` — derive the LLM message history by walking the surface linked list (skipping non-surface events like chunks and boundaries; a `replace` shadows the nodes it covers). The surface is the single source of derived history — there is no raw-log fallback.
+- `session.surface: SurfaceManager` — the derived surface, lazily rebuilt from `surfaceOp` markers in the log. Processes only new events (delta) on each access — the log is append-only, so prior events never change.
 - `session.events`, `session.seq`, `session.id`
-- `session.header: SessionHeader` — immutable creation metadata (`version`, `id`, `createdAt`, optional `cwd`/`parentSession`). Kept out of the event log (a storage concern, not replayable state); a minimal header (stamped with the current `SESSION_FORMAT_VERSION`) is synthesized for bare `Session` construction.
+- `session.header: SessionHeader` — immutable creation metadata (`version`, `id`, `createdAt`, optional `cwd`/`parentSession`/`seedLength`). Kept out of the event log (a storage concern, not replayable state); a minimal header (stamped with the current `SESSION_FORMAT_VERSION`) is synthesized for bare `Session` construction.
 
-### Metadata types (`types.ts`)
+### Surface types
 
-- `SessionHeader` — immutable session metadata, written once: `{ version, id, createdAt, cwd?, parentSession? }`. Owned here (beside `SessionId`) because `Session.header` is typed by it; persistence backends re-export it rather than own it (which would force a package cycle).
+- `SurfaceOp` — how a surface node entered the linked list: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace nodes from `start` through `end` inclusive — both must be valid surface node seqs; `start === end` replaces a single node). Used by compaction to shadow old nodes without deleting them.
+- `SurfaceIntent` — `{ surfaceOp: SurfaceOp; sourceEventSeqs?: number[] }`, the required third parameter to `session.append()` for surface-eligible types.
+- `SurfaceNode` — `{ seq: number; prev: number | null; next: number | null }`, one node in the surface linked list.
+- `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully-formed surface node (type is surface-eligible AND `surfaceOp` present); the second is the type-only check (is this one of the five `SurfaceEventType` values?), used to detect a surface-eligible event MISSING its marker — e.g. when validating a seed/load log.
 
 ### Session event vocabulary (`types.ts`)
 
-The append-only log: `turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/message`, `assistant/chunk`, `tool/call`, `tool/result`, `steering/message`, `context/message`. Token usage rides on `assistant/message.usage`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.
+The append-only log: `turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/message`, `assistant/chunk`, `tool/call`, `tool/result`, `steering/message`, `context/message`, `todo/write`. Token usage rides on `assistant/message.usage`; an operational error's step is on `turn/end.reason` for `kind: 'error'`.
 
-Merge-extensible via `SessionEventMap` — a compaction plugin adds `compaction/marker`, etc.
+Merge-extensible via `SessionEventMap` — the compaction seam adds `compact/start`, `compact/summary`, and `compact/end`.
 
 Also defines `TurnTriggerMap` and `TurnEndReasonMap` (merge-extensible sum types for typed turn boundaries — `kind`-tagged instead of strings).
 
+Every `SessionEvent` carries two optional top-level fields (structural metadata):
+
+- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed nodes behind a compaction marker).
+- `surfaceOp?: SurfaceOp` — how this event entered the surface. Absent for non-surface events (boundaries, chunks, usage, errors).
+
+### Metadata types (`types.ts`)
+
+- `SessionHeader` — immutable session metadata, written once: `{ version, id, createdAt, cwd?, parentSession?, seedLength? }`. Owned here (beside `SessionId`) because `Session.header` is typed by it; persistence backends re-export it rather than own it (which would force a package cycle).
+
 ### Extension points
 
 - Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log.
-- Replay/fork: `ctx.sessions.create(id, { seed })` seeds a new session with an existing event log.
+- Replay/fork: `ctx.sessions.create(id, { seed })` seeds a new session with an existing event log. The surface rebuilds deterministically from `surfaceOp` markers in the seeded events. The seed is validated to the SAME invariants `append` enforces — including that every surface-eligible event (`SurfaceEventType`) carries a `surfaceOp` marker — so a marker-less message event is rejected at construction rather than silently vanishing from `deriveMessages()` (the surface is the sole derivation path) on resume.
+- Compaction: a future plugin appends a new event with `surfaceOp: { op: 'replace', start, end }` to shadow old surface nodes.
 
 ### What is NOT here (TODO)
 
-- **Session branching/tree** (pi-style entry tree) — defered unless needed beyond seed-based forking.
+- **Session branching/tree** (pi-style entry tree) — deferred unless needed beyond seed-based forking.

packages/core/session/src/index.ts

@@ -10,12 +10,15 @@ import { Context, Service } from 'cordis'
 import { isAbsolute } from 'node:path'
 import type { ContentBlock, Message, MessageSource } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION, SessionId } from './types.ts'
-import type { CreateSessionOptions, SessionEvent, SessionEventMap, SessionEventType, SessionHeader } from './types.ts'
+import type { CreateSessionOptions, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SurfaceIntent, SurfaceEventType } from './types.ts'
 import { isJsonValue } from './json.ts'
+import { SurfaceManager, isSurfaceEligibleType } from './surface.ts'
 
 export * from './types.ts'
 export { isJsonValue } from './json.ts'
 export { interruptedTurnClosers } from './repair.ts'
+export type { SurfaceNode } from './surface.ts'
+export { isSurfaceEvent, isSurfaceEligibleType } from './surface.ts'
 
 declare module 'cordis' {
   interface Context {
@@ -77,12 +80,27 @@ export class Session {
   onAppend: ((event: SessionEvent) => void) | undefined
 
   /**
-   * Immutable creation metadata (format version, cwd, lineage). Supplied by
-   * the store via `ctx.sessions.create()`. When a `Session` is constructed
-   * bare (tests, ad-hoc replay), a minimal header is synthesized (stamped with
-   * the current {@link SESSION_FORMAT_VERSION}) so `session.header` is always
-   * present. Kept out of the event log — it is a storage concern, not
-   * replayable conversation state.
+   * Derived surface — a cached linked list of message-producing events.
+   * Lazily rebuilt from `surfaceOp` markers in the log; processes only new
+   * events (delta) on each access — the log is append-only, so prior events
+   * never change.
+   * `append`. Undefined until first accessed (including after fork/seed).
+   */
+  private _surface: SurfaceManager | undefined
+
+  /** The surface linked list over this session's event log. */
+  get surface(): SurfaceManager {
+    if (!this._surface) this._surface = new SurfaceManager(this.log)
+    return this._surface
+  }
+
+  /**
+   * Immutable creation metadata (format version, cwd, lineage, seed boundary).
+   * Supplied by the store via `ctx.sessions.create()`. When a `Session` is
+   * constructed bare (tests, ad-hoc replay), a minimal header is synthesized
+   * (stamped with the current {@link SESSION_FORMAT_VERSION}) so
+   * `session.header` is always present. Kept out of the event log — it is a
+   * storage concern, not replayable conversation state.
    */
   readonly header: SessionHeader
 
@@ -102,6 +120,16 @@ export class Session {
         if (!isJsonValue(event.data)) {
           throw new Error(`seed event "${event.type}" (seq ${event.seq}) carries non-JSON-serializable data`)
         }
+        // Surface-eligible events MUST carry a surfaceOp marker — the surface is
+        // the sole source of derived history, so a marker-less message event
+        // would load fine yet vanish from deriveMessages(). `append` enforces
+        // this at compile time via its typed overload; a seed arrives as raw
+        // SessionEvent[] (replay/fork/load), bypassing that, so re-check at
+        // runtime here rather than silently resuming with empty history.
+        if (isSurfaceEligibleType(event.type)
+          && (event as SessionEvent<SurfaceEventType>).surfaceOp === undefined) {
+          throw new Error(`seed event "${event.type}" (seq ${event.seq}) is surface-eligible but carries no surfaceOp marker`)
+        }
       })
       // Deep-clone each seed event, NOT just the array: the seed events and
       // their `data` are still owned by the caller (or the source session of a
@@ -129,6 +157,15 @@ export class Session {
    * `onAppend`. The hot path never blocks on I/O — persistence plugins buffer
    * asynchronously.
    *
+   * @param type - The event type (key of {@link SessionEventMap}).
+   * @param data - The event payload; must be JSON-serializable.
+   * @param opts - Surface metadata: `surfaceOp` controls how the event enters
+   *   the surface linked list; `sourceEventSeqs` records provenance (the seq
+   *   numbers of events this one derives from). REQUIRED for
+   *   {@link SurfaceEventType} events (every message-producing event must
+   *   declare how it joins the surface, the sole source of derived history) and
+   *   rejected by the compiler for non-surface types like `turn/start` or
+   *   `assistant/chunk`.
    * @throws if `data` is not losslessly JSON-serializable (BigInt, function,
    *   symbol, undefined, non-finite number, circular ref, or an exotic object
    *   like Map/Set/Date). The event log is the durable source of truth, so this
@@ -137,10 +174,26 @@ export class Session {
    *   throw surfaces at the buggy caller's append site, not asynchronously in a
    *   backend flush.
    */
-  append<T extends SessionEventType>(type: T, data: SessionEventMap[T]): SessionEvent<T> {
+  append<T extends SessionEventType>(
+    type: T,
+    data: SessionEventMap[T],
+    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []
+  ): SessionEvent<T> {
     if (!isJsonValue(data)) {
       throw new Error(`session event "${type}" carries non-JSON-serializable data`)
     }
+    const surfaceOpts: SurfaceIntent | undefined = opts[0]
+    // Surface-eligible events MUST carry a surfaceOp marker — the surface is the
+    // sole source of derived history, so a marker-less message event would be
+    // logged yet vanish from deriveMessages(). The typed `opts` overload makes
+    // the marker mandatory only when `T` is a SPECIFIC SurfaceEventType literal;
+    // when `T` widens to the SessionEventType union (a caller iterating raw
+    // events: `for (const e of log) append(e.type, e.data)`), the conditional
+    // rest collapses to optional and the compiler stops enforcing it. Re-check
+    // at runtime so that loophole can't silently drop history.
+    if (isSurfaceEligibleType(type) && surfaceOpts?.surfaceOp === undefined) {
+      throw new Error(`session event "${type}" is surface-eligible and requires a surfaceOp marker`)
+    }
     // Snapshot `data` into the log, NOT the caller's reference: the validation
     // above proves it is JSON-serializable AT THIS MOMENT, but the caller still
     // owns the object and could mutate it afterwards (before a persistence
@@ -150,14 +203,38 @@ export class Session {
     // validated. structuredClone is safe because serializability was just
     // checked. The returned event carries the SAME snapshot, so a caller reading
     // back `event.data` sees the logged value, not its own mutable input.
-    const event = { type, seq: this.log.length, time: Date.now(), data: structuredClone(data) } as SessionEvent<T>
-    this.log.push(event)
-    this.onAppend?.(event)
+    //
+    // Surface metadata is snapshot separately: sourceEventSeqs (number[] —
+    // primitives, so array spread is a complete copy) and surfaceOp (a string
+    // primitive, or cloned if it's a replace object).
+    // Build the event shape with conditional surface fields via spreading.
+    // The result is cast through `unknown` because the conditional spreads
+    // produce an intersection type that the assignability checker can't
+    // narrow to a specific discriminated-union member when T is generic.
+    // This is a safe internal boundary: data was validated above, and
+    // surface metadata was snapshot from primitive/clone-safe values.
+    const event = {
+      type,
+      seq: this.log.length,
+      time: Date.now(),
+      data: structuredClone(data),
+      ...surfaceOpts?.sourceEventSeqs !== undefined ? { sourceEventSeqs: [...surfaceOpts.sourceEventSeqs] } : {},
+      ...surfaceOpts?.surfaceOp !== undefined ? {
+        surfaceOp: typeof surfaceOpts.surfaceOp === 'string' ? surfaceOpts.surfaceOp : structuredClone(surfaceOpts.surfaceOp),
+      } : {},
+    } as unknown as SessionEvent<T>
+    this.log.push(event as unknown as SessionEvent)
+    this.onAppend?.(event as unknown as SessionEvent)
     return event
   }
 
   /**
-   * Derive the LLM message history from the event log.
+   * Derive the LLM message history by walking the session surface — the linked
+   * list of message-producing events maintained by `surfaceOp` markers. The
+   * surface is the single source of derived history: every message-producing
+   * append records its `surfaceOp`, so a raw event with no marker (a chunk, a
+   * turn boundary) is correctly absent, and a compaction `replace` deletes the
+   * shadowed nodes from the derivation.
    *
    * - `user/message` → user message
    * - `assistant/message` → assistant message (chunks are skipped — they are
@@ -179,45 +256,60 @@ export class Session {
    */
   deriveMessages(): Message[] {
     const messages: Message[] = []
-    for (const event of this.log) {
-      // Intentionally non-exhaustive: only message-producing events derive
-      // history; turn/step boundaries and chunks are trace/replay data.
-      // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
-      switch (event.type) {
-        case 'user/message': {
-          messages.push({ role: 'user', content: structuredClone(event.data.content) })
-          break
-        }
-        case 'assistant/message': {
-          // Skip an empty-content assistant/message: it exists only to host a
-          // max-tokens step's usage and must not inject a content-less assistant
-          // turn into the provider transcript.
-          if (event.data.content.length === 0) break
-          messages.push({ role: 'assistant', content: structuredClone(event.data.content) })
-          break
-        }
-        case 'tool/result': {
-          const { callId, content, isError } = event.data
-          messages.push({
-            role: 'user',
-            content: [{ type: 'tool-result', toolCallId: callId, content: structuredClone(content), isError }],
-          })
-          break
-        }
-        case 'context/message': {
-          const { content, source } = event.data
-          messages.push({ role: 'user', content: renderTagged('context', structuredClone(content), source) })
-          break
-        }
-        case 'steering/message': {
-          const { content, source } = event.data
-          messages.push({ role: 'user', content: renderTagged('steering', structuredClone(content), source) })
-          break
-        }
-      }
+    for (const node of this.surface.nodes) {
+      // Surface nodes are built from this.log — node.seq is always a valid
+      // index by construction. The non-null assertion expresses that invariant.
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const msg = this._deriveOneMessage(this.log[node.seq]!)
+      // A surface node is one of the five message-producing types, but an
+      // empty-content assistant/message (a max-tokens step that hosts only
+      // usage) derives to null and must not enter the transcript.
+      if (msg) messages.push(msg)
     }
     return messages
   }
+
+  /**
+   * Derive a single LLM message from one surface event, or null if it produces
+   * no message (an empty-content assistant/message that exists only to host
+   * usage).
+   */
+  private _deriveOneMessage(event: SessionEvent): Message | null {
+    // Intentionally non-exhaustive: only message-producing events derive
+    // history; turn/step boundaries, chunks, usage, and errors are
+    // trace/replay data.
+
+    switch (event.type) {
+      case 'user/message': {
+        return { role: 'user', content: structuredClone(event.data.content) }
+      }
+      case 'assistant/message': {
+        // Skip an empty-content assistant/message: it exists only to host a
+        // max-tokens step's usage and must not inject a content-less assistant
+        // turn into the provider transcript.
+        if (event.data.content.length === 0) return null
+        return { role: 'assistant', content: structuredClone(event.data.content) }
+      }
+      case 'tool/result': {
+        const { callId, content, isError } = event.data
+        return {
+          role: 'user',
+          content: [{ type: 'tool-result', toolCallId: callId, content: structuredClone(content), isError }],
+        }
+      }
+      case 'context/message': {
+        const { content, source } = event.data
+        return { role: 'user', content: renderTagged('context', structuredClone(content), source) }
+      }
+      case 'steering/message': {
+        const { content, source } = event.data
+        return { role: 'user', content: renderTagged('steering', structuredClone(content), source) }
+      }
+      /* v8 ignore next 2 -- unreachable: only surface nodes (the 5 message-producing types) reach here */
+      default:
+        return null
+    }
+  }
 }
 
 /**

packages/core/session/src/repair.ts

@@ -62,7 +62,12 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
   // call is "pending" until its matching tool/result arrives. Reset at every
   // turn boundary so a committed earlier turn (already balanced) never leaks a
   // phantom pending call into the interrupted-turn repair.
-  const pendingCalls = new Map<CallId, { step: number }>()
+  // Track pending tool calls with their callSeq (the seq of the `tool/call`
+  // event, captured for surface sourceEventSeqs provenance on the synthetic
+  // result). CallSeq is set from `tool/call` events; the assistant/message
+  // block scan may register a call first (it appears earlier in the log), and
+  // the later `tool/call` event fills in the seq.
+  const pendingCalls = new Map<CallId, { step: number; callSeq?: number }>()
   for (const event of events) {
     switch (event.type) {
       case 'turn/start':
@@ -89,6 +94,18 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
           if (block.type === 'tool-call') pendingCalls.set(block.id, { step: event.data.step })
         }
         break
+      case 'tool/call':
+        // Capture the tool/call event seq for surface provenance on the
+        // synthesized tool/result. The entry may already exist (registered by
+        // the assistant/message above) or may be new (if the assistant/message
+        // came from a prior step that was already closed).
+        {
+          const entry = pendingCalls.get(event.data.callId)
+          if (entry) {
+            entry.callSeq = event.seq
+          }
+        }
+        break
       case 'tool/result':
         pendingCalls.delete(event.data.callId)
         break
@@ -114,7 +131,7 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
   // crash, so deriveMessages() yields a valid provider transcript on resume (a
   // dangling assistant tool-call is rejected by every provider). Insertion
   // order follows the Map (insertion = log order of the assistant messages).
-  for (const [callId, { step }] of pendingCalls) {
+  for (const [callId, { step, callSeq }] of pendingCalls) {
     closers.push({
       type: 'tool/result',
       seq: seq++,
@@ -127,6 +144,8 @@ export function interruptedTurnClosers(events: readonly SessionEvent[]): Session
         isError: true,
         error: { name: 'InterruptedError', code: 'interrupted' },
       },
+      surfaceOp: 'append',
+      ...callSeq !== undefined ? { sourceEventSeqs: [callSeq] } : {},
     })
   }
 

packages/core/session/src/surface.ts

@@ -0,0 +1,159 @@
+/**
+ * Surface layer on top of the session event log: a derived, cached linked list
+ * of events that produce LLM messages. Rebuilt deterministically from
+ * `surfaceOp` markers in the log — the log is the source of truth; the surface
+ * is a view.
+ *
+ * @module @deepseek-ai/dsh-session/surface
+ */
+
+import type { SessionEvent, SurfaceEvent, SurfaceEventType, SurfaceOp } from './types.ts'
+
+/**
+ * The set of event type strings that are eligible for the surface linked list.
+ * Mirrors the {@link SurfaceEventType} union; kept as a runtime set so the
+ * type guard can check membership without a chain of string comparisons.
+ */
+const SURFACE_EVENT_TYPES = new Set<string>([
+  'user/message',
+  'assistant/message',
+  'tool/result',
+  'context/message',
+  'steering/message',
+])
+
+/**
+ * Whether an event's `type` is surface-eligible (one of the five
+ * message-producing {@link SurfaceEventType} values). This is the TYPE check
+ * only — it does NOT require `surfaceOp` to be present. Use it to detect a
+ * surface-eligible event that is MISSING its mandatory marker (e.g. validating
+ * a seed/load log); use {@link isSurfaceEvent} to narrow to a fully-formed
+ * {@link SurfaceEvent} with `surfaceOp` present.
+ */
+export function isSurfaceEligibleType(type: string): boolean {
+  return SURFACE_EVENT_TYPES.has(type)
+}
+
+/**
+ * Narrow a {@link SessionEvent} to {@link SurfaceEvent}: checks that the
+ * event's `type` is surface-eligible AND that `surfaceOp` is present.
+ * The narrowed type has mandatory {@link SurfaceOp}.
+ */
+export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent {
+  if (!SURFACE_EVENT_TYPES.has(event.type)) return false
+  // surfaceOp is optional on SessionEvent (even for surface-eligible types)
+  // but mandatory on SurfaceEvent — this check is the narrowing gate.
+  if ((event as SessionEvent<SurfaceEventType>).surfaceOp === undefined) return false
+  return true
+}
+
+/** One node in the surface linked list. */
+export interface SurfaceNode {
+  /** The event seq of this surface node. */
+  seq: number
+  /** The previous surface node's seq, or null if this is the head. */
+  prev: number | null
+  /** The next surface node's seq, or null if this is the tail. */
+  next: number | null
+}
+
+/**
+ * Maintains a cached linked list of surface nodes, rebuilt lazily from
+ * `surfaceOp` markers in the event log. Because the log is append-only, it
+ * processes only the delta since the last rebuild — new events are folded
+ * into the existing surface in O(new events) rather than rescanning the
+ * whole log.
+ */
+export class SurfaceManager {
+  /** Surface nodes in linked-list order (head to tail). Empty until first access. */
+  private _nodes: SurfaceNode[] = []
+  /** Map from event seq → node. */
+  private _nodeBySeq = new Map<number, SurfaceNode>()
+  /** The last processed seq. -1 forces a full rebuild on first access. */
+  private _lastProcessedSeq = -1
+
+  constructor(private log: readonly SessionEvent[]) {}
+
+  /**
+   * Reset to unprocessed state. Call after the log has been replaced
+   * wholesale (e.g. after Session seed). Not needed for normal appends —
+   * those are picked up incrementally.
+   */
+  invalidate(): void {
+    this._lastProcessedSeq = -1
+    this._nodes = []
+    this._nodeBySeq.clear()
+  }
+
+  /** The surface nodes in linked-list order (head to tail). */
+  get nodes(): readonly SurfaceNode[] {
+    if (this._lastProcessedSeq < this.log.length - 1) this._processDelta()
+    return this._nodes
+  }
+
+  /**
+   * Process events from `_lastProcessedSeq + 1` through the end of the log,
+   * folding new surface markers into the existing linked list.
+   */
+  private _processDelta(): void {
+    for (let i = this._lastProcessedSeq + 1; i < this.log.length; i++) {
+      // Index is bounded by i < this.log.length — never undefined.
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const event = this.log[i]!
+      // isSurfaceEvent checks event.type first (is it a surface-eligible type?)
+      // then checks that surfaceOp is present. Only after both pass do we treat
+      // it as a SurfaceEvent with mandatory surfaceOp.
+      if (!isSurfaceEvent(event)) continue
+
+      if (event.surfaceOp === 'append') {
+        const tail = this._nodes.length > 0 ? this._nodes[this._nodes.length - 1] : undefined
+        const node: SurfaceNode = { seq: event.seq, prev: tail?.seq ?? null, next: null }
+        if (tail) tail.next = event.seq
+        this._nodes.push(node)
+        this._nodeBySeq.set(event.seq, node)
+      } else {
+        this._replace(event.seq, event.surfaceOp)
+      }
+    }
+    this._lastProcessedSeq = this.log.length - 1
+  }
+
+  /** Apply a replace operation to the in-progress surface. */
+  private _replace(
+    newSeq: number,
+    op: Extract<SurfaceOp, { op: 'replace' }>,
+  ): void {
+    const startNode = this._nodeBySeq.get(op.start)
+    if (!startNode) {
+      throw new Error(`surface replace: start seq ${op.start} not found in surface`)
+    }
+    const endNode = this._nodeBySeq.get(op.end)
+    if (!endNode) {
+      throw new Error(`surface replace: end seq ${op.end} not found in surface`)
+    }
+    const startIdx = this._nodes.indexOf(startNode)
+    const endIdx = this._nodes.indexOf(endNode)
+    if (startIdx > endIdx) {
+      throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`)
+    }
+
+    // Remove shadowed nodes from `[startIdx, endIdx]` inclusive.
+    const count = endIdx - startIdx + 1
+    const removed = this._nodes.splice(startIdx, count)
+    for (const r of removed) this._nodeBySeq.delete(r.seq)
+
+    // Insert the new node where the removed range was.
+    const prevNode = startIdx > 0 ? this._nodes[startIdx - 1] : undefined
+    const nextNode = startIdx < this._nodes.length ? this._nodes[startIdx] : undefined
+
+    const newNode: SurfaceNode = {
+      seq: newSeq,
+      prev: prevNode?.seq ?? null,
+      next: nextNode?.seq ?? null,
+    }
+    if (prevNode) prevNode.next = newSeq
+    if (nextNode) nextNode.prev = newSeq
+    this._nodes.splice(startIdx, 0, newNode)
+    this._nodeBySeq.set(newSeq, newNode)
+  }
+}

packages/core/session/src/types.ts

@@ -149,6 +149,24 @@ export interface TurnEndReasonMap {
 
 export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap]
 
+/**
+ * One entry in an agent's todo list — the unit of the `todo/write`
+ * {@link SessionEventMap} event's whole-list snapshot.
+ *
+ * Deliberately minimal: a human-readable `content` line and a three-state
+ * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
+ * on every write (last-write-wins), so entries need no stable identity, and the
+ * status triple is exactly the ACP `PlanEntryStatus`, so a UI bridge can map a
+ * todo list onto an ACP `plan` 1:1 (synthesizing the priority ACP additionally
+ * requires).
+ */
+export interface TodoItem {
+  /** What this task is — a short imperative line shown in the UI. */
+  content: string
+  /** Lifecycle state. `in_progress` marks the single task being worked now. */
+  status: 'pending' | 'in_progress' | 'completed'
+}
+
 /**
  * The session event vocabulary — the append-only source of truth for an
  * agent's whole interaction history. The LLM message history is *derived*
@@ -194,15 +212,92 @@ export interface SessionEventMap {
   'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string } }
   /** Steering content injected between steps of a running turn. */
   'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
+  /**
+   * The agent's whole todo list, carried as a full snapshot and replaced
+   * wholesale on each write — the current list is the most recent `todo/write`
+   * (last-write-wins on replay, no fold). Appended by an owning agent via
+   * `session.append('todo/write', { todos })`.
+   *
+   * NOT a {@link SurfaceEventType}: it produces no LLM message and never reaches
+   * `deriveMessages()`, so it carries no `surfaceOp` and stays off the surface —
+   * it is durable, replayable UI state, distinct from the conversation history.
+   * It is a `SessionEventMap` member riding the existing `session/event` emit,
+   * not a first-class Cordis `interface Events` notification, so it has no
+   * cordis-catalog row.
+   */
+  'todo/write': { todos: TodoItem[] }
 }
 
 export type SessionEventType = keyof SessionEventMap
 
+/**
+ * The subset of {@link SessionEventType} values whose events produce LLM
+ * messages and are eligible to appear on the surface linked list. Only these
+ * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}.
+ */
+export type SurfaceEventType =
+  | 'user/message'
+  | 'assistant/message'
+  | 'tool/result'
+  | 'context/message'
+  | 'steering/message'
+
+/**
+ * A {@link SessionEvent} that is **on** the surface linked list — its
+ * `surfaceOp` is guaranteed present (mandatory), narrowed from a
+ * surface-eligible {@link SessionEvent} by checking both `type` and
+ * `surfaceOp` at runtime.
+ *
+ * Use the `isSurfaceEvent` type guard (in `surface.ts`) to narrow a
+ * `SessionEvent` to this type.
+ */
+export type SurfaceEvent = SessionEvent<SurfaceEventType> & { surfaceOp: SurfaceOp }
+
+/**
+ * How a session event entered the surface linked list. Only valid on
+ * {@link SurfaceEventType} events.
+ *
+ * - `'append'`: added to the tail — normal path for user/assistant/tool/context
+ *   messages.
+ * - `{ op: 'replace', start, end }`: replaces surface nodes from `start`
+ *   (inclusive) through `end` (inclusive) with this node. Both must exist as
+ *   surface nodes in the current surface. `start === end` replaces a single
+ *   node. The node's {@link SessionEvent.sourceEventSeqs} must include every
+ *   shadowed surface node. Used by compaction and possible other manipulations.
+ */
+export type SurfaceOp =
+  | 'append'
+  | { op: 'replace'; start: number; end: number }
+
+/**
+ * Surface metadata passed to {@link Session.append}.
+ * `surfaceOp` controls how the event enters the surface linked list;
+ * `sourceEventSeqs` records the seq numbers of events that are provenance
+ * sources of this one (e.g. the `assistant/chunk` seqs behind an
+ * `assistant/message`, or the shadowed nodes behind a compaction replacement).
+ *
+ * Required for {@link SurfaceEventType} events — every message-producing event
+ * MUST declare how it enters the surface, because the surface is the sole
+ * source of derived history. Non-surface event types (`turn/start`,
+ * `assistant/chunk`, `error`, …) cannot carry surface metadata.
+ */
+export interface SurfaceIntent {
+  surfaceOp: SurfaceOp
+  sourceEventSeqs?: number[]
+}
+
 /**
  * One immutable entry in the session log.
  *
  * A proper discriminated union over `type` (not independent `type`/`data`
  * unions), so `switch (event.type)` narrows `event.data` without casts.
+ *
+ * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
+ * they only exist on {@link SurfaceEventType} variants (`user/message`,
+ * `assistant/message`, `tool/result`, `context/message`, `steering/message`).
+ * Non-surface events (boundary markers, chunks, usage, errors) never carry
+ * surface metadata — the compiler enforces this at `Session.append()`
+ * call sites.
  */
 export type SessionEvent<T extends SessionEventType = SessionEventType> = {
   [K in SessionEventType]: {
@@ -212,5 +307,14 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /** Unix epoch milliseconds. */
     time: number
     data: SessionEventMap[K]
-  }
+  } & (K extends SurfaceEventType ? {
+    /**
+     * Seq numbers of events that are provenance sources of this event
+     * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
+     * or the surface nodes shadowed by a compaction marker).
+     */
+    sourceEventSeqs?: number[]
+    /** How this event entered the surface; absent for non-surface events. */
+    surfaceOp?: SurfaceOp
+  } : object)
 }[T]

packages/core/session/tests/properties.spec.ts

@@ -11,22 +11,29 @@ import { describe, expect, it } from 'vitest'
 import fc from 'fast-check'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import type { SessionEventMap, SessionEventType } from '@deepseek-ai/dsh-session'
+import type { SessionEventMap, SessionEventType, SurfaceIntent } from '@deepseek-ai/dsh-session'
 
-type Appendable = { [T in SessionEventType]: { type: T; data: SessionEventMap[T] } }[SessionEventType]
+// An appendable event: its type/data plus, for surface-eligible types, the
+// explicit surface intent the generator declares (mirroring how a real caller
+// passes it). The intent is part of the generated fixture, NOT synthesized by
+// `build`, so each arbitrary states the marker it produces.
+type Appendable = {
+  [T in SessionEventType]: { type: T; data: SessionEventMap[T]; intent?: SurfaceIntent }
+}[SessionEventType]
 
 const textContentArb = fc.array(
   fc.record({ type: fc.constant<'text'>('text'), text: fc.string() }),
   { maxLength: 3 },
 )
 
-// A message-producing event (these DO affect derived history).
+// A message-producing event (these DO affect derived history). Each carries an
+// explicit `surfaceOp: 'append'` intent — the marker the real loop passes.
 const messageEventArb: fc.Arbitrary<Appendable> = fc.oneof(
-  textContentArb.map((content): Appendable => ({ type: 'user/message', data: { content, source: { kind: 'user' } } })),
-  textContentArb.map((content): Appendable => ({ type: 'assistant/message', data: { turn: 1, step: 1, content } })),
-  textContentArb.map((content): Appendable => ({ type: 'assistant/message', data: { turn: 1, step: 1, content, usage: { inputTokens: 1, outputTokens: 1 } } })),
+  textContentArb.map((content): Appendable => ({ type: 'user/message', data: { content, source: { kind: 'user' } }, intent: { surfaceOp: 'append' } })),
+  textContentArb.map((content): Appendable => ({ type: 'assistant/message', data: { turn: 1, step: 1, content }, intent: { surfaceOp: 'append' } })),
+  textContentArb.map((content): Appendable => ({ type: 'assistant/message', data: { turn: 1, step: 1, content, usage: { inputTokens: 1, outputTokens: 1 } }, intent: { surfaceOp: 'append' } })),
   fc.record({ id: fc.string({ minLength: 1 }), content: textContentArb, isError: fc.boolean() })
-    .map((r): Appendable => ({ type: 'tool/result', data: { turn: 1, step: 1, callId: CallId(r.id), content: r.content, isError: r.isError } })),
+    .map((r): Appendable => ({ type: 'tool/result', data: { turn: 1, step: 1, callId: CallId(r.id), content: r.content, isError: r.isError }, intent: { surfaceOp: 'append' } })),
 )
 
 // A non-message event (trace/replay data — must NOT affect derived history).
@@ -44,7 +51,11 @@ const logArb = fc.array(anyEventArb, { maxLength: 25 })
 let counter = 0
 function build(events: Appendable[]): Session {
   const session = new Session(SessionId(`prop-${counter++}`))
-  for (const e of events) session.append(e.type, e.data)
+  for (const e of events) {
+    // Forward the generated intent verbatim; non-surface events carry none.
+    if (e.intent !== undefined) session.append(e.type, e.data, e.intent)
+    else session.append(e.type, e.data)
+  }
   return session
 }
 

packages/core/session/tests/repair.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { interruptedTurnClosers } from '../src/index.ts'
-import type { SessionEvent } from '../src/index.ts'
+import type { SessionEvent, SurfaceEvent } from '../src/index.ts'
 
 /**
  * Unit coverage for the crash-recovery closer synthesis. The persistence
@@ -137,4 +137,36 @@ describe('interruptedTurnClosers', () => {
     const result = closers[0]!
     expect(result.type === 'tool/result' && result.data.callId).toBe('call-b')
   })
+
+  it('synthesized tool/result carries surfaceOp and sourceEventSeqs when tool/call was logged', () => {
+    const events: SessionEvent[] = [
+      userTurnStart(1, 0),
+      { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },
+      { type: 'assistant/message', seq: 2, time: 2, data: { turn: 1, step: 1, content: [
+        { type: 'tool-call', id: CallId('call-1'), name: 'bash', arguments: '{}' },
+      ] } },
+      { type: 'tool/call', seq: 3, time: 3, data: { turn: 1, step: 1, callId: CallId('call-1'), name: 'bash', arguments: '{}' } },
+    ]
+    const closers = interruptedTurnClosers(events)
+    expect(closers.map(e => e.type)).toEqual(['tool/result', 'step/end', 'turn/end'])
+    const result = closers[0]!
+    expect((result as SurfaceEvent).surfaceOp).toBe('append')
+    expect((result as SurfaceEvent).sourceEventSeqs).toEqual([3])
+  })
+
+  it('handles tool/call without a matching assistant/message entry gracefully', () => {
+    // A tool/call event exists in the log but no assistant/message registered
+    // the callId in pendingCalls (e.g., a plugin appended it directly, or the
+    // assistant/message from a prior step didn't have this call). The repair
+    // should still close the turn — it just won't synthesize a result for this
+    // call (there's nothing to answer).
+    const events: SessionEvent[] = [
+      userTurnStart(1, 0),
+      { type: 'step/start', seq: 1, time: 1, data: { turn: 1, step: 1 } },
+      { type: 'tool/call', seq: 2, time: 2, data: { turn: 1, step: 1, callId: CallId('orphan'), name: 'bash', arguments: '{}' } },
+    ]
+    const closers = interruptedTurnClosers(events)
+    // No pending calls → no synthetic tool/result, just step/end + turn/end.
+    expect(closers.map(e => e.type)).toEqual(['step/end', 'turn/end'])
+  })
 })

packages/core/session/tests/session.spec.ts

@@ -2,12 +2,13 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SESSION_FORMAT_VERSION, Session, SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEventType, TodoItem } from '@deepseek-ai/dsh-session'
 
 describe('Session', () => {
   it('derives message history from the event log', () => {
     const session = new Session(SessionId('s1'))
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-    session.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } })
+    session.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hi' } })
     session.append('assistant/message', {
       turn: 1, step: 1,
@@ -15,8 +16,8 @@ describe('Session', () => {
         { type: 'text', text: 'let me check' },
         { type: 'tool-call', id: CallId('c1'), name: 'echo', arguments: '{}' },
       ],
-    })
-    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false })
+    }, { surfaceOp: 'append' })
+    session.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
     session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
 
     const messages = session.deriveMessages()
@@ -44,12 +45,12 @@ describe('Session', () => {
     session.append('context/message', {
       content: [{ type: 'text', text: 'file changed: a.ts' }],
       source: { kind: 'plugin', plugin: 'watcher' },
-    })
+    }, { surfaceOp: 'append' })
     session.append('steering/message', {
       turn: 1,
       content: [{ type: 'text', text: 'focus on tests' }],
       source: { kind: 'user' },
-    })
+    }, { surfaceOp: 'append' })
 
     const [contextMessage, steeringMessage] = session.deriveMessages()
     expect(contextMessage!.role).toBe('user')
@@ -60,8 +61,8 @@ describe('Session', () => {
 
   it('replays identically from a seeded event log', () => {
     const original = new Session(SessionId('s3'))
-    original.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } })
-    original.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }] })
+    original.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    original.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }] }, { surfaceOp: 'append' })
 
     const replayed = new Session(SessionId('s3-replay'), [...original.events])
     expect(replayed.deriveMessages()).toEqual(original.deriveMessages())
@@ -70,11 +71,11 @@ describe('Session', () => {
 
   it('isolates the log from mutation through a derived message (append-only contract)', () => {
     const session = new Session(SessionId('s4'))
-    session.append('user/message', { content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } })
+    session.append('user/message', { content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     session.append('tool/result', {
       turn: 1, step: 1, callId: CallId('c1'),
       content: [{ type: 'text', text: 'tool out' }], isError: false,
-    })
+    }, { surfaceOp: 'append' })
     const before = structuredClone(session.events)
 
     // A request middleware / adapter mutates the messages it was handed.
@@ -95,7 +96,7 @@ describe('Session', () => {
 
   it('rejects non-JSON-serializable event data at the source (incl. sparse arrays)', () => {
     const session = new Session(SessionId('s5'))
-    const bad = (extra: unknown) => () => session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra } as never)
+    const bad = (extra: unknown) => () => session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra } as never, { surfaceOp: 'append' })
     expect(bad(1n)).toThrow(/non-JSON-serializable/)
     expect(bad(() => 0)).toThrow(/non-JSON-serializable/)
     expect(bad(Symbol('s'))).toThrow(/non-JSON-serializable/)
@@ -120,9 +121,24 @@ describe('Session', () => {
     expect(session.events).toHaveLength(0)
   })
 
+  it('rejects a surface-eligible append with no surfaceOp marker (runtime guard for the union-widening loophole)', () => {
+    const session = new Session(SessionId('s5b'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    // The typed overload makes surfaceOp mandatory only when the type argument is
+    // a SPECIFIC SurfaceEventType literal. A caller iterating raw events widens it
+    // to the SessionEventType union, where the conditional rest collapses to
+    // optional — the exact shape `for (const e of log) append(e.type, e.data)`
+    // produces. Reproduce that here and assert the runtime guard rejects it.
+    const widenedType = 'user/message' as SessionEventType
+    expect(() => session.append(widenedType, { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }))
+      .toThrow(/surface-eligible and requires a surfaceOp marker/)
+    // The rejected append never entered the log (only turn/start is present).
+    expect(session.events).toHaveLength(1)
+  })
+
   it('accepts dense arrays and nested plain objects', () => {
     const session = new Session(SessionId('s6'))
-    expect(() => session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra: [1, 2, [3, { a: null, b: true }]] } as never)).not.toThrow()
+    expect(() => session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' }, extra: [1, 2, [3, { a: null, b: true }]] } as never, { surfaceOp: 'append' })).not.toThrow()
     expect(session.events).toHaveLength(1)
   })
 
@@ -143,10 +159,23 @@ describe('Session', () => {
     expect(() => new Session(SessionId('seed-gap'), gapSeed)).toThrow(/contiguous|seq/)
   })
 
+  it('validates seed events: rejects a surface-eligible event missing its surfaceOp marker', () => {
+    // A surface-eligible event (user/message) with no surfaceOp would load fine
+    // but vanish from deriveMessages() (the surface is the sole derivation path),
+    // so a resume/fork would silently lose history. append() forbids this at
+    // compile time; a raw seed must be rejected at runtime to match.
+    const markerlessSeed = [
+      { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
+      { type: 'user/message' as const, seq: 1, time: 2, data: { content: [{ type: 'text' as const, text: 'hi' }], source: { kind: 'user' as const } } },
+      { type: 'turn/end' as const, seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' as const } } },
+    ] as SessionEvent[]
+    expect(() => new Session(SessionId('seed-no-marker'), markerlessSeed)).toThrow(/surface-eligible but carries no surfaceOp/)
+  })
+
   it('accepts a well-formed contiguous serializable seed', () => {
     const goodSeed = [
       { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
-      { type: 'user/message' as const, seq: 1, time: 2, data: { content: [{ type: 'text' as const, text: 'hi' }], source: { kind: 'user' as const } } },
+      { type: 'user/message' as const, seq: 1, time: 2, data: { content: [{ type: 'text' as const, text: 'hi' }], source: { kind: 'user' as const } }, surfaceOp: 'append' as const },
       { type: 'turn/end' as const, seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' as const } } },
     ] as SessionEvent[]
     const session = new Session(SessionId('seed-ok'), goodSeed)
@@ -156,7 +185,7 @@ describe('Session', () => {
   it('snapshots the seed: mutating the original after construction does not affect session.events', () => {
     const seed = [
       { type: 'turn/start' as const, seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
-      { type: 'user/message' as const, seq: 1, time: 2, data: { content: [{ type: 'text' as const, text: 'original' }], source: { kind: 'user' as const } } },
+      { type: 'user/message' as const, seq: 1, time: 2, data: { content: [{ type: 'text' as const, text: 'original' }], source: { kind: 'user' as const } }, surfaceOp: 'append' as const },
       { type: 'turn/end' as const, seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' as const } } },
     ] as SessionEvent[]
     const session = new Session(SessionId('seed-snapshot'), seed)
@@ -174,7 +203,7 @@ describe('Session', () => {
   it('snapshots append data: mutating the passed object after append does not affect session.events', () => {
     const session = new Session(SessionId('append-snapshot'))
     const data = { content: [{ type: 'text' as const, text: 'original' }], source: { kind: 'user' as const } }
-    const event = session.append('user/message', data)
+    const event = session.append('user/message', data, { surfaceOp: 'append' })
     // Mutate the caller's object after append returns. A shared reference would
     // make session.events diverge from the value that passed validation.
     data.content[0]!.text = 'HACKED'
@@ -201,7 +230,7 @@ describe('SessionStore', () => {
     const session = ctx.sessions.create()
     expect(created).toEqual([session])
 
-    session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } })
+    session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     expect(events).toHaveLength(1)
     expect(events[0]![0]).toBe(session)
     expect(events[0]![1].type).toBe('user/message')
@@ -216,7 +245,7 @@ describe('SessionStore', () => {
     const a = ctx.sessions.create(SessionId('fixed'))
     expect(() => ctx.sessions.create(SessionId('fixed'))).toThrow('already exists')
 
-    a.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } })
+    a.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     const forked = ctx.sessions.create(SessionId('fork'), { seed: [...a.events] })
     expect(forked.deriveMessages()).toEqual(a.deriveMessages())
   })
@@ -309,7 +338,7 @@ describe('SessionStore', () => {
 
     await fiber.dispose()
     expect(ctx.sessions.get(SessionId('scoped'))).toBeUndefined()
-    session.append('user/message', { content: [{ type: 'text', text: 'late' }], source: { kind: 'user' } })
+    session.append('user/message', { content: [{ type: 'text', text: 'late' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     expect(observed).toBe(0)
   })
 
@@ -332,7 +361,67 @@ describe('SessionStore', () => {
     ctx.on('session/event', (_session, event) => void events.push(event))
     const session = ctx.sessions.create(SessionId('fixed'))
     expect(ctx.sessions.get(SessionId('fixed'))).toBe(session)
-    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } })
+    session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
     expect(events).toHaveLength(1)
   })
 })
+
+describe('todo/write event', () => {
+  it('appends the whole-list snapshot and isolates the log from later mutation', () => {
+    const session = new Session(SessionId('t1'))
+    const todos: TodoItem[] = [
+      { content: 'plan the work', status: 'in_progress' },
+      { content: 'write the code', status: 'pending' },
+    ]
+    session.append('todo/write', { todos })
+
+    const event = session.events.findLast(e => e.type === 'todo/write')!
+    expect(event.type).toBe('todo/write')
+    expect(event.data.todos).toEqual(todos)
+
+    // The append snapshots its input: mutating the caller's array afterward must
+    // not change what the log holds (the durable-source-of-truth contract).
+    todos.push({ content: 'sneak in', status: 'pending' })
+    todos[0]!.status = 'completed'
+    expect(event.data.todos).toEqual([
+      { content: 'plan the work', status: 'in_progress' },
+      { content: 'write the code', status: 'pending' },
+    ])
+  })
+
+  it('is last-write-wins: the current list is the most recent todo/write', () => {
+    const session = new Session(SessionId('t2'))
+    session.append('todo/write', { todos: [{ content: 'first', status: 'pending' }] })
+    session.append('todo/write', { todos: [
+      { content: 'first', status: 'completed' },
+      { content: 'second', status: 'in_progress' },
+    ] })
+
+    const current = session.events.findLast(e => e.type === 'todo/write')!.data.todos
+    expect(current).toEqual([
+      { content: 'first', status: 'completed' },
+      { content: 'second', status: 'in_progress' },
+    ])
+  })
+
+  it('is NOT a surface event: it produces no derived message and joins no surface node', () => {
+    const session = new Session(SessionId('t3'))
+    session.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const before = session.deriveMessages().length
+    session.append('todo/write', { todos: [{ content: 'a task', status: 'pending' }] })
+    // The todo event must not add a message to the derived history…
+    expect(session.deriveMessages()).toHaveLength(before)
+    // …and must not appear on the surface linked list.
+    expect(session.surface.nodes.some(node => node.seq === session.seq - 1)).toBe(false)
+  })
+
+  it('round-trips through a seeded replay identically (durable, no surfaceOp needed)', () => {
+    const original = new Session(SessionId('t4'))
+    original.append('todo/write', { todos: [{ content: 'only', status: 'completed' }] })
+    // Seeding a non-surface event with no surfaceOp must not throw.
+    const replayed = new Session(SessionId('t4-replay'), [...original.events])
+    expect(replayed.events.findLast(e => e.type === 'todo/write')!.data.todos)
+      .toEqual([{ content: 'only', status: 'completed' }])
+    expect(replayed.seq).toBe(original.seq)
+  })
+})

packages/core/session/tests/surface.spec.ts

@@ -0,0 +1,319 @@
+import { describe, expect, it } from 'vitest'
+import type { SessionEvent, SurfaceEvent, SurfaceEventType } from '@deepseek-ai/dsh-session'
+import { Session, SessionId, isSurfaceEligibleType, isSurfaceEvent } from '@deepseek-ai/dsh-session'
+import { CallId } from '@deepseek-ai/dsh-llm'
+
+/** Build a minimal session with turn boundaries and a single user message. */
+function surfaceSession(): Session {
+  const s = new Session(SessionId('ss'))
+  s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+  s.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+  s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'hi' }] }, { surfaceOp: 'append' })
+  s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+  return s
+}
+
+describe('SurfaceManager', () => {
+  it('rebuilds a linked list from surfaceOp: append markers', () => {
+    const s = surfaceSession()
+    const nodes = s.surface.nodes
+    // Only the user/message and assistant/message carry surfaceOp: 'append'.
+    // The turn boundaries do not have surface markers.
+    expect(nodes.length).toBe(2)
+    expect(nodes[0]!.seq).toBe(1) // user/message (turn/start is seq 0)
+    expect(nodes[0]!.prev).toBeNull()
+    expect(nodes[0]!.next).toBe(2) // assistant/message (seq 2)
+    expect(nodes[1]!.seq).toBe(2)
+    expect(nodes[1]!.prev).toBe(1)
+    expect(nodes[1]!.next).toBeNull()
+  })
+
+  it('invalidate resets to full rebuild', () => {
+    const s = surfaceSession()
+    expect(s.surface.nodes.length).toBe(2)
+    // After invalidate, the surface should rebuild from scratch on next access.
+    ;(s.surface).invalidate()
+    expect(s.surface.nodes.length).toBe(2) // same result, but rebuilt
+  })
+
+  it('empty surface yields empty nodes', () => {
+    const s = new Session(SessionId('empty'))
+    // Only turn boundaries, no surface nodes.
+    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    s.append('step/start', { turn: 1, step: 1 })
+    s.append('step/end', { turn: 1, step: 1 })
+    s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    expect(s.surface.nodes.length).toBe(0)
+    // deriveMessages returns empty array
+    expect(s.deriveMessages()).toEqual([])
+  })
+
+  it('picks up new events incrementally (delta processing)', () => {
+    const s = surfaceSession()
+    expect(s.surface.nodes.length).toBe(2)
+    // Append another surface node
+    s.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+    expect(s.surface.nodes.length).toBe(3)
+    expect(s.surface.nodes[2]!.seq).toBe(4) // seq 4: after turn/end at seq 3
+    expect(s.surface.nodes[2]!.prev).toBe(2)
+    expect(s.surface.nodes[1]!.next).toBe(4)
+  })
+
+  it('replays identically from a seeded log with surface markers', () => {
+    const original = surfaceSession()
+    original.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' })
+    const replayed = new Session(SessionId('replay'), [...original.events])
+    // Surface rebuilds from the seeded log's markers.
+    expect(replayed.surface.nodes.map(n => n.seq)).toEqual([1, 2, 4])
+    expect(replayed.deriveMessages()).toEqual(original.deriveMessages())
+  })
+
+  it('rebuild with replace operation splices out shadowed nodes', () => {
+    const s = surfaceSession()
+    // seq: 0=turn/start, 1=user, 2=assistant, 3=turn/end
+    // Surface nodes: seq 1 (user), seq 2 (assistant).
+    // Replace both with a compaction marker. Both 1 and 2 are valid surface seqs.
+    s.append('assistant/message',
+      { turn: 2, step: 1, content: [{ type: 'text', text: 'summary' }] },
+      { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] },
+    )
+    // Now the surface should have just the compaction node.
+    expect(s.surface.nodes.length).toBe(1)
+    expect(s.surface.nodes[0]!.seq).toBe(4) // seq of the compaction marker
+    expect(s.surface.nodes[0]!.prev).toBeNull()
+    expect(s.surface.nodes[0]!.next).toBeNull()
+  })
+
+  it('replace with both ends at real nodes splices only the range', () => {
+    const s = new Session(SessionId('range'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
+    s.append('user/message', { content: [{ type: 'text', text: 'c' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
+    // Replace seq 0 through 1 inclusive: shadow a and b, keep c.
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'summary' }] },
+      { surfaceOp: { op: 'replace', start: 0, end: 1 }, sourceEventSeqs: [0, 1] },
+    ) // seq 3
+    expect(s.surface.nodes.map(n => n.seq)).toEqual([3, 2])
+    // Links: 3 ↔ 2
+    expect(s.surface.nodes[0]!.prev).toBeNull()
+    expect(s.surface.nodes[0]!.next).toBe(2)
+    expect(s.surface.nodes[1]!.prev).toBe(3)
+    expect(s.surface.nodes[1]!.next).toBeNull()
+  })
+
+  it('single-node replacement (start === end)', () => {
+    const s = new Session(SessionId('single'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
+    // Replace only seq 1 (single node).
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
+      { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
+    ) // seq 2
+    expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 2])
+    expect(s.surface.nodes[0]!.next).toBe(2)
+    expect(s.surface.nodes[1]!.prev).toBe(0)
+  })
+
+  it('throws when replace start is not found', () => {
+    const s = new Session(SessionId('bad-start'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
+      { surfaceOp: { op: 'replace', start: 5, end: 0 }, sourceEventSeqs: [5, 0] },
+    )
+    expect(() => s.surface.nodes).toThrow(/surface replace: start seq 5 not found/)
+  })
+
+  it('throws when replace end is not found', () => {
+    const s = new Session(SessionId('bad-end'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
+      { surfaceOp: { op: 'replace', start: 0, end: 99 }, sourceEventSeqs: [0] },
+    )
+    expect(() => s.surface.nodes).toThrow(/surface replace: end seq 99 not found/)
+  })
+
+  it('throws when start is after end', () => {
+    const s = new Session(SessionId('reversed'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
+    // start=1, end=0 would be reversed order.
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'y' }] },
+      { surfaceOp: { op: 'replace', start: 1, end: 0 }, sourceEventSeqs: [1, 0] },
+    )
+    expect(() => s.surface.nodes).toThrow(/start seq 1.*after end seq 0/)
+  })
+
+  it('sourceEventSeqs is snapshot so caller mutation does not affect logged event', () => {
+    const s = new Session(SessionId('immutable'))
+    const sources = [10, 20]
+    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'h' }] }, { surfaceOp: 'append', sourceEventSeqs: sources })
+    // Mutate caller's array after append.
+    sources.push(30)
+    sources[0] = 99
+    const logged = s.events[0]! as SurfaceEvent
+    expect(logged.sourceEventSeqs).toEqual([10, 20])
+  })
+
+  it('replace starting at non-head position links to previous node correctly', () => {
+    const s = new Session(SessionId('mid-replace'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0
+    s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1
+    s.append('user/message', { content: [{ type: 'text', text: 'c' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2
+    // Replace the middle node (seq 1) only, keeping seq 0 and seq 2.
+    s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] },
+      { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] },
+    ) // seq 3
+    expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 3, 2])
+    // Links: 0 → 3 → 2
+    expect(s.surface.nodes[0]!.prev).toBeNull()
+    expect(s.surface.nodes[0]!.next).toBe(3)
+    expect(s.surface.nodes[1]!.prev).toBe(0)
+    expect(s.surface.nodes[1]!.next).toBe(2)
+    expect(s.surface.nodes[2]!.prev).toBe(3)
+    expect(s.surface.nodes[2]!.next).toBeNull()
+  })
+
+  it('surfaceOp replace object is snapshot so caller mutation is isolated', () => {
+    const s = new Session(SessionId('immutable-op'))
+    s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const op = { op: 'replace' as const, start: 0, end: 0 }
+    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 's' }] }, { surfaceOp: op, sourceEventSeqs: [0] })
+    // Mutate caller's object after append.
+    op.start = 99
+    const logged = s.events[1]! as SurfaceEvent
+    expect(logged.surfaceOp).toEqual({ op: 'replace', start: 0, end: 0 })
+  })
+})
+
+describe('deriveMessages with surface', () => {
+  it('uses the surface path when surface markers are present', () => {
+    const s = surfaceSession()
+    const messages = s.deriveMessages()
+    expect(messages).toHaveLength(2)
+    expect(messages[0]!.role).toBe('user')
+    expect(messages[0]!.content[0]).toMatchObject({ type: 'text', text: 'hello' })
+    expect(messages[1]!.role).toBe('assistant')
+    expect(messages[1]!.content[0]).toMatchObject({ type: 'text', text: 'hi' })
+  })
+
+  it('surface path skips non-surface events (chunks, boundaries)', () => {
+    const s = new Session(SessionId('filter'))
+    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } })
+    s.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 1, text: 'i' } })
+    s.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'hi' }] }, { surfaceOp: 'append' })
+    s.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    // Chunks and boundaries are NOT in the surface, so only 2 messages.
+    expect(s.deriveMessages()).toHaveLength(2)
+  })
+
+  it('deriveMessages via surface respects replace (shadowed nodes are excluded)', () => {
+    const s = new Session(SessionId('compacted'))
+    s.append('user/message', { content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    s.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'compacted' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] })
+    // Only the compaction node is visible.
+    const messages = s.deriveMessages()
+    expect(messages).toHaveLength(1)
+    expect(messages[0]!.content[0]).toMatchObject({ type: 'text', text: 'compacted' })
+  })
+
+  it('context/message and steering/message appear on surface', () => {
+    const s = new Session(SessionId('ctx'))
+    s.append('context/message', { content: [{ type: 'text', text: 'file changed' }], source: { kind: 'plugin', plugin: 'watcher' } }, { surfaceOp: 'append' })
+    s.append('steering/message', { turn: 1, content: [{ type: 'text', text: 'focus' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+    const messages = s.deriveMessages()
+    expect(messages).toHaveLength(2)
+    expect(messages[0]!.content[0]).toMatchObject({ type: 'text', text: '<context source="plugin">' })
+    expect(messages[1]!.content[0]).toMatchObject({ type: 'text', text: '<steering source="user">' })
+  })
+})
+
+describe('Session.append surface opts', () => {
+  it('records sourceEventSeqs and surfaceOp on the event', () => {
+    const s = new Session(SessionId('opts'))
+    const event = s.append('assistant/message',
+      { turn: 1, step: 1, content: [{ type: 'text', text: 'h' }] },
+      { surfaceOp: 'append', sourceEventSeqs: [3, 5, 7] },
+    )
+    expect(event.sourceEventSeqs).toEqual([3, 5, 7])
+    expect(event.surfaceOp).toBe('append')
+    // The logged event matches the returned event.
+    expect((s.events[0]! as SurfaceEvent).sourceEventSeqs).toEqual([3, 5, 7])
+    expect((s.events[0]! as SurfaceEvent).surfaceOp).toBe('append')
+  })
+
+  it('deriveMessages skips a surface node that derives to null (empty assistant/message)', () => {
+    // An empty-content assistant/message is surface-eligible (it can host usage)
+    // but _deriveOneMessage returns null for it, so the surface derivation path's
+    // null-check is exercised — the node is on the surface yet produces no message.
+    const seed: SessionEvent[] = [
+      { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+      { type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } },
+      { type: 'assistant/message', seq: 2, time: 3, data: { turn: 1, step: 1, content: [] }, surfaceOp: 'append' },
+      { type: 'step/end', seq: 3, time: 4, data: { turn: 1, step: 1 } },
+      { type: 'turn/end', seq: 4, time: 5, data: { turn: 1, reason: { kind: 'completed' } } },
+    ]
+    const s = new Session(SessionId('nomessage'), seed)
+    // The empty assistant/message is on the surface but _deriveOneMessage returns null for it.
+    expect(s.deriveMessages()).toHaveLength(0)
+  })
+
+  it('a non-surface event carries no surface fields', () => {
+    const s = new Session(SessionId('noopts'))
+    s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    expect((s.events[0] as SessionEvent<SurfaceEventType>).sourceEventSeqs).toBeUndefined()
+    expect((s.events[0] as SessionEvent<SurfaceEventType>).surfaceOp).toBeUndefined()
+  })
+
+  it('surfaceOp primitives are not cloned (they are immutable)', () => {
+    const s = new Session(SessionId('prim'))
+    const event = s.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append' })
+    // The string 'append' is a primitive — identity-preserving is fine.
+    expect(event.surfaceOp).toBe('append')
+  })
+})
+
+describe('surface type guards', () => {
+  it('isSurfaceEligibleType is true only for message-producing types', () => {
+    expect(isSurfaceEligibleType('user/message')).toBe(true)
+    expect(isSurfaceEligibleType('assistant/message')).toBe(true)
+    expect(isSurfaceEligibleType('tool/result')).toBe(true)
+    expect(isSurfaceEligibleType('context/message')).toBe(true)
+    expect(isSurfaceEligibleType('steering/message')).toBe(true)
+    expect(isSurfaceEligibleType('turn/start')).toBe(false)
+    expect(isSurfaceEligibleType('assistant/chunk')).toBe(false)
+  })
+
+  it('isSurfaceEvent narrows a fully-formed surface event', () => {
+    const s = surfaceSession()
+    const userMessage = s.events.find(e => e.type === 'user/message')!
+    expect(isSurfaceEvent(userMessage)).toBe(true)
+  })
+
+  it('isSurfaceEvent rejects a non-surface-eligible type', () => {
+    const s = surfaceSession()
+    const turnStart = s.events.find(e => e.type === 'turn/start')!
+    expect(isSurfaceEvent(turnStart)).toBe(false)
+  })
+
+  it('isSurfaceEvent rejects a surface-eligible type missing its surfaceOp marker', () => {
+    // A surface-eligible type whose mandatory surfaceOp is absent — the state a
+    // seed/load log can carry before the marker is validated. surfaceOp is
+    // optional on SessionEvent, so this is a representable runtime value.
+    const markerless: SessionEvent = {
+      type: 'user/message',
+      seq: 0,
+      time: 0,
+      data: { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } },
+    }
+    expect(isSurfaceEligibleType(markerless.type)).toBe(true)
+    expect(isSurfaceEvent(markerless)).toBe(false)
+  })
+})