Persist the seed boundary so fork-child replay routes correctly

A fork subagent seeds its child session with a prefix of the parent's log, and
that seed becomes the child's persisted log — so a fork child's .jsonl begins
with the PARENT's events, including the parent's assistant/chunk events. The
snapshot replay harness derived a child's script from its whole log, which would
replay the parent's recorded responses as the child's model calls. Spawn-only
scenarios never hit it, but a fork snapshot would mis-route silently.

Record the seed boundary and skip the inherited prefix at replay:

- SessionHeader gains an optional `seedLength` (how many leading events were
  inherited via a seed), threaded through CreateSessionOptions/CreateAgentOptions
  meta and stamped by the fork backend (= seeded-prefix length; absent for spawn).
  It is EXPLICIT, never inferred from seed.length: a resume seeds the whole stored
  log, so the resume path passes the persisted boundary back.
- Both persistence backends round-trip it: JSONL header line, SQLite seed_length
  column. The SQLite table change bumps SCHEMA_VERSION 2->3; per the pre-release
  stance the backend rejects an older user_version on open with NO migration.
- llm-replay's parseSessionHeader reads seedLength and loadSessionScripts derives
  a child script from events AFTER the boundary. seedLength is 0 for spawn, so
  spawn replay is byte-for-byte unchanged.

Closes the routing-correctness gap the per-session snapshot replay RFC under-
stated; a recorded fork scenario remains a future addition but now derives
correctly. RFC: docs/rfc/implemented/testing/2026-06-22-fork-child-replay-seed-boundary.md.

Regression coverage: a fork child fixture whose seeded prefix carries a parent
chunk (derived script must exclude it, proven red without the slice); a seedLength
persistence round-trip through the shared coordinator contract (both backends);
the fork backend stamping it; resume preserving it from the persisted header.

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

@@ -219,6 +219,9 @@ export class AgentLoop extends Service implements AgentFactory {
         createdAt: meta.createdAt,
         ...meta.cwd !== undefined ? { cwd: meta.cwd } : {},
         ...meta.parentSession !== undefined ? { parentSession: meta.parentSession } : {},
+        // Reconstruct the seed boundary from the persisted header, NOT from
+        // `events.length` (the resume seeds the WHOLE stored log).
+        ...meta.seedLength !== undefined ? { seedLength: meta.seedLength } : {},
       },
     })
     return this.startOwned(options.agentId, options.agentOptions ?? {}, session)

packages/core/agent-loop/tests/resume.spec.ts

@@ -94,9 +94,9 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     await ctx2.fiber.dispose()
   })
 
-  it('resume of a forked session preserves the parentSession lineage in the header', async () => {
-    // Lifecycle 1: persist a FORKED session (carries parentSession in its
-    // header) by creating it with a complete-turn seed — the write path
+  it('resume of a forked session preserves the parentSession lineage and seed boundary in the header', async () => {
+    // Lifecycle 1: persist a FORKED session (carries parentSession + seedLength
+    // in its header) by creating it with a complete-turn seed — the write path
     // materializes the fork (header + seed) on disk.
     const seed: SessionEvent[] = [
       { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
@@ -104,12 +104,18 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     ]
     const adapter1 = new MockAdapter([textResponse('a')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const forked = ctx1.sessions.create(SessionId('forked-sess'), { seed, meta: { cwd: '/w', parentSession: SessionId('parent-sess') } })
+    const forked = ctx1.sessions.create(SessionId('forked-sess'), {
+      seed,
+      meta: { cwd: '/w', parentSession: SessionId('parent-sess'), seedLength: seed.length },
+    })
     await ctx1.parallel('session/flush', forked)
     await ctx1.fiber.dispose()
 
-    // Lifecycle 2: resume it; the parentSession header survives the round-trip
-    // (exercises resume's parentSession-present branch).
+    // Lifecycle 2: resume it; the parentSession + seedLength header survives the
+    // round-trip (exercises resume's parentSession- and seedLength-present
+    // branches). seedLength must come from the PERSISTED header, not from the
+    // resume seed length (which is the whole stored log, not the original
+    // boundary).
     const adapter2 = new MockAdapter([textResponse('b')])
     const ctx2 = new Context()
     await ctx2.plugin(LlmService)
@@ -123,6 +129,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
     const a2 = (await ctx2.agents.resume({ agentId: AgentId('m'), resumeSessionId: SessionId('forked-sess') })).agent as ReactLoopAgent
     expect(a2.session.header.parentSession).toBe('parent-sess')
     expect(a2.session.header.cwd).toBe('/w')
+    expect(a2.session.header.seedLength).toBe(seed.length)
     await ctx2.fiber.dispose()
   })
 

packages/core/agent/src/index.ts

@@ -30,13 +30,14 @@ export interface CreateAgentOptions {
   /** The live session's id (NOT derived from agentId). */
   sessionId: SessionId
   /**
-   * Session creation metadata: validated absolute `cwd` and `parentSession`
-   * fork lineage. Mirrors the `cwd`/`parentSession` fields of
+   * Session creation metadata: validated absolute `cwd`, `parentSession`
+   * fork lineage, and the `seedLength` seed boundary. Mirrors the
+   * `cwd`/`parentSession`/`seedLength` fields of
    * {@link CreateSessionOptions.meta} in dsh-session (the internal-only
    * `createdAt`, used when reconstructing a persisted session, is deliberately
    * excluded — a factory caller never sets it).
    */
-  meta?: { cwd?: string; parentSession?: SessionId }
+  meta?: { cwd?: string; parentSession?: SessionId; seedLength?: number }
   /**
    * Seed events to reconstruct the child session's log from (the fork lineage
    * primitive). When present, the factory creates the session with this event

packages/core/session/src/index.ts

@@ -289,6 +289,7 @@ export class SessionStore extends Service {
       createdAt: options?.meta?.createdAt ?? Date.now(),
       ...cwd !== undefined ? { cwd } : {},
       ...options?.meta?.parentSession !== undefined ? { parentSession: options.meta.parentSession } : {},
+      ...options?.meta?.seedLength !== undefined ? { seedLength: options.meta.seedLength } : {},
     }
     return new Session(sessionId, options?.seed, header)
   }

packages/core/session/src/types.ts

@@ -50,6 +50,16 @@ export interface SessionHeader {
   cwd?: string
   /** The session this one was forked from (seed lineage), if any. */
   parentSession?: SessionId
+  /**
+   * How many leading events were INHERITED via a seed rather than produced by
+   * this session — the seed boundary. Set when a fork seeds a child with a
+   * prefix of the parent's log (= the seeded prefix length); absent/0 means the
+   * session produced all its own events. Persisted so a reload reconstructs the
+   * boundary instead of re-deriving it from the full stored log, and so a replay
+   * harness can skip the inherited prefix when deriving the child's OWN script
+   * (the seeded events are the parent's, not this child's model calls).
+   */
+  seedLength?: number
 }
 
 /**
@@ -63,10 +73,16 @@ export interface CreateSessionOptions {
   /**
    * Creation metadata. The store fills in `version`/`id` and defaults
    * `createdAt` to now; the caller supplies the storage-level fields (validated
-   * absolute `cwd`, `parentSession` lineage, and — when reconstructing a
-   * persisted session — the original `createdAt` to preserve it).
+   * absolute `cwd`, `parentSession` lineage, the seed boundary `seedLength`, and
+   * — when reconstructing a persisted session — the original `createdAt` to
+   * preserve it).
+   *
+   * `seedLength` is EXPLICIT, not inferred from `seed.length`: a reconstruction
+   * (resume/load) seeds the WHOLE stored log, so its `seed.length` is the full
+   * length, not the original boundary — the caller must pass the persisted
+   * boundary back. A fresh fork passes its actual seeded-prefix length.
    */
-  meta?: { cwd?: string; parentSession?: SessionId; createdAt?: number }
+  meta?: { cwd?: string; parentSession?: SessionId; createdAt?: number; seedLength?: number }
 }
 
 /**

packages/session-persistence/session-persistence-jsonl/src/format.ts

@@ -24,6 +24,7 @@ export interface HeaderLine {
   createdAt: number
   cwd?: string
   parentSession?: SessionId
+  seedLength?: number
 }
 
 /** Build the header line object from a {@link SessionHeader}. */
@@ -35,6 +36,7 @@ export function toHeaderLine(header: SessionHeader): HeaderLine {
     createdAt: header.createdAt,
     ...header.cwd !== undefined ? { cwd: header.cwd } : {},
     ...header.parentSession !== undefined ? { parentSession: header.parentSession } : {},
+    ...header.seedLength !== undefined ? { seedLength: header.seedLength } : {},
   }
 }
 
@@ -46,6 +48,7 @@ export function fromHeaderLine(line: HeaderLine): SessionHeader {
     createdAt: line.createdAt,
     ...line.cwd !== undefined ? { cwd: line.cwd } : {},
     ...line.parentSession !== undefined ? { parentSession: line.parentSession } : {},
+    ...line.seedLength !== undefined ? { seedLength: line.seedLength } : {},
   }
 }
 

packages/session-persistence/session-persistence-sqlite/src/index.ts

@@ -224,19 +224,21 @@ export class SessionPersistenceSqlite extends SessionPersistence implements Pers
    */
   private writeRow(meta: SessionHeader): void {
     this.db.prepare(`
-      INSERT INTO sessions (id, version, created_at, cwd, parent_session)
-      VALUES (?, ?, ?, ?, ?)
+      INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length)
+      VALUES (?, ?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         version = excluded.version,
         created_at = excluded.created_at,
         cwd = excluded.cwd,
-        parent_session = excluded.parent_session
+        parent_session = excluded.parent_session,
+        seed_length = excluded.seed_length
     `).run(
       meta.id,
       meta.version,
       meta.createdAt,
       meta.cwd ?? null,
       meta.parentSession ?? null,
+      meta.seedLength ?? null,
     )
   }
 }

packages/session-persistence/session-persistence-sqlite/src/schema.ts

@@ -15,7 +15,7 @@ import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-se
  * layout; orthogonal to a session's own `version` (which versions the EVENT
  * vocabulary, stored per session in the `sessions` row).
  */
-export const SCHEMA_VERSION = 2
+export const SCHEMA_VERSION = 3
 
 /**
  * A row of the `sessions` table — the out-of-log metadata ({@link SessionHeader}).
@@ -30,6 +30,7 @@ export interface SessionRow {
   created_at: number
   cwd: string | null
   parent_session: string | null
+  seed_length: number | null
 }
 
 /** An `events` table row: one `SessionEvent` mapped 1:1 (`data` is JSON text). */
@@ -51,8 +52,8 @@ export interface EventRow {
  * current {@link SCHEMA_VERSION}; an existing database whose version is NOT the
  * current one (written by a different, incompatible build — older or newer) is
  * REJECTED rather than opened against a layout this build does not understand.
- * There are no migrations: v1 had a different `sessions` layout and is not
- * upgraded in place.
+ * There are no migrations: an earlier layout (v1's different `sessions` shape,
+ * v2 without the `seed_length` column) is not upgraded in place — it is rejected.
  */
 export function openDatabase(path: string): DatabaseSync {
   const db = new DatabaseSync(path)
@@ -76,7 +77,8 @@ export function openDatabase(path: string): DatabaseSync {
       version        INTEGER NOT NULL,
       created_at     INTEGER NOT NULL,
       cwd            TEXT,
-      parent_session TEXT
+      parent_session TEXT,
+      seed_length    INTEGER
     ) STRICT
   `)
   db.exec(`
@@ -100,6 +102,7 @@ export function rowToMeta(row: SessionRow): SessionHeader {
     createdAt: row.created_at,
     ...row.cwd !== null ? { cwd: row.cwd } : {},
     ...row.parent_session !== null ? { parentSession: row.parent_session as SessionId } : {},
+    ...row.seed_length !== null ? { seedLength: row.seed_length } : {},
   }
 }
 

packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts

@@ -315,7 +315,7 @@ describe('SessionPersistenceSqlite: durability and crash semantics', () => {
   })
 
   it('exposes the schema version constant', () => {
-    expect(SCHEMA_VERSION).toBe(2)
+    expect(SCHEMA_VERSION).toBe(3)
   })
 })
 

packages/session-persistence/session-persistence/tests/coordinator-contract.ts

@@ -123,6 +123,26 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
       }
     })
 
+    it('round-trips the seed boundary (seedLength) through persistence', async () => {
+      // A forked child records how many leading events were inherited via the
+      // seed; the boundary must survive a reload (so a resume/replay can tell the
+      // inherited prefix from the child's own events). Both backends carry it on
+      // the header — JSONL on the header line, SQLite in the seed_length column.
+      const fix = await makeFixture()
+      const { ctx, fiber } = await freshCtx(fix)
+      try {
+        const session = ctx.sessions.create(SessionId('forked-child'), { meta: { cwd: WORK, seedLength: 3 } })
+        send(session, oneTurnLog())
+        await ctx.parallel('session/flush', session)
+
+        const loaded = await ctx.sessionPersistence.load(SessionId('forked-child'))
+        expect(loaded.meta.seedLength).toBe(3)
+      } finally {
+        await fiber.dispose()
+        await fix.cleanup()
+      }
+    })
+
     it('snapshot-on-buffer: mutating an event after session/event does not corrupt the persisted copy', async () => {
       const fix = await makeFixture()
       const { ctx, fiber } = await freshCtx(fix)

packages/subagent/subagent-fork/tests/subagent-fork.spec.ts

@@ -106,6 +106,10 @@ describe('dsh-subagent-fork', () => {
     expect(seededUser).toBeDefined()
     // Lineage stamped.
     expect(child.session.header.parentSession).toBe(parent.session.header.id)
+    // The seed boundary is recorded on the header (= the seeded prefix length),
+    // so a reload / replay harness can tell the inherited prefix from the
+    // child's own events.
+    expect(child.session.header.seedLength).toBe(parentPrefixLen)
     await run.dispose()
   })
 

packages/subagent/subagent-inprocess/src/index.ts

@@ -122,6 +122,9 @@ export function startInProcessRun(
     meta: {
       ...parentHeader.cwd !== undefined ? { cwd: parentHeader.cwd } : {},
       parentSession: parentHeader.id,
+      // Record the seed boundary so a reload (and a replay harness) can tell the
+      // inherited prefix from the child's OWN events. 0 for a fresh spawn.
+      ...seedLength > 0 ? { seedLength } : {},
     },
     ...options.seed !== undefined ? { seed: options.seed } : {},
     agentOptions,

packages/support/llm-replay/src/index.ts

@@ -140,18 +140,21 @@ export function parseSessionLog(text: string): SessionEvent[] {
 
 /**
  * Read the identifying facts off a session log's header line (line 0): the
- * recorded session `id` (diagnostics) and `createdAt` (the deterministic
- * ordering key that binds a recorded script to a live session — see
- * {@link SessionScript}). A header missing either field falls back to a stable
- * default (`''` / `0`) rather than throwing: a no-model fixture is header-only
- * and still orders fine as the single (primary) script.
+ * recorded session `id` (diagnostics), `createdAt` (the deterministic ordering
+ * key that binds a recorded script to a live session — see
+ * {@link SessionScript}), and `seedLength` (the seed boundary — how many leading
+ * events were INHERITED via a fork seed rather than produced by this session's
+ * own model calls; absent ⇒ 0). A header missing a field falls back to a stable
+ * default (`''` / `0` / `0`) rather than throwing: a no-model fixture is
+ * header-only and still orders fine as the single (primary) script.
  */
-export function parseSessionHeader(text: string): { id: string; createdAt: number } {
+export function parseSessionHeader(text: string): { id: string; createdAt: number; seedLength: number } {
   const firstLine = text.split('\n').find(line => line.trim().length > 0) ?? '{}'
-  const parsed = JSON.parse(firstLine) as { id?: unknown; createdAt?: unknown }
+  const parsed = JSON.parse(firstLine) as { id?: unknown; createdAt?: unknown; seedLength?: unknown }
   return {
     id: typeof parsed.id === 'string' ? parsed.id : '',
     createdAt: typeof parsed.createdAt === 'number' ? parsed.createdAt : 0,
+    seedLength: typeof parsed.seedLength === 'number' ? parsed.seedLength : 0,
   }
 }
 
@@ -257,10 +260,17 @@ export function loadSessionScripts(config: ReplayConfig): SessionScript[] {
     }
     const text = readFileSync(childFile, 'utf8')
     const header = parseSessionHeader(text)
+    // Derive the child's script from its OWN events only — events AT OR AFTER
+    // the seed boundary. A FORK child's log begins with the seeded parent prefix
+    // (the parent's events, including its `assistant/chunk`s); replaying those as
+    // the child's model calls would feed the child the PARENT's recorded
+    // responses. `seedLength` is 0 for a fresh (spawn) child, so this is a no-op
+    // there.
+    const ownEvents = parseSessionLog(text).slice(header.seedLength)
     children.push({
       recordedId: header.id,
       createdAt: header.createdAt,
-      entries: deriveReplayScript(parseSessionLog(text)),
+      entries: deriveReplayScript(ownEvents),
       primary: false,
     })
   }

packages/support/llm-replay/tests/llm-replay.spec.ts

@@ -35,12 +35,13 @@ const TEXT_CHUNKS: StreamChunk[] = [
 ]
 
 /** Build a minimal session-JSONL string: a header line + the given events. */
-function sessionJsonl(events: SessionEvent[], header?: { id?: string; createdAt?: number }): string {
+function sessionJsonl(events: SessionEvent[], header?: { id?: string; createdAt?: number; seedLength?: number }): string {
   const headerLine = JSON.stringify({
     type: 'session',
     version: 0,
     id: header?.id ?? 's1',
     createdAt: header?.createdAt ?? 0,
+    ...header?.seedLength !== undefined ? { seedLength: header.seedLength } : {},
   })
   return [headerLine, ...events.map(e => JSON.stringify(e))].join('\n') + '\n'
 }
@@ -370,17 +371,22 @@ describe('installLlmReplay (through the real waterfall)', () => {
 })
 
 describe('parseSessionHeader', () => {
-  it('reads id and createdAt off the header line', () => {
+  it('reads id, createdAt, and seedLength off the header line', () => {
     expect(parseSessionHeader(sessionJsonl([], { id: 'abc', createdAt: 42 })))
-      .toEqual({ id: 'abc', createdAt: 42 })
+      .toEqual({ id: 'abc', createdAt: 42, seedLength: 0 })
   })
 
-  it('falls back to id="" / createdAt=0 when the header lacks them', () => {
-    expect(parseSessionHeader('{"type":"session","version":0}\n')).toEqual({ id: '', createdAt: 0 })
+  it('reads a non-zero seedLength (a fork child header)', () => {
+    expect(parseSessionHeader('{"type":"session","version":0,"id":"child","createdAt":7,"seedLength":4}\n'))
+      .toEqual({ id: 'child', createdAt: 7, seedLength: 4 })
+  })
+
+  it('falls back to id="" / createdAt=0 / seedLength=0 when the header lacks them', () => {
+    expect(parseSessionHeader('{"type":"session","version":0}\n')).toEqual({ id: '', createdAt: 0, seedLength: 0 })
   })
 
   it('falls back on an empty buffer (no header line)', () => {
-    expect(parseSessionHeader('')).toEqual({ id: '', createdAt: 0 })
+    expect(parseSessionHeader('')).toEqual({ id: '', createdAt: 0, seedLength: 0 })
   })
 })
 
@@ -420,6 +426,32 @@ describe('loadSessionScripts', () => {
       .toThrow(/child fixture not found/)
   })
 
+  it('derives a FORK child script from its OWN events only (skips the seeded parent prefix)', () => {
+    // A fork child's log begins with the seeded parent prefix — the parent's
+    // events, INCLUDING its assistant/chunk events. Deriving the child script
+    // from the whole log would replay the PARENT's recorded responses as the
+    // child's model calls. With seedLength recorded, the child script must
+    // contain only the child's OWN chunks (those after the boundary).
+    const parentChunk: StreamChunk = { type: 'text-delta', index: 0, text: 'PARENT-RESPONSE' }
+    const childChunks: StreamChunk[] = [{ type: 'text-delta', index: 0, text: 'CHILD-RESPONSE' }, { type: 'finish', reason: { kind: 'stop' } }]
+    const f = writeSession('session.jsonl', { id: 'parent', createdAt: 100 }, [TEXT_CHUNKS])
+    // The child fixture: 2 seeded parent events (a chunk + its finish) then the
+    // child's own turn. seedLength = 2 marks where the inherited prefix ends.
+    const childEvents: SessionEvent[] = [
+      chunkEvent(0, 1, 1, parentChunk),
+      chunkEvent(1, 1, 1, { type: 'finish', reason: { kind: 'stop' } }),
+      chunkEvent(2, 2, 1, childChunks[0]!),
+      chunkEvent(3, 2, 1, childChunks[1]!),
+    ]
+    const childPath = join(dir, 'session.1.jsonl')
+    writeFileSync(childPath, sessionJsonl(childEvents, { id: 'child', createdAt: 200, seedLength: 2 }), 'utf8')
+
+    const scripts = loadSessionScripts({ file: f, childFiles: [childPath] })
+    // The child script is ONLY the child's own model call — the parent's seeded
+    // chunk is gone.
+    expect(scripts[1]?.entries).toEqual([{ kind: 'chunks', chunks: childChunks }])
+  })
+
   it('uses the override for the primary and still derives children', () => {
     writeFileSync(file, sessionJsonl([], { id: 'p', createdAt: 1 }), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')