pi-crew 0.9.17 → 0.9.18

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [v0.9.18] — perf fix bundle-mode spawn + config cache (2026-07-02)
+
+Five commits addressing items from the v0.9.17 performance review (`docs/perf/performance-review-2026-07.md`):
+
+### Highlights
+
+- **CRITICAL — fix bundle-mode background runner spawn.** `spawnBackgroundTeamRun` in `src/runtime/async-runner.ts:226` was computing the `background-runner.ts` path via `import.meta.url-relative` resolution. The path landed correctly in source (strip-types loader) but BROKE in the bundle (default v0.9.17+): esbuild's `__esm` helper does not preserve per-module `import.meta.url`, so the path resolved to `<pi-crew>/background-runner.ts` (missing `src/runtime/`). Spawned runners then ENOENTed at ~4s into every team run. Fixed with `packageRoot()` from `utils/paths.ts` — mirrors the same pattern as the v0.9.17 fix in `pi-args.ts:10` (commit `0dd93e0`). Verified live: 3 E2E team runs after the fix (test-coalesce-static, fast-fix, research) all spawned the background runner cleanly.
+- **F4 mitigation — wire `saveRunTasksCoalesced` into the checkpoint path.** The 50ms-debounce coalescer in `state-store.ts:428` had been dormant (0 callers). Now called from `persistSingleTaskUpdate` (called ~5× per task from `task-runner.ts:233, 424, 538, 617, 1347`). Two safety guards: `flushPendingAtomicWrites()` at the top of the mtime-CAS retry loop (defeats the stale-read window under concurrent coalesced writers) and the mtime CAS itself still guards against concurrent non-coalesced writers. Trade-off: checkpoint writes are now best-effort within a 50ms window — terminal writes still use full fsync via `saveRunTasks`.
+- **F16 quick win — 2s TTL+mtime cache for `loadConfig`.** `loadConfig` had 78 callers (top: `register.ts` 11, `registration/ui.ts` 6, `team-tool.ts` 5) and was called 1 Hz idle / 6 Hz active with zero cache. Each call reads up to 4 files (legacy, user, `.crew/config.json`, `.pi/pi-crew.json`), parses JSON, runs full TypeBox `Value.Check` validation, and merges. New cache follows the same pattern as `manifest-cache.ts`. Cache key is a deterministic JSON encoding of `(filePath, legacyPath, projectPath, projectPiCrewJsonPath, cwd)`. On hit, return cached value without parsing; on miss or mtime change, re-parse. New exports for tests/ops: `__test__setConfigCacheTtlMs`, `__test__getConfigCacheTtlMs`, `__test__getConfigCacheEntry`, `__test__configCacheSize`, `invalidateConfigCache`, `flushConfigCache`. Caveat documented: caches for 2s even if the user just edited their config in a separate process — acceptable for the perf win.
+- **D — documented atomic-write-v2 migration plan.** New `docs/migration/atomic-write-v2-migration.md` (297 lines) covers why migrate (F3, F4, F6: drop the dir-fsync cost added by 13f4490), API differences, 3-phase migration plan (dual-write behind feature flag → switch default → deprecate v1), risks + mitigations, effort estimate (M = 3-5 days), and a MIGRATE decision. Existing `atomic-write-v2.ts` (0 callers today) is the v2 surface; v1 (`atomic-write.ts`) keeps symlink-safety + link+unlink atomicity. Phase 1 is gated by `PI_CREW_ATOMIC_WRITER` env flag with instant rollback.
+
+### Verification
+
+| Gate | Result |
+|---|---|
+| TSC | ✅ |
+| Lint | ✅ |
+| format:check | ✅ |
+| check:conflict-markers | ✅ |
+| check:lazy-imports | ✅ |
+| check:bundle-staleness | ✅ |
+| test:unit local (config-cache) | ✅ 7/7 |
+| test:unit local (safe-bash, post-style-fix) | ✅ 26/26 |
+| test:unit local (coalesce + atomic-write-coalesced + file-coalescer + progress-event-coalescer) | ✅ 26/26 |
+| Live E2E: test-coalesce-static (3 tasks) | ✅ all 3 resultArtifacts + heartbeats + clean closeout |
+| Live E2E: fast-fix (explore→execute→verify) | ✅ consistency=1, 14 min |
+| Live E2E: research (explore→analyze→write) | ✅ consistency=1, summary 4.7KB |
+| CI Ubuntu / Node 22 | ✅ (post-push) |
+| CI macOS / Node 22 | ✅ (post-push) |
+| CI Windows / Node 22 | ✅ (post-push) |
+
+### Changed
+
+- `src/runtime/async-runner.ts:224-235` — `runnerPath` now uses `packageRoot()` (1 import added at line 11).
+- `src/runtime/task-runner/state-helpers.ts:1-2, 57-69, 121-127` — wire `saveRunTasksCoalesced` + `flushPendingAtomicWrites` guard.
+- `src/state/state-store.ts:425-434` — export `saveRunTasksCoalesced` (was local), update doc comment.
+- `src/config/config.ts:69-166, 1077-1100` — new cache module + cache-aware `loadConfig`.
+- `test/unit/config-cache.test.ts` (new, 242 lines, 7 tests).
+- `docs/migration/atomic-write-v2-migration.md` (new, 297 lines) — migration plan + decision.
+- `docs/perf/performance-review-2026-07.md` — verification report (added in v0.9.18 cycle).
+- 31 files via biome auto-fix (`style: biome auto-fixes` commit `299338e`) — import-sort + minor semantic.
+
+### Migration notes
+
+- No public-API breaking changes. Existing workflows and configs continue to work without modification.
+- The `loadConfig` cache is transparent — first call hits disk, subsequent calls within 2s return cached value. To force a refresh (e.g. after a config edit), call `invalidateConfigCache()` from a custom integration or just wait 2s.
+- The `saveRunTasksCoalesced` swap is checkpoint-only; terminal writes remain fully durable. If a process crashes mid-50ms-buffer, the last checkpoint may be lost but the on-disk `manifest.json` + `tasks.json` source of truth is preserved.
+- The atomic-write-v2 migration plan describes a 3-phase rollout behind `PI_CREW_ATOMIC_WRITER=v1|v2` flag (default v1 until Phase 2). Users on critical/durability-sensitive deployments can opt into v2 after Phase 1 stabilizes.
+
 ## [v0.9.17] — coalesced micro-tasks (M6) ships + closeout race fix (2026-07-02)
 
 Two end-to-end correctness fixes for the M6 real-dispatch path + one workload-sizing refinement, plus a startup-latency fix discovered during user testing.

package/dist/build-meta.json

@@ -6119,7 +6119,7 @@
       "format": "esm"
     },
     "src/state/atomic-write.ts": {
-      "bytes": 27629,
+      "bytes": 27623,
       "imports": [
         {
           "path": "node:crypto",
@@ -6232,7 +6232,7 @@
       "format": "esm"
     },
     "src/config/config.ts": {
-      "bytes": 43977,
+      "bytes": 49215,
       "imports": [
         {
           "path": "node:fs",
@@ -6443,7 +6443,7 @@
       "format": "esm"
     },
     "src/utils/safe-paths.ts": {
-      "bytes": 17496,
+      "bytes": 17260,
       "imports": [
         {
           "path": "node:fs",
@@ -6562,7 +6562,7 @@
       "format": "esm"
     },
     "src/state/state-store.ts": {
-      "bytes": 34202,
+      "bytes": 34567,
       "imports": [
         {
           "path": "node:fs",
@@ -7341,7 +7341,7 @@
       "format": "esm"
     },
     "src/runtime/child-pi.ts": {
-      "bytes": 61941,
+      "bytes": 61943,
       "imports": [
         {
           "path": "node:child_process",
@@ -10449,19 +10449,8 @@
       "format": "esm"
     },
     "src/runtime/mcp-proxy.ts": {
-      "bytes": 4219,
-      "imports": [
-        {
-          "path": "@earendil-works/pi-coding-agent",
-          "kind": "import-statement",
-          "external": true
-        },
-        {
-          "path": "@sinclair/typebox",
-          "kind": "import-statement",
-          "external": true
-        }
-      ],
+      "bytes": 4214,
+      "imports": [],
       "format": "esm"
     },
     "src/runtime/model-resolver.ts": {
@@ -12427,7 +12416,7 @@
       "format": "esm"
     },
     "src/extension/team-onboard.ts": {
-      "bytes": 5136,
+      "bytes": 5120,
       "imports": [
         {
           "path": "node:fs",
@@ -12458,7 +12447,7 @@
       "format": "esm"
     },
     "src/extension/team-tool/anchor.ts": {
-      "bytes": 5655,
+      "bytes": 5660,
       "imports": [
         {
           "path": "src/runtime/anchor-manager.ts",
@@ -12479,7 +12468,7 @@
       "format": "esm"
     },
     "src/extension/team-tool/auto-summarize.ts": {
-      "bytes": 4516,
+      "bytes": 4521,
       "imports": [
         {
           "path": "src/runtime/auto-summarize.ts",
@@ -12783,7 +12772,7 @@
       "format": "esm"
     },
     "src/runtime/verification-integrity.ts": {
-      "bytes": 3921,
+      "bytes": 3852,
       "imports": [
         {
           "path": "node:crypto",
@@ -12835,7 +12824,7 @@
       "format": "esm"
     },
     "src/runtime/async-runner.ts": {
-      "bytes": 13888,
+      "bytes": 14599,
       "imports": [
         {
           "path": "node:child_process",
@@ -12882,6 +12871,11 @@
           "kind": "import-statement",
           "original": "../utils/internal-error.ts"
         },
+        {
+          "path": "src/utils/paths.ts",
+          "kind": "import-statement",
+          "original": "../utils/paths.ts"
+        },
         {
           "path": "src/runtime/orphan-worker-registry.ts",
           "kind": "import-statement",
@@ -13505,7 +13499,7 @@
       "format": "esm"
     },
     "src/ui/tool-renderers/index.ts": {
-      "bytes": 28404,
+      "bytes": 28409,
       "imports": [
         {
           "path": "@earendil-works/pi-tui",
@@ -14093,11 +14087,6 @@
       ],
       "format": "esm"
     },
-    "src/runtime/team-runner-artifacts.ts": {
-      "bytes": 550,
-      "imports": [],
-      "format": "esm"
-    },
     "src/runtime/coalesce-tasks.ts": {
       "bytes": 11044,
       "imports": [
@@ -14109,88 +14098,6 @@
       ],
       "format": "esm"
     },
-    "src/runtime/task-runner/output-splitter.ts": {
-      "bytes": 5912,
-      "imports": [],
-      "format": "esm"
-    },
-    "src/runtime/workspace-tree.ts": {
-      "bytes": 10201,
-      "imports": [
-        {
-          "path": "node:fs/promises",
-          "kind": "import-statement",
-          "external": true
-        },
-        {
-          "path": "node:path",
-          "kind": "import-statement",
-          "external": true
-        }
-      ],
-      "format": "esm"
-    },
-    "src/runtime/run-coalesced-task-group.ts": {
-      "bytes": 9226,
-      "imports": [
-        {
-          "path": "node:fs/promises",
-          "kind": "import-statement",
-          "external": true
-        },
-        {
-          "path": "node:path",
-          "kind": "import-statement",
-          "external": true
-        },
-        {
-          "path": "src/runtime/role-permission.ts",
-          "kind": "import-statement",
-          "original": "./role-permission.ts"
-        },
-        {
-          "path": "src/runtime/child-pi.ts",
-          "kind": "import-statement",
-          "original": "./child-pi.ts"
-        },
-        {
-          "path": "src/runtime/task-runner/output-splitter.ts",
-          "kind": "import-statement",
-          "original": "./task-runner/output-splitter.ts"
-        },
-        {
-          "path": "src/runtime/workspace-tree.ts",
-          "kind": "import-statement",
-          "original": "./workspace-tree.ts"
-        },
-        {
-          "path": "src/state/state-store.ts",
-          "kind": "import-statement",
-          "original": "../state/state-store.ts"
-        },
-        {
-          "path": "src/state/artifact-store.ts",
-          "kind": "import-statement",
-          "original": "../state/artifact-store.ts"
-        },
-        {
-          "path": "src/state/event-log.ts",
-          "kind": "import-statement",
-          "original": "../state/event-log.ts"
-        },
-        {
-          "path": "src/runtime/worker-heartbeat.ts",
-          "kind": "import-statement",
-          "original": "./worker-heartbeat.ts"
-        },
-        {
-          "path": "src/runtime/team-runner-artifacts.ts",
-          "kind": "import-statement",
-          "original": "./team-runner-artifacts.ts"
-        }
-      ],
-      "format": "esm"
-    },
     "src/runtime/concurrency.ts": {
       "bytes": 2709,
       "imports": [
@@ -14342,6 +14249,93 @@
       ],
       "format": "esm"
     },
+    "src/runtime/task-runner/output-splitter.ts": {
+      "bytes": 5912,
+      "imports": [],
+      "format": "esm"
+    },
+    "src/runtime/team-runner-artifacts.ts": {
+      "bytes": 550,
+      "imports": [],
+      "format": "esm"
+    },
+    "src/runtime/workspace-tree.ts": {
+      "bytes": 10201,
+      "imports": [
+        {
+          "path": "node:fs/promises",
+          "kind": "import-statement",
+          "external": true
+        },
+        {
+          "path": "node:path",
+          "kind": "import-statement",
+          "external": true
+        }
+      ],
+      "format": "esm"
+    },
+    "src/runtime/run-coalesced-task-group.ts": {
+      "bytes": 9226,
+      "imports": [
+        {
+          "path": "node:fs/promises",
+          "kind": "import-statement",
+          "external": true
+        },
+        {
+          "path": "node:path",
+          "kind": "import-statement",
+          "external": true
+        },
+        {
+          "path": "src/state/artifact-store.ts",
+          "kind": "import-statement",
+          "original": "../state/artifact-store.ts"
+        },
+        {
+          "path": "src/state/event-log.ts",
+          "kind": "import-statement",
+          "original": "../state/event-log.ts"
+        },
+        {
+          "path": "src/state/state-store.ts",
+          "kind": "import-statement",
+          "original": "../state/state-store.ts"
+        },
+        {
+          "path": "src/runtime/child-pi.ts",
+          "kind": "import-statement",
+          "original": "./child-pi.ts"
+        },
+        {
+          "path": "src/runtime/role-permission.ts",
+          "kind": "import-statement",
+          "original": "./role-permission.ts"
+        },
+        {
+          "path": "src/runtime/task-runner/output-splitter.ts",
+          "kind": "import-statement",
+          "original": "./task-runner/output-splitter.ts"
+        },
+        {
+          "path": "src/runtime/team-runner-artifacts.ts",
+          "kind": "import-statement",
+          "original": "./team-runner-artifacts.ts"
+        },
+        {
+          "path": "src/runtime/worker-heartbeat.ts",
+          "kind": "import-statement",
+          "original": "./worker-heartbeat.ts"
+        },
+        {
+          "path": "src/runtime/workspace-tree.ts",
+          "kind": "import-statement",
+          "original": "./workspace-tree.ts"
+        }
+      ],
+      "format": "esm"
+    },
     "src/runtime/runtime-policy.ts": {
       "bytes": 1637,
       "imports": [
@@ -14478,7 +14472,7 @@
       "format": "esm"
     },
     "src/runtime/task-id.ts": {
-      "bytes": 5801,
+      "bytes": 5793,
       "imports": [
         {
           "path": "node:crypto",
@@ -14646,13 +14640,18 @@
       "format": "esm"
     },
     "src/runtime/task-runner/state-helpers.ts": {
-      "bytes": 4925,
+      "bytes": 5872,
       "imports": [
         {
           "path": "node:fs",
           "kind": "import-statement",
           "external": true
         },
+        {
+          "path": "src/state/atomic-write.ts",
+          "kind": "import-statement",
+          "original": "../../state/atomic-write.ts"
+        },
         {
           "path": "src/state/locks.ts",
           "kind": "import-statement",
@@ -15176,11 +15175,6 @@
           "kind": "import-statement",
           "original": "../worktree/branch-freshness.ts"
         },
-        {
-          "path": "src/runtime/team-runner-artifacts.ts",
-          "kind": "import-statement",
-          "original": "./team-runner-artifacts.ts"
-        },
         {
           "path": "src/runtime/cancellation.ts",
           "kind": "import-statement",
@@ -15191,11 +15185,6 @@
           "kind": "import-statement",
           "original": "./coalesce-tasks.ts"
         },
-        {
-          "path": "src/runtime/run-coalesced-task-group.ts",
-          "kind": "import-statement",
-          "original": "./run-coalesced-task-group.ts"
-        },
         {
           "path": "src/runtime/concurrency.ts",
           "kind": "import-statement",
@@ -15266,6 +15255,11 @@
           "kind": "import-statement",
           "original": "./role-permission.ts"
         },
+        {
+          "path": "src/runtime/run-coalesced-task-group.ts",
+          "kind": "import-statement",
+          "original": "./run-coalesced-task-group.ts"
+        },
         {
           "path": "src/runtime/run-tracker.ts",
           "kind": "import-statement",
@@ -15301,6 +15295,11 @@
           "kind": "import-statement",
           "original": "./task-runner.ts"
         },
+        {
+          "path": "src/runtime/team-runner-artifacts.ts",
+          "kind": "import-statement",
+          "original": "./team-runner-artifacts.ts"
+        },
         {
           "path": "src/runtime/usage-tracker.ts",
           "kind": "import-statement",
@@ -15616,7 +15615,7 @@
       "format": "esm"
     },
     "src/runtime/result-extractor.ts": {
-      "bytes": 7082,
+      "bytes": 6991,
       "imports": [
         {
           "path": "node_modules/@sinclair/typebox/build/esm/value/index.mjs",
@@ -15632,7 +15631,7 @@
       "format": "esm"
     },
     "src/runtime/dynamic-workflow-context.ts": {
-      "bytes": 40910,
+      "bytes": 40912,
       "imports": [
         {
           "path": "node:crypto",
@@ -17987,11 +17986,6 @@
           "kind": "import-statement",
           "original": "./message-renderers.ts"
         },
-        {
-          "path": "./notification-router.ts",
-          "kind": "import-statement",
-          "external": true
-        },
         {
           "path": "src/extension/registration/artifact-cleanup.ts",
           "kind": "import-statement",
@@ -18167,7 +18161,7 @@
       "imports": [],
       "exports": [],
       "inputs": {},
-      "bytes": 6411752
+      "bytes": 6421066
     },
     "dist/index.mjs": {
       "imports": [
@@ -19162,22 +19156,22 @@
           "external": true
         },
         {
-          "path": "node:fs/promises",
+          "path": "node:child_process",
           "kind": "import-statement",
           "external": true
         },
         {
-          "path": "node:path",
+          "path": "node:fs",
           "kind": "import-statement",
           "external": true
         },
         {
-          "path": "node:child_process",
+          "path": "node:path",
           "kind": "import-statement",
           "external": true
         },
         {
-          "path": "node:fs",
+          "path": "node:fs/promises",
           "kind": "import-statement",
           "external": true
         },
@@ -20317,7 +20311,7 @@
           "bytesInOutput": 5243
         },
         "src/state/atomic-write.ts": {
-          "bytesInOutput": 15545
+          "bytesInOutput": 15539
         },
         "src/config/defaults.ts": {
           "bytesInOutput": 4396
@@ -20332,7 +20326,7 @@
           "bytesInOutput": 1330
         },
         "src/config/config.ts": {
-          "bytesInOutput": 35555
+          "bytesInOutput": 38804
         },
         "src/errors.ts": {
           "bytesInOutput": 8094
@@ -20356,7 +20350,7 @@
           "bytesInOutput": 4422
         },
         "src/utils/safe-paths.ts": {
-          "bytesInOutput": 8540
+          "bytesInOutput": 8526
         },
         "src/utils/scan-cache.ts": {
           "bytesInOutput": 3769
@@ -20377,7 +20371,7 @@
           "bytesInOutput": 1785
         },
         "src/state/state-store.ts": {
-          "bytesInOutput": 18223
+          "bytesInOutput": 18501
         },
         "src/utils/file-coalescer.ts": {
           "bytesInOutput": 1204
@@ -20488,7 +20482,7 @@
           "bytesInOutput": 1642
         },
         "src/runtime/child-pi.ts": {
-          "bytesInOutput": 43953
+          "bytesInOutput": 43955
         },
         "src/runtime/heartbeat-gradient.ts": {
           "bytesInOutput": 953
@@ -21181,7 +21175,7 @@
           "bytesInOutput": 1564
         },
         "src/extension/team-onboard.ts": {
-          "bytesInOutput": 4513
+          "bytesInOutput": 4497
         },
         "src/runtime/anchor-manager.ts": {
           "bytesInOutput": 11040
@@ -21220,13 +21214,13 @@
           "bytesInOutput": 6961
         },
         "src/runtime/verification-integrity.ts": {
-          "bytesInOutput": 916
+          "bytesInOutput": 900
         },
         "src/runtime/workspace-lock.ts": {
           "bytesInOutput": 2699
         },
         "src/runtime/async-runner.ts": {
-          "bytesInOutput": 8929
+          "bytesInOutput": 8931
         },
         "src/subagents/async-entry.ts": {
           "bytesInOutput": 119
@@ -21369,21 +21363,9 @@
         "src/worktree/branch-freshness.ts": {
           "bytesInOutput": 2373
         },
-        "src/runtime/team-runner-artifacts.ts": {
-          "bytesInOutput": 279
-        },
         "src/runtime/coalesce-tasks.ts": {
           "bytesInOutput": 4350
         },
-        "src/runtime/task-runner/output-splitter.ts": {
-          "bytesInOutput": 3242
-        },
-        "src/runtime/workspace-tree.ts": {
-          "bytesInOutput": 7286
-        },
-        "src/runtime/run-coalesced-task-group.ts": {
-          "bytesInOutput": 6313
-        },
         "src/runtime/concurrency.ts": {
           "bytesInOutput": 2156
         },
@@ -21414,6 +21396,18 @@
         "src/runtime/retry-executor.ts": {
           "bytesInOutput": 2406
         },
+        "src/runtime/task-runner/output-splitter.ts": {
+          "bytesInOutput": 3242
+        },
+        "src/runtime/team-runner-artifacts.ts": {
+          "bytesInOutput": 279
+        },
+        "src/runtime/workspace-tree.ts": {
+          "bytesInOutput": 7286
+        },
+        "src/runtime/run-coalesced-task-group.ts": {
+          "bytesInOutput": 6313
+        },
         "src/runtime/runtime-policy.ts": {
           "bytesInOutput": 575
         },
@@ -21442,7 +21436,7 @@
           "bytesInOutput": 1482
         },
         "src/runtime/task-id.ts": {
-          "bytesInOutput": 1382
+          "bytesInOutput": 1374
         },
         "src/runtime/task-packet.ts": {
           "bytesInOutput": 3564
@@ -21475,7 +21469,7 @@
           "bytesInOutput": 767
         },
         "src/runtime/task-runner/state-helpers.ts": {
-          "bytesInOutput": 3106
+          "bytesInOutput": 3125
         },
         "src/runtime/task-runner/tail-read.ts": {
           "bytesInOutput": 762
@@ -21553,13 +21547,13 @@
           "bytesInOutput": 1927
         },
         "src/runtime/result-extractor.ts": {
-          "bytesInOutput": 4266
+          "bytesInOutput": 4250
         },
         "src/runtime/semaphore.ts": {
           "bytesInOutput": 1460
         },
         "src/runtime/dynamic-workflow-context.ts": {
-          "bytesInOutput": 20183
+          "bytesInOutput": 20185
         },
         "src/runtime/dynamic-workflow-runner.ts": {
           "bytesInOutput": 6259
@@ -21784,7 +21778,7 @@
           "bytesInOutput": 81
         }
       },
-      "bytes": 3076796
+      "bytes": 3080272
     }
   }
 }