[Feature]: Evaluate forkSession as alternative to /clear for batch isolation

[sjnims]

Parent Issue

Sub-issue of #344 (Leverage Additional SDK v0.2.25 Capabilities)

Feature Type

SDK integration (Agent SDK)

Problem or Need

Batch isolation currently uses persistSession: true + continue: true + explicit /clear command between scenarios (session-batching.ts:563-608). This adds a round-trip per scenario in a batch. The current approach is battle-tested and provides ~80% overhead reduction vs individual sessions.

Proposed Solution

Evaluate SDK v0.2.25 forkSession option as an alternative to /clear + continue for batch isolation.

Potential benefits:

• Eliminate the /clear query round-trip, reducing per-scenario overhead
• Fork semantics may provide better isolation than /clear

Key questions requiring investigation:

1. Does forkSession fork the subprocess or the conversation state?
2. How does it interact with enableFileCheckpointing and rewindFiles()?
3. What are the performance characteristics vs /clear?
4. Does forking preserve or reset tool state?

Files Affected

• src/stages/3-execution/session-batching.ts — executeBatch, sendClearCommand, buildScenarioQueryInput
• src/stages/3-execution/sdk-client.ts — QueryOptions

Risk Assessment

High risk — Session batching is a core optimization (80% overhead reduction). Any regression here impacts all batch execution. The interaction between forkSession, persistSession, continue, and file checkpointing needs careful testing.

Recommended Approach

1. Create experimental branch for forkSession evaluation
2. Benchmark against current /clear approach (latency, memory, isolation quality)
3. Test interaction with file checkpointing
4. If results are positive, implement as opt-in configuration option
5. Only consider deprecating /clear approach after extensive production validation

Priority Rationale

Highest potential impact but also highest risk. Current approach works well and is battle-tested. Should be thoroughly evaluated before any production adoption.

---

🤖 Created with Claude Code

[claude]

Analysis: Evaluate forkSession as Alternative to /clear for Batch Isolation

1. Problem Assessment

Is the problem clearly defined? Yes — the issue is well-scoped. The current batch isolation mechanism uses persistSession: true + continue: true + an explicit /clear round-trip between scenarios (session-batching.ts:559-604). While this works reliably and provides ~80% overhead reduction vs isolated sessions, each /clear command adds one full SDK query round-trip per scenario transition.

Root cause / underlying issue: The /clear approach is fundamentally a workaround — it resets conversation state by sending a command through the model, rather than using SDK-level session management. forkSession could provide a first-class SDK mechanism for branching session state without the round-trip overhead.

Affected stage: Stage 3 (Execution) only. No impact on analysis, generation, or evaluation stages.

Missing information: The issue correctly identifies the key unknowns:

1. Fork semantics: Does forkSession fork the subprocess, the conversation history, or both?
2. Interaction with enableFileCheckpointing: Current code rewinds files BEFORE /clear (session-batching.ts:423-430). Fork semantics may change this ordering requirement.
3. Performance characteristics: No benchmarks exist yet for forkSession vs /clear.
4. Tool state preservation: Does forking reset or preserve MCP server connections, plugin state, and hook registrations?

These unknowns make the status:needs-design label appropriate. This analysis can guide the design investigation.

---

2. Proposed Solution Evaluation

The issue's recommended approach (experimental branch → benchmark → test → opt-in config → production validation) is sound. Here's a more detailed evaluation:

Current /clear flow (session-batching.ts:763-773):

Scenario N completes → rewindFiles() → sendClearCommand() → Scenario N+1 starts

Proposed forkSession flow (conceptual):

Scenario N completes → rewindFiles() → fork session → Scenario N+1 starts on fork

Tradeoffs:

• Pro: Eliminates one SDK query round-trip per scenario transition (the /clear call at session-batching.ts:595-601 consumes the entire response stream just to discard it)
• Pro: SDK-native isolation may be more robust than /clear which relies on the model processing a slash command
• Con: forkSession semantics are not yet well-understood — fork could mean process-level fork (expensive) or conversation-level fork (cheap)
• Con: Unknown interaction with persistSession: true + continue: true pattern used throughout (session-batching.ts:521-522, 587-588)

Risks:

• Session state leakage between scenarios if fork doesn't fully isolate
• Memory growth if forked sessions accumulate state
• Breaking the file checkpointing flow which currently depends on specific ordering (session-batching.ts:423-430)
• Hook lifecycle issues — stateless hooks are shared across batches (hooks-factory.ts) and may not survive fork boundaries

Edge cases:

• What happens when a forked session errors? Does the parent session remain usable?
• Can you fork a session that has already been forked?
• How does fork interact with abortController — does aborting a fork affect the parent?

---

3. Alternative Approaches

Option A: forkSession replacement (issue's proposal)

• Pros: Potentially eliminates round-trip overhead, SDK-native semantics
• Cons: Highest risk, unknown SDK behavior, complex migration
• Impact: Changes core batch execution flow

Option B: Hybrid — forkSession for isolation, keep /clear as fallback

• Pros: Graceful degradation if fork fails, A/B testable, incremental adoption
• Cons: Increased code complexity maintaining two paths
• Impact: Adds new session strategy variant (e.g., batched_by_component_fork) alongside existing strategy

Option C: Optimize existing /clear approach

• Pros: No risk to battle-tested path, incremental improvement
• Cons: Still has round-trip overhead, doesn't leverage new SDK capabilities
• Implementation: Could optimize sendClearCommand() by reducing the options payload, or investigate if /clear can be made non-blocking

Option D: Pre-forked session pool

• Pros: Amortizes fork cost across scenarios, enables parallel execution within a batch
• Cons: High complexity, memory overhead, may not match SDK's fork model
• Impact: Would require significant rearchitecting of executeBatch() (session-batching.ts:682-802)

---

4. Implementation Considerations

Files requiring changes:

File	Change
src/stages/3-execution/session-batching.ts	New fork-based batch execution path, modify executeBatch() (~lines 682-802), new function parallel to sendClearCommand()
src/stages/3-execution/sdk-client.ts	forkSession already in QueryOptions (line 186) — no type changes needed
src/config/schema.ts	Add new session strategy variant if opt-in (line 114)
src/types/config.ts	Extend SessionStrategy union type (line 42)
config.yaml	Document new strategy option

Breaking changes: None if implemented as opt-in strategy. The existing batched_by_component behavior should remain the default.

State/resume impact: Minimal. Pipeline state (src/state/types.ts) tracks stage-level progress, not session-level state. Resume capability would work as-is since it operates at the scenario result level.

Testing requirements:

• Unit tests: Mock forkSession behavior in session-batching.test.ts, verify isolation guarantees
• Integration tests: Run actual batched scenarios with fork, compare results to /clear baseline
• Benchmarks: Measure per-scenario overhead (latency) and memory usage for fork vs /clear
• Regression tests: Ensure file checkpointing + fork interaction works correctly
• Hook lifecycle tests: Verify stateful/stateless hook behavior across fork boundaries

---

5. Recommendation

Recommended approach: Option B (Hybrid) — implement forkSession as an opt-in alternative strategy while keeping /clear as the default and fallback.

Rationale: The current /clear approach is battle-tested with ~80% overhead reduction. forkSession has high potential but significant unknowns. A hybrid approach lets us evaluate fork semantics safely without risking the production path.

Suggested implementation order:

1. Spike: SDK investigation — Create a minimal test harness that exercises forkSession with persistSession, continue, enableFileCheckpointing, and hooks. Answer the four key questions from the issue. This should be done before any production code changes.

2. Add batched_by_component_fork strategy — Extend SessionStrategy in src/types/config.ts:42 and src/config/schema.ts:114. This keeps the feature opt-in and isolated.

3. Implement fork-based batch execution — Add a sendForkSession() function parallel to sendClearCommand() in session-batching.ts. Modify executeBatch() to dispatch based on strategy.

4. Benchmark and validate — Run side-by-side comparisons. Key metrics: per-scenario transition latency, total batch duration, memory consumption, isolation quality (no state leakage).

5. Production validation — Run with real plugins before considering making fork the default.

Follow-up issues to create:

• Spike: Investigate forkSession SDK semantics and interaction with persistSession/continue/enableFileCheckpointing (prerequisite for this work)
• Benchmark harness: Create tooling to compare session strategies on identical scenario sets
• Documentation: Update docs/ and .serena/memories/ with fork strategy details once implemented

Current label appropriateness: The status:needs-design label is correct. The spike investigation (step 1) should be completed before detailed design work begins. The issue's questions about fork semantics are the critical unknowns that must be answered first.