isolate-work-in-worktree

Isolate work in worktree

Contract

Inputs

• runId (required): unique identifier for the run, used verbatim as a path segment and branch suffix; it must be a single path segment (no /, not . or ..).
• pattern (required at create): short label of the work pattern, kept on the manifest entry for audit.
• Base branch (optional, default main) and repo root (optional, default cwd; must be inside a git repository).
• Status for mark (required): exactly one of active, rejected, escalated, merged, stale.
• Cleanup set (optional): status CSV, default rejected,escalated, plus an age cutoff in the form <n> + s|m|h|d (for example 24h).

Procedure

1. Bind the root. Run git rev-parse --is-inside-work-tree; on failure stop without mutating. All state lives under .loop-worktrees/: the manifest at .loop-worktrees/manifest.json shaped exactly {"version":1,"worktrees":[]}, and the mutex at .loop-worktrees/.manifest.mutex. If the manifest exists in any other shape, stop — never rewrite a manifest that was not validated. Add .loop-worktrees/ to .gitignore so worktree contents never enter the index.
2. Serialize manifest mutations with the mutex. Before each read-modify-write, create .loop-worktrees/.manifest.mutex with exclusive create; if it exists and its mtime is older than 30 seconds, remove it and retry; otherwise retry after a short backoff until a 30-second deadline, then fail naming the mutex path. Delete the mutex when the mutation ends, success or failure. Pure reads take no mutex.
3. Create. Refuse a runId that is not a single path segment. Under the mutex, read the manifest: if an entry with the same id has status active, refuse and name its existing path. Otherwise run git worktree add -b loop/<runId> .loop-worktrees/<runId> <base>, which creates the branch and checks it out in one step. Replace any prior entry with the same id and append {"id":<runId>,"path":".loop-worktrees/<runId>","branch":"loop/<runId>","baseBranch":<base>,"pattern":<pattern>,"createdAt":<ISO-8601 UTC>,"status":"active"}. Write the manifest atomically: write a temp file in the same directory, then rename it over manifest.json.
4. Mark outcomes; never delete entries to record them. Under the mutex: reject any status outside the five-value set; find the entry by id or fail naming the id; set its status; write the manifest atomically as in step 3. Marking preserves the audit trail; removal happens only in cleanup.
5. Clean up terminal worktrees. Under the mutex: select entries whose status is in the requested set — default rejected and escalated; active is never selected, so mark a finished run terminal first — and, when a cutoff is given, whose createdAt is older than now minus the cutoff. For each selected entry run git worktree remove .loop-worktrees/<id> without --force; a git refusal, typically uncommitted or untracked files, is recorded as skipped with its reason and the entry stays in the manifest. Rewrite the manifest without the removed ids, atomically.
6. Reconcile manifest and disk. List git worktrees with git worktree list --porcelain and compare paths under .loop-worktrees/ against the manifest. Worktrees registered with git but missing from the manifest are orphans: report them, and remove one only on explicit instruction, still without --force. Drop manifest entries whose directory no longer exists with an atomic manifest write. Treat a missing path as absent, not an error, since rm -rf, a crash mid-cleanup, or a container wipe can leave git listing a prunable entry.