feat(daemon): opt-in per-task worktree isolation for local_directory tasks

[fsafey]

Opt-in per-task worktree isolation for local_directory (VWO-367)

Rebased on current main (v0.4.3). Mergeable on its own merits: the default path is byte-for-byte unchanged, and the new flag is inert until a resource sets it. It does not depend on #5494 — see the deployment note at the end for how the two compose.

Problem

A local_directory project_resource binds a task's WorkDir to a user's live checkout, and the daemon holds a whole-task path mutex (LocalPathLocker, keyed on the checkout realpath) for the task's entire life — sidecar writes, the git index, and cleanup all mutate that one shared tree. For a fleet whose agents all target one checkout, that collapses their designed concurrency to one task at a time. (Pre-lock versions had the opposite failure: unsynchronized tasks in one tree, producing .claude/skills/<name>-multica-N collision litter.)

Change

Per-resource opt-in local_directory.resource_ref.isolate (polymorphic JSONB — no migration; the field lives on both handler.localDirectoryRef and the daemon mirror so validateLocalDirectoryRef's re-marshal can't strip it).

• isolate:false (default): unchanged — in-place edit under the whole-task mutex. Preserves the contract of agents that must edit the user's live tree in place. Stored payloads for existing rows are byte-identical (omitempty, pinned by test).
• isolate:true: the daemon cuts a per-task worktree off the checkout's repository — git worktree add -b multica/worktree/<shortTaskID> <envRoot>/workdir HEAD — own working tree, own git index, sidecars contained in the disposable worktree. The whole-task mutex is skipped; only the brief git worktree add/remove critical sections are serialized (per-source-repo, in-process; cross-process races are covered by git's own lockfiles).

Enabling it: set "isolate": true in the resource's resource_ref via the project-resources API (or CLI). A UI toggle can follow independently.

New execenv/local_worktree.go (create / remove / prune-orphan), composed from the existing execenv git helpers. Wired into execenv.Prepare (worktree cut before context files land, so sidecars go inside the isolated tree), the daemon acquire path (mutex skip on opt-in), PrepareParams.Isolate, deferred teardown, and Environment.Cleanup.

Lifecycle ownership

• create: daemon. commit/rebase/push: the agent, in its worktree, on its per-task branch (scratch — work worth keeping must be pushed before the task ends). conflict: surfaces as an ordinary rebase/non-fast-forward in the agent's own worktree — a visible conflict instead of a silent lost update.
• cleanup: deferred git worktree remove --force + branch delete + prune on the graceful path. Crash recovery is self-healing with no GC wiring: creating the next task's worktree opportunistically reaps dangling registry entries and orphan multica/worktree/* branches (reapOrphansLocked); a live sibling can never be touched (prune only drops missing-dir entries; checked-out branches are skipped). Idempotent everywhere.

Tests (Go 1.26.1; DB-backed suites against pgvector/pg17 + cmd/migrate up, mirroring CI)

• go build ./... pass; go vet (daemon/execenv/handler) clean; gofmt -l clean — all on the v0.4.3 rebase.
• Full package suites pass: internal/handler (DB-backed), internal/daemon, internal/daemon/execenv. -race on the isolation + acquire tests passes.
• Module scenarios: concurrent distinct index TestIsolated_ConcurrentDistinctIndex; provider-failure/cancel cleanup TestIsolated_ProviderFailureLeavesNoOrphan / …RepeatedCleanupIdempotent; crash + orphan recovery TestIsolated_CrashOrphanRecovery + TestIsolated_NextTaskReapsCrashOrphanBranchAndEntry; rebase conflict TestIsolated_RebaseConflictSurfaces; no writes to the source checkout TestIsolated_NoWritesToSourceWorkingTree; prune preserves live worktrees TestPruneOrphan_PreservesLiveWorktree.
• Wiring: TestPrepare_IsolateCutsWorktree / …IsolateRequiresGitRepo / …InPlaceDefaultUnchanged (execenv), TestAcquireLocalDirectoryLock_IsolateSkipsPathMutex (proceeds immediately while another task holds the lock; in-place control still locks), TestValidateLocalDirectoryRefIsolateRoundTrip (flag survives validation; default payload unchanged).
• Repro note for containerized runs: the suite must not run as root — TestValidateLocalPath needs a non-root $HOME and TestRunTask_InjectsPrivateTaskTempDir needs IS_SANDBOX=1 (both pre-existing environment guards, untouched here).
• Also verified: main's recent MUL-4869 (reuse workdir on manual retry) is server-side only and does not interact — the daemon still skips reuse whenever a local_directory assignment exists.

Deployment note (for operators enabling isolate on shared checkouts)

Worktree isolation removes working-tree/index/sidecar sharing between tasks of one daemon. If a machine can accidentally run two daemons against the same repository (the failure #5494 addresses), land and deploy the single-owner lock first, then opt in — the two changes compose but are independent to merge. Same-path serialization of tracked shared files across isolated worktrees (when two tasks edit the same file) reconciles through ordinary git conflicts; fleets that need stricter ordering should serialize at the workflow level.

Rollback

Set the resource back to isolate:false (or drop the field) → the next task reverts to in-place + whole-task mutex, no redeploy. Blast radius of the change is only opted-in resources.

🤖 Generated with Claude Code

[vercel]

@fsafey is attempting to deploy a commit to the IndexLabs Team on Vercel.

A member of the Team first needs to authorize it.