perf(desktop): batch session telemetry checkpoints

[Nath-Vikky]

Summary

Desktop session telemetry currently rewrites the complete .telemetry.json sidecar after:

• TurnStarted
• every Usage event
• every successful read_file
• TurnDone

Each save serializes the full, growing snapshot with json.MarshalIndent, writes a temporary file, and atomically replaces the sidecar. Read-heavy turns therefore perform many synchronous full-file rewrites inside the serialized frontend event path.

This change replaces per-event persistence with bounded synchronous checkpoints:

• TurnStarted updates in-memory timing without writing the sidecar.
• In-turn Usage and successful read_file mutations checkpoint every 16 events.
• The 30-second age limit is evaluated when the next Usage or read_file mutation arrives; no background timer is created.
• TurnDone always forces a synchronous checkpoint.
• Out-of-turn telemetry remains immediately persisted.
• Graceful shutdown forces a checkpoint before closing the controller and switches the sink into draining mode, so late telemetry is also persisted immediately.
• Failed checkpoints remain due for the next Usage/read_file mutation or forced boundary.

The sidecar path, JSON v2 format, and existing tmp + ReplaceFile atomic-write behavior are unchanged. No background writer or goroutine is introduced.

Results

Representative workload: 9 Usage events and 8 successful read_file events per turn.

Measurement	Before	After	Change
Deterministic 20-turn test	380 writes	40 writes	-89.5%
Windows 100-turn persistence workload	1900 writes	200 writes	-89.5%
Isolated Windows persistence time, 6 alternating-order runs	1.922–2.170s	0.205–0.225s	8.72–10.59x

The Windows comparison used the real saveTelemetry filesystem path, alternated execution order between runs, and verified that the final before/after snapshots were identical.

This is an isolated persistence-path stress workload, not an end-to-end Agent speedup claim. The change substantially reduces in-turn write amplification, but TurnDone still writes the full snapshot, so lifetime persistence is not fully linearized.

Durability and compatibility

With healthy filesystem I/O, completed turns and graceful shutdowns remain fully checkpointed.

An abrupt process kill may lose at most one checkpoint window—conservatively up to 16 intermediate Usage/read_file mutations plus elapsed time since the last checkpoint. This affects only the private Desktop telemetry sidecar; the session transcript and tool results are persisted through their existing paths.

Persistent filesystem failures still cannot provide a finite durability guarantee, matching the existing best-effort error behavior.

The change is Desktop-only and provider-independent. It does not affect CLI/serve, provider requests, prompts, tools, session JSONL, or user-visible telemetry fields.

Issues

N/A — independently identified while profiling the Desktop telemetry persistence path.

Verification

• cd desktop && go test . -run 'Test(TelemetryCheckpoint|TabEventSinkTelemetryCheckpoint|Shutdown.*Telemetry)' -count=50
• Focused session rotation, recovery, rebind, attach/detach, and shutdown lifecycle tests
• Real recordUsageTelemetry / recordReadTelemetry / TurnDone → saveTelemetry → loadTelemetry round-trip
• go test ./internal/control -count=1
• go test ./internal/event -count=1
• go test ./internal/boot -run TestBuildCoalescesAgentStreamDeltas -count=1
• cd desktop && go vet .
• go run ./tools/repolint
• gofmt and git diff --check

The full Desktop suite produced only two pre-existing Windows environment-dependent failures (TestRemoteWindowRecoversAcrossRealSSHDrop and TestTrySubagentProfileCancelAbortsRunAndIsSingleFlight); no telemetry or lifecycle test failed.

Local -race was unavailable because the Windows Go environment has no CGO compiler. The repository Desktop CI runs the full race suite.

Documentation impact

Documentation-impact: none - changes only the persistence cadence of a private Desktop telemetry sidecar; no command, setting, user-visible behavior, or file format changes.

Cache impact

Cache-impact: none - no provider request, prompt, tool schema, serialization, or cache-prefix behavior changes.
Cache-guard: N/A - Desktop sidecar persistence only; focused checkpoint and lifecycle tests cover the changed path.
System-prompt-review: N/A