Files

T

Tianyi Cui 78d60366ec Record fork and mixed spawn+fork snapshot scenarios

The seed-boundary change made fork-child replay route correctly but shipped
with no recorded fork scenario — the seedLength slice was exercised only by
llm-replay unit tests and a persistence round-trip, never by the full-transcript
snapshot tier. Add two recorded scenarios that drive a real fork child through
it:

- subagent-fork: parent completes a turn, then forks one child (child fixture
  carries a non-zero seedLength, the boundary the replay slice consumes).
- subagent-mixed: parent completes a turn, then delegates once via spawn
  (seedLength 0) and once via fork (non-zero seedLength) in one transcript —
  the first scenario to drive two subagent backends at once, exercising both
  branches of the slice.

Both need a completed turn-1 so the fork seed is a non-empty completed-turn
prefix (a turn-1 fork seeds empty = spawn, which would not exercise the slice).
Removing the slice turns both scenarios red (the fork child receives the
parent's recorded chunks), proving the guard bites.

ACP (out-of-process) subagent replay remains a different shape, still tracked
as TODO(acp-subagent-replay).

2026-06-22 21:20:54 +08:00

5.6 KiB

Raw Blame History

RFC: Persist the seed boundary so fork-child replay routes correctly

Status: implemented

Problem

The per-session snapshot replay RFC made the snapshot tier express a nested-agent shape: a parent plus one recorded log per in-process subagent, each replayed as its own script keyed by calling session. It noted (§ Scope, final bullet) that a fork snapshot was "a trivial future addition, not a gap in the keying." That was wrong about a fork child specifically — not the keying, but the script derivation.

A subagent script is derived from a recorded session log by deriveReplayScript: it groups the log's assistant/chunk events by (turn, step) into one replay entry per stream() call. This is correct for a spawn child, whose log contains only its own model calls.

A fork child is different. The fork backend seeds the child session with a balanced completed-turn prefix of the parent's log (dsh-subagent-inprocess), and that seed becomes the child session's persisted log (Session's constructor copies the seed into this.log). So a fork child's .jsonl begins with the parent's events — including the parent's assistant/chunk events — and only then carries the child's own turn.

Deriving the child script from the whole fork-child log therefore replays the parent's recorded responses as the child's model calls: the live fork child's first stream() would receive the parent's first recorded chunk sequence instead of its own. The recorded scenarios are all spawn today, so this never fired — but a fork snapshot would have mis-routed silently, exactly the class of bug the snapshot tier exists to catch.

Decision

Record where a session's inherited prefix ends, persist it, and have the replay harness derive a child's script from its own events only.

1. `seedLength` on the session header

SessionHeader gains an optional seedLength: number — how many leading events were inherited via a seed rather than produced by this session. The fork backend stamps it (= the seeded-prefix length) when it creates the child; a fresh spawn leaves it absent (≡ 0). It is threaded through CreateSessionOptions.meta (and CreateAgentOptions.meta), set in SessionStore.prepare.

seedLength is explicit, never inferred from seed.length. A reconstruction (resume/load) seeds the session with its WHOLE stored log, so seed.length there is the full length, not the original boundary — the resume path passes the persisted seedLength back from the loaded header instead. (Same shape as createdAt, which is also explicitly preserved on reconstruction rather than re-defaulted to now.)

2. Both persistence backends round-trip it

JSONL: a seedLength field on the header line (toHeaderLine/fromHeaderLine).
SQLite: a seed_length column on the sessions table.

The SQLite change is a breaking table-layout change, so SCHEMA_VERSION bumps 2 → 3. Per the repo's pre-release stance (§ "Pre-release stance" in AGENTS.md) the backend rejects a non-current user_version on open rather than migrating it — there is no persisted user data to preserve, so no migration code is written (the existing reject-not-migrate path at openDatabase already enforces this; v1 and now v2 are both rejected).

3. Replay derives a child script after the boundary

dsh-llm-replay's parseSessionHeader now also reads seedLength (absent ⇒ 0), and loadSessionScripts derives a child's entries from parseSessionLog(text).slice(seedLength) — the events at or after the boundary, i.e. the child's own model calls. For a spawn child seedLength is 0 and this is a no-op, so spawn scenarios are byte-for-byte unchanged.

This closes the routing correctness gap, and two recorded fork scenarios exercise it end to end — see Record fork and mixed spawn+fork snapshot scenarios.

Alternatives considered

Derive the boundary heuristically in llm-replay (the seeded prefix is contiguous parent events ending at the last turn/end before the child's first user/message). Rejected: a brittle heuristic in the test harness that re-derives a fact the producer already knows. Persisting the boundary at its source (the fork backend) is the "explicit > implicit at package seams" rule applied across the persistence boundary — the reader of a child fixture never has to reconstruct where the inheritance ended.
Pin the format version instead of bumping (the SESSION_FORMAT_VERSION = 0 "unstable" stance the event log uses). Rejected for the SQLite table layout: SCHEMA_VERSION is the monotonic bump-and-reject knob (a small enumerable set of revisions worth telling apart), distinct from the event-vocabulary version. Adding a column is precisely the breaking table change it versions, so it bumps.

Consequences

A new persisted header field across core + both backends; the core-data-structures catalog (persistence.md) is updated in the same change (its SessionHeader / CreateSessionOptions type-equiv blocks).
Existing SQLite databases at schema v2 are rejected on open (no user data pre-release).
Spawn replay is unchanged (seedLength 0). Fork replay now routes a child to its own script; covered by a regression in llm-replay's tests (a child fixture whose seeded prefix carries a parent chunk — the derived child script must exclude it, proven red without the slice) and a persistence round-trip test (both backends, via the shared coordinator contract).

5.6 KiB Raw Blame History