Add worktree preparation for project dependencies

[jonathanKingston]

Closes #2376.

Fresh worktrees can now check and prepare the project's own dependencies through one bounded capability. Preflight detects npm, pnpm, Yarn Classic/modern, or Bun from the package-manager declaration and lockfile, reports runtime requirements and dependency state, and returns an exact preparation plan. Optional native setup and other ecosystems use .copse/worktree-preparation.json to declare commands, inputs, and read-only checks. This repository's Electron/gortex setup uses that same declaration.

Preparation approval displays the actual install and declared setup commands, network policy, and selected project. The preflight fingerprint is required and rechecked before each step. Installs use frozen lockfiles and manager-specific lifecycle disabling through Socket Firewall. All subprocesses remain inside the OS sandbox; preflight and offline preparation have no network access. Writes stay in the selected project and fixed managed caches, with no unsandboxed fallback.

Workspace detection follows declared patterns and exclusions, including apps/ layouts. Readiness invalidates on runtime/manager identity, manifests, lockfiles, package configuration, patches, declared inputs, and opted-in version-check output. Nested project selection is confined to the execution root. Unknown projects and conflicting inputs receive configuration guidance; readiness covers dependencies and declared checks, not build/test success.

Compatibility includes npm, pnpm, Yarn 1/2/3/4, Bun text/binary locks, Yarn Plug'n'Play, and Python virtual-environment interpreter symlinks. Modern Yarn requires an exact version declaration so its build-disabling flags are unambiguous. Runtime installation/version switching and Windows sandbox support are separate capabilities.

Validation:

• Full static gates: typecheck, lint, format, dead-code, test oracle, and e2e syntax.
• Current foundation pnpm run check: all static gates and 9,235 tests passed, with no failures or skips.
• Real sandbox smoke installs and offline reuse: npm 11.19.0, pnpm 10.34.5, Yarn 1.22.22/2.4.3/3.8.7/4.9.2, and Bun 1.4.2. Lifecycle markers remained absent. Yarn 2 was exercised on Node 22.22.2; other JS fixtures used Node 24.20.0. Yarn 2/3 additionally fetched a registry dependency through Socket Firewall.
• Real declared Python virtual-environment setup and offline reuse passed. This repository's declared native-runtime check also passed read-only in the sandbox.
• Focused Electron result-card and exact-plan approval tests passed; both screenshots were inspected.
• Adversarial coverage includes malicious probes/scripts, symlink writes, offline isolation despite another agent's network grant, stale approval plans, redirected fingerprints, and legacy Yarn proxy/CA preservation.

Visual evidence: tests/e2e/screenshots/worktree-preparation-tools.png and tests/e2e/screenshots/worktree-preparation-approval.png.

The general contract and roadmap are in docs/plans/project-worktree-preparation.md. #2654 tracks automatic Python/Rust/Go adapters; #2655 tracks JVM/.NET/Ruby/PHP adapters. Declarations support these ecosystems now; automatic detection is not claimed before its adapter and real tests ship. #2377 and #2378 remain independent Git and edit-ownership workstreams.

Co-Authored-By: Copse noreply@copse.dev
Copse-Models: acp:codex-acp#gpt-5.6-sol, acp:claude-acp#opus[1m]

Current follow-up: #2669 adds automatic locked uv/Python preparation on top of this foundation. #2654 remains open for hash-locked pip, Cargo and Go.

CI repair: rebased onto main at a184d2792, including the data-stable model-intellect assertion. Backups now keep the checkout read-only while writing Git objects/refs/logs and the scratch index, preventing Linux sandbox placeholders from entering git add -A. Regression tests cover ordinary home-contained repositories, nested linked worktrees, exact snapshot contents, unchanged index/status, and denied writes to working files, config and hooks. The focused model-picker Electron test passed and its screenshot was inspected.

The read-only chat-store mount also excludes its scratch directory and active checkout, preserving their separate write grants on Linux. Current head: 31e5f3872. Full CI verification passed: precheck, Linux unit tests, build, benchmark, all eight e2e shards, and the aggregate CI gate.

The proposed-image e2e fixture now uses a real non-Git project to require approval. It no longer relies on a Git backup failing. The focused image and Changes-refresh specs both passed; the proposed-image screenshot was inspected and matches the existing reference.

[copse-release-bot]

Reference screenshots ready for review

Review GitHub’s image diffs in screenshot PR #2671.
Merge it (or enable auto-merge) to apply the accepted PNGs to copse/build-2376-29fb13.

Rendered for 31e5f38729e0 by CI run 34762467104; the immutable artifact is reference-screenshot-candidates-34762467104.

If this source branch moves, a later successful render closes the stale review PR and replaces this link.

[jonathanKingston]

Validation found one blocking containment mismatch on current head.

The approval copy says writes are limited to the active worktree and Copse-managed caches, but runPreparationStep calls node:child_process.spawn directly. Socket Firewall mediates network access; it does not enforce filesystem write boundaries. readProjectPackage only checks mutable values in the checked-out package.json, so a branch can preserve name: copse-panel and the exact prepare:native string while replacing scripts/prepare-native-artifacts.mts. Approving prepare_worktree would then execute that branch-controlled script outside the project sandbox with ordinary host filesystem authority.

Please run both preparation subprocesses inside an enforcing sandbox whose only write grants are the execution root and the enumerated managed cache roots, and add an adversarial fixture proving a spoofed native-preparation script cannot write elsewhere. Until then, keep this draft. The focused screenshot itself looks clear, and the latest source CI is green, but those do not establish the bounded-write claim.

[github-actions]

🖥️ PR preview

• Marketing site
• Browser demo
  Interactive, with a mocked backend — jump to a scenario:
• Builds a cupcake site
• Agent-proposed edits open the Changes panel
• Markdown list indentation
• Unattended container run
• Responsive composer footer
• Subagent display visual reference
• Subagent stays ungrouped beside reading tools
• Semantic search subagent markdown
• Light-theme approval with a bright accent
• Light-theme syntax, fills, and selection
• Grouped outside-sandbox command approval
• Remote desktop discovered-port list with one selected
• Settings scroll + sticky footer geometry
• Per-model reasoning / temperature / top-p
• Thread switch hydration notice
• Thread switch hydration failure
• Apple Development test profile
• Chat layout styling
  _{Static demo of the renderer against a mock API — the browser pane, terminal, and all main-process IPC are stubbed, so it never proves main-process behaviour. Rebuilt whenever a push changes the demo bundle; these links go live once the queued deploy lands, shortly after this comment. Removed when the PR closes.}