Skip to content

feat(server): opt-in copy-on-write worktree templates - #67

Draft
kvnloo wants to merge 1 commit into
upstream-main-57cd05904dfrom
proto/template-clone-worktrees
Draft

kvnloo wants to merge 1 commit into
upstream-main-57cd05904dfrom
proto/template-clone-worktrees

Conversation

@kvnloo

@kvnloo kvnloo commented Nov 3, 2026 •

Copy link
Copy Markdown
Owner

Problem

A new worktree of a pnpm monorepo pays for a full checkout and then a full vp i in its setup script. On t3code itself that is most of the time between "new thread in a worktree" and "agent can start", and it grows when several worktrees are launched at once.

Change

An opt-in server setting, enableWorktreeTemplates (default off; Settings → Worktrees → Advanced → Clone new worktrees from templates), same shape as enableWorktreeFast in upstream PR 28727.

  • Probe: once per worktrees folder per server run, cp --reflink=always (Linux: FICLONE) or cp -c (macOS: clonefile) on a scratch file. Unsupported filesystems and Windows never touch the template path and leave nothing behind.
  • Capture: after a worktree's setup script exits 0, ThreadLaunchService forks a capture off the launch path: tracked files at the worktree's commit plus node_modules, stored in .t3-templates/ beside the worktrees, keyed by the hash of the lockfiles at that commit. Two templates kept per repository; older ones are evicted.
  • Clone: createWorktree looks up a template for the start ref's lockfile hash. On a hit it runs git worktree add --no-checkout, clones the template with copy-on-write cp (batched, 4 at a time, one semaphore shared by every clone on the server), writes an index whose stat data matches the clones so the first git status does not re-hash, checks out only what differs from the template's commit, and rewrites pnpm's .pnpm-workspace-state-v1.json to the new path so vp i in setup is a no-op check. Clone progress reports through the existing checkout progress stage.
  • Fallback: any clone failure logs a warning, clears the half-made tree and runs the stock reset --hard checkout. Turning the setting off deletes the repository's templates the next time it gets a worktree.

Lines (git diff --numstat, +/-): worktreeTemplates.ts +409, worktreeTemplates.test.ts +243, GitVcsDriverCore.ts +48/-1, WorktreesSettings.tsx +38/-1, ThreadLaunchService.ts +14, docs/user/project-settings.md +12, settingsSearch.ts +9, GitManager.ts +8/-6, GitVcsDriver.ts +4, contracts/settings.ts +3, GitWorkflowService.ts +2. Total +790/-8; +547 without the test. That is above the ~500 target. Split for upstream: (1) contracts setting + worktreeTemplates.ts + createWorktree/capture wiring + tests (server only, setting reachable only through settings.json); (2) Settings UI + search + user docs.

Against Julius's bar (upstream PR 12631 review)

  • Measured on t3code itself: yes, below, through GitVcsDriverCore.createWorktree plus scripts/setup-worktree.ts (vp i --frozen-lockfile -- --yes), not a separate referee.
  • Before/after vp i: the setup/ws column is the setup script (vp i) per worktree, stock vs opt-in.
  • One-time filesystem probe: per worktrees folder, cached for the server run.
  • Visible setup progress: clone progress is the checkout stage's percent; setup still streams as before.
  • Opt-in only: default off; off also removes templates.

Measurements

Host: Linux 7.2.9 (CachyOS), 24 GB RAM plus zram, shared with other heavy jobs (2–7 GB available, ~12–14 GB swap in use). The kernel's global OOM killer fired during several N=4 attempts (order-3 allocations failing in the compositor, reclaimable slab ~4.8 GB); killed attempts were cleaned up and retried, and only complete runs with every gate green are counted. Of the 6 killed measured attempts, 5 were opt-in N=4 (btrfs 2, xfs 3) and 1 stock N=4 (btrfs + 26996): creating ~840k cloned inodes in ~15–25 s looks like it adds to that pressure. Not established as the cause, but a risk to check before recommending this on memory-tight hosts. Pin 57cd05904d. Each root is an isolated git clone --shared of t3code with its own pnpm store/cache/state on the same filesystem, warm store. Arms interleaved per round, N=3 rounds; "all ready" = wall time until every worktree is created and its setup script exited 0.

python3 referee/tools/run_template_clone_bench.py <root>/proto/btrfs btrfs 3
python3 referee/tools/run_template_clone_bench.py <root>/proto/btrfs btrfs-pr26996 3 refs/bench/pr26996   # 26996 head 55477f8d20 as the benched repo commit
python3 referee/tools/run_template_clone_bench.py /workspace/_autoresearch-xfs/proto xfs 3

Each bench run (one arm, one N) holds a host-wide flock and waits for ≥1 GB available memory; order per round alternates (stock/opt-in, opt-in/stock). One warm-up stock run fills the store; one opt-in "first use" run has no template yet and captures it.
(driver: bench_template_clone.ts, run with node from apps/server, calls makeGitVcsDriverCore().createWorktree with { worktreeTemplates: true|false } then the setup script.)

fs N stock all ready p50 [min–max] s opt-in all ready p50 [min–max] s opt-in/stock setup (vp i) per ws stock → opt-in
btrfs 1 17.3 [17.1–18.2] 11.3 [6.4–18.8] 0.66 14.0 → 2.4
btrfs 4 39.4 [38.2–55.9] 21.2 [17.3–25.9] 0.46 28.9 → 1.4
xfs 1 4.6 [4.6–4.8] 5.5 [5.3–10.1] 1.15 2.9 → 1.0
xfs 4 19.2 [17.6–26.8] 26.8 [20.0–34.6] 1.40 9.3 → 2.3
btrfs + 26996 config 1 3.3 [3.2–4.1] 2.4 [2.4–4.0] 0.75 1.0 → 1.0
btrfs + 26996 config 4 18.4 [17.0–18.8] 6.9 [4.6–8.2] 0.37 2.5 → 1.9

First use (no template yet) runs the stock path; capture then runs in the background (btrfs 8.7 s, xfs 10.1 s, btrfs+26996 2.5 s).

Reading: the template removes vp i from setup everywhere, but it moves the cost into the clone. On btrfs that is a clear win (N=4 roughly halves). On XFS with a warm same-filesystem store, stock pnpm is already fast and cloning node_modules file by file (create/ws 24 s at N=4) is slower than installing, so opt-in loses on XFS. Probe success alone is therefore not a reason to turn it on; a follow-up could compare a clone against the last stock install per root and stop using templates where they lose. With 26996's virtual store, node_modules is mostly symlinks, the clone is cheap, and the two compose to the best numbers here.

Relation to upstream PRs 28727 and 26996

  • 28727 (git-worktree-fast on macOS) clones tracked files only, so vp i still runs after it. Both sit in createWorktree; they compose as: template hit → this path; else enableWorktreeFast on macOS → git-worktree-fast; else stock. The setting is shaped the same way so both can live under Settings → Worktrees → Advanced.
  • 26996 (shared pnpm virtual store) is not included here. It composes: with it the template's node_modules is mostly links and the clone cost drops (last two rows).

Not checked

  • macOS / APFS (cp -c path): no macOS host available; only the probe/flag selection is written for it.
  • Windows: the setting is a no-op there by construction; not run.
  • Non-pnpm repos beyond the unit test's lockfile keying.
  • Remote/tunnel clients: only the settings toggle is client-facing; not exercised in a real client.
  • Web, desktop and mobile were not run in a real client; web typecheck passes.
  • Mixed versions: no server capability gates the toggle (the worktree-location row uses one), so a newer client shows it for an older server.
  • Capture timing: with async setup an agent may already be running when capture copies node_modules; tracked files come from the commit, but an agent writing into node_modules during the ~3–10 s capture would land in the template. Not exercised.
  • Memory behaviour of the clone under pressure (see the OOM note above); no memory measurement per arm was taken.

Checks run: vp test run src/vcs/worktreeTemplates.test.ts (5 passed: clone with stat-clean index and resolving symlinks; probe off → stock and no templates; reuse for a newer commit and rebuild on lockfile change with eviction; fallback on clone failure; teardown removes the worktree and turning off removes templates), tsc --noEmit for apps/server, packages/contracts and apps/web, vp lint on the touched paths, pre-commit fmt/lint/knip.

Implemented by Claude Opus 5.5 via the Hermes ACP harness in T3 Code.

New worktrees can be cloned from a template (tracked files at a commit plus
node_modules) captured after a worktree's setup script succeeds, keyed by the
lockfiles. Off by default; a one-time clone probe per worktrees folder gates
it, and any failure falls back to the stock checkout.

Implemented by Claude Opus 5.5 via the Hermes ACP harness in T3 Code.
@github-actions github-actions Bot added the vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. label Nov 8, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant