Managed worktrees: adopt OpenClaw lifecycle (snapshot, provision, GC)

[sambitcreate]

Summary

Aiden already has a strong owned-worktree core (userData/worktrees, ownership markers, fail-closed admission, quarantine delete, startup crash reconcile, desktop + remote APIs). We should not rewrite that stack — add OpenClaw’s product lifecycle layer on top.

Reference plan (Notion draft): https://app.notion.com/p/3da80314a1c481ea9631e23994e8689d
OpenClaw docs: https://docs.openclaw.ai/concepts/managed-worktrees
OpenClaw PRs: openclaw/openclaw#100535 · openclaw/openclaw#100788
steipete (2026-09-13): worktrees ~80% faster via APFS/Btrfs/XFS/ReFS folder clones — treat CoW as P2 after correctness.

What Aiden has today

• Layout: userData/worktrees/<repo>-<12hex>/<branchSlug>-<uuid8> (git.ts:4645-4654)
• Create: git worktree add -b <branch> … HEAD only — no base-ref picker (git.ts:4625-4658)
• Ownership: aiden-owner + device/inode; admission gates terminals/LLM/schedules
• Delete: clean-only (incl. ignored); quarantine + native remover; no snapshot/restore (git.ts:4835-4851)
• UI: /worktree, create → new chat (chat-pane.tsx:2459-2504); remote create/delete

P0

1. Snapshot-before-delete + restore (refs/aiden/snapshots/…) — dirty work is stuck today
2. Disk admission before create
3. Disable Git hooks on managed worktree add
4. .worktreeinclude provisioning
5. Fail-closed .aiden/worktree-setup.sh with sanitized env only (AIDEN_SOURCE_TREE_PATH / AIDEN_WORKTREE_PATH)

P1

• aiden/<name> branch namespace + base-ref picker
• Idle GC (~7d) + snapshot retain (~30d); manual never auto-swept
• Settings → Worktrees (list / restore / force)

P2

• APFS/Btrfs/ReFS CoW acceleration
• Configurable worktreeRoot

Do not

• Run setup scripts with full process env
• Auto-sweep manual worktrees
• Chase CoW before snapshot/restore is correct

Acceptance (MVP)

• Hooks disabled on managed create
• Disk admission gates create
• .worktreeinclude copies recorded ignored files
• Dirty delete snapshots then removes; restore recreates unstaged dirty state
• Existing ownership/admission/quarantine delete still pass

[pullfrog]

Plan: Managed worktree lifecycle (snapshot, provision, GC)

Actionable. No duplicate candidates. The issue correctly scopes this as an additive lifecycle layer over Aiden's owned-worktree core — createWorktree (main/services/git.ts:4625), ownership markers, admission gates, journaled quarantine delete (main/services/managed-worktree-remover.ts), and startup reconcile (main/services/managed-worktree-deletion-recovery.ts) all stay intact.

Guiding constraints (from the issue + OpenClaw reference)

• Never weaken existing safety invariants: ownership marker + device/inode identity, fail-closed admission, descriptor-bound quarantine removal, removal journal, startup reconcile.
• Setup scripts and provisioning receive sanitized environments only.
• Manual worktrees are never auto-swept.
• Correctness (snapshot/restore) before filesystem acceleration (P2).

---

M0 — Contracts and durable state (prerequisite, no behavior change)

1. Extend ManagedWorktree (main/services/types.ts:102) with optional, legacy-tolerant fields: snapshotId?, owner?: "manual" | "session", lastUsedAt?. Every existing record defaults to manual, no snapshot.
2. New device-local snapshot registry (main/services/worktree-snapshot-store.ts + -core.ts): needed because deleting a managed worktree removes its Workspace record, so restore needs a store that outlives it. Record: snapshot id, repo commonDir, branch, base commit, snapshot commit, provisioned-file manifest, created-at, expiry, original checkout path/name/owner. Atomic writes, 0600, bounded shape validation, crash recovery like configStore.
3. Mirror ManagedWorktree validation in main/services/config-store-core.ts:192 and main/services/portable-config-core.ts:245; confirm new fields stay out of the remote protocol (forbidden-key lists in main/services/aiden-remote-protocol.ts:565).
4. Write the plan doc (docs/plans/managed-worktrees-lifecycle-plan.md) and index it in docs/plans/README.md, per repo convention.

Tests: round-trip/legacy-record validation, store corruption fail-closed, projection exclusion.

M1 — Hooks disabled + disk admission (fast, independent wins)

1. Hooks/filesystem monitors off for managed Git work. Extend GitRunOptions (main/services/git.ts:90) with an explicit disableRepositoryHooks flag routed through the existing gitCommandConfigEnvironment mechanism (git.ts:413) as core.hooksPath=<empty> + core.fsmonitor=false. Apply to worktree add, provisioning checkouts, snapshot index ops, and rollback. Note git worktree add runs post-checkout; test with a hook that would write a sentinel or fail.
2. Disk admission core module (main/services/worktree-disk-admission.ts): injected statfs (tests fake it), policy = max(4 GiB, 10% of volume) capped at 16 GiB + 2× checkout/provisioned estimate. Estimate from the source checkout via bounded git ls-files/lstat walk; on overflow or statfs error, stop allocation with an actionable error (fail closed). Wire before worktree add and re-check before provisioning/setup.

Tests: admit/reject boundaries, unavailable-reading fail-closed, hook-sentinel absent, existing create/rollback tests still pass.

M2 — .worktreeinclude provisioning + .aiden/worktree-setup.sh

1. Provisioning core (main/services/worktree-provision-core.ts):
   • Read <repo.root>/.worktreeinclude, one gitignore-syntax pattern per line, # comments.
   • Eligible set = paths Git reports as ignored + untracked (git ls-files -z --others --ignored --exclude-standard), then filter to .worktreeinclude matches using Git itself: git check-ignore -v -z --stdin with a temp core.excludesFile copy, matching the reported source path. This avoids a new dependency and inherits true gitignore semantics. Pin the -v -z record format in a test.
   • Copy with create-exclusive semantics (never overwrite), preserve modes, skip symlinks, verify every destination stays inside the new worktree, and record every path actually created in the snapshot registry manifest ("recorded" is the authority for later snapshots/restore, even if the include file changes).
   • Failure after any files were copied rolls the whole creation back via the existing rollbackWorktree path.
2. Setup script (main/services/worktree-setup-core.ts): run <repo.root>/.aiden/worktree-setup.sh only when present and executable, cwd = new worktree, dedicated 120 s timeout, bounded output capture. Env is exactly PATH, LANG, LC_ALL, AIDEN_SOURCE_TREE_PATH, AIDEN_WORKTREE_PATH — never process.env. Nonzero exit/signal/timeout aborts creation and removes branch + checkout.
3. Order inside the existing create transaction (workspace-worktree-application-service.ts:59): create → provision → setup → save. Disk re-check before provision.

Tests: comment/negation/** patterns, symlink skip, no-overwrite, mode preservation, env isolation assertion (sentinel secret not visible to the script), timeout/abort rollback.

M3 — Snapshot before delete + restore (P0 core)

1. Snapshot creation on GitService: build a temporary index (gitIndexFile already supported, git.ts:93) with read-tree HEAD + add -A, write-tree, commit-tree (parent = current HEAD), then CAS update-ref refs/aiden/snapshots/<id>. Captures tracked + non-ignored untracked as unstaged content; ignored files never enter the object database. Provisioned ignored files are copied into the device-local snapshot store with modes + manifest. Verify HEAD has not moved before publishing; if it has, preserve the checkout and tell the user to retry.
2. Delete transaction change (git.ts:4761): remove the blanket dirty_worktree refusal. Inside the enqueueMutation critical section and before quarantine: verify ownership/admission → create snapshot (or reuse an existing one) → persist snapshot id to the workspace record + removal journal → proceed with the existing quarantine/removal. If snapshotting fails, deletion stops with an actionable error; an explicit force mode discards snapshot safety (Settings/remote must confirm it separately). Clean worktrees keep today's fast path.
3. Restore (GitService.restoreManagedWorktree): create the branch at the saved base commit with --no-checkout, materialize the snapshot tree through a temp index + checkout-index so the index stays at base and the result is unstaged modifications + untracked files + unstaged deletions (exact dirty-state reproduction), then restore provisioned ignored files from the store and re-establish the ownership marker/identity record. No reusable template needed for MVP.
4. Crash safety: extend the removal journal so recovery knows whether a snapshot was published; reconcilePendingManagedWorktreeDeletions must either finalize deletion with the snapshot retained in the registry, or safely retry. Snapshot refs survive git gc because they are pinned refs; document the retention coupling.
5. Result shape: extend GitDeleteWorktreeResult with snapshot identity so the UI can say "removed; restorable for 30 days".

Tests (extend main/services/git.test.ts around the existing worktree suite, ~2598+): dirty delete snapshots + removes; restore reproduces unstaged edits/untracked/deleted files; ignored provisioned files round-trip; ignored-but-unprovisioned files do not block; snapshot failure aborts; HEAD-moved retry; existing moved/replaced/identity/journal tests unchanged.

M4 — P1: namespace, base ref, GC, Settings → Worktrees

1. aiden/<name> branch namespace + base-ref picker: extend parseWorktreeCreateParams (main/handlers/worktree-create-params.ts) with optional baseRef and name; branch = aiden/<slug>; resolve and pin the base ref to a commit inside the mutation (rev-parse --verify <ref>^{commit}); reject occupied names with an actionable error (numeric suffixing can follow). Update git-branch-picker.tsx (reuse useGitBranches to offer local + remote refs) and the chat-pane.tsx:1714 / composer flows. Remote create body gains optional baseRef; keep branch back-compat or version the contract (aiden-remote-git.ts:674).
2. Ownership + GC: persist owner + lastUsedAt; startup + hourly sweep snapshots/removes session-owned worktrees idle > 7 days; expire snapshots after 30 days; manual records are never swept. Honest caveat: Aiden only creates manual worktrees today, so GC is dormant until session-owned creation exists — build it ready but do not fake scheduling.
3. Settings → Worktrees pane: add worktrees to renderer/shared/settings-section.ts, NAV_ICONS/CONTENT/DESCRIPTIONS in renderer/main/settings-view.tsx:75, new renderer/components/settings/worktrees-settings.tsx following docs/settings-design-system.md. Lists active + restorable records with restore, force delete, and snapshot expiry. New IPC channels route through the application service (not raw git.ts), mirror the INVOKE_PREFIXES contract (ipc-contract.test.ts), and stay local-only for MVP.
4. Update docs/aiden-remote-api-v1.md; verify iOS/Android consumers for the changed dirty-delete semantics and new optional create fields even if no client UI changes.

M5 — P2 (deferred, explicitly after M3)

• Filesystem acceleration behind a probe + fallback (APFS clonefile, Btrfs snapshots, ReFS block clones; per-file COPYFILE_FICLONE_FORCE is the low-cost first step), and configurable device-local worktreeRoot (absolute/~, validated, default stays userData/worktrees). Not before snapshot/restore is proven.

---

Acceptance mapping

MVP acceptance	Milestone
Hooks disabled on managed create	M1
Disk admission gates create	M1
.worktreeinclude copies and records ignored files	M2
Dirty delete snapshots then removes; restore recreates unstaged state	M3
Existing ownership/admission/quarantine delete still pass	M1–M3 regression suites

Test & CI wiring

• New core modules get dedicated *.test.ts files. Per repo learnings, a test:* script alone is not CI coverage: either add files to the composite test array (where main/services/git.test.ts already runs) or chain a new script into pretest and pretest:coverage. Unregistered files silently never run.
• Run npm run type-check, the focused suites, then npm test before finishing; add a renderer test for the Settings pane in the style of settings-design.test.tsx.
• Migration/contract changes touch config-store-core.test.ts, portable-config-core tests, workspace-worktree-application-service.test.ts, aiden-remote-git.test.ts, aiden-remote-workspaces.test.ts, and the IPC contract test.

Risks / decisions needed

1. Setup-script authority: OpenClaw runs it only for operator.admin. Aiden's remote git:write devices can create worktrees; proposal is to run .aiden/worktree-setup.sh only for the attended desktop path and skip it for remote callers (with an explicit note), pending an owner decision.
2. Changing dirty-delete semantics is a client-visible contract change (remote delete currently surfaces dirty_worktree). Remote clients must be checked; force-delete should require its own confirmation.
3. Snapshot store growth: provisioned ignored files may be large/secret-adjacent, so they stay in a 0600 device-local store outside the repo object DB, with a byte budget and 30-day cleanup.
4. GC pass with no session-owned worktrees is intentionally a no-op until a session/scheduled workflow creates them.
5. check-ignore -v -z format depends on Git; pin it in a test and fall back to a bounded internal matcher if needed. No new dependency planned.
6. Partial clones / missing objects during snapshot and restore need the OpenClaw-style bounded error guidance rather than silent failure.

Suggested PR breakdown

1. M0 (contracts + snapshot store) → 2. M1 (hooks + disk admission) → 3. M2 (provision + setup) → 4. M3 (snapshot/restore + journal/recovery) → 5. M4 (namespace/base-ref + GC + Settings) → 6. M5 (P2). Each PR keeps the existing safety suites green; only the intentional dirty-delete tests change in M3.

Task list (3/4 completed)

• Gather context: worktree core, git service, UI, remote APIs, memory/docs
• Analyze OpenClaw reference lifecycle vs Aiden's owned-worktree core
• Write structured plan with milestones, files, tests, risks
• Post plan via report_progress

  ^{｜ Implement plan ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using DeepSeek Flash ｜ 𝕏}