pi-crew 0.9.51 → 0.9.53

package/docs/issue-29-analysis.md

@@ -1,189 +0,0 @@
-# Issue #29 Analysis: Hardcoded `.crew/state/runs` Path Crashes pi
-
-> **Status**: ANALYZED — no code changes applied (per user request).
-> **Reporter**: sethmorton (external, opened 2026-06-05)
-> **Affects**: pi-crew 0.6.0 / 0.6.1 (issue present in v0.6.1 too — not fixed in any post-v0.6.1 commit as of `e95e055`).
-> **Severity**: **CRITICAL** — full-harness uncaughtException, can crash pi.
-
----
-
-## 1. Reporter's Claims — Verification Matrix
-
-| Claim | Verified? | Evidence |
-|---|---|---|
-| `waitForRun()` hardcodes `.crew/state/runs/<runId>` at `run-tracker.ts:82` | ✅ YES | `src/runtime/run-tracker.ts:82` — `const runDir = path.join(cwd, ".crew", "state", "runs", runId);` |
-| `projectCrewRoot()` correctly resolves to `.pi/teams/` for `.pi/`-only projects | ✅ YES | `src/utils/paths.ts:88-97` |
-| The throw escapes as an unhandled promise rejection | ✅ PARTIAL | Both direct call sites (`team-tool.ts:817`, `team-tool/run.ts:211,344`) wrap in `try/catch`. **However**, the issue is real when `waitForRun` is called indirectly through `subagent-manager.ts`. |
-| `subagent-manager.ts:250` re-throws via `record.promise` IIFE | ⚠️ LINE-DRIFT | Issue says `~line 250` — in current code (commit `e95e055`), `record.promise` IIFE starts at line 258 and the `throw error;` is at line 281. The mechanism is correct; line numbers drifted from prior code. |
-
-## 2. Root Cause Analysis
-
-### Why it crashes (in `.pi/`-only projects)
-
-`projectCrewRoot(cwd)` (in `src/utils/paths.ts:88-97`) returns:
-
-```
-1. .crew/  (if exists)
-2. .pi/teams/  (if .pi/ exists and .crew/ doesn't)
-3. .crew/  (default, would be created by ensureCrewDirectory)
-```
-
-In a `.pi/`-based project **without** `.crew/`, run state lives at:
-```
-.pi/teams/state/runs/<runId>/
-```
-
-But `waitForRun()` (line 82) hardcodes:
-```
-.crew/state/runs/<runId>/
-```
-
-The early-exit check `fs.existsSync(runDir)` returns `false`, throwing:
-```
-Error: Run <runId> not found. No run directory at <cwd>/.crew/state/runs/<runId>
-```
-
-### Why this becomes a `uncaughtException`
-
-The throw in `waitForRun` propagates differently depending on caller:
-
-| Caller | Wrapped in try/catch? | Result |
-|---|---|---|
-| `team-tool.ts:817` (wait action) | ✅ YES | Returns error to user — safe |
-| `team-tool/run.ts:211` (async.run) | ✅ YES | Returns error to user — safe |
-| `team-tool/run.ts:344` (foreground) | ✅ YES | Returns error to user — safe |
-| **`subagent-manager.ts:270` (pollRunToTerminal)** | ⚠️ **NO** | `record.promise` rejects → line 281 `throw error` re-throws → if no caller awaits → **unhandled rejection** |
-
-The `subagent-manager.ts` path is the actual crash site. Direct `waitForRun` calls in `team-tool.ts` are safe.
-
-### Why the run "exists" in `.pi/teams/...`
-
-The background worker process (`background-runner.ts`) correctly **reads/writes** to the right path **once it uses `projectCrewRoot()`** — but it does NOT. The same hardcoding is present in `background-runner.ts:139, 172`. So the **background worker itself is writing to `.crew/state/runs/...` (wrong path)**, while the **manifest claims it lives at `.pi/teams/state/runs/...`** (correct path).
-
-Wait — let me re-verify this. The manifest is created by which process?
-
-Actually, the **run manifest is created at the orchestrator** (using `projectCrewRoot`), and the **background worker reads/writes log/exit-code files using the same wrong path**. The manifest's `stateRoot` field is correct (`.pi/teams/...`), but the background worker writes its log to `<cwd>/.crew/state/runs/.../background.log`, which is the wrong path.
-
-Result: the manifest correctly points to `.pi/teams/...` but the background worker logs/exit-codes go to `.crew/.../background.log`. The manifest loader (`loadRunManifestById` → `scopeBaseRoot` → `projectCrewRoot`) reads from the correct path. So if the manifest is created and persists, polling SHOULD work. The early-exit `fs.existsSync` check fires only on the very first poll iteration before any manifest has been written.
-
-## 3. Affected Sites — Complete Inventory
-
-Hardcoded `.crew/state/runs/...` paths that ignore `projectCrewRoot()`:
-
-| File | Line | Code | Used for |
-|---|---|---|---|
-| `src/runtime/run-tracker.ts` | 82 | `path.join(cwd, ".crew", "state", "runs", runId)` | **CRASH SITE**: `waitForRun()` early-exit |
-| `src/runtime/background-runner.ts` | 139 | `path.join(_cwd, ".crew/state/runs", _runId, "background.log")` | Background worker log redirect |
-| `src/runtime/background-runner.ts` | 172 | `path.join(cwd, ".crew", "state", "runs", runId, "exit-code.txt")` | Exit code persistence |
-| `src/runtime/skill-effectiveness.ts` | 115 | `join(process.cwd(), ".crew/state/runs/${runId}/skill-metrics.jsonl")` | Skill metrics storage |
-| `src/runtime/skill-effectiveness.ts` | 125 | `join(process.cwd(), ".crew/state/runs/${runId}/skill-activations.jsonl")` | Skill activation storage |
-| `src/runtime/checkpoint.ts` | 166 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `saveCheckpoint` |
-| `src/runtime/checkpoint.ts` | 177 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `loadCheckpoint` |
-| `src/runtime/checkpoint.ts` | 188 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `clearCheckpoint` |
-| `src/runtime/checkpoint.ts` | 199 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `hasCheckpoint` |
-| `src/runtime/checkpoint.ts` | 209 | `path.join(process.cwd(), ".crew/state/runs", runId)` | `listCheckpoints` |
-| `src/state/decision-ledger.ts` | 29 | `stateRoot ?? \`.crew/state/runs/${runId}\`` | `getLedgerPath` fallback (always hit when called without `stateRoot`) |
-
-**11 sites across 5 files** confirmed affected.
-
-### Already correct (for reference)
-
-| File | Line | Why correct |
-|---|---|---|
-| `src/state/crew-init.ts` | 209 | `safeJoin(crewRoot, "state", "runs")` — uses `crewRoot` parameter |
-| `src/extension/team-tool.ts` | 1210 | `path.join(projectCrewRoot(ctx.cwd), "state", "runs", params.runId)` ✓ |
-| `src/extension/team-onboard.ts` | 28 | `path.join(crewRoot, "state", "runs")` — uses parameter |
-| `src/runtime/stale-reconciler.ts` | 389 | Inside `tmpDir` workspace scan — these are pi-crew's own zombie workspaces, not user `.pi/` projects, so this is acceptable (but inconsistent) |
-
-## 4. Why the Bug Survives (it should have been caught)
-
-- ✅ `loadRunManifestById` and `loadRunManifestByIdAsync` in `state-store.ts` correctly use `projectCrewRoot()` via `scopeBaseRoot` → `useProjectState`.
-- ❌ `waitForRun()` and the 10 other sites above bypass the resolver and hardcode the path.
-- The hardcoded path is **inconsistent** with the resolver — clearly a copy-paste/regression.
-- The issue is **only triggered in `.pi/`-only projects** (no `.crew/`). Standard `.crew/` projects (the original pi-crew use case) never hit it.
-
-## 5. Recommended Fix (NOT APPLIED per user request)
-
-### Phase 1 — Use the resolver everywhere
-
-Replace each hardcoded path with:
-
-```ts
-import { projectCrewRoot } from "../utils/paths.ts";
-// ...
-const stateRoot = path.join(projectCrewRoot(cwd), "state", "runs", runId);
-```
-
-For sites that take `process.cwd()`, switch to taking a `cwd` parameter (callers pass the real cwd). This is a small refactor for `skill-effectiveness.ts` and `checkpoint.ts` since their current API uses `process.cwd()`.
-
-### Phase 2 — Defense in depth (the reporter's second suggestion)
-
-The reporter's point about `subagent-manager.ts` is also valid: **a single run failure should never crash the harness**. The current pattern at line 281 `throw error; // H4: Propagate rejection` deliberately rejects the promise, but if no one awaits it, it becomes unhandled.
-
-Two options:
-
-**A) Add a safety net in `subagent-manager.ts` (recommended)**:
-
-```ts
-private start(record: SubagentRecord, ...) {
-  // ...
-  record.promise = (async () => { ... })();
-  // Defense in depth: a subagent failure should never crash pi.
-  // Attach a no-op catch so that even if no caller awaits, the rejection
-  // doesn't propagate to unhandledRejection → uncaughtException.
-  record.promise.catch((error) => {
-    logInternalError("subagent-manager.start.unhandled", error, `id=${record.id}`);
-  });
-}
-```
-
-This protects the harness against **any** future rejection path, not just the one fixed in Phase 1.
-
-**B) Remove the `throw error;` at line 281** — the record is already marked `error` status, the caller can read it. This is a deeper change to the API contract.
-
-Option (A) is the smaller, safer change.
-
-## 6. Test Coverage
-
-Tests exist for `checkpoint` (`checkpoint.test.ts`, `checkpoint-cov.test.ts`) and `skill-effectiveness` (`skill-effectiveness.test.ts`) but they likely use a `.crew/`-based temp project, so they wouldn't catch this bug. A regression test should:
-
-1. Create a temp project with `.pi/` (no `.crew/`)
-2. Call each affected function (`waitForRun`, `saveCheckpoint`, `getSkillMetricsPath`, etc.)
-3. Assert the result path is `.pi/teams/...` (not `.crew/...`)
-
-For the `subagent-manager.ts` defense-in-depth: spawn a subagent whose `runner` rejects, assert pi does not exit and the record is marked `error`.
-
-## 7. Impact Assessment
-
-- **Blast radius**: All pi-crew users with `.pi/`-only projects.
-- **Trigger frequency**: Low — requires the background worker to fail/die AND `waitForRun` to be called indirectly via `subagent-manager.ts`. The `team-tool` direct paths are safe.
-- **Severity**: CRITICAL — full-harness crash with misleading "Run not found" error pointing at a path that, by design, should never exist.
-
-## 8. Recommended PR Description (draft)
-
-> **Title**: fix(issue #29): use projectCrewRoot() for run-state paths in all 11 affected sites
->
-> **Body**:
->
-> The `.pi/`-based project layout (`.pi/teams/`) is not handled by the 11 hardcoded `.crew/state/runs/...` sites listed in the analysis. The most severe site is `waitForRun()` in `src/runtime/run-tracker.ts:82`, which throws on a non-existent path and (via `subagent-manager.ts:281`) can escape as an unhandled rejection that crashes pi.
->
-> Fix:
-> 1. Replace all 11 hardcoded paths with `path.join(projectCrewRoot(cwd), "state", "runs", runId)`.
-> 2. For sites that use `process.cwd()` (`skill-effectiveness.ts`, `checkpoint.ts`), switch to taking a `cwd` parameter.
-> 3. Add `record.promise.catch(...)` in `subagent-manager.ts:start()` as defense in depth — a subagent failure should never crash the harness.
-> 4. Add regression tests using a `.pi/`-only temp project.
->
-> Closes #29.
-
----
-
-## Status
-
-- ✅ Issue reproduced in code (all 11 sites verified)
-- ✅ Root cause identified
-- ✅ Fix plan drafted
-- ❌ **Code changes NOT applied** (per user request: "nothing has been changed yet")
-- ❌ Tests NOT added
-- ❌ v0.6.2 NOT released
-
-Ready to apply when requested by the user.

package/docs/live-mailbox-runtime.md

@@ -1,36 +0,0 @@
-# Live Mailbox Runtime Direction
-
-`pi-crew` currently uses workflow child-process orchestration: a run materializes tasks, executes them through the scheduler, writes artifacts/events, and optionally launches child Pi workers.
-
-A full live mailbox runtime is intentionally out of scope for the current stable surface. Current foundational mailbox files are intentionally simple and local:
-
-```text
-{stateRoot}/mailbox/inbox.jsonl
-{stateRoot}/mailbox/outbox.jsonl
-{stateRoot}/mailbox/delivery.json
-{stateRoot}/mailbox/tasks/{taskId}/inbox.jsonl
-{stateRoot}/mailbox/tasks/{taskId}/outbox.jsonl
-```
-
-They are exposed through safe API operations (`read-mailbox`, `send-message`, `ack-message`, `read-delivery`, `validate-mailbox`) but do not yet imply always-on long-lived workers. If a full runtime is added later, it should build on the foundations already present:
-
-- `src/state/contracts.ts` for status/event contracts
-- `src/state/task-claims.ts` for claim/lease safety
-- `src/runtime/worker-heartbeat.ts` for liveness
-- `src/state/locks.ts` for run-level mutation safety
-- `action: "api"` for safe interop boundaries
-
-## Proposed phases
-
-1. **Read-only interop** — already started with `api` operations.
-2. **Heartbeat writers** — allow workers to update heartbeat/progress safely.
-3. **Claim-safe task lifecycle** — expose claim/release/transition operations with tokens.
-4. **Mailbox** — add worker inbox/leader inbox files and delivery state.
-5. **Live workers** — only after the above contracts are stable.
-
-## Non-goals for now
-
-- No always-on background worker pool.
-- No automatic destructive cleanup of dirty worktrees.
-- No recursive team spawning by workers.
-- No mailbox mutation without locks and schema validation.

package/docs/migration/atomic-write-v2-migration.md

@@ -1,299 +0,0 @@
-# atomic-write-v2 migration plan
-
-> **Note:** `atomic-write-v2.ts` was consolidated into `atomic-write.ts` as of v0.9.42. This document is preserved as historical record — the migration was completed with v1 winning on simplicity + symlink-safety + link+unlink atomicity. The v2 class was never adopted; no v2 API surface ships with pi-crew.
-
-> Status: **PROPOSED** — decision RECOMMEND MIGRATE (staged, feature-flagged).
-> Source: performance review `docs/perf/performance-review-2026-07.md` (findings F3–F6).
-> Scope: replace the standalone-function module `src/state/atomic-write.ts`
-> with the class-based `src/state/atomic-write-v2.ts` (`AtomicWriter`) over
-> three staged phases behind a feature flag.
-
-## Table of contents
-
-- [1. Why migrate](#1-why-migrate)
-- [2. API differences](#2-api-differences)
-- [3. Migration phases](#3-migration-phases)
-  - [Phase 1 — dual-write (feature flag)](#phase-1--dual-write-feature-flag)
-  - [Phase 2 — switch default](#phase-2--switch-default)
-  - [Phase 3 — deprecate v1](#phase-3--deprecate-v1)
-- [4. Risks and mitigations](#4-risks-and-mitigations)
-- [5. Effort estimate](#5-effort-estimate)
-- [6. Decision](#6-decision)
-- [7. Appendix — call-site inventory](#7-appendix--call-site-inventory)
-
-## 1. Why migrate
-
-The performance review (F3, F4, F6) traced a write-path regression to commit
-`13f4490`. That commit hardened `atomicWriteFile` against a CI-flake stale-read
-race (the `mailbox-replay` intermittent failure) by adding **two** `fsync`
-calls per synchronous write:
-
-1. **Data fsync** — `fs.fsyncSync(fd)` on the temp file before rename
-   (`atomic-write.ts` ~line 287, in the `atomicWriteFile` write body). This
-   forces the written bytes out of the page cache to disk so a subsequent
-   `readFileSync` after the rename always sees the new content.
-2. **Directory fsync** — `fs.fsyncSync(dirFd)` on the parent directory after
-   the rename (`atomic-write.ts` ~lines 307–309, POSIX-only, skipped on
-   Windows). This makes the directory-entry update (the rename) durable so a
-   subsequent `open()` cannot race and observe `ENOENT` or stale content on a
-   high-I/O CI runner.
-
-The dir-fsync is the expensive half. `persistSingleTaskUpdate` calls the write
-path ~5 times per task; at 2 fsync per call that is roughly **+10 fsync per
-task**, and directory fsync is especially costly on Windows and on
-network/overlay filesystems. The review also had to bump the CI timeout
-600s → 900s (commit `9bbeb45`) partly to absorb this cost.
-
-`atomic-write-v2.ts` (the `AtomicWriter` class) keeps only the **data fsync**,
-and even that is **best-effort** — it is wrapped in a `try/catch` that swallows
-the error (`atomic-write-v2.ts` ~line 30 in `writeSync`, and `fd.sync()` in
-`writeAsync`). It performs **no directory fsync at all**.
-
-### Quantified difference
-
-| Cost per write         | atomic-write.ts (v1)                  | atomic-write-v2.ts (v2)         |
-| ---------------------- | ------------------------------------- | ------------------------------- |
-| Data fsync             | 1 (mandatory, throws on failure)      | 1 (best-effort, swallowed)      |
-| Directory fsync        | 1 (POSIX only)                        | 0                               |
-| `isSymlinkSafePath`    | 2 full ancestor walks (pre + pre-rename) | 0                            |
-| `lstat` syscalls       | ~10+ per level × 2 for a deep path    | 0                               |
-| Rename mechanism       | `link()` + `unlink()` (+ retry/jitter) | `rename()` (single syscall)    |
-
-The headline is roughly **2× fewer fsync operations per call** (drop the dir
-fsync, keep data fsync), plus the elimination of two full ancestor-walk
-symlink scans (F5) and the `link()`+`unlink()` pair in favor of a single
-`rename()`. On a deep state-store path (`.crew/state/runs/{runId}/…`) the v1
-path issues ~20+ `lstat` calls per write for symlink validation alone; v2
-issues none. The net expected win on the hot `persistSingleTaskUpdate` path is
-approximately halving the per-call durability cost, with a larger relative win
-on syscall count.
-
-The trade-off is explicit: **v2 loses the dir-fsync durability guarantee.** On
-journaled Linux filesystems (ext4 with `data=ordered`, xfs) the rename is still
-crash-atomic, but a power loss in the sub-millisecond window between write and
-directory-entry flush can leave the *old* content visible after reboot. On
-tmpfs this window is effectively the whole lifetime of the entry (no
-durability at all). This is the guarantee the `13f4490` commit was added to
-provide, so dropping it must be a conscious, documented decision (see
-[risks](#4-risks-and-mitigations)).
-
-## 2. API differences
-
-The two modules are shaped very differently, so migration is not a
-drop-in symbol rename — callers change from free functions to a constructed
-instance.
-
-### v1 — `atomic-write.ts` (module of standalone functions)
-
-- `atomicWriteFile(filePath, content, expectedHash?)`
-- `atomicWriteFileAsync(filePath, content)`
-- `atomicWriteJson(filePath, value)`
-- `atomicWriteJsonAsync(filePath, value)`
-- `atomicWriteJsonCoalesced(filePath, value, coalesceMs?)` — 50 ms coalescing buffer
-- `flushPendingAtomicWrites()` — flush the coalesce buffer
-- `isSymlinkSafePath(filePath)` — exported symlink-safety guard
-- `renameWithRetry(...)` / `renameWithRetryAsync(...)` — exported rename helpers with jitter
-- `readJsonFile(filePath)` — tolerant JSON reader
-
-Behavioral characteristics:
-
-- **Symlink safety**: explicit `isSymlinkSafePath` check both **before open**
-  and **again immediately before rename** (TOCTOU re-check), plus a
-  post-rename `lstat` guard on failure.
-- **Rename**: `link()` + `unlink()` (`renameWithLinkSync` /
-  `renameWithLinkAsync`) so the destination symlink is *not* followed; Windows
-  falls back to `renameSync`/`MoveFileEx`. Retries with exponential backoff and
-  ±20% jitter.
-- **Durability**: mandatory data fsync (throws on failure) + POSIX directory
-  fsync.
-- **Tmp naming**: `${filePath}.${randomUUID()}.tmp`.
-- **Coalescing**: a per-path buffer with generation counters, retry/backoff,
-  and process `exit`/`SIGTERM`/`SIGINT` auto-flush hooks.
-- **Optional worker offload**: `atomicWriteFileAsync` can dispatch to a worker
-  thread when `PI_CREW_WORKER_ATOMIC_WRITER=1`.
-
-### v2 — `atomic-write-v2.ts` (`AtomicWriter` class)
-
-- `new AtomicWriter(baseDir)` — constructed with a base directory
-- `writeSync(targetPath, content)`
-- `writeAsync(targetPath, content)`
-- `writeJsonSync(targetPath, value)`
-- `writeJsonAsync(targetPath, value)`
-- private `.gitignore`-on-first-use per directory (writes `*\n` the first time
-  a directory is touched)
-
-Behavioral characteristics:
-
-- **Symlink safety**: **none** — no `isSymlinkSafePath`, no pre/post checks.
-- **Rename**: plain `rename()` (POSIX-atomic but **symlink-following**), single
-  syscall, no retry/jitter loop.
-- **Durability**: best-effort data fsync (swallowed), **no directory fsync**.
-- **Tmp naming**: `${targetPath}.${randomUUID()}.tmp` (same scheme as v1).
-- **Coalescing**: none (no buffer, no flush hooks).
-- **Reader**: none (no `readJsonFile` equivalent).
-
-### Feature-gap summary (what v2 does NOT have yet)
-
-| Capability                         | v1  | v2  | Notes                                              |
-| ---------------------------------- | --- | --- | -------------------------------------------------- |
-| Symlink-safe rename                | ✅   | ❌   | v2 uses `rename()` which follows symlinks          |
-| `isSymlinkSafePath` export         | ✅   | ❌   | consumed elsewhere — must stay available           |
-| Coalesced writes + flush hooks     | ✅   | ❌   | required by `saveRunTasksCoalesced` path (F4)      |
-| `readJsonFile`                     | ✅   | ❌   | tolerant reader used across state-store            |
-| Retry/backoff on contended rename  | ✅   | ❌   | v2 throws on first `rename()` failure              |
-| Windows short/long-name handling   | ✅   | ❌   | v1 has explicit `MoveFileEx` fallback              |
-| Directory fsync                    | ✅   | ❌   | the durability guarantee being intentionally dropped |
-| `.gitignore` on first use          | ❌   | ✅   | v2 convenience; v1 leaves this to callers          |
-
-**Implication:** a straight swap is not viable until v2 grows (or the
-dispatcher re-provides) the coalescing buffer, the tolerant reader, the retry
-loop, and an opt-in symlink guard. The phased plan below keeps v1 as the source
-of those capabilities during transition rather than porting them all up front.
-
-## 3. Migration phases
-
-### Phase 1 — dual-write (feature flag)
-
-Estimated ~1–2 days.
-
-- Introduce an environment feature flag `PI_CREW_ATOMIC_WRITER` with values
-  `v1` (default) and `v2`.
-- Add a thin adapter module `src/state/atomic-write-dispatcher.ts` that exposes
-  the v1 free-function surface (`atomicWriteFile`, `atomicWriteJson`, and their
-  async variants) and routes each call to either the v1 functions or a shared
-  `AtomicWriter` instance based on the flag. Capabilities v2 lacks
-  (`atomicWriteJsonCoalesced`, `flushPendingAtomicWrites`, `isSymlinkSafePath`,
-  `readJsonFile`) continue to delegate to v1 unconditionally in this phase.
-- Keep `atomic-write.ts` as the default; nothing changes for users who do not
-  set the flag.
-- Add a benchmark test that writes N files through both paths under **tmpfs**
-  and **ext4** and asserts the fsync-count / wall-clock delta matches the
-  ~2× prediction. Land it under `test/bench/` (guarded so it does not run in
-  the default `test:unit` gate).
-
-Exit criteria: flag flips implementation with zero behavior change for default
-users; benchmark confirms the predicted delta.
-
-### Phase 2 — switch default
-
-Estimated ~1–2 days.
-
-- Flip the dispatcher default to `v2`; users can opt back to the old path with
-  `PI_CREW_ATOMIC_WRITER=v1`.
-- Route direct callers of `atomicWriteFile` / `atomicWriteJson` (in
-  `extension/team-tool.ts`, `state-store.ts`, and any other direct importers)
-  through the dispatcher rather than importing `atomic-write.ts` directly.
-- Before flipping, back-fill v2 (or the dispatcher wrapper around v2) with the
-  currently-missing durability/safety features that production relies on:
-  retry-on-contended-rename, an **opt-in** symlink guard for
-  `userPiRoot()`-adjacent writes, and either the coalescing buffer or continued
-  delegation to v1 for the coalesced path.
-- Monitor for one full release cycle. Watch for stale-read CI flakes (the exact
-  failure `13f4490` fixed) — if they resurface, the dir-fsync drop is the prime
-  suspect and the flag provides an instant rollback.
-
-Exit criteria: one clean release cycle on the v2 default with no stale-read or
-symlink regressions reported.
-
-### Phase 3 — deprecate v1
-
-Estimated ~1 day.
-
-- Remove `atomic-write.ts` and the `v1` flag branch (keep any still-needed
-  utilities — notably the symlink-safe `link()`+`unlink()` helper and
-  `isSymlinkSafePath` — either in the renamed module or a small
-  `symlink-safety.ts`).
-- Rename `atomic-write-v2.ts` → `atomic-write.ts` and update imports.
-- Add a `CHANGELOG.md` entry under a **minor** version bump documenting the
-  durability trade-off (no directory fsync by default) and the
-  `PI_CREW_ATOMIC_WRITER` flag removal.
-
-Exit criteria: single implementation, no flag, green CI, CHANGELOG documents
-the durability change.
-
-## 4. Risks and mitigations
-
-### Drop of strict symlink safety (security)
-
-v2 performs **no** `isSymlinkSafePath` check and uses `rename()`, which follows
-a symlink at the destination. An attacker who can plant a symlink inside
-`userPiRoot()` (or an ancestor of a write target) could redirect a write to an
-arbitrary path.
-
-Mitigations:
-
-1. v2 callers must pre-validate every target path via the `paths.ts` helpers so
-   writes are confined to the user's own pi-crew state tree.
-2. Keep the v1 `link()`+`unlink()` rename helper and `isSymlinkSafePath` as
-   reusable utilities even after the module rename, and offer them as an opt-in
-   "safe rename" mode in the dispatcher for `userPiRoot()`-adjacent writes.
-3. Add a CI test that plants a symlink inside the `.pi/agent/pi-crew/` tree and
-   asserts the writer refuses (or does not follow) it.
-
-### Lockfile / tmp collision risk
-
-Both implementations name temp files `${target}.${randomUUID()}.tmp`. UUIDv4
-collision probability is astronomically low (documented here for completeness).
-The larger concern is the inode-scan cost of many `.tmp` siblings in a large
-directory. Recommend writing tmp files into a per-process subdir
-(`<baseDir>/.tmp/<pid>/`) to bound directory size and simplify crash cleanup.
-
-### Crash-durability regression
-
-v2's missing directory fsync means a power loss in the window between the data
-write and the directory-entry flush can leave the **old** content visible after
-reboot. This is rare on journaled filesystems (ext4/xfs) and common on tmpfs.
-
-Mitigations:
-
-1. Document the trade-off in the v2 module docblock and in `CHANGELOG.md`.
-2. Keep the flag so at-risk deployments (non-journaled FS, tmpfs-backed state)
-   can pin `v1`.
-3. Optionally expose a per-call `durable: true` option in the dispatcher that
-   re-enables the directory fsync for the small set of writes that truly need
-   it (e.g. terminal manifest writes), so the common path stays fast while the
-   critical path stays durable.
-
-## 5. Effort estimate
-
-**Size: M (3–5 days.)**
-
-| Work item                                  | Estimate |
-| ------------------------------------------ | -------- |
-| Phase 1 — flag + dispatcher + benchmark    | ~1–2 days |
-| Phase 2 — feature back-fill + switch + soak | ~1–2 days |
-| Phase 3 — deprecate + rename + CHANGELOG   | ~1 day    |
-| Benchmark harness (tmpfs + ext4)           | ~0.5 day  |
-| Docs / review pass                         | ~0.5 day  |
-
-## 6. Decision
-
-**RECOMMEND MIGRATE** — staged, feature-flagged.
-
-Justification:
-
-- The write path is hot: `persistSingleTaskUpdate` calls it ~5×/task and the
-  state-store fires on the same 1 Hz idle / 6 Hz active cadence as
-  `loadConfig`. Halving the per-call durability cost (drop dir fsync, keep data
-  fsync) plus eliminating the double ancestor-walk symlink scan is a meaningful
-  and broadly-applied win.
-- The durability risk from dropping the directory fsync is bounded: it only
-  matters on non-journaled/tmpfs filesystems and only within the sub-millisecond
-  on-disk write window. The `PI_CREW_ATOMIC_WRITER=v1` fallback lets at-risk
-  setups opt out.
-- The symlink-safety regression is the sharpest edge and is mitigated by
-  `paths.ts` pre-validation, an opt-in safe-rename mode, and a CI symlink-plant
-  test — not by accepting v2 as-is.
-
-Because the plan is staged behind a flag with an instant rollback, the blast
-radius at each step is small and the exact CI flake that `13f4490` fixed remains
-observable (and reversible) during the Phase 2 soak.
-
-## 7. Appendix — call-site inventory
-
-Before Phase 2, enumerate the direct importers to route through the dispatcher.
-As of this plan, `atomic-write-v2.ts` has **0 importers** (confirmed by
-`grep -rn "atomic-write-v2" src/`). The v1 surface is consumed by
-`state-store.ts`, `extension/team-tool.ts`, and the coalesced/reader paths;
-run `grep -rn "atomic-write\b" src/` at the start of Phase 2 to produce the
-authoritative list, since call sites shift between now and then.