Making parallel OpenCode sessions cheap on Windows

TL;DR

Live Event throughput with four SSE subscribers: 77,537 -> 145,942 delivered Events/s (+88.2%), with 48.4% less CPU work.

The local 81.7-second profile spent most active samples starting processes, resolving executables, and repeatedly attempting snapshots. The table gives the evidence for each commit. Percentages are overlapping profile paths and must not be added together.

What the profile actually showed

The profile covered 81.7 seconds and contained 4,820 samples. The first 10.4 seconds included server startup. I used sample counts for ranking because the profile contains long wall-time gaps. Assigning a multi-second gap to the next sampled frame would incorrectly make SSE or tracing look like a multi-second synchronous call.

The categories overlap. For example, Schema work can run inside an Event path that also has tracing.

The matching server log supplied the missing command context:

• The profiled server attempted 36 snapshots during the capture.
• A second server process attempted 2 more snapshots in the same period.
• Every attempt failed on the same app-owned index.lock.
• The lock was zero bytes and had not changed since June 2.
• The old snapshot index saw 2,302 tracked changes and 3,181 untracked files, or about 5,483 candidates, before each failed write.

This was not a retry timer. Every normal model step asked for another start or end snapshot, so active Sessions repeatedly entered the same expensive failure path.

Why snapshots started so many processes

The runner takes one snapshot before the physical model attempt and another after provider and tool work:

• start snapshot
• end snapshot and file comparison

Before this branch, a clean unchanged step used:

start: diff-files + ls-files + write-tree
end:   diff-files + ls-files + write-tree
diff:  diff --name-only

total: 7 Git processes

Ten Sessions that reached the same boundary could therefore request about 70 Git processes. Windows process creation made this much more visible than Linux or macOS.

The old mutable-index design

OpenCode keeps snapshot objects in an app-owned Git repository under the OpenCode data directory. The user repository and the snapshot repository have different indexes:

user:     <project>/.git/index
OpenCode: <data>/snapshot/<project>/<worktree>/index

This correctly prevents a user git add from fighting with an OpenCode git add. It does not prevent two OpenCode server processes from sharing the same OpenCode index. Git protects a mutable index by creating index.lock, writing the new index, and renaming it into place. A process crash can leave the lock behind.

The supplied machine had exactly this state. The best fix was not a larger stale-lock manager. It was to remove the shared mutable index.

Disposable indexes and immutable trees

Git supports an alternate index with GIT_INDEX_FILE. Git still creates a mandatory lock next to that alternate index, but every capture now has a unique path:

capture-a.index
capture-a.index.lock

capture-b.index
capture-b.index.lock

The lock gives one capture crash-safe index writes. It cannot block another capture, another Session, or a later server process.

The capture flow is now:

create unique temporary index path
read immutable base tree into temporary index
inspect the requested Location scope
return the base tree if nothing changed
apply changed paths to the temporary index
write an immutable tree object
delete the temporary index and its private lock

The implementation is in the deep Git boundary:

• temporary index lifetime
• one tagged status scan and linear candidate planning
• tree capture orchestration
• Location-owned immutable tree chain

The design follows Git's plumbing model:

• git read-tree reads an immutable tree into an index. Its -i documentation explicitly describes temporary indexes.
• git write-tree creates an immutable tree object from a fully merged index.
• GIT_OPTIONAL_LOCKS=0 prevents read commands from doing optional index refresh writes. It does not disable mandatory private-index locks.

The first capture starts from the source HEAD tree. Later captures start from the last successful Location tree. OpenCode does not read, modify, or delete the user's index or the legacy OpenCode index.

Shared object storage is a different concurrency problem

Git indexes are mutable. Git blobs and trees are content-addressed and immutable. The private snapshot repository still shares one object directory so that stored tree IDs remain available after a server restart.

The clean fixture tests passed with concurrent object writes. The live Windows repository found a real platform edge: two Git processes can race to create the same loose object. Git makes completed loose objects read-only on Windows. The losing writer can then receive Permission denied.

The final design keeps the common path simple:

1. Read the base tree into a private index.
2. Run one status scan.
3. Return immediately when clean.
4. Only a changed capture acquires the existing stale-safe Effect file lock before it writes blobs and trees.

See changed-object publication. Source objects are exposed with GIT_ALTERNATE_OBJECT_DIRECTORIES; no persisted alternate file is needed. Git documents persistent alternates in objects/info/alternates; the environment form gives the same read path without another mutable app file.

This lock is not a replacement index lock. Clean captures do not acquire it. It protects the one shared resource that remains: changed object publication.

Process count after the snapshot changes

For the first clean model step:

start: resolve HEAD tree + read-tree + tagged ls-files
end:   read-tree + tagged ls-files
diff:  skipped because tree IDs match

total: 5 Git processes

Later clean steps reuse the previous immutable tree and use 4 Git processes. This is down from 7. Changed captures use extra processes only for the actual add, tree write, and changed-file report.

The branch also resolves git.exe once. The native Windows fast path is deliberately narrow:

• cached Git executable
• absolute .exe and .com fast path

Shell commands, shebang scripts, .cmd, and .bat files still use cross-spawn. This preserves Windows script behavior while removing repeated which, isexe, and shebang reads for Git.

Removing work from every streamed event

After snapshots, the next repeated path was model output. A provider can emit many text, reasoning, and tool-input deltas for one physical attempt.

Encode once per event, not once per client

The old server route created a Schema encoder wrapper, encoded the Event, called JSON.stringify, allocated an SSE Event, ran the Effect SSE channel, and encoded text for every subscriber.

The new route:

• compiles the Schema encoder once;
• renders the exact data: <json>\n\n frame directly;
• stores encoded bytes in a WeakMap keyed by the shared Event object;
• shares one encoding across concurrent subscribers;
• pre-encodes the heartbeat.

See the Event handler.

Keep useful spans, remove per-delta spans

Named Effect.fn handlers create trace spans and call-site stack data. That is useful for a request, step, tool, or compaction operation. It is high-cardinality noise for each token delta.

The per-delta handlers now use Effect.fnUntraced, while coarse operational spans remain. The Session location is also bound once when the publisher is created, so each Event does not search ambient Effect context and allocate another location value.

See the bound publisher and untraced event path and per-delta publication.

This intentionally reduces trace detail. It does not change Session events, ordering, or persistence.

Making the remaining CPU proportional to real work

Windows file search

Windows uses the ripgrep and fuzzysort search path. The old index callback rebuilt Array.from(directories) for every file and repeatedly sliced and joined path prefixes. Each autocomplete query also rebuilt the mixed target list and prepared targets again.

The new path appends each directory once, prepares each target when it enters the index, and invalidates the combined list only when a new file arrives. See filesystem search indexing and the cached query target list. Fuzzysort documents prepared targets in its prepare API.

Effect Schema codecs

Stable ripgrep and tool schemas now create their decoder and encoder functions once:

• ripgrep decoder
• tool codecs

Schema validation remains at the same boundaries. Only repeated wrapper construction is removed.

SQLite projectors

The message updater now tells its adapter to edit an assistant or shell. The memory adapter keeps Immer and immutable replacement. The SQLite adapter owns a newly decoded private value, so it applies the edit directly and encodes it once.

The projector also:

• selects only id, type, and data;
• decodes the known assistant or shell member schema;
• uses json_extract(..., '$.callID') and limit 1 for shell lookup;
• prepares three message reads once per projector layer;
• prepares two durable Event reads once per Event layer.

See message edit ownership, prepared projector reads, and prepared durable Event reads. Drizzle describes prepared placeholders in its prepared statement guide.

Prepared queries still execute through the current Effect transaction service. The transaction and rollback tests pass.

Live Windows verification with the broken state left in place

The final Snapshot service was run directly against C:\Repos\sst\opencode and the same app data used by the profile.

The zero-byte June 2 index.lock remained present before and after the run. Its length and timestamps did not change.

The parallel CPU value includes real changed-object publication. The sequential run shows about 20 ms of OpenCode process CPU per capture while most wall time is Windows child-process latency. This is a focused Snapshot benchmark, not a replacement full-server profile.

Replaying a real 18-Session Event workload

The original CPU profile gave stack samples, but it could not recover Event payloads, delta boundaries, or timing. I therefore attached a local recorder to the elected OpenCode service for 10 minutes while 18 real Sessions were active.

The raw trace stayed on the local machine. It contains 4,932 SSE Events, 10.26 MB of frames, 722 tool calls, 515 reasoning deltas, 82 text deltas, and tool-success frames up to 115 KB. Nothing in the benchmark invents prompt text, tool output, delta sizes, Event order, or inter-arrival timing.

The installed service was newer than both commits under test. It had moved the old data.timestamp value to top-level created, renamed session.next.* Events to session.*, and added several operational Event types. The replay adapter therefore does only source-defined version conversions:

• move the captured created millisecond value back to data.timestamp;
• restore the target's session.next.* names;
• restore callID, provider metadata, structured tool output, and reasoning IDs from captured values according to the target publisher source;
• require the target Schema to decode and re-encode every adapted payload without another data change;
• exclude new Event types that have no target equivalent.

This validates 4,305 of 4,931 non-connection Events, or 87.3% by count and 97.0% by captured bytes. The excluded 3.0% of bytes is mainly newer shell lifecycle, inbox, execution, instruction, and usage Events.

Harness

Each measured process uses the exact target commit, a fresh isolated SQLite database, the production EventV2.publish path, the production Server Event handler, and real streamed SSE response bodies. The harness is in-process, so it excludes TCP cost and includes both the publisher and the SSE readers in the same Bun process.

The harness performs 100 unmeasured live-Event warm-up publications, forces a full GC, then records wall time, process.cpuUsage(), and RSS every 5 ms. A result of 100% CPU means one full core. Every run verifies that every selected Event reaches every subscriber. A 128-Event delivery window prevents the production 256-Event bounded subscriber queue from overflowing.

Maximum-throughput results are medians. The aggregate test uses five alternating base/candidate runs. The live-only test uses seven alternating runs and repeats the same 607-Event live trace 100 times. Later cycles change only the Event ID so every publication has real object identity and cannot reuse an earlier cycle's cached frame.

Live delta and fan-out path

This isolates the non-durable Event and SSE path. One cycle contains the real captured delta sizes and mix; 100 cycles provide 60,700 source Events and enough CPU time for stable measurement.

The first cache implementation used Effect Cache. Replay showed that its fibers, TTL state, and strong retention made the candidate 27% to 66% slower. The final handler uses a WeakMap<Event, Uint8Array>: one subscriber is effectively neutral, while additional subscribers share the exact encoded frame with no retained Event lifetime.

Aggregate publication path

This publishes all 4,305 compatible Events, including durable SQLite commits, and delivers the stream to each subscriber. Windows SQLite wall time varied widely between runs, so CPU work is the more stable aggregate signal.

At four subscribers, the aggregate candidate uses 19.6% less CPU work, delivers 7.8% more frames per second, and peaks 17.9 MiB lower. The higher candidate CPU percentage is not more CPU work: the candidate finishes sooner, so its reduced CPU time is concentrated into less wall time.

Original-timing paced replay

The same 4,305 Events were also replayed once at their captured inter-arrival times for 592.38 seconds with four subscribers. The base and candidate used isolated databases and ran together at this low average load.

Throughput is equal by design because the original timing controls publication. The candidate uses 5.0% less CPU work at that cadence. The single-run total RSS difference was present before measurement began, while measured replay growth was lower for the candidate. Use the repeated unpaced median for the more stable peak-RSS comparison.

Raw aggregate results remain local. The sensitive replay trace was deleted after the benchmark. The PR reports only aggregate counts and medians.

Verification

• Pre-push workspace typecheck: 30 tasks passed.
• Core focused suites: 73 tests passed.
• LLM provider suites: 82 tests passed.
• Native Windows executable and .cmd routing: 2 focused tests passed.
• V2 HTTP Event integration: 3 tests passed.
• Core, server, LLM, CLI, and sdk-next package typechecks passed.

Repository-wide lint remains blocked by one pre-existing octal escape error in packages/session-ui/src/v2/components/prompt-input/index.tsx. It also reports 4,854 existing warnings. No changed file produced a lint error.

Compatibility and tradeoffs

• Public Protocol and Server HttpApi contracts do not change.
• Snapshot tree IDs and restore behavior do not change.
• The user Git index is never modified by snapshot capture.
• Legacy app snapshot index and index.lock files are ignored, not migrated or deleted.
• Clean captures do not acquire the object publication lock.
• Changed captures serialize immutable object publication across server processes on Windows.
• Per-delta trace spans are removed. Coarse operational spans remain.
• SSE bytes remain standard data: frames with the existing heartbeat and response headers.

The result keeps the normal flow visible: read a base tree, inspect one scope, return immediately when clean, and publish immutable objects only when files changed.