pi-crew 0.2.3 → 0.2.5

package/skills/widget-rendering/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: widget-rendering
+description: Pi TUI crew widget data sources, display priority, and rendering performance. Use when debugging empty agents, ghost runs, or widget timing issues.
+---
+
+# widget-rendering
+
+The crew widget (`src/ui/crew-widget.ts`) displays active runs and their agents in the Pi TUI. It must render synchronously at TTY refresh rate without blocking. Understanding the data sources and timing rules is essential for debugging display issues.
+
+## Three Data Sources
+
+The widget has three sources, used in priority order:
+
+### 1. `liveAgents` Map (real-time, highest priority)
+
+In-memory map from `live-agent-manager.ts`. Provides:
+- Real-time tool names: `activeTools` Map (toolName → description)
+- Turn count, response text, compaction count
+- Session stats: context %, token usage
+- Status from the handle
+
+**When used:** Agents with `liveHandle && liveHandle.status === "running"` get the live activity description (tool labels, response text, turn counter).
+
+**When NOT used:** After `evictStaleLiveAgentHandles()` removes a handle, widget falls back to agent records on disk.
+
+### 2. Snapshot cache (500ms TTL)
+
+`RunSnapshotCache` from `run-snapshot-cache.ts` caches parsed manifests and agents for 500ms. Reduces disk reads during rapid refresh.
+
+**When used:** As the fallback when no live handle exists. Prevents excessive disk reads on every render tick.
+
+**Invalidation:** Cache is invalidated when:
+- `invalidate()` is called on a specific run
+- An empty result is returned (forces refresh on next tick)
+- TTL expires (500ms)
+
+### 3. `agents.json` on disk (durables, lowest priority)
+
+`readCrewAgents(run)` reads `artifactsRoot/agents.json`. Provides:
+- Final agent status (completed/failed/cancelled)
+- Tool count, token usage from final record
+- Error messages
+- Timestamps (startedAt, completedAt)
+
+**When used:** For completed agents, or when snapshot cache misses.
+
+---
+
+## Display Priority
+
+```
+for each active run:
+  for each agent in run:
+    if liveAgents has this agent (by agentId or taskId):
+      → use live activity description (tool labels, response text)
+      → use live status (running/queued/waiting)
+      → use live session stats (context %, turns, tokens)
+    else if snapshot cache has fresh data:
+      → use cached agent status
+      → use cached tool count, tokens, progress
+    else:
+      → read agents.json from disk
+      → use disk agent status
+
+    if status is completed/failed/cancelled:
+      → apply linger rules (finishedAgents: 1min, errors: 2min)
+```
+
+---
+
+## Active Runs Filtering
+
+`activeWidgetRuns()` determines which runs to show. Key filter: `isDisplayActiveRun(manifest, tasks)` from `process-status.ts`.
+
+**Rule: `hasStaleAsyncProcess()`**
+
+A run with an async PID is considered stale (hidden) if:
+1. PID is recorded but process is dead, AND
+2. The run is more than 30 minutes old (`STALE_ACTIVE_RUN_MS = 30 * 60 * 1000`)
+
+**Rule: `isDisplayActiveRun()`**
+
+```typescript
+export function isDisplayActiveRun(manifest: TeamRunManifest, tasks: TeamTaskState[]): boolean {
+  if (manifest.status === "running" || manifest.status === "waiting") {
+    if (manifest.async?.pid) {
+      if (hasStaleAsyncProcess(manifest.async.pid, manifest.updatedAt)) return false;
+    }
+    const hasActiveTask = tasks.some((t) => t.status === "running" || t.status === "queued" || t.status === "waiting");
+    if (!hasActiveTask) return false;
+    return true;
+  }
+  return false;
+}
+```
+
+This filters out ghost runs (PID dead, manifest still "running") that are more than 30 minutes old.
+
+---
+
+## Stale Handle Eviction
+
+**On every widget refresh**, `evictStaleLiveAgentHandles()` is called at the start of `activeWidgetRuns()`:
+
+```typescript
+export function activeWidgetRuns(...): WidgetRun[] {
+  evictStaleLiveAgentHandles(); // prevent memory leaks
+  const runs = preloadedManifests ?? ...;
+  // ...
+}
+```
+
+**Eviction rule:** Remove handles where:
+- Status is terminal (not running/queued/waiting), AND
+- `updatedAt` is more than 10 minutes ago
+
+```typescript
+const STALE_HANDLE_MS = 10 * 60 * 1000;
+if (handle.status !== "running" && handle.status !== "queued" && handle.status !== "waiting") {
+  const age = now - new Date(handle.updatedAt).getTime();
+  if (age > STALE_HANDLE_MS) {
+    liveAgents.delete(agentId);
+    safeDisposeLiveSession(handle);
+  }
+}
+```
+
+**Why called on every refresh:** Ensures the in-memory Map stays bounded even during long Pi sessions. Completed agents linger for 10 minutes (for visibility), then get evicted.
+
+---
+
+## Frame Timing Rules
+
+### `renderTick()` must be non-blocking
+
+Every render cycle (`renderTick` / `requestAnimationFrame`) must complete in <16ms to maintain 60fps. The widget must not:
+- Call `fs.readFileSync` on hot paths
+- Call `loadConfig()` during render
+- Scan directories (`readdirSync`)
+- Make network calls
+
+**Solution:** Preload everything async before the first render.
+
+### Widget refresh intervals
+
+| Scenario | Interval |
+|---|---|
+| Live agents running | 160ms (`LIVE_REFRESH_MS`) |
+| No live agents, recent activity | 2s |
+| Idle | 10s |
+
+### TTL interactions
+
+- Snapshot cache TTL = 500ms
+- Preload interval must be < TTL to avoid render-time gaps
+- If preload interval ≥ TTL, the cache always has fresh data for render
+
+---
+
+## Agent Activity Description
+
+`agentActivity(agent, liveHandle?)` generates the activity string shown in the widget:
+
+```typescript
+function agentActivity(agent: CrewAgentRecord, liveHandle?: LiveAgentHandle): string {
+  if (liveHandle && liveHandle.status === "running") {
+    const live = describeLiveActivity(liveHandle);
+    // Prefer richer agent.progress data if live is just the fallback
+    if (live === "thinking…" && agent.progress?.currentTool)
+      return `${TOOL_LABELS[agent.progress.currentTool] ?? agent.progress.currentTool}…`;
+    return live;
+  }
+  // Fallback chain from agent records
+  if (agent.progress?.currentTool) return `${TOOL_LABELS[agent.progress.currentTool]}…`;
+  if (recent output) return lastOutput line;
+  if (activityState === "needs_attention") return "needs attention";
+  if (status === "queued") return "queued";
+  if (status === "running") {
+    if (age < 5s && no tool) return "spawning…";
+    return "thinking…";
+  }
+  if (status === "failed") return agent.error ?? "failed";
+  return "done";
+}
+```
+
+**Tool name extraction:** `TOOL_LABELS` maps tool names to readable labels:
+```typescript
+const TOOL_LABELS = {
+  read: "reading",
+  bash: "running command",
+  edit: "editing",
+  write: "writing",
+  grep: "searching",
+  find: "finding files",
+  ls: "listing",
+};
+```
+
+---
+
+## Ghost Run Display Bug Patterns
+
+### Bug: Agent shows "running" in widget but process is dead
+
+**Root cause:** `agents.json` still has status "running" while the actual PID is dead.
+
+**Fix path:** `reconcileAllStaleRuns` now calls `upsertCrewAgent` when repairing tasks, syncing agent status files. Also `purgeStaleActiveRunIndex` and `cancelOrphanedRuns` now sync agent records.
+
+### Bug: Widget shows empty agent (no name, no status)
+
+**Root cause:** `agentActivity` fallback chain returned `"done"` with no name. The agent description construction had fallbacks to empty strings.
+
+**Fix applied:** `agentActivity` now uses `handle.agent ?? handle.role ?? agent.agent ?? agent.role ?? "Agent"` as the description base. Plus `(running)` suffix uses `handle.status` not `agent.status`.
+
+### Bug: Ghost runs appear after Pi restart
+
+**Root cause:** `active-run-index.json` is missing on restart, so `purgeStaleActiveRunIndex()` doesn't know about orphaned runs. `reconcileAllStaleRuns` (disk scan) was never called.
+
+**Fix applied:** `reconcileAllStaleRuns` is now called at session start in `register.ts`.
+
+### Bug: "worker blinks" — agent appears and disappears in 1 frame
+
+**Root cause:** Worker spawns and crashes in <1 frame. Structured logs (`worker.spawned` + rapid `worker.exit`) expose the crash cause.
+
+**Fix:** Event log tracing skill documents this pattern.
+
+---
+
+## Anti-patterns
+
+- **Blocking render with fs calls**: Every `readFileSync`, `readdirSync`, `fs.statSync` in the render path causes frame drops. Preload everything async.
+- **Stale cache in hot path**: If snapshot cache TTL is too long, widget shows outdated state. Keep TTL at 500ms or less.
+- **No invalidation on empty**: When `readCrewAgents` returns `[]` (no agents yet), the cache must be invalidated on next tick to prevent showing empty for too long.
+- **Expired handles accumulating**: Without `evictStaleLiveAgentHandles`, the Map grows indefinitely. Call it on every refresh.
+- **Widget showing stale health warnings**: Completed/cancelled/failed runs should not show health warnings. Filter by status.
+
+---
+
+## Source patterns
+
+- `src/ui/crew-widget.ts` — render, refresh, activeWidgetRuns, evictStaleLiveAgentHandles, agentActivity, describeLiveActivity
+- `src/ui/run-snapshot-cache.ts` — SnapshotCache, get, refreshIfStale, TTL=500ms
+- `src/runtime/crew-agent-records.ts` — readCrewAgents, agents.json
+- `src/runtime/process-status.ts` — hasStaleAsyncProcess, isDisplayActiveRun
+- `src/runtime/background-runner.ts` — active run filtering with async PID check
+- `src/runtime/active-run-registry.ts` — purgeStaleActiveRunIndex
+
+---
+
+## Verification
+
+```bash
+cd pi-crew
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/crew-widget.test.ts test/unit/run-snapshot-cache.test.ts test/unit/live-agent-manager.test.ts
+npm test
+```

package/skills/workspace-isolation/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: workspace-isolation
+description: Workspace isolation boundaries in pi-crew. Use when ensuring agents from workspace A cannot access workspace B, or when implementing worktree-based parallel execution.
+---
+
+# workspace-isolation
+
+pi-crew enforces workspace isolation so that agents, runs, and live sessions from one project folder cannot be accessed from another. The workspace boundary is `manifest.cwd` — the directory where a run was initiated.
+
+## Workspace Boundary Definition
+
+**`manifest.cwd`** is the canonical workspace root. Every run record carries the directory where it was created.
+
+**Why it matters:** Pi can have multiple workspace folders open simultaneously. Without isolation, an agent from workspace A could be steered/controlled from workspace B.
+
+**Rules:**
+- Every run's `manifest.cwd` is set at creation time
+- Every live agent handle carries `workspaceId = manifest.cwd`
+- Widget queries filter by `manifest.cwd`
+- API operations reject cross-workspace access
+
+## Live Agent Workspace Check
+
+`LiveAgentHandle.workspaceId` field (added to prevent cross-workspace access):
+
+```typescript
+interface LiveAgentHandle {
+  // ... other fields
+  /** Workspace where this agent was spawned — used for session-scoped visibility. */
+  workspaceId: string;
+}
+```
+
+**Enforcement in `api.ts`** (team-tool operations):
+
+```typescript
+// list-active-live-agents: filter by workspace
+listActiveLiveAgentsByWorkspace(manifest.cwd);
+
+// steer-agent, follow-up-agent, stop-agent, resume-agent:
+const live = getLiveAgent(agentId);
+if (live && live.workspaceId !== manifest.cwd)
+  return result(`Live agent '${agentId}' does not belong to workspace ${manifest.cwd}.`, { status: "error" }, true);
+```
+
+**Enforcement in `live-agent-manager.ts`**:
+
+```typescript
+// listLiveAgentsByWorkspace(workspaceId): filter by workspaceId
+export function listLiveAgentsByWorkspace(workspaceId: string): LiveAgentHandle[] {
+  return listLiveAgents().filter((a) => a.workspaceId === workspaceId);
+}
+```
+
+## Team Workspace Modes
+
+### `single` (default)
+
+- All agents run in the project root (`manifest.cwd`)
+- No worktree creation
+- Simpler, but all workers share the same git state
+
+### `worktree` (parallel isolation)
+
+- Each task (or phase) gets its own git worktree
+- Worktree path: `<repo-root>/.worktrees/<runId>/<taskId>/`
+- Branch name: `crew/<runId>-<taskId>` (sanitized)
+- Allows parallel code-changing tasks without git conflicts
+
+**Entry point in `team-runner.ts`:**
+```typescript
+const worktree = workspaceMode === "worktree" && task.worktree !== undefined
+  ? { path: task.worktree.path, branch: task.worktree.branch, reused: task.worktree.reused }
+  : undefined;
+```
+
+**Worktree lifecycle:**
+
+1. **Creation** (`prepareTaskWorkspace` in `worktree-manager.ts`):
+   - Check leader repo is clean (`assertCleanLeader`)
+   - `git worktree add <path> <branch>`
+   - Link `node_modules` if present
+   - Mark reused if already exists
+
+2. **Naming convention**:
+   ```
+   Branch: crew/<sanitized-runId>-<sanitized-taskId>
+   Path: .worktrees/<runId>/<taskId>/
+   ```
+
+3. **Cleanup** (on task/run completion):
+   - Check dirty state
+   - `git worktree remove <path> --force` (only if force=true)
+   - Preserve dirty worktrees unless explicitly forced
+
+**Safety rules:**
+- Leader repo must be clean before creating worktrees
+- One owner per file/symbol/migration path
+- Branch names derived deterministically from run/task IDs (no user-controlled path fragments)
+
+## Cross-Workspace Prevention
+
+**In api.ts (`handleTeamToolCall`):**
+
+```typescript
+if (operation === "list-live-agents") {
+  return result(JSON.stringify(
+    listActiveLiveAgentsByWorkspace(loaded.manifest.cwd),  // ← filtered by workspace
+    null, 2
+  ), { action: "api", status: "ok", runId: loaded.manifest.runId });
+}
+```
+
+**In cancel.ts:**
+- Verifies run ownership before allowing cancel
+- Cross-session cancel rejected unless force=true
+
+**In respond.ts:**
+- Verifies task ownership before responding
+- Cross-session respond rejected unless force=true
+
+**In crash-recovery.ts:**
+- `purgeStaleActiveRunIndex` only affects runs in the current workspace (cwd)
+- `reconcileAllStaleRuns` only scans the current workspace's `.crew/state/runs/`
+
+## Live Session Workspace
+
+`LiveSessionConfig` carries workspaceId:
+
+```typescript
+interface LiveSessionConfig {
+  // ... other fields
+  /** Workspace directory — used for path containment and isolation. */
+  workspaceId: string;
+}
+```
+
+**Propagation chain:**
+```
+team-tool.ts (handleTeamToolCall)
+  → TeamContext { workspaceId: cwd }
+  → LiveSessionConfig { workspaceId }
+  → registerLiveAgent({ workspaceId })
+  → LiveAgentHandle { workspaceId }
+```
+
+## Configuration
+
+**defaults.ts isolation settings:**
+
+```typescript
+const DEFAULT_PATHS = {
+  crewRoot: ".crew",           // under project root
+  stateRoot: ".crew/state",     // under project root
+};
+```
+
+All paths are resolved relative to `manifest.cwd`, ensuring state stays under the project root.
+
+## Anti-patterns
+
+- **Passing raw cwd without validation**: Always use `resolveContainedPath` to ensure paths stay under workspace root.
+- **Cross-workspace respond/cancel**: Even with force=true, foreign session operations should be rejected. Check `ownerSessionId`.
+- **Symlink traversal**: Use `resolveRealContainedPath` to resolve symlinks and detect escape attempts.
+- **Worktree name collision**: Use deterministic names from run/task IDs. Never accept user-controlled branch names.
+- **Dirty worktree removal**: Never force-remove worktrees with uncommitted changes unless explicitly confirmed.
+
+---
+
+## Source patterns
+
+- `src/extension/team-tool/api.ts` — workspaceId filter in list-live-agents, steer-agent, follow-up-agent, stop-agent, resume-agent
+- `src/runtime/live-agent-manager.ts` — workspaceId in LiveAgentHandle, listLiveAgentsByWorkspace, listActiveLiveAgentsByWorkspace
+- `src/runtime/live-session-runtime.ts` — LiveSessionConfig, workspaceId in session creation
+- `src/runtime/team-runner.ts` — workspaceId passed through executeTeamRun
+- `src/state/state-store.ts` — initRunManifest with cwd, manifest.cwd
+- `src/worktree/worktree-manager.ts` — prepareTaskWorkspace, assertCleanLeader, linkNodeModulesIfPresent
+- `src/config/defaults.ts` — DEFAULT_PATHS (state under project root)
+
+---
+
+## Verification
+
+```bash
+cd pi-crew
+# Verify workspace filter in list-live-agents
+node --experimental-strip-types -e "
+import { listLiveAgentsByWorkspace, listActiveLiveAgentsByWorkspace } from './src/runtime/live-agent-manager.ts';
+console.log('By workspace:', listLiveAgentsByWorkspace(process.cwd()).length);
+console.log('Active by workspace:', listActiveLiveAgentsByWorkspace(process.cwd()).length);
+"
+
+# Verify worktree creation
+node --experimental-strip-types -e "
+import { prepareTaskWorkspace } from './src/worktree/worktree-manager.ts';
+// Requires a clean git repo and workspaceMode='worktree'
+"
+
+npx tsc --noEmit
+node --experimental-strip-types --test test/unit/worktree-manager.test.ts test/unit/isolation-policy.test.ts
+npm test
+```

package/skills/worktree-isolation/SKILL.md

@@ -5,35 +5,219 @@ description: Conflict-safe git worktree workflow. Use when running parallel impl
 
 # worktree-isolation
 
-Use this skill for worktree-based execution or cleanup.
+Use this skill for worktree-based execution or cleanup. Git worktrees create isolated working directories that allow parallel code-changing tasks without git conflicts.
 
-## Source patterns distilled
+## How Worktrees Work
 
-- pi-subagents worktree runner and cleanup patterns
-- pi-crew worktrees: `src/worktree/worktree-manager.ts`, `src/worktree/cleanup.ts`, `src/worktree/branch-freshness.ts`
-- Team runner workspace mode: `src/runtime/team-runner.ts`, workflow/team resource fields
+A git worktree is a separate working directory linked to the same repository. It has its own:
+- Working directory (different path)
+- HEAD (can be on a different branch)
+- Staged/unstaged changes
 
-## Rules
+But it shares:
+- Object database (`.git/objects`)
+- Refs (branches, tags)
 
-- Use worktree mode for parallel or risky code-changing tasks when the repository is clean enough and merge ownership is clear.
-- Assign one owner per file/symbol/migration path to avoid conflict-heavy merges.
-- Name branches/worktrees deterministically from run/task IDs; avoid user-controlled path fragments without sanitization.
-- Before cleanup, check dirty state. Preserve dirty worktrees unless `force` is explicitly set.
-- Record worktree paths and branch metadata in artifacts/events so the operator can inspect or recover.
-- Do not run destructive git operations without explicit confirmation and evidence of target path containment.
+This means creating a worktree is cheap (no clone needed) and fast.
+
+## When to Use Worktrees
+
+**Use worktree mode when:**
+- Running parallel implementation workers that modify the same repo
+- Isolating risky changes that might need to be discarded
+- Running multiple agents on the same codebase simultaneously
+- Running a long task that would block other work
+
+**Don't use worktree mode when:**
+- The task is read-only (use scaffold mode instead)
+- Only one agent needs to work at a time
+- The repository has uncommitted changes (must be clean)
+
+## Worktree Lifecycle
+
+### 1. Creation
+
+**Prerequisites:**
+- Leader repository must be clean (`git status` empty)
+- Sufficient disk space for worktree directory
+
+**Creation flow:**
+```
+team-runner.ts (workspaceMode: "worktree")
+  → prepareTaskWorkspace(manifest, task)
+    → assertCleanLeader(repoRoot)
+    → git worktree add <path> <branch>
+    → linkNodeModulesIfPresent(repoRoot, worktreePath)
+    → return { cwd: worktreePath, worktreePath, branch }
+```
+
+**Naming convention:**
+- Branch: `crew/<sanitized-runId>-<sanitized-taskId>`
+- Path: `.worktrees/<runId>/<taskId>/`
+- Deterministic from run/task IDs — no user-controlled fragments
+
+**Example:**
+```
+Run: team_20260514092752_218fe358085d7115
+Task: 01_explore
+
+Branch: crew/team-20260514092752-218fe358085d7115/01-explore
+Path: .worktrees/team-20260514092752-218fe358085d7115/01-explore/
+```
+
+### 2. Reuse
+
+If a worktree with the same branch already exists, it is reused instead of recreated:
+
+```typescript
+// Check if worktree already exists
+const existing = git(cwd, ["worktree", "list", "--porcelain"]);
+if (existing.includes(branch)) {
+  return { reused: true, worktreePath: parsePath(existing) };
+}
+```
+
+Reuse is safe when the worktree's base branch hasn't diverged (checked via `branch-freshness.ts`).
+
+### 3. Work in worktree
+
+Each task works in its own worktree directory:
+- `cwd` = worktree path
+- `git status` shows only that task's changes
+- Changes are isolated from other worktrees and the leader
+
+### 4. Cleanup
+
+**On task completion:**
+1. Check dirty state (uncommitted changes)
+2. If dirty and not forced → preserve (report to operator)
+3. If clean → `git worktree remove <path>`
+
+**On force cleanup:**
+- `git worktree remove <path> --force`
+- Removes even if there are changes (but logs a warning)
+
+**Safety rules:**
+- Never force-remove dirty worktrees by default
+- Always check `git status` before cleanup
+- Report worktree paths in events/artifacts for recovery
+
+## Stale Worktree Detection
+
+Worktrees can become stale when:
+- The base branch has moved
+- The run was abandoned mid-task
+- Node modules are out of date
+
+**Detection approach:**
+```typescript
+// Check if base branch has diverged
+function isStaleWorktree(worktreePath: string, baseBranch: string): boolean {
+  const current = git(worktreePath, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const ahead = git(worktreePath, ["rev-list", "--count", `${baseBranch}..HEAD`]);
+  const behind = git(worktreePath, ["rev-list", "--count", `HEAD..${baseBranch}`]);
+  return Number(ahead) > 10 || Number(behind) > 0;
+}
+```
+
+**Cleanup stale worktrees:**
+```bash
+# List all worktrees
+git worktree list
+
+# Remove stale worktree
+git worktree remove .worktrees/stale-task --force
+```
+
+## Merge Conflict Strategy
+
+When worktrees complete and changes need to be merged back:
+
+1. **One owner per file/symbol**: Assign each file to exactly one worktree. No two worktrees modify the same file.
+2. **Merge order**: If multiple worktrees produce changes, merge in reverse creation order.
+3. **Conflict detection**: `git status --porcelain` shows conflicts.
+4. **Conflict resolution**: Resolve in the leader branch, then continue.
+
+**If conflicts occur:**
+```bash
+git merge --no-commit <branch>
+# Resolve conflicts manually
+git add <resolved-files>
+git commit -m "Merge branch and resolve conflicts"
+```
+
+## Branch Freshness Check
+
+Before reusing a worktree, verify the base branch hasn't diverged:
+
+```typescript
+function checkBranchFreshness(worktreePath: string, baseBranch: string): {
+  fresh: boolean;
+  ahead: number;
+  behind: number;
+} {
+  const status = git(worktreePath, ["status", "--porcelain"]);
+  if (status.trim()) return { fresh: false, ahead: 0, behind: 0 }; // dirty
+
+  const current = git(worktreePath, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+  if (current !== baseBranch) return { fresh: false, ahead: 0, behind: 0 }; // different branch
+
+  // Check divergence
+  const ahead = Number(git(worktreePath, ["rev-list", "--count", `${baseBranch}..HEAD`]));
+  const behind = Number(git(worktreePath, ["rev-list", "--count", `HEAD..${baseBranch}`]));
+  return { fresh: ahead === 0 && behind === 0, ahead, behind };
+}
+```
+
+## Crash Recovery
+
+If a task crashes mid-worktree:
+1. Find orphaned worktrees: `git worktree list`
+2. Check for abandoned runs in `.crew/state/runs/`
+3. If run is failed/cancelled and worktree is dirty → report to operator
+4. If run is completed → safe to clean up
 
 ## Anti-patterns
 
-- Parallel editing the same file in multiple worktrees without a merge plan.
-- Force-removing dirty worktrees by default.
-- Reusing stale worktrees after the base branch has moved without freshness checks.
-- Storing worktrees outside the intended contained workspace root.
+- **Parallel editing same file**: Assign one owner per file. Use the task ID in branch names to track ownership.
+- **Force-removing dirty worktrees**: Always report dirty state to operator before cleanup.
+- **Reusing stale worktrees**: Check `branch-freshness.ts` before reuse. If base branch moved, recreate instead.
+- **Storing worktrees outside workspace root**: All worktrees must be under `<repo-root>/.worktrees/`. Never store outside.
+- **Worktree name collision**: Use deterministic naming from run/task IDs, not user input.
+
+---
+
+## Source patterns
+
+- `src/worktree/worktree-manager.ts` — prepareTaskWorkspace, assertCleanLeader, linkNodeModulesIfPresent, sanitizeBranchPart
+- `src/worktree/cleanup.ts` — worktree cleanup logic, dirty state detection
+- `src/worktree/branch-freshness.ts` — branch divergence detection
+- `src/runtime/team-runner.ts` — workspaceMode handling, worktree passed to task
+- `src/runtime/task-runner.ts` — worktreePath in task context
+
+---
 
 ## Verification
 
 ```bash
 cd pi-crew
+
+# List all worktrees
+git worktree list
+
+# Check leader repo is clean
+git status --short
+
+# Verify worktree creation
+node --experimental-strip-types -e "
+import { prepareTaskWorkspace } from './src/worktree/worktree-manager.ts';
+// Requires clean repo and workspaceMode='worktree'
+"
+
+# TypeScript
 npx tsc --noEmit
-node --experimental-strip-types --test test/integration/worktree-mode.test.ts test/unit/run-index.test.ts
+
+# Tests
+node --experimental-strip-types --test test/unit/worktree-manager.test.ts test/integration/worktree-mode.test.ts
 npm test
-```
+```