Support worktree-scoped local app isolation for parallel QA

[flazouh]

Summary

Acepe should support worktree-scoped local app isolation for local source/dev runs so developers can QA features from multiple checkouts in parallel without shared-state collisions.

Today, local dev launches still behave like one shared app namespace:

• dev SQLite DB is shared
• agent installer cache is shared
• logs are shared
• Acepe-managed local settings/project metadata are effectively shared
• app identity/labeling does not clearly distinguish a worktree run from the main checkout

This makes it awkward to run Acepe from the main checkout and from a linked worktree at the same time.

Desired behavior

When Acepe is launched from a linked git worktree:

• detect that runtime context automatically
• launch as its own app process with its own state initialization
• use a worktree-scoped local namespace instead of the shared default local namespace
• isolate the whole Acepe-managed local state for that run, including at minimum:
  • SQLite DB
  • logs
  • agent installer cache
  • other local caches
  • Acepe-managed app settings / project metadata carried in the DB
• visibly identify the app using the worktree folder basename
• keep storage collision-safe by using repo + folder for the underlying namespace key

When Acepe is launched from the main checkout or from a non-worktree context:

• keep the existing shared local namespace behavior

Packaged/installed builds should keep the normal packaged app identity and shared local namespace behavior.

Scope boundaries

• No per-worktree packaged app products or release channels
• No manual namespace selector in the UI
• No isolation of third-party/provider-owned storage outside Acepe-managed local state
• No automatic migration of historical shared dev data into per-worktree namespaces
• No orphaned-namespace cleanup for deleted/renamed worktrees in this change

Important decisions already made

• Auto-detect worktrees instead of using a manual toggle
• Process isolation, not second-window isolation
• Whole-namespace isolation for Acepe-managed local state
• Folder basename for display, repo+folder for storage
• Return to short adjective-animal worktree names so worktree labels remain readable during QA

Planning questions

• What runtime signal should be the source of truth for linked-worktree detection?
• What minimum dev-only launch identity differentiation is needed if the OS collapses same-identifier app launches?
• Which additional Acepe-managed paths still need rerouting beyond DB/logs/agent installer cache?
• What canonical repo identity should qualify the storage namespace key?
• Which visible surfaces should show the worktree label?
• What should the visible label do when the basename is too long?
• What exact adjective-animal naming rule should govern Acepe-created worktrees?

Notes from requirements review

Two important things to keep an eye on during planning:

1. The concurrent local launch requirement may require some dev-only identity differentiation depending on OS behavior.
2. The worktree naming change may be worth separating from core isolation work if it starts expanding the scope too much.

Reference

Requirements doc: docs/brainstorms/2026-04-23-worktree-app-isolation-requirements.md