pi-web/.pi-web/relays/worktree-autodetect/status.md

Status — relay "worktree-autodetect"

🏁 FINISHED — the relay reached its finish line

All three legs are complete and committed on feat/worktree-autodetect. npm run verify is green. No further leg was spawned; leg 3 was the last one by design.

Remaining human action: review the branch and merge it. Nothing is blocked.

Current position

Every charter finish-line condition is satisfied:

1. ✅ Prunable worktrees hidden — 266f941. discoverGitWorktrees parses prunable; WorkspaceService filters those worktrees out, while always keeping the project's own worktree so a project is never empty.
2. ✅ Non-disruptive client refresh — d0f8f9f. WorkspaceController.refreshSelectedProjectTopology() applies results through applyProjectWorkspaces only, never selectWorkspace, so selection, session, file tree, git status, and terminal selection survive. A vanished selected workspace is left alone for the existing deletion path to handle.
3. ✅ Wired to the existing resume path — 84545fb. Called from PiWebApp.refreshAfterBrowserResume and refreshAppData. No new timer, watcher, process, endpoint, or push channel. Remote machines work through the existing machinePrefix + FEDERATED_HTTP_ROUTES plumbing.
4. ✅ Tests — prunable parsing/filtering (gitWorktreeDiscovery.test.ts, workspaceService.test.ts), refresh-preserves-selection and refresh-when-selected-workspace-disappeared (workspaceController.test.ts, 7 tests), resume + app-data wiring (PiWebApp.workspaceTopology.test.ts, 3 tests).
5. ✅ npm run verify green (228 files / 1840 passed, 2 skipped) and .changeset/worktree-autodetect.md exists.

Nothing in this work touched src/server/sessiond.ts, session runtime ownership, or the daemon protocol. No manual session daemon restart is required.

Leg tracking

• Last completed leg: 3 (final — wiring, docs, changeset, full verify)
• Next leg to run: none. Relay complete; do not spawn another runner.

Shipped behavior, as a user sees it

A worktree created or deleted outside PI WEB shows up in (or disappears from) the workspace list the next time the browser tab regains focus or becomes visible. Detection is resume-scoped, not instant, by explicit human decision. A worktree whose checkout directory was rm -rfed no longer appears as a selectable workspace. Documented in docs/faq.html under #worktree-list-out-of-date.

Relevant context if anyone picks this branch up

• Commits: 266f941 (server filter), d0f8f9f (client refresh method), 84545fb (wiring + docs + changeset), plus three docs(relay) packet commits.
• The invariant to protect on any future edit: never route a background topology refresh through selectWorkspace. It calls clearActiveSession() and resetWorkspaceScopedState() with no already-selected guard, which would close the session socket and blank the chat on every browser resume. workspaceController.test.ts was mutation-checked against exactly that regression in leg 2.
• The relay packet lives under .pi-web/, which is gitignored; packet commits used git add -f.

Blockers

None. No intervention signal fired in any leg. The one serious known risk — visible UI churn on refresh — did not materialize and needed no workaround.