Annotate mode: extend the version diff to folder sessions

[BenNewman100]

Summary

#960 / #961 brought the version diff to annotate mode — but only for single-file sessions. Folder sessions (plannotator annotate <dir>) still serve every file as a plain render: the file tree's only change signal is the git-based workspace status (uncommitted changes), so a committed-clean folder shows no change signal anywhere, and opening a file never shows what changed since the last round.

This closes the same iterative-loop gap #960 described, for multi-doc reviews: annotate a docs folder → the agent revises several files → reopen the folder and see the highlighted changes per file before the next round. Today that loop forces a choice between the folder's navigation and the single file's diff.

Request

Run the existing history pipeline for eligible files in folder sessions:

• Snapshot on first open — when a folder session first serves an eligible file, save it to the per-file version history (lazily, memoized per server launch; the existing saveToHistory dedupe keeps unchanged files from minting versions).
• Serve the diff fields on the doc response — previousPlan/versionInfo alongside the doc content, same fields single-file sessions use.
• Render the existing diff UI in the doc view — inline highlights and the +N/-M badge via the same PlanDiffViewer machinery, plus per-file version browsing.

Notes / constraints

• History stays continuous across modes. Reuse the existing path-keyed annotate slug, so a file has one version thread whether opened solo or via its folder. No new storage concept.
• v1 scope: .md / .txt only — HTML deferred, mirroring how feat(annotate): per-file version diff for .md and .html (rendered HTML highlights) #961 landed markdown-first.
• No history-based tree badges — the git workspace-status badges are untouched; the diff renders in the file view only.
• Same gates as single-file sessions — the annotatable-file size cap, the annotateHistory config toggle, and graceful degradation to a plain render if history storage is unavailable.
• Per CLAUDE.md, lands in both the Bun (packages/server/annotate.ts) and Pi (apps/pi-extension/server/serverAnnotate.ts) runtimes.

One question: is it right for this to ride the existing annotateHistory toggle (default-on), or would you prefer a separate opt-in for folder sessions?

Happy to contribute this — PR incoming.

[backnotprop]

Thanks for this. The write-up matches how the code actually works, and the scoping is right. Green light, we would be glad to take the PR.

Answering your question first: ride the existing annotateHistory toggle. No second setting. The condition is that snapshots stay strictly lazy, only files the user actually opens get a history write. Opening a file is the consent act, same as single-file annotate. We will call out the expanded surface in the docs when this lands.

Guardrails for the implementation:

1. The doc-serving handler (handleDoc in packages/server/reference-handlers.ts) is shared with the plan server. The history hook must be an explicit option enabled only by folder annotate sessions (the HandleDocOptions / onSourceDocumentServed pattern used by source-save is the template). Wired as default behavior, plan-mode linked-doc browsing would silently start copying repo files into the data dir.
2. Two runtimes: everything lands in both the Bun server (packages/server/annotate.ts + reference-handlers.ts) and the Pi mirror (apps/pi-extension/server/serverAnnotate.ts).
3. Use the same resolved-absolute-path slug the single-file session computes, so a file keeps one version thread whether opened solo or via its folder. Watch symlinks and case-insensitive filesystems here.
4. On the client, usePlanDiff already has a PlanDiffFetchers seam for pointing version fetches at per-file endpoints, and the folder doc view renders through the same Viewer as the root document. Most of the work is unwiring the current suppression in App.tsx and making the diff state reset when the active doc changes, not new UI.

Two UX notes worth designing for up front:

• The tree badges (git, uncommitted-vs-HEAD) and your in-file diff (vs last-seen version) will show different numbers for the same file, and both will be right. Give the in-file badge a label or tooltip like "since last review" so the two baselines read as different questions rather than a bug.
• Deferring history-based tree indicators is fine for v1, but note the consequence: in the committed-clean case (the headline scenario), nothing in the tree points at which files changed, so discovery is click-through. A small, visually distinct tree marker is the natural v2.

One scope nudge: the single-file pipeline already covers the whole plain-text set (.yaml, .json, .toml, etc.) identically to .txt, so matching that set for folder files costs nothing extra. Deferring HTML is the right call either way, its diff depends on session-scoped asset rewriting.

Last thing, on our side rather than yours: history has no pruning today, and this widens that surface. Not a blocker for the PR, but we may pair it with retention work.