Worktree unmaterialized at coder start: .peer-sync/.claude exist but git worktree is missing

[lukstafi]

Summary

When the coder agent for task-ab90fcb7 started, the worktree directory existed at the expected path with .peer-sync/, .claude/, and .ludics-orchestration.json populated, but the actual git worktree had never been created — git did not recognize the path. The agent had to recover manually: move the orchestration files aside, rmdir the empty parent, git worktree add <path> <branch> from the main repo, then move the orchestration files back. This succeeded but suggests a setup-script gap (orchestration scaffolding ran without a successful worktree-create), not coder error.

Data Points

• task-ab90fcb7 (centralize taskId normalization): Worktree at /Users/lukstafi/ludics-task-ab90fcb7-s1/ had only orchestration scaffolding (.peer-sync, .claude, .ludics-orchestration.json) — no actual git worktree. Recovery required moving these aside, rmdir, git worktree add, restore. (from coder, 2026-04-28)

Raw Excerpts

Original feedback

Worktree was unmaterialized at start. The .peer-sync and .claude dirs existed at /Users/lukstafi/ludics-task-ab90fcb7-s1/ but the actual git worktree had never been created. Recovery path that worked: move .peer-sync/.claude/.ludics-orchestration.json aside, rmdir the empty parent, git worktree add <path> <branch> from the main repo, then move the orchestration files back. Worth flagging if this recurs — may indicate a setup-script gap rather than coder error. — task-ab90fcb7--workflow-feedback-coder.md

Suggested Action

1. Investigate setup ordering: Find where orchestration scaffolding (.peer-sync, .claude, .ludics-orchestration.json) is populated relative to git worktree add. The scaffolding must run AFTER the worktree create, or it must abort and clean up if the worktree-create failed.
2. Add a precondition check at coder-startup: if the directory exists but git -C <path> rev-parse --git-dir fails, log a clear error and either (a) auto-recover via the documented recovery path, or (b) fail loudly so the orchestrator can re-provision instead of leaving the agent to improvise.
3. Track recurrence: Add a journal event or counter every time this recovery path is taken, so we can tell whether this is a one-off or a systemic gap.

---

Filed by ludics-feedback-digest

[lukstafi]

Update — auto-recovery landed (task-d2a16a60, PR #435)

addWorktree and processDeferredCleanups now auto-recover orphan worktree dirs whose contents match an allow-list (.peer-sync/, .claude/, .ludics-orchestration.json, .gitignore) and throw a clearer error otherwise. Both call sites share ORPHAN_RECOVERY_ALLOWLIST. Commit 19e7030, 1626 tests pass.

Durable learnings worth carrying forward

• existsSync follows symlinks — a dangling symlink at target reports false, but the next renameSync(tempDir/entry, target) fails with EEXIST because the link still occupies the inode. Guard restore-paths with an lstatSync-based helper that checks isSymbolicLink(). Reusable for any "node_modules-style symlink in worktree scaffolding" restore. Anchor: src/orchestration/worktrees.ts:lstatExistsLink.
• Recovery temp dirs belong as siblings of the target, not under it — ${path}.orphan-recover, not ${path}/.... Putting it under ${path}/ collides with git worktree add (refuses non-empty dir); putting it in os.tmpdir() risks crossing filesystems and breaking renameSync atomicity.
• Best-effort fallback contract needs a dual-assertion test — when a cleanup step is deliberately outside the failed = true → push back into remaining contract (so its failure does not resurrect the entry), the test must assert both: (a) the side-effect under the failure case (e.g., stray file preserved) AND (b) loadDeferredCleanups() returns empty. Without (b), the test would pass even if the fallback wrongly flipped failed.
• .DS_Store carve-out — listed in IGNORE_PATTERNS so its presence does not block recovery, but not in ORPHAN_RECOVERY_ALLOWLIST so it cannot cause recovery to succeed alone. The two-list distinction is load-bearing; future maintainers should preserve it.

The original report's "Track recurrence" suggestion (data point 3 in this issue's Suggested Action) is no longer needed — the recovery path is now silent and idempotent. The "investigate setup ordering" suggestion (data point 1) is the still-open root cause: nothing in this PR addresses why the orchestration scaffolding ran without a successful worktree-create.

---

Filed by ludics-feedback-digest