Perf: projection-cached VCS driver for diff/checkpoint reads (port of t3code #2586) #1246

Background

Inspired by pingdotgg/t3code#2586 — Optimize VCS diff loading to be up to 98% faster. They consolidated git shellouts behind a typed Effect-native driver, fed diff context from a SQLite projection of the read model, and capped output. The same pattern fits Panopticon directly.

Relationship to the Effect migration

This issue is not the canonical Effect migration cleanup issue. The remaining migration-completion work is tracked in PAN-1313.

This issue stays open because it is a separate performance/architecture change: introduce a projection-cached VCS driver and move git diff/checkpoint reads behind it.

PAN-1313 should classify the current VCS-heavy files first:

• src/lib/checkpoint/checkpoint-manager.ts
• src/lib/cloister/review-context.ts
• src/lib/cloister/merge-agent.ts
• src/lib/cloister/inspect-checkpoints.ts
• src/lib/close-out.ts

After that classification, this issue should consume the chosen canonical API shape. Do not resurrect the old PAN-1250 / PAN-1251 / PAN-1252 dependency split; those migration slices were consolidated into PAN-1313.

Problem

Panopticon shells out to git from many places, with no shared driver and no cache:

Symptoms:

• Every dashboard refresh that touches diff data can re-spawn git.
• Review-context manifests are rebuilt even when the base/head SHA pair has not moved.
• Large diffs can dump megabytes through server paths.
• Timeout, output cap, quoting, and typed-error behavior are repeated across call sites.
• PAN-70 already banned execSync in dashboard server code; this is the structural next step for git process use.

Goal

Cut p95 diff-read latency by at least 80% for hot paths and consolidate git read/diff/checkpoint operations behind one typed Effect-native VCS driver.

Non-goals

• This does not finish the whole Effect migration; PAN-1313 does that.
• This does not replace every git write operation in one pass unless it naturally falls out of the driver shape.
• This does not change checkpoint on-disk/ref semantics.
• This does not add non-git VCS support, though the driver shape can leave room for it.

Design

1. VCS driver

Add a VcsDriver service under src/lib/vcs/ with Effect-typed errors and arg-array process execution. The driver should cover the operations needed by checkpoint, review-context, merge-agent, inspect-checkpoints, close-out, and dashboard diff reads.

2. Single git process primitive

Add one runGit primitive with:

• arg-array execution only
• default timeout
• output byte cap
• truncation marker
• typed errors
• process cleanup on cancellation
• observability for slow/truncated commands

3. Projection cache

Add a cache keyed by (workspace_id, base_sha, head_sha, format, paths_hash) so repeated diff reads can return without re-running git when HEAD has not moved.

4. Review-context reuse

Make review-context builds reuse cached output for identical base/head SHA pairs.

5. Regression guard

Add a guard that prevents new raw git shellouts outside the VCS driver once migration is complete.

Acceptance criteria

• src/lib/vcs/ contains a typed Effect-native VCS driver and runGit primitive.
• Diff reads support timeout, truncation, and typed errors consistently.
• Repeated review-context builds for the same base/head SHA pair hit cache.
• Dashboard timeline diff reads use cached data when possible.
• Large diff output is capped with a clear truncation marker.
• Existing checkpoint/review/merge/inspect/close-out callers consume the VCS driver where in scope.
• A regression guard prevents new raw git shellouts outside the driver after migration.
• PAN-1313 remains the only canonical issue for finishing the original Effect migration; this issue remains the VCS-driver performance/architecture follow-up.
• npm run typecheck passes.
• Relevant focused tests pass.

Open questions

1. Should the cache live in the dashboard SQLite database or per-workspace under .pan/cache/?
2. Should the driver cover branch/write operations immediately, or start with diff/read operations only?
3. Should slow git commands emit operator-visible activity events, or only structured logs?

References

• Upstream PR: Optimize VCS diff loading to be up to 98% faster pingdotgg/t3code#2586
• Canonical migration cleanup: PAN-1313
• Flywheel dependency-awareness: PAN-1253