diff --git a/changelog/unreleased/claudecode-fork.md b/changelog/unreleased/claudecode-fork.md new file mode 100644 index 00000000..a1de029b --- /dev/null +++ b/changelog/unreleased/claudecode-fork.md @@ -0,0 +1,21 @@ +--- +category: Fixed +--- + +- `integrations/claudecode`: fork works on a runtime that snapshots memory. A fork child's turns no + longer all fail with `claudecode: session has earlier turns but this harness holds no state for + it`. The child's first turn adopts its parent's Claude Code session from the cloned harness memory + and continues it under the child's own id with `--resume --fork-session --session-id + `; the parent's transcript is left untouched. The child adopts only when its History + ends with the fork marker, the harness started the last turn before the marker (a turn journaled + without an execution start counts), and exactly one session on the clone last ran that turn; + otherwise it still fails closed with the same error. That includes a fork of a child whose turn + never reached the harness, and a fork whose last turn the harness refused before starting it + (context already done, another turn running, or a fork of it in flight). Until Claude Code + confirms the child's own session, every child attempt, a retry after a cancelled or failed one + included, checks again that the parent has not started a turn since the fork, and fails the same + way if it has. While that attempt runs, a turn of the parent, and of any fork not yet confirmed + between the child and the session it copies, fails with `claudecode: a fork of this session is + running a turn that may still read this session's conversation; retry when it ends`, so continuing + the parent right after a fork on an instance that serves both fails until the child's turn ends. + Claude Code's transcript directory must be on the filesystem the runtime clones. diff --git a/docs/harness-authoring.md b/docs/harness-authoring.md index 92834c5f..b5fd9249 100644 --- a/docs/harness-authoring.md +++ b/docs/harness-authoring.md @@ -920,11 +920,28 @@ gives up, for the calls it makes itself, what depends on the host making the cal deliberately. The class is not declared in `Describe`: the host cannot see a model call that does not reach it, so say which class your harness is in its documentation. [`integrations/claudecode`](../integrations/claudecode) is an unmediated harness that runs Claude -Code, in its own module so the root module names no model provider. Fork does not work with it yet. -On a runtime that snapshots memory, forking a session that has run a turn creates a child, but the -child holds no Claude Code session of its own, so every turn on it fails with -`claudecode: session has earlier turns but this harness holds no state for it`. A follow-up issue -tracks adopting the parent's Claude Code session on the child. +Code, in its own module so the root module names no model provider. Fork works on a runtime that +snapshots memory: the child runs on a clone of its parent's compute, and its first turn adopts the +parent's Claude Code session with `--resume --fork-session --session-id `. +Claude Code copies the parent's transcript under the child's own id and leaves the parent's +untouched. The transcript directory (`CLAUDE_CONFIG_DIR`, default `$HOME/.claude`) must be on the +filesystem the runtime clones. The child adopts only when its History ends with the fork marker, the +harness started the last turn before the marker (a turn journaled without an execution start +counts), and exactly one Claude Code session on the clone last ran that turn. Until Claude Code +confirms the child's own session, every child attempt, a retry after a cancelled or failed one +included, checks again that the parent has not started a turn since the fork. While that attempt +runs, a turn of the parent, and of any fork not yet confirmed between the child and the session it +copies, fails with `claudecode: a fork of this session is running a turn that may still read this +session's conversation; retry when it ends`, so the parent's transcript cannot move on before Claude +Code copies it. On an instance that serves both sessions, continuing the parent right after a fork +therefore fails until the child's turn ends. If any adoption check fails, every turn on the child +fails with `claudecode: session has earlier turns but this harness holds no state for it`. That +covers a clone of a different instance, a parent that ran on after the fork on a shared instance, a +child whose first turn was journaled but never reached the harness, and a fork of that child. It +also covers a fork whose last turn the harness refused before starting it (the turn's context was +already done, another turn was running, or a fork of it was in flight): the harness cannot tell that +turn from one that ran elsewhere. A later parent turn that the harness runs lets a new fork adopt +again. What is different: diff --git a/integrations/claudecode/claudecode.go b/integrations/claudecode/claudecode.go index 7f9842fa..28579dd7 100644 --- a/integrations/claudecode/claudecode.go +++ b/integrations/claudecode/claudecode.go @@ -3,7 +3,8 @@ // // claude -p --output-format stream-json --verbose --include-partial-messages \ // --permission-mode --setting-sources user --strict-mcp-config \ -// (--session-id|--resume) [--model m] [--max-turns n] [--max-budget-usd x] +// (--session-id | --resume | --resume --fork-session --session-id ) \ +// [--model m] [--max-turns n] [--max-budget-usd x] // // with the turn's text inputs on stdin, and maps its stream-json events onto the sink. The recorded // fixtures in testdata come from Claude Code 2.1.311; New does not check the installed version. @@ -55,9 +56,41 @@ // init moves to the next attempt, so a transcript left by a dead attempt cannot block the session. // Nothing extra is persisted: the memory snapshot carries the id, and the runtime's snapshot must // also preserve the filesystem that holds Claude Code's transcripts. A harness instance that holds -// no state for a session whose History already has turns (memory lost, a fork child, or a session -// that started on another harness) refuses the turn rather than start an empty conversation -// (EXE-43). A re-run of an execution this instance already started fails without starting Claude +// no state for a session whose History already has turns (memory lost, or a session that started +// on another harness) refuses the turn rather than start an empty conversation (EXE-43). +// +// A fork child on a runtime that snapshots memory runs on a clone of its parent's compute, so its +// harness memory holds the parent's entry, keyed by the parent's session UID, and none of its own. +// Its first turn adopts the parent's Claude Code session when all of these hold: History ends with +// a LIFECYCLE FORK marker and no EXECUTION_START or INPUT after it; the last execution before the +// marker, the fork point, is one this instance started; and exactly one session entry, not running +// a turn, has that execution as its last. The fork point is the execution of the last +// EXECUTION_START or INPUT before the marker, so an execution journaled with no EXECUTION_START +// (EXE-31) counts, and a legacy INPUT with no execution ID is not a known fork point. The child +// then passes --resume --fork-session --session-id : Claude Code copies the +// parent's transcript under the child's own id and leaves the parent's untouched, and later child +// turns pass --resume . The parent's entry is read, never changed. Until Claude Code +// confirms the child's id, every child attempt, a retry of one cancelled before it ran or one that +// failed before init included, rechecks that the parent is still idle at the fork point, so it +// never copies a turn the parent began after the fork. While such an attempt runs, a turn of the +// parent, and of any fork not yet confirmed between the child and the session it copies, is +// refused with a fork-in-progress error, so the transcript cannot move on before Claude Code +// copies it: on an instance that serves both, continuing the parent right after a fork fails +// until the child's turn ends. A parent whose id Claude Code never confirmed has no conversation +// to continue, so the child starts its own, as the parent's next turn would. Any other fork child +// with no state refuses as above: a fork onto an instance that did not run the parent's last +// turn, a parent that ran on after the fork point on a shared instance (before the child's id is +// confirmed), or a child whose first turn was journaled but never reached this instance (a turn +// after the marker that this instance holds no record of). Such a child stays refused for good, +// and so does a fork of it: its unrecorded turn is the grandchild's fork point. A fork of a child +// whose id is not confirmed yet is refused whenever a retry of that child would be. The same holds +// for a fork whose fork point this instance refused before recording it as started (its ctx was +// already done, another turn was running, or a fork of it was in progress): the instance cannot +// tell that turn from one that ran elsewhere. A later parent turn that starts on the instance +// gives a new fork a known fork point. The transcript directory (CLAUDE_CONFIG_DIR, default +// HOME/.claude) must be on the filesystem the runtime clones with the memory. +// +// A re-run of an execution this instance already started fails without starting Claude // Code; an interrupted turn is not retried (EXE-42). Every EXECUTION_START or INPUT is evidence that // Claude Code may already have run. The journal cannot distinguish a process that started and died // before its first event from an execution a wrapper failed before invoking this harness, so this @@ -201,6 +234,16 @@ type sessionState struct { established bool // system/init confirmed the id for attempt; later turns resume it pending bool // the id for attempt was handed to a process that did not confirm it running bool // a turn is in flight + // lastExec is the execution ID of the last turn begin accepted. A fork child matches the + // session it forks from by it. + lastExec string + // forkParent and forkPoint name the session a fork child adopted and the execution it forked + // at, until Claude Code confirms the child's own id; empty when the session starts its own. + // Every attempt until then rechecks them (forkSource). + forkParent, forkPoint string + // forkReaders counts the fork-child attempts in flight that reserved this session (begin); + // while it is nonzero, a turn of this session is refused (errForkInFlight). + forkReaders int } // New validates cfg and returns a harness. @@ -330,8 +373,9 @@ func argValue(v string) bool { } // Describe declares REQUIRES_MEMORY_SNAPSHOT (the Claude Code session id lives in harness memory -// and the transcript on the compute's filesystem), not ForkSafe (a fork child holds no session of -// its own), and Streaming. +// and the transcript on the compute's filesystem), not ForkSafe (a fork by replay cannot rebuild +// the conversation; a fork that clones memory adopts the parent's session, see the package doc), +// and Streaming. func (h *Harness) Describe(context.Context) (api.Descriptor, error) { var models []string if h.cfg.Model != "" { @@ -355,6 +399,7 @@ var ( errRerun = errors.New("claudecode: execution already started on this harness; an interrupted turn is not retried") errStateLost = errors.New("claudecode: session has earlier turns but this harness holds no state for it (memory lost, fork, or harness switch)") errBusy = errors.New("claudecode: another turn is running for this session") + errForkInFlight = errors.New("claudecode: a fork of this session is running a turn that may still read this session's conversation; retry when it ends") errNoPrompt = errors.New("claudecode: inputs carry no text") errNonText = errors.New("claudecode: inputs must be text only") errPromptSize = errors.New("claudecode: inputs exceed the 10 MB prompt limit") @@ -370,11 +415,12 @@ func (h *Harness) Run(ctx context.Context, s *api.Start, sink api.EventSink) err if s == nil || s.SessionUID == "" { return errNoSession } - if err := h.begin(ctx, s); err != nil { + forkFrom, reserved, err := h.begin(ctx, s) + if err != nil { return err } established := false - defer func() { h.end(s.SessionUID, established) }() + defer func() { h.end(s.SessionUID, established, reserved) }() prompt, err := promptText(s.Inputs) if err != nil { @@ -384,77 +430,198 @@ func (h *Harness) Run(ctx context.Context, s *api.Start, sink api.EventSink) err if err != nil { return err } - flag, id := h.sessionArg(s.SessionUID) + flag, id, forkFrom := h.sessionArg(s.SessionUID, forkFrom) t := &turn{ h: h, sink: sink, sessionUID: s.SessionUID, flag: flag, sessionID: id, + forkFrom: forkFrom, model: model, receipts: h.receiptMode(s), } - err = t.run(ctx, h.args(flag, id, model), prompt) + err = t.run(ctx, h.args(flag, id, forkFrom, model), prompt) established = t.initSeen return err } // begin applies the checks that need harness memory and marks the turn running. It creates the // session's state on the first turn, before input validation, so a first turn that fails -// validation does not make every later turn look like lost memory. A turn whose ctx is already -// done stops there, before the execution is recorded as started, so nothing runs and a retry of -// it is not refused. -func (h *Harness) begin(ctx context.Context, s *api.Start) error { +// validation does not make every later turn look like lost memory; a fork child's first turn +// adopts the session it forks from (adoptFork) or is refused. Until Claude Code confirms a fork +// child's own id, every attempt, the first included, rechecks that the session it forks from is +// still idle at the fork point and returns the id the attempt forks (forkFrom), or is refused: an +// attempt cancelled or failed before init must not copy a transcript that has moved on since. A +// turn whose ctx is already done stops there, before the execution is recorded as started, so +// nothing runs and a retry of it is not refused; a fork taken right after it, with no later turn, +// is refused. +// +// Such an attempt also reserves every session forkSource checked (sources) until end releases +// them: Claude Code reads the source transcript some time after begin returns, so a turn of the +// session it forks from, which appends to that transcript, is refused meanwhile with +// errForkInFlight. Only the session whose confirmed id the attempt forks can move under it; the +// unconfirmed forks in between and a source with no conversation are reserved too, deliberately +// conservative, so one rule covers the chain. Every refusal comes before the reservation, so begin +// never returns an error holding one. A turn refused this way, like one refused as busy, is not +// recorded as started. +func (h *Harness) begin(ctx context.Context, s *api.Start) (string, []string, error) { h.mu.Lock() defer h.mu.Unlock() + var ( + forkFrom string + sources []string + ) if _, ok := h.started[s.ExecutionID]; ok { - return errRerun + return "", nil, errRerun } st := h.sessions[s.SessionUID] - if st == nil { + fresh := st == nil + if fresh { + st = &sessionState{} if hasPriorTurn(s.History) { - return errStateLost + parent, point, ok := h.adoptFork(s.History) + if !ok { + return "", nil, errStateLost + } + st.forkParent, st.forkPoint = parent, point } - st = &sessionState{} + } + if !st.established && st.forkParent != "" { + var ok bool + if forkFrom, sources, ok = h.forkSource(st.forkParent, st.forkPoint); !ok { + return "", nil, errStateLost + } + } + if fresh { h.sessions[s.SessionUID] = st } if err := ctx.Err(); err != nil { - return interruptedErr(err) + return "", nil, interruptedErr(err) } if st.running { - return errBusy + return "", nil, errBusy + } + if st.forkReaders > 0 { + return "", nil, errForkInFlight } h.started[s.ExecutionID] = struct{}{} + st.lastExec = s.ExecutionID st.running = true - return nil + for _, uid := range sources { + h.sessions[uid].forkReaders++ + } + return forkFrom, sources, nil } -// end clears the running mark and records whether Claude Code confirmed the session id. -func (h *Harness) end(sessionUID string, established bool) { +// adoptFork decides whether a session with no state of its own is a fork child of a session this +// instance holds, and returns that session's UID and the fork point; begin then checks the parent's +// conversation with forkSource. ok is false, and the turn fails closed, unless history ends with a +// FORK marker with no turn after it, the last execution before the marker (the fork point) is one +// this instance started, and exactly one idle session's last begun execution is the fork point. The +// last execution is the one of the last EXECUTION_START or INPUT before the marker, as hasPriorTurn +// reads a turn: an execution with no EXECUTION_START (EXE-31) still counts, and a legacy INPUT with +// no execution ID is not a known fork point. An execution this instance never started is not +// skipped: it may have run elsewhere or on a process that died, and adopting an older execution's +// session would continue an older conversation than the parent's last turn. That includes one begin +// refused before recording it (ctx done, busy, a fork in progress). Executions a wrapper omitted +// under EXE-44 are absent from history. The caller holds h.mu. +func (h *Harness) adoptFork(history []api.Event) (parentUID, point string, ok bool) { + marker := -1 + for i := len(history) - 1; i >= 0; i-- { + e := history[i] + if e.Kind == api.EventExecutionStart || e.Kind == api.EventInput { + return "", "", false // a turn after the fork that this instance holds no record of + } + if e.Kind == api.EventLifecycle && e.Lifecycle != nil && e.Lifecycle.Kind == api.LifecycleFork { + marker = i + break + } + } + if marker < 0 { + return "", "", false + } + for _, e := range slices.Backward(history[:marker]) { + if e.Kind == api.EventExecutionStart || e.Kind == api.EventInput { + point = e.ExecutionID + break + } + } + if _, ok := h.started[point]; point == "" || !ok { + return "", "", false // an execution this instance never started may have run: unknown state + } + found := false + for uid, st := range h.sessions { + if st.lastExec != point || st.running { + continue + } + if found { + return "", "", false // ambiguous: no execution begins under two sessions, so state is corrupt + } + parentUID, found = uid, true + } + return parentUID, point, found +} + +// forkSource returns the Claude Code session id a fork of parentUID taken at execution point +// continues: the parent's confirmed id; the id the parent, itself a fork child not yet confirmed, +// still forks from; or "" when the parent never had a conversation. ok is false while the parent +// is gone, running a turn, or has begun a turn after point: its conversation then holds more than +// the fork point's, or may. The same holds up the chain of fork children not yet confirmed. chain +// holds the UIDs of the sessions it checked, parentUID and every one up that chain, for begin to +// reserve. The caller holds h.mu. +func (h *Harness) forkSource(parentUID, point string) (from string, chain []string, ok bool) { + p := h.sessions[parentUID] + switch { + case p == nil || p.running || p.lastExec != point: + return "", nil, false + case p.established: + return sessionID(parentUID, p.attempt), []string{parentUID}, true + case p.forkParent == "": + return "", []string{parentUID}, true + } + if from, chain, ok = h.forkSource(p.forkParent, p.forkPoint); !ok { + return "", nil, false + } + return from, append(chain, parentUID), true +} + +// end clears the running mark, releases the sessions begin reserved, and records whether Claude +// Code confirmed the session id. Run defers it as soon as begin succeeds, so every path out of an +// attempt releases its reservation. +func (h *Harness) end(sessionUID string, established bool, reserved []string) { h.mu.Lock() defer h.mu.Unlock() + for _, uid := range reserved { + if r := h.sessions[uid]; r != nil { // never deleted; checked so a release cannot panic + r.forkReaders-- + } + } st := h.sessions[sessionUID] st.running = false if established { st.established = true st.pending = false + st.forkParent, st.forkPoint = "", "" } } // sessionArg picks --resume for a confirmed session id, else --session-id with the current attempt, // moving to the next attempt when the previous one was handed to a process that never confirmed it. -func (h *Harness) sessionArg(sessionUID string) (flag, id string) { +// forkFrom, from begin, is set for a fork child until its own id is confirmed: the turn then forks +// that session into the --session-id one. +func (h *Harness) sessionArg(sessionUID, forkFrom string) (flag, id, from string) { h.mu.Lock() defer h.mu.Unlock() st := h.sessions[sessionUID] if st.established { - return "--resume", sessionID(sessionUID, st.attempt) + return "--resume", sessionID(sessionUID, st.attempt), "" } if st.pending { st.attempt++ } st.pending = true - return "--session-id", sessionID(sessionUID, st.attempt) + return "--session-id", sessionID(sessionUID, st.attempt), forkFrom } // hasPriorTurn reports whether History records an earlier turn: an execution start, or an input @@ -510,8 +677,10 @@ func (h *Harness) turnModel(requested string) (string, error) { return requested, nil } -// args builds the claude argv after the binary. The prompt goes on stdin, out of argv and ps. -func (h *Harness) args(flag, id, model string) []string { +// args builds the claude argv after the binary. The prompt goes on stdin, out of argv and ps. A +// nonempty forkFrom resumes that session and forks it into id, which Claude Code accepts only with +// --session-id. +func (h *Harness) args(flag, id, forkFrom, model string) []string { args := []string{ "-p", "--output-format", "stream-json", @@ -521,8 +690,11 @@ func (h *Harness) args(flag, id, model string) []string { // Only user settings, and no MCP server: the work dir cannot widen the permission mode. "--setting-sources", "user", "--strict-mcp-config", - flag, id, } + if forkFrom != "" { + args = append(args, "--resume", forkFrom, "--fork-session") + } + args = append(args, flag, id) if model != "" { args = append(args, "--model", model) } diff --git a/integrations/claudecode/claudecode_test.go b/integrations/claudecode/claudecode_test.go index d468aa1e..d5573a9e 100644 --- a/integrations/claudecode/claudecode_test.go +++ b/integrations/claudecode/claudecode_test.go @@ -904,7 +904,7 @@ func TestCancelledBeforeStart(t *testing.T) { } // A ctx cancelled after begin, while the inputs are checked, still launches nothing. tr := &turn{h: h, sink: &recordingSink{t: t}, sessionUID: "uid", flag: "--resume", sessionID: sessionID("uid", 0)} - if err := tr.run(ctx, h.args(tr.flag, tr.sessionID, ""), "go"); !errors.Is(err, context.Canceled) { + if err := tr.run(ctx, h.args(tr.flag, tr.sessionID, "", ""), "go"); !errors.Is(err, context.Canceled) { t.Fatalf("run = %v", err) } if got := starts(t, h); len(got) != 1 { diff --git a/integrations/claudecode/fake_test.go b/integrations/claudecode/fake_test.go index 36be1525..d9563f34 100644 --- a/integrations/claudecode/fake_test.go +++ b/integrations/claudecode/fake_test.go @@ -23,7 +23,7 @@ import ( // The test binary doubles as a fake claude: the harness runs it with "-p" first, which no go test // invocation passes. The fake reads its scenario from fake-claude.json in its working directory, // records what it saw in fake-claude-record.jsonl there, and replays stream-json lines with -// {{SESSION_ID}} replaced by the id from --session-id or --resume. It never touches the network. +// {{SESSION_ID}} replaced by the id from --session-id, else --resume. It never touches the network. const ( scenarioFile = "fake-claude.json" @@ -89,12 +89,26 @@ func fakeClaude(args []string) int { fmt.Fprintln(os.Stderr, sc.Stderr) } - var id string + // The session the turn runs under: --session-id names it, also when --resume names the session + // a --fork-session copies. Claude Code 2.1.311 refuses --session-id with --resume unless + // --fork-session is also given, and so does the fake. + flags := make(map[string]string) for i, a := range args { - if (a == "--session-id" || a == "--resume") && i+1 < len(args) { - id = args[i+1] + if a == "--fork-session" { + flags[a] = "" + } else if (a == "--session-id" || a == "--resume") && i+1 < len(args) { + flags[a] = args[i+1] } } + _, resume := flags["--resume"] + id, sessionID := flags["--session-id"] + if _, fork := flags["--fork-session"]; resume && sessionID && !fork { + fmt.Fprintln(os.Stderr, "Error: --session-id can only be used with --continue or --resume if --fork-session is also specified.") + return 1 + } + if !sessionID { + id = flags["--resume"] + } out := bufio.NewWriter(os.Stdout) emit := func(line string) { out.WriteString(strings.ReplaceAll(line, "{{SESSION_ID}}", id)) diff --git a/integrations/claudecode/fork_test.go b/integrations/claudecode/fork_test.go new file mode 100644 index 00000000..5c56606e --- /dev/null +++ b/integrations/claudecode/fork_test.go @@ -0,0 +1,768 @@ +package claudecode + +import ( + "context" + "errors" + "slices" + "testing" + "time" + + "github.com/agent-primitives/sessions/api" +) + +// The tests here run the parent's and the child's turns on one harness: its memory then holds what +// a memory-tier fork's clone holds, the parent's entry keyed by the parent's UID. + +// turnEvents is what the host journals for a completed turn: its start and input, then what the +// harness reported. +func turnEvents(exec string) []api.Event { + return []api.Event{ + {ExecutionID: exec, Kind: api.EventExecutionStart, ExecutionStart: &api.ExecutionStart{}}, + {ExecutionID: exec, Kind: api.EventInput, Message: api.TextMessage("user", "go")}, + {ExecutionID: exec, Kind: api.EventOutput, Message: api.TextMessage("assistant", "Hello, world.")}, + {ExecutionID: exec, Kind: api.EventEnd}, + } +} + +// forkMarker is the child's first record after the copied prefix (controller.Fork). +func forkMarker() []api.Event { + return []api.Event{{Kind: api.EventLifecycle, Lifecycle: &api.Lifecycle{Kind: api.LifecycleFork, Detail: "parent@2"}}} +} + +// lastSessionFlags returns the session flags of the fake's last start. With Config{} they end the +// argv, after the ten fixed arguments. +func lastSessionFlags(t *testing.T, h *Harness) []string { + t.Helper() + got := starts(t, h) + if len(got) == 0 { + t.Fatal("no process started") + } + return got[len(got)-1].Args[10:] +} + +func wantFlags(t *testing.T, h *Harness, want ...string) { + t.Helper() + if got := lastSessionFlags(t, h); !slices.Equal(got, want) { + t.Fatalf("session flags = %q, want %q", got, want) + } +} + +func sessionSnapshot(h *Harness, uid string) (sessionState, bool) { + h.mu.Lock() + defer h.mu.Unlock() + st, ok := h.sessions[uid] + if !ok { + return sessionState{}, false + } + return *st, true +} + +// setRunning marks a session's turn in flight, or not, as begin and end do. +func setRunning(h *Harness, uid string, running bool) { + h.mu.Lock() + defer h.mu.Unlock() + h.sessions[uid].running = running +} + +// forkReaders returns how many fork-child attempts hold uid reserved. +func forkReaders(h *Harness, uid string) int { + st, _ := sessionSnapshot(h, uid) + return st.forkReaders +} + +// pausedTurn starts a turn whose fake claude emits nothing and blocks, as a fork child's process +// does before Claude Code has read the transcript it forks, and waits until it blocks. It then sets +// the scenario back to a text turn for the turns that follow. stop cancels the turn and returns +// its error; cleanup stops it if the test did not. +func pausedTurn(t *testing.T, h *Harness, uid, exec string, history []api.Event) (stop func() error) { + t.Helper() + blocked := func() (n int) { + for _, r := range records(t, h) { + if r.Event == "blocking" { + n++ + } + } + return n + } + before := blocked() + setScenario(t, h, scenario{Block: true}) + ctx, cancel := context.WithCancel(context.Background()) + done := make(chan error, 1) + go func() { done <- h.Run(ctx, startFor(uid, exec, history, "go"), &recordingSink{t: t}) }() + var stopped bool + var err error + stop = func() error { + if !stopped { + cancel() + err, stopped = <-done, true + } + return err + } + t.Cleanup(func() { stop() }) + for deadline := time.Now().Add(10 * time.Second); blocked() == before; time.Sleep(10 * time.Millisecond) { + select { + case err := <-done: + stopped = true + t.Fatalf("%s turn %s ended before it blocked: %v", uid, exec, err) + default: + } + if time.Now().After(deadline) { + t.Fatalf("%s turn %s never blocked", uid, exec) + } + } + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + return stop +} + +// forkInFlightTurn runs a turn that must be refused because a fork of its session is in flight: +// nothing spawns and the session's state is unchanged. +func forkInFlightTurn(t *testing.T, h *Harness, uid, exec string, history ...[]api.Event) { + t.Helper() + before, _ := sessionSnapshot(h, uid) + spawned := len(starts(t, h)) + if err := runTurn(t, h, uid, exec, history...); !errors.Is(err, errForkInFlight) { + t.Fatalf("%s turn %s = %v, want %v", uid, exec, err, errForkInFlight) + } + if got := len(starts(t, h)); got != spawned { + t.Fatalf("spawned %d processes, want %d", got, spawned) + } + if got, _ := sessionSnapshot(h, uid); got != before { + t.Fatalf("%s state = %+v, want %+v unchanged", uid, got, before) + } +} + +func runTurn(t *testing.T, h *Harness, uid, exec string, history ...[]api.Event) error { + t.Helper() + return h.Run(context.Background(), startFor(uid, exec, slices.Concat(history...), "go"), &recordingSink{t: t}) +} + +// refusedTurn runs a turn whose ctx is already done: begin refuses it before recording the +// execution as started, and nothing runs. +func refusedTurn(t *testing.T, h *Harness, uid, exec string, history []api.Event) { + t.Helper() + ctx, cancel := context.WithCancel(context.Background()) + cancel() + if err := h.Run(ctx, startFor(uid, exec, history, "go"), &recordingSink{t: t}); !errors.Is(err, context.Canceled) { + t.Fatalf("%s turn %s = %v, want context.Canceled", uid, exec, err) + } +} + +// TestForkChildAdoptsParentSession: a fork child with no state of its own forks the parent's +// Claude Code session into its own id, then resumes its own; the parent's state and session are +// untouched. +func TestForkChildAdoptsParentSession(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + parent, _ := sessionSnapshot(h, "parent") + + sink := &recordingSink{t: t} + if err := h.Run(context.Background(), startFor("child", "e2", slices.Concat(turnEvents("e1"), forkMarker()), "go"), sink); err != nil { + t.Fatal(err) + } + wantFlags(t, h, "--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child", 0)) + if !slices.Equal(sink.outputs, []string{"Hello, world."}) { + t.Fatalf("child outputs = %q", sink.outputs) + } + if got, _ := sessionSnapshot(h, "parent"); got != parent { + t.Fatalf("parent state = %+v, want %+v unchanged", got, parent) + } + + if err := runTurn(t, h, "child", "e3", turnEvents("e1"), forkMarker(), turnEvents("e2")); err != nil { + t.Fatal(err) + } + wantFlags(t, h, "--resume", sessionID("child", 0)) + if err := runTurn(t, h, "parent", "e4", turnEvents("e1")); err != nil { + t.Fatal(err) + } + wantFlags(t, h, "--resume", sessionID("parent", 0)) +} + +// TestForkChildWithoutSingleParentFailsClosed: a session with no state whose History does not +// identify exactly one idle session as the one it forks from is refused as lost state, before +// anything runs, and no state is created for it. +func TestForkChildWithoutSingleParentFailsClosed(t *testing.T) { + t.Parallel() + forked := slices.Concat(turnEvents("e1"), forkMarker()) + for _, test := range []struct { + name string + parent bool // the parent ran e1 on the harness first + setup func(t *testing.T, h *Harness) + history []api.Event + }{ + {name: "no fork marker", parent: true, history: turnEvents("e1")}, + {name: "no session on the instance", history: forked}, + {name: "fork point not started here", parent: true, history: slices.Concat(turnEvents("e0"), forkMarker())}, + // The fork point is the last execution before the marker, never an older one this instance + // started: e2 may have run elsewhere or on a process that died, so adopting e1's session + // could continue an older conversation than the parent's last turn. + { + name: "fork point ran elsewhere after a turn started here", + parent: true, + history: slices.Concat(turnEvents("e1"), turnEvents("e2"), forkMarker()), + }, + { + name: "fork point has no execution id", + parent: true, + history: slices.Concat(turnEvents("e1"), turnEvents(""), forkMarker()), + }, + // Owner-accepted consequence: begin refused e2 before recording it as started, and the + // instance cannot tell that from an e2 that ran elsewhere. + { + name: "fork point refused before it started", + parent: true, + history: slices.Concat(turnEvents("e1"), turnEvents("e2"), forkMarker()), + setup: func(t *testing.T, h *Harness) { + refusedTurn(t, h, "parent", "e2", turnEvents("e1")) + }, + }, + { + name: "fork point refused while another turn was running", + parent: true, + history: slices.Concat(turnEvents("e1"), turnEvents("e2"), forkMarker()), + setup: func(t *testing.T, h *Harness) { + setRunning(h, "parent", true) + if err := runTurn(t, h, "parent", "e2", turnEvents("e1")); !errors.Is(err, errBusy) { + t.Fatalf("parent turn e2 = %v, want %v", err, errBusy) + } + setRunning(h, "parent", false) + }, + }, + // An execution with no EXECUTION_START (EXE-31) is still an execution: its INPUT marks it, + // as hasPriorTurn reads it, so it is the fork point rather than skipped for e1. + { + name: "fork point has no execution start", + parent: true, + history: slices.Concat(turnEvents("e1"), turnEvents("e2")[1:], forkMarker()), + }, + { + name: "fork of a fork whose turn has no execution start", + parent: true, + history: slices.Concat(forked, turnEvents("e2")[1:], forkMarker()), + }, + { + name: "fork point is a legacy input with no execution id", + parent: true, + history: slices.Concat(turnEvents("e1"), turnEvents("")[1:], forkMarker()), + }, + // A fork of a fork follows the same rule as the first child: e2, the first child's turn, is + // the fork point, and this instance holds no record of it having started. + { + name: "fork of a fork whose turn never reached here", + parent: true, + history: slices.Concat(forked, turnEvents("e2"), forkMarker()), + }, + { + name: "fork of a fork whose turn was refused before it started", + parent: true, + history: slices.Concat(forked, turnEvents("e2"), forkMarker()), + setup: func(t *testing.T, h *Harness) { + refusedTurn(t, h, "fork1", "e2", forked) + }, + }, + {name: "parent ran after the fork point", parent: true, history: forked, setup: func(t *testing.T, h *Harness) { + if err := runTurn(t, h, "parent", "e3", turnEvents("e1")); err != nil { + t.Fatal(err) + } + }}, + {name: "child turn after the marker", parent: true, history: slices.Concat(forked, turnEvents("e2"))}, + {name: "legacy input after the marker", parent: true, history: slices.Concat(forked, turnEvents("e2")[1:])}, + {name: "two sessions match", parent: true, history: forked, setup: func(_ *testing.T, h *Harness) { + h.mu.Lock() + defer h.mu.Unlock() + h.sessions["other"] = &sessionState{lastExec: "e1", established: true} + }}, + {name: "parent turn in flight", parent: true, history: forked, setup: func(_ *testing.T, h *Harness) { + setRunning(h, "parent", true) + }}, + } { + t.Run(test.name, func(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if test.parent { + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + } + if test.setup != nil { + test.setup(t, h) + } + parent, _ := sessionSnapshot(h, "parent") + spawned := len(starts(t, h)) + + if err := runTurn(t, h, "child", "e9", test.history); !errors.Is(err, errStateLost) { + t.Fatalf("Run = %v, want %v", err, errStateLost) + } + if got := len(starts(t, h)); got != spawned { + t.Fatalf("spawned %d processes, want %d", got, spawned) + } + if st, ok := sessionSnapshot(h, "child"); ok { + t.Fatalf("child state created: %+v", st) + } + if got, _ := sessionSnapshot(h, "parent"); got != parent { + t.Fatalf("parent state = %+v, want %+v unchanged", got, parent) + } + }) + } +} + +// TestForkAfterParentRecovers: a fork whose fork point the instance refused is refused, but once +// the parent runs a later turn on the instance, a new fork has a known fork point and adopts. +func TestForkAfterParentRecovers(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + refusedTurn(t, h, "parent", "e2", turnEvents("e1")) + if err := runTurn(t, h, "child", "e3", turnEvents("e1"), turnEvents("e2"), forkMarker()); !errors.Is(err, errStateLost) { + t.Fatalf("fork after refused turn = %v, want %v", err, errStateLost) + } + if err := runTurn(t, h, "parent", "e4", turnEvents("e1"), turnEvents("e2")); err != nil { + t.Fatal(err) + } + history := slices.Concat(turnEvents("e1"), turnEvents("e2"), turnEvents("e4"), forkMarker()) + if err := runTurn(t, h, "child2", "e5", history); err != nil { + t.Fatal(err) + } + wantFlags(t, h, "--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child2", 0)) +} + +// TestForkChildFirstTurnFailsBeforeInit: a fork attempt that dies before init may have left a +// transcript under the child's id, so the next attempt forks into the child's next id. +func TestForkChildFirstTurnFailsBeforeInit(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + setScenario(t, h, scenario{Exit: 1}) + if err := runTurn(t, h, "child", "e2", turnEvents("e1"), forkMarker()); err == nil { + t.Fatal("failed turn returned nil") + } + wantFlags(t, h, "--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child", 0)) + + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "child", "e3", turnEvents("e1"), forkMarker(), turnEvents("e2")); err != nil { + t.Fatal(err) + } + wantFlags(t, h, "--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child", 1)) + if err := runTurn(t, h, "child", "e4", turnEvents("e1"), forkMarker(), turnEvents("e2"), turnEvents("e3")); err != nil { + t.Fatal(err) + } + wantFlags(t, h, "--resume", sessionID("child", 1)) +} + +// TestForkChildCancelledBeforeStart: a child turn cancelled before it starts launches nothing but +// keeps the adopted state, so its retry still forks the parent's session. +func TestForkChildCancelledBeforeStart(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + ctx, cancel := context.WithCancel(context.Background()) + cancel() + history := slices.Concat(turnEvents("e1"), forkMarker()) + if err := h.Run(ctx, startFor("child", "e2", history, "go"), &recordingSink{t: t}); !errors.Is(err, context.Canceled) { + t.Fatalf("Run = %v, want context.Canceled", err) + } + if got := len(starts(t, h)); got != 1 { + t.Fatalf("spawned %d processes, want 1", got) + } + if err := runTurn(t, h, "child", "e2", history); err != nil { + t.Fatalf("retry = %v", err) + } + wantFlags(t, h, "--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child", 0)) +} + +// TestForkOfUnconfirmedParent: a parent whose id Claude Code never confirmed has no conversation, +// so the child starts its own, as the parent's next turn would. +func TestForkOfUnconfirmedParent(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Exit: 1}) + if err := runTurn(t, h, "parent", "e1"); err == nil { + t.Fatal("failed turn returned nil") + } + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "child", "e2", turnEvents("e1"), forkMarker()); err != nil { + t.Fatal(err) + } + wantFlags(t, h, "--session-id", sessionID("child", 0)) +} + +// TestForkOfFork: a grandchild forks from the session its parent, itself a fork child, runs under: +// the child's own once confirmed, else the one the child was forking from. +func TestForkOfFork(t *testing.T) { + t.Parallel() + for _, test := range []struct { + name string + child *scenario // the child's turn e2, if it ran + history []api.Event + wantFrom string + }{ + { + name: "child confirmed", + child: &scenario{Fixture: "text_turn.jsonl"}, + history: slices.Concat(turnEvents("e1"), forkMarker(), turnEvents("e2"), forkMarker()), + wantFrom: sessionID("child", 0), + }, + { + name: "child failed before init", + child: &scenario{Exit: 1}, + history: slices.Concat(turnEvents("e1"), forkMarker(), turnEvents("e2"), forkMarker()), + wantFrom: sessionID("parent", 0), + }, + { + name: "child never ran", + history: slices.Concat(turnEvents("e1"), forkMarker(), forkMarker()), + wantFrom: sessionID("parent", 0), + }, + } { + t.Run(test.name, func(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + if test.child != nil { + setScenario(t, h, *test.child) + if err := runTurn(t, h, "child", "e2", turnEvents("e1"), forkMarker()); (err == nil) != (test.child.Exit == 0) { + t.Fatalf("child turn = %v, want failure %t", err, test.child.Exit != 0) + } + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + } + if err := runTurn(t, h, "grandchild", "e3", test.history); err != nil { + t.Fatal(err) + } + wantFlags(t, h, "--resume", test.wantFrom, "--fork-session", "--session-id", sessionID("grandchild", 0)) + }) + } +} + +// TestForkPointWithoutExecutionStart: an execution with no EXECUTION_START (EXE-31) that this +// instance started is a fork point the child adopts, read from its INPUT. +func TestForkPointWithoutExecutionStart(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + if err := runTurn(t, h, "child", "e2", turnEvents("e1")[1:], forkMarker()); err != nil { + t.Fatal(err) + } + wantFlags(t, h, "--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child", 0)) +} + +// TestForkChildRetryRevalidatesSource: until Claude Code confirms a fork child's own id, every +// attempt rechecks that the session it forks from is idle at the fork point. A source that ran on +// (its transcript now holds turns after the fork) or is running refuses the attempt as lost state, +// as a first attempt would be, before anything runs. Once the child's id is confirmed its turns +// resume its own transcript and the parent no longer matters. +func TestForkChildRetryRevalidatesSource(t *testing.T) { + t.Parallel() + forked := slices.Concat(turnEvents("e1"), forkMarker()) + cancelled := func(t *testing.T, h *Harness) { refusedTurn(t, h, "child", "e2", forked) } + failedBeforeInit := func(t *testing.T, h *Harness) { + setScenario(t, h, scenario{Exit: 1}) + if err := runTurn(t, h, "child", "e2", forked); err == nil { + t.Fatal("failed child turn returned nil") + } + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + } + parentRanOn := func(t *testing.T, h *Harness) { + if err := runTurn(t, h, "parent", "e3", turnEvents("e1")); err != nil { + t.Fatal(err) + } + } + for _, test := range []struct { + name string + child func(t *testing.T, h *Harness) // the child's first attempt, e2 + source func(t *testing.T, h *Harness) // what happens to the parent before the next attempt + uid string // the session of the next attempt + exec string + hist []api.Event + want []string // session flags on success; nil wants errStateLost + }{ + { + name: "cancelled child, parent unchanged", child: cancelled, + uid: "child", exec: "e2", hist: forked, + want: []string{"--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child", 0)}, + }, + {name: "cancelled child, parent ran on", child: cancelled, source: parentRanOn, uid: "child", exec: "e2", hist: forked}, + { + name: "cancelled child, parent turn in flight", child: cancelled, + source: func(_ *testing.T, h *Harness) { setRunning(h, "parent", true) }, + uid: "child", exec: "e2", hist: forked, + }, + { + name: "child failed before init, parent unchanged", child: failedBeforeInit, + uid: "child", exec: "e5", hist: slices.Concat(forked, turnEvents("e2")), + want: []string{"--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child", 1)}, + }, + { + name: "child failed before init, parent ran on", child: failedBeforeInit, source: parentRanOn, + uid: "child", exec: "e5", hist: slices.Concat(forked, turnEvents("e2")), + }, + // The grandchild forks from the child, which is still forking from the parent: the + // parent's transcript, past the child's fork point, is not the child's conversation. + { + name: "fork of an unconfirmed child whose parent ran on", child: failedBeforeInit, source: parentRanOn, + uid: "grandchild", exec: "e4", hist: slices.Concat(forked, turnEvents("e2"), forkMarker()), + }, + { + name: "confirmed child, parent ran on", + child: func(t *testing.T, h *Harness) { + if err := runTurn(t, h, "child", "e2", forked); err != nil { + t.Fatal(err) + } + }, + source: parentRanOn, + uid: "child", exec: "e4", hist: slices.Concat(forked, turnEvents("e2")), + want: []string{"--resume", sessionID("child", 0)}, + }, + } { + t.Run(test.name, func(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + test.child(t, h) + if test.source != nil { + test.source(t, h) + } + spawned := len(starts(t, h)) + err := runTurn(t, h, test.uid, test.exec, test.hist) + if test.want != nil { + if err != nil { + t.Fatalf("attempt = %v", err) + } + wantFlags(t, h, test.want...) + return + } + if !errors.Is(err, errStateLost) { + t.Fatalf("attempt = %v, want %v", err, errStateLost) + } + if got := len(starts(t, h)); got != spawned { + t.Fatalf("spawned %d processes, want %d", got, spawned) + } + }) + } +} + +// TestForkChildReservesSource: while a fork child's attempt runs, before Claude Code has read the +// transcript it forks, a turn of the session it forks from is refused, so that transcript cannot +// move past the fork point. The refused turn is not recorded as started: a fork taken at it fails +// closed, and its retry runs once the child's attempt ends. +func TestForkChildReservesSource(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + stop := pausedTurn(t, h, "child", "e2", slices.Concat(turnEvents("e1"), forkMarker())) + if got := forkReaders(h, "parent"); got != 1 { + t.Fatalf("parent reserved by %d attempts, want 1", got) + } + forkInFlightTurn(t, h, "parent", "e3", turnEvents("e1")) + if err := stop(); err == nil { + t.Fatal("cancelled child turn returned nil") + } + if got := forkReaders(h, "parent"); got != 0 { + t.Fatalf("parent reserved by %d attempts after the child ended, want 0", got) + } + + if err := runTurn(t, h, "child2", "e4", turnEvents("e1"), turnEvents("e3"), forkMarker()); !errors.Is(err, errStateLost) { + t.Fatalf("fork at the refused turn = %v, want %v", err, errStateLost) + } + if err := runTurn(t, h, "parent", "e3", turnEvents("e1")); err != nil { + t.Fatalf("retry of the refused parent turn = %v", err) + } + wantFlags(t, h, "--resume", sessionID("parent", 0)) +} + +// TestForkChildRetryReservesSource: each attempt of a fork child not yet confirmed reserves the +// session it forks from again, and releases it when it ends. +func TestForkChildRetryReservesSource(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + forked := slices.Concat(turnEvents("e1"), forkMarker()) + setScenario(t, h, scenario{Exit: 1}) + if err := runTurn(t, h, "child", "e2", forked); err == nil { + t.Fatal("failed child turn returned nil") + } + if got := forkReaders(h, "parent"); got != 0 { + t.Fatalf("parent reserved by %d attempts after the first ended, want 0", got) + } + + stop := pausedTurn(t, h, "child", "e3", slices.Concat(forked, turnEvents("e2"))) + wantFlags(t, h, "--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child", 1)) + forkInFlightTurn(t, h, "parent", "e4", turnEvents("e1")) + if err := stop(); err == nil { + t.Fatal("cancelled child turn returned nil") + } + if err := runTurn(t, h, "parent", "e4", turnEvents("e1")); err != nil { + t.Fatalf("parent turn after the retry ended = %v", err) + } +} + +// TestForkChildReleasesSource: every way a fork child's attempt ends releases the session it +// forks from; an attempt refused before it is recorded as started reserves nothing. +func TestForkChildReleasesSource(t *testing.T) { + t.Parallel() + forked := slices.Concat(turnEvents("e1"), forkMarker()) + for _, test := range []struct { + name string + child func(t *testing.T, h *Harness) + }{ + {name: "ctx done before begin", child: func(t *testing.T, h *Harness) { refusedTurn(t, h, "child", "e2", forked) }}, + {name: "input validation fails", child: func(t *testing.T, h *Harness) { + data := api.Message{Role: "user", Parts: []api.Part{{Data: map[string]any{"k": "v"}}}} + s := &api.Start{ExecutionID: "e2", SessionUID: "child", History: forked, Inputs: []api.Message{data}} + if err := h.Run(context.Background(), s, &recordingSink{t: t}); !errors.Is(err, errNonText) { + t.Fatalf("child turn = %v, want %v", err, errNonText) + } + }}, + {name: "fails before init", child: func(t *testing.T, h *Harness) { + setScenario(t, h, scenario{Exit: 1}) + if err := runTurn(t, h, "child", "e2", forked); err == nil { + t.Fatal("failed child turn returned nil") + } + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + }}, + {name: "cancelled while running", child: func(t *testing.T, h *Harness) { + if err := pausedTurn(t, h, "child", "e2", forked)(); err == nil { + t.Fatal("cancelled child turn returned nil") + } + }}, + {name: "succeeds", child: func(t *testing.T, h *Harness) { + if err := runTurn(t, h, "child", "e2", forked); err != nil { + t.Fatal(err) + } + }}, + } { + t.Run(test.name, func(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + test.child(t, h) + if got := forkReaders(h, "parent"); got != 0 { + t.Fatalf("parent reserved by %d attempts, want 0", got) + } + if err := runTurn(t, h, "parent", "e3", turnEvents("e1")); err != nil { + t.Fatalf("parent turn = %v", err) + } + }) + } +} + +// TestForkOfUnconfirmedForkReservesChain: a grandchild forking through a child whose id is not +// confirmed reserves both, so neither the parent, whose transcript it copies, nor the child can +// start a turn until the grandchild's attempt ends. +func TestForkOfUnconfirmedForkReservesChain(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + forked := slices.Concat(turnEvents("e1"), forkMarker()) + setScenario(t, h, scenario{Exit: 1}) + if err := runTurn(t, h, "child", "e2", forked); err == nil { + t.Fatal("failed child turn returned nil") + } + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + childHist := slices.Concat(forked, turnEvents("e2")) + + stop := pausedTurn(t, h, "grandchild", "e3", slices.Concat(childHist, forkMarker())) + wantFlags(t, h, "--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("grandchild", 0)) + forkInFlightTurn(t, h, "parent", "e4", turnEvents("e1")) + forkInFlightTurn(t, h, "child", "e5", childHist) + if err := stop(); err == nil { + t.Fatal("cancelled grandchild turn returned nil") + } + for _, uid := range []string{"parent", "child"} { + if got := forkReaders(h, uid); got != 0 { + t.Fatalf("%s reserved by %d attempts, want 0", uid, got) + } + } + if err := runTurn(t, h, "child", "e5", childHist); err != nil { + t.Fatalf("child turn = %v", err) + } + if err := runTurn(t, h, "parent", "e4", turnEvents("e1")); err != nil { + t.Fatalf("parent turn = %v", err) + } +} + +// TestConcurrentForksReserveSource: two fork children in flight each hold the parent; it stays +// reserved until both attempts end. +func TestConcurrentForksReserveSource(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + forked := slices.Concat(turnEvents("e1"), forkMarker()) + stop1 := pausedTurn(t, h, "child1", "e2", forked) + stop2 := pausedTurn(t, h, "child2", "e3", forked) + if got := forkReaders(h, "parent"); got != 2 { + t.Fatalf("parent reserved by %d attempts, want 2", got) + } + if err := stop1(); err == nil { + t.Fatal("cancelled child1 turn returned nil") + } + forkInFlightTurn(t, h, "parent", "e4", turnEvents("e1")) + if err := stop2(); err == nil { + t.Fatal("cancelled child2 turn returned nil") + } + if err := runTurn(t, h, "parent", "e4", turnEvents("e1")); err != nil { + t.Fatalf("parent turn = %v", err) + } +} + +// TestConfirmedForkReservesNothing: once Claude Code confirmed a fork child's own id, its turns +// resume its own transcript, so they leave the parent free to run. +func TestConfirmedForkReservesNothing(t *testing.T) { + t.Parallel() + h := newTestHarness(t, Config{}) + setScenario(t, h, scenario{Fixture: "text_turn.jsonl"}) + if err := runTurn(t, h, "parent", "e1"); err != nil { + t.Fatal(err) + } + forked := slices.Concat(turnEvents("e1"), forkMarker()) + if err := runTurn(t, h, "child", "e2", forked); err != nil { + t.Fatal(err) + } + stop := pausedTurn(t, h, "child", "e3", slices.Concat(forked, turnEvents("e2"))) + wantFlags(t, h, "--resume", sessionID("child", 0)) + if got := forkReaders(h, "parent"); got != 0 { + t.Fatalf("parent reserved by %d attempts, want 0", got) + } + if err := runTurn(t, h, "parent", "e4", turnEvents("e1")); err != nil { + t.Fatalf("parent turn = %v", err) + } + if err := stop(); err == nil { + t.Fatal("cancelled child turn returned nil") + } +} diff --git a/integrations/claudecode/integration_test.go b/integrations/claudecode/integration_test.go index cd0198e3..bff6f98f 100644 --- a/integrations/claudecode/integration_test.go +++ b/integrations/claudecode/integration_test.go @@ -86,10 +86,18 @@ func TestControllerOverWire(t *testing.T) { } } -// wireController serves h over gRPC and returns a controller-backed exec: each call sets the -// fake's scenario to fixture and runs one Exec through Harness.Connect. model is the policy's only -// model. +// wireController serves h over gRPC and returns a controller-backed exec for session "uid": each +// call sets the fake's scenario to fixture and runs one Exec through Harness.Connect. model is the +// policy's only model. func wireController(t *testing.T, h *Harness, model string) (*eventlog.Log, eventlog.Store, func(fixture string) ([]eventlog.Record, error)) { + t.Helper() + log := eventlog.New() + store := eventlog.AsStore(log) + return log, store, wireExec(t, h, serveWire(t, h), log, "uid", model) +} + +// serveWire serves h in a gRPC server and returns the host's client for it. +func serveWire(t *testing.T, h *Harness) api.Harness { t.Helper() lis := bufconn.Listen(1 << 20) srv := grpc.NewServer() @@ -105,18 +113,20 @@ func wireController(t *testing.T, h *Harness, model string) (*eventlog.Log, even t.Fatal(err) } t.Cleanup(func() { conn.Close() }) - remote := harnesswire.NewClientHarness(v1.NewHarnessClient(conn)) + return harnesswire.NewClientHarness(v1.NewHarnessClient(conn)) +} - log := eventlog.New() - store := eventlog.AsStore(log) - c, err := controller.New(store, nil, - controller.WithSessionUID("uid"), +// wireExec returns an exec for session uid's journal log, run over remote by a controller. +func wireExec(t *testing.T, h *Harness, remote api.Harness, log *eventlog.Log, uid, model string) func(fixture string) ([]eventlog.Record, error) { + t.Helper() + c, err := controller.New(eventlog.AsStore(log), nil, + controller.WithSessionUID(uid), controller.WithModelPolicy(api.ModelPolicy{Default: model, Allowed: []string{model}}), ) if err != nil { t.Fatal(err) } - return log, store, func(fixture string) ([]eventlog.Record, error) { + return func(fixture string) ([]eventlog.Record, error) { setScenario(t, h, scenario{Fixture: fixture}) head := log.Head() err := c.Exec(context.Background(), remote, []api.Message{*api.TextMessage("user", "go")}, head) @@ -124,6 +134,59 @@ func wireController(t *testing.T, h *Harness, model string) (*eventlog.Log, even } } +// TestForkOverWire: a child forked from a real parent journal (controller.Fork) and driven over +// harnesswire under its own UID gets the FORK marker in its Start.History, so its first turn forks +// the parent's Claude Code session into its own; the parent still resumes its own session. +func TestForkOverWire(t *testing.T) { + t.Parallel() + const model = "claude-test-model-1" + h := newTestHarness(t, Config{}) + remote := serveWire(t, h) + parentLog := eventlog.New() + parent := wireExec(t, h, remote, parentLog, "parent", model) + if _, err := parent("tool_turn.jsonl"); err != nil { + t.Fatal(err) + } + + childLog := eventlog.New() + if err := controller.Fork(eventlog.AsStore(parentLog), eventlog.AsStore(childLog), parentLog.Head()); err != nil { + t.Fatal(err) + } + child := wireExec(t, h, remote, childLog, "child", model) + for i, want := range [][]string{ + {"--resume", sessionID("parent", 0), "--fork-session", "--session-id", sessionID("child", 0)}, + {"--resume", sessionID("child", 0)}, + } { + recs, err := child("text_turn.jsonl") + if err != nil { + t.Fatalf("child turn %d: %v", i+1, err) + } + if got, wantKinds := kinds(recs), []api.EventKind{ + api.EventExecutionStart, api.EventInput, api.EventUsage, api.EventOutput, api.EventEnd, + }; !slices.Equal(got, wantKinds) { + t.Fatalf("child turn %d kinds = %v, want %v", i+1, got, wantKinds) + } + got := starts(t, h) + args := got[len(got)-1].Args + if j := slices.Index(args, want[0]); j < 0 || !slices.Equal(args[j:j+len(want)], want) { + t.Fatalf("child turn %d args = %q, want %q", i+1, args, want) + } + } + + if _, err := parent("text_turn.jsonl"); err != nil { + t.Fatal(err) + } + got := starts(t, h) + if args := got[len(got)-1].Args; slices.Contains(args, "--fork-session") || !slices.Contains(args, sessionID("parent", 0)) { + t.Fatalf("parent turn args = %q, want --resume %s", args, sessionID("parent", 0)) + } + for _, log := range []*eventlog.Log{parentLog, childLog} { + if err := eventlog.AsStore(log).Verify(); err != nil { + t.Fatal(err) + } + } +} + func kinds(recs []eventlog.Record) []api.EventKind { out := make([]api.EventKind, len(recs)) for i, r := range recs { diff --git a/integrations/claudecode/turn.go b/integrations/claudecode/turn.go index 7287c5b1..3be057cc 100644 --- a/integrations/claudecode/turn.go +++ b/integrations/claudecode/turn.go @@ -104,6 +104,7 @@ type turn struct { sessionUID string flag string // --session-id or --resume sessionID string + forkFrom string // with --session-id: the session the turn forks into sessionID model string receipts bool // full receipts; false once the session or turn budget is spent @@ -360,6 +361,7 @@ func (t *turn) run(ctx context.Context, args []string, prompt string) error { } t.h.logger.Warn("claudecode: claude failed before system/init", "session_uid", t.sessionUID, "flag", t.flag, "claude_session_id", t.sessionID, + "fork_from", t.forkFrom, "exit_status", cmd.ProcessState.String(), "stderr", line) } return err