pi-crew 0.9.51 → 0.9.53

package/docs/FEATURE_INTAKE.md

@@ -1,126 +0,0 @@
-# Feature Intake
-
-Every implementation prompt must pass through the intake gate before code changes.
-
-## Intake Flow
-
-```text
-User prompt / issue
-        │
-        ▼
-Classify input type
-        │
-        ▼
-Identify affected modules
-(src/runtime, src/state, src/extension, src/ui, src/utils)
-        │
-        ▼
-Run risk checklist
-        │
-        ▼
-Choose lane: tiny, normal, or high-risk
-        │
-        ▼
-Create/update story packet (normal+)
-or patch directly (tiny)
-```
-
-## Input Types
-
-| Type | Use when | Artifact |
-|------|----------|----------|
-| Bug fix | Fix crash, wrong behavior, test failure | Direct patch or story |
-| Feature | New capability (new tool action, new runtime mode) | Story packet |
-| Refactor | Internal restructure without behavior change | Direct patch |
-| Performance | Improve speed/memory/concurrency | Story packet |
-| Security | Fix vulnerability, harden boundary | High-risk story |
-| Docs | README, comments, harness files | Direct patch |
-| Dependency | Update/add/remove dependencies | Story packet |
-| Harness improvement | Improve this operating model | Direct docs update |
-
-## Lanes
-
-### Tiny
-Low-risk: docs, names, narrow edits, comment fixes.
-
-Requirements:
-- Patch directly
-- Run `npm run typecheck`
-- Update harness only if friction found
-
-### Normal
-Story-sized behavior with bounded blast radius.
-
-Requirements:
-- Create/update story in `docs/stories/`
-- Link affected product docs
-- Add/update test matrix entries
-- Run `npm test` + `npm run typecheck`
-- Update `docs/TEST_MATRIX.md`
-
-### High-Risk
-Affects security, data integrity, state mutation, concurrency, or multiple modules.
-
-Requirements:
-- Create high-risk story folder in `docs/stories/`
-- Fill overview, design, exec plan, validation
-- Ask human confirmation before implementation
-- Record decision in `docs/decisions/`
-
-## Risk Checklist
-
-| Risk flag | Applies when work touches |
-|-----------|---------------------------|
-| State mutation | manifest.json, tasks.json, events.jsonl writes |
-| Concurrency | shared mutable state, race conditions, locks |
-| Child process | spawning Pi workers, worktree isolation |
-| Error handling | catch blocks, error propagation, crash recovery |
-| External tools | `gh` CLI, `git` commands, shell execution |
-| API contract | team tool API shape, tool parameters |
-| Platform | Windows vs Unix path handling, EBUSY/EPERM |
-| Backward compat | state format changes, config migration |
-| Dependencies | new npm packages, native modules |
-| Security | command injection, path traversal, trust boundaries |
-
-## Classification
-
-```text
-0-1 flags:
-  tiny or normal, based on code impact
-
-2-3 flags:
-  normal with stronger validation
-
-4+ flags:
-  high-risk
-
-Hard gates (always high-risk):
-  - State mutation + concurrency
-  - Child process spawning
-  - External tool execution (command injection surface)
-  - Removing or weakening error handling
-  - Changing state file format without migration
-```
-
-## Affected Modules
-
-| Module | Path | Blast radius |
-|--------|------|-------------|
-| Extension | `src/extension/` | Tool API, registration, hooks |
-| Runtime | `src/runtime/` | Team runner, task runner, child process, async |
-| State | `src/state/` | Durable state, events, locks, artifacts |
-| UI | `src/ui/` | TUI dashboard, overlay, widgets |
-| Utils | `src/utils/` | Shared utilities, conflict detection, git |
-| Worktree | `src/worktree/` | Git worktree management |
-| Config | `src/config/` | Runtime config, resource discovery |
-| Tests | `test/` | Unit tests, integration |
-
-## Output Example
-
-```text
-Lane: normal
-Reason: touches state mutation and concurrency in team-runner.ts
-Modules: src/runtime/team-runner.ts, src/state/state-store.ts
-Story: docs/stories/US-015-durable-state-locking.md
-Validation: npm test, npm run typecheck, CI 3/3
-```

package/docs/HARNESS.md

@@ -1,87 +0,0 @@
-# Harness
-
-pi-crew is a Pi extension for multi-agent orchestration. This harness helps
-agents and humans collaborate on developing pi-crew in a reliable, inspectable,
-and easy-to-steer way.
-
-The product is pi-crew itself. The harness is the operating environment that
-helps agents understand the product, classify work, track decisions, and
-validate changes.
-
-## Mental Model
-
-```text
-Human intent (issue, prompt, request)
-         │
-         ▼
-  Feature intake
-  (classify → risk lane)
-         │
-         ▼
-  Story packet or direct patch
-         │
-         ▼
-  Agent work loop
-  (explore → plan → execute → verify)
-         │
-         ▼
-  Product delta (code, tests, docs)
-         │
-         ▼
-  Validation proof (tests, typecheck, CI)
-         │
-         ▼
-  Harness delta (decisions, test matrix, backlog)
-         │
-         ▼
-  Next intent
-```
-
-Each task has 2 outputs:
-1. **Product delta**: code changes, test changes, API shape, config changes
-2. **Harness delta**: docs, decisions, test matrix updates, backlog items
-
-## Source Hierarchy
-
-Agents read in this order:
-
-1. `AGENTS.md` — operating rules and important paths
-2. `docs/HARNESS.md` — this file, the collaboration model
-3. `docs/FEATURE_INTAKE.md` — before turning a request into work
-4. `docs/product/` — current product contract
-5. `docs/ARCHITECTURE.md` — implementation shape
-6. `docs/stories/` — active and completed stories
-7. `docs/TEST_MATRIX.md` — proof status
-8. `docs/decisions/` — why important choices were made
-
-## Validation Ladder
-
-pi-crew already has validation commands:
-
-| Level | Command | What it proves |
-|-------|---------|----------------|
-| quick | `npm run typecheck` | TypeScript correctness + strip-types import |
-| unit | `npm test` | 1600+ unit tests, all pass |
-| lint | `npm run check` | Biome lint + format |
-| CI | GitHub Actions | Cross-platform (ubuntu, windows, macos) |
-
-Agents **must not** claim validation passes without running the actual command.
-
-## Growth Rule
-
-The harness grows from friction. When an agent:
-- Gets confused about expected behavior
-- Has to repeat manual reasoning
-- Lacks a validation command
-- Discovers a missing rule
-- Sees a recurring failure pattern
-
-→ The agent must improve the harness directly or propose changes in `docs/HARNESS_BACKLOG.md`.
-
-## Working Conventions
-
-- Vietnamese for communication, English for code/comments
-- Commit message format: `fix:`, `feat:`, `docs:` — conventional commits
-- Every code change must pass `npm test` + `npm run typecheck`
-- MEDIUM+ bugs found during review must be fixed before claiming done
-- LOW issues documented in `docs/HARNESS_BACKLOG.md` if recurring

package/docs/HARNESS_BACKLOG.md

@@ -1,89 +0,0 @@
-# Harness Backlog
-
-Use when an agent discovers a missing harness capability but should not change the operating model immediately.
-
-## Items
-
-### HB-001: Integration test harness
-
-**Discovered while**: Review round 9 — all tests are unit tests, no multi-module integration tests exist.
-
-**Current pain**: Cannot verify team-runner → state-store → child-process integration end-to-end without manual testing.
-
-**Suggested improvement**: Add `test/integration/` with real file-system state, real child processes (with timeout).
-
-**Risk**: normal
-
-**Status**: ✅ PARTIALLY DONE (2026-06-24). The bulk of HB-001 was already
-covered by 21 existing `test/integration/` files (team-runner path via
-`mock-child-run`, `full-feature-smoke`, `phase3-6-*`). The genuine remaining
-gap — interleaved manifest+task+event writes reloaded consistently (the
-realistic run-load pattern) — is now covered by
-`test/integration/state-durability-hb001.test.ts`. Child-process exit →
-state-store reconcile is covered by `async-restart-recovery.test.ts`.
-
-### HB-002: Windows-specific test coverage
-
-**Discovered while**: RR-002 Windows EBUSY fix — only tested manually, no automated Windows-specific tests.
-
-**Current pain**: Windows bugs only caught in CI, not locally.
-
-**Suggested improvement**: Add `test/platform/` with Windows-specific tests (EBUSY retry, path handling).
-
-**Risk**: normal
-
-**Status**: ✅ DONE (2026-06-24). `test/platform/` ships with two files:
-`windows-rename.test.ts` (EBUSY/EPERM rename retry path via `renameWithRetry`,
-self-skips off win32) and `posix-tools.test.ts` (BSD-vs-GNU grep, /var →
-/private/var realpath, POSIX-shell resolution — self-skips on win32).
-Runbook in `test/platform/README.md`. The CI OS matrix (ubuntu/windows/macos)
-exercises each platform's tests.
-
-### HB-003: Performance regression baseline
-
-**Discovered while**: Review noted `sleepSync` busy-wait on Windows — no perf benchmarks exist.
-
-**Current pain**: Cannot detect performance regressions.
-
-**Suggested improvement**: Add benchmark suite for critical paths (state writes, event append, task dispatch).
-
-**Risk**: tiny
-
-**Status**: ✅ DONE (2026-06-24). `test/bench/` now has 6 benchmarks:
-the pre-existing `register-startup`, `render-flush`, `snapshot-cache`, plus
-three new ones covering the gaps HB-003 flagged — `atomic-write.bench.ts`
-(`atomicWriteJson` cold/warm), `event-append.bench.ts` (serial lock
-contention vs batch), `task-graph-scheduler.bench.ts` (DAG build/refresh/
-full-run). All run via `npm run bench` → `test/bench/results.json`; baseline
-via `npm run bench:capture`. Each prints min/p50/p95/p99/max percentiles.
-
-### HB-004: Real-binary smoke tests for ctx.agent() paths
-
-**Discovered while**: Real-world `team action='run'` smoke testing on 2026-06-24
-caught three bugs that the unit suite (which mocks child-pi) missed entirely.
-
-**Current pain**: The unit tests for `dynamic-workflow-context.ts` and
-`child-pi.ts` use `PI_TEAMS_MOCK_CHILD_PI` and never shell out to the real `pi`
-binary. As a result they cannot catch:
-  - argv flags the real `pi` rejects (e.g. the `--crew-subagent` regression),
-  - env/persona interactions that change real model output (e.g. the
-    schema+systemPrompt drop),
-  - exit-code races in the real spawn lifecycle (e.g. the
-    `disableTools:true` → `exit null` race).
-
-**Suggested improvement**: Add `test/smoke/` (gated behind a `PI_CREW_SMOKE=1`
-env so CI doesn't bill tokens by default) that runs real `.dwf.ts` workflows
-end-to-end via `team action='run'` and asserts on the resulting
-`events.jsonl` + `summary.md`. One workflow per feature family
-(phase/log/pipeline/agent/schema/worktree). Document the runbook in
-`docs/troubleshooting.md`.
-
-**Risk**: normal (token cost when run; otherwise read-only)
-
-**Status**: ✅ DONE (2026-06-24). `test/smoke/` shipped with 5 smoke tests
-(argv-flags, agent-plain, agent-schema, agent-disabletools, dwf-workflow),
-all gated behind `PI_CREW_SMOKE=1`. `npm run test:smoke` runs them. CI
-manual-dispatch workflow at `.github/workflows/smoke.yml` (requires
-`PI_AUTH_JSON` secret). Runbook in `docs/troubleshooting.md`. Each smoke test
-maps to a real bug it would have caught (HB-003a, the schema+systemPrompt
-drop, the `--crew-subagent` argv regression).

package/docs/PROJECT_REVIEW.md

@@ -1,270 +0,0 @@
-# pi-crew — Project Review
-
-> Review date: 2026-05-18
-> Version: `pi-crew@0.2.19`
-> Scope: the entire source (`index.ts`, `src/**`), config, tests, docs, scripts.
-> Method: read source directly, cross-referenced against `AGENTS.md`/`docs/architecture.md`, ran `npm run typecheck` + `npm run test:unit`.
-
-## Overview
-
-`pi-crew` is a multi-agent orchestration Pi extension (teams + workflows + worktrees + async background runs), with a **durable-first model**: every run/task/event is persisted to disk (JSONL + atomic JSON writes) so that foreground, async background, dashboard, and crash recovery all read the same source of truth.
-
-The codebase is mature, uses **TypeScript strict mode** (`noImplicitAny`, `strict: true`), has a broad test suite (1596 tests pass, 2 skipped, 0 failures), clear layered architecture (extension / runtime / state / worktree / utils), and many defensive notes ("3.1 backpressure", "2.10 cache", "P1 catch unhandled errors") indicating it has been iterated over many review rounds.
-
-### Quick health-check results
-
-| Category | Result |
-|---|---|
-| `npm run typecheck` (`tsc --noEmit` + strip-types import) | PASS |
-| `npm run test:unit` (1598 tests / 128 suites) | 1596 pass · 2 skip · 0 fail (~90s) |
-| `npm pack --dry-run` (via `npm run ci`) | Not checked in this session |
-| Linter (ESLint) | No `lint` script; relies on `tsc strict` |
-| Number of `.ts` files in `src/` | ~190 modules |
-
----
-
-## 1. Notable strengths
-
-1. **Consistent path-safety**: `utils/safe-paths.ts` (`assertSafePathId`, `resolveContainedPath`, `resolveRealContainedPath`) is used uniformly in `state-store.ts`, `artifact-store.ts`, `mailbox.ts`. It has two layers: a string-based containment check and a real-path check (defends against symlink escape after mkdir).
-2. **Multi-layered defensive atomic writes** (`state/atomic-write.ts`):
-   - `O_EXCL | O_CREAT | O_NOFOLLOW` when opening the temp file.
-   - `fstatSync` post-open to verify a regular file (defends against TOCTOU on Windows where `O_NOFOLLOW = 0`).
-   - Rename retry with exponential backoff + jitter (defends against lockstep starvation).
-   - Coalesced variant `atomicWriteJsonCoalesced` for high-frequency state writes; flush on `exit`/`SIGTERM`/`SIGINT`.
-3. **Redaction (`utils/redaction.ts`)** handles many patterns: PEM private keys, Authorization headers, Bearer tokens, inline secret patterns, key-name matching (`apiKey`, `password`, `secret`, ...). Applied in `appendEvent`, `appendMailboxMessage`, `writeArtifact`, `appendTranscript`.
-4. **Env sanitization (`utils/env-filter.ts`)**: default secret-pattern deny-list, allow-list mode for `worktree.setupHook` to pass only `PATH`, `HOME`, `PI_*`.
-5. **Process kill tree** (`runtime/child-pi.ts`):
-   - Windows: `taskkill /T /F` + verify-after-2s + retry if PID is still alive.
-   - POSIX: `process.kill(-pid, "SIGTERM")` (process group) with an absolute-pid fallback; SIGKILL escalation after `HARD_KILL_MS`; fast-cancel SIGKILL after 200ms on user cancel.
-   - Lifecycle events have a structured shape `{ type, pid, exitCode?, error?, ts }`.
-6. **Backpressure**: pause child stdout when more than 256KB is undrained.
-7. **Lazy imports marked with `// LAZY:`** with a specific reason (reduces ~1.4s import cost at registration), plus a `check:lazy-imports` script to enforce it.
-8. **Run / task contract guards**: `shouldMergeTaskUpdate` (prevents a stale snapshot from regressing terminal state), monotonic finishedAt, `canTransitionRunStatus`, plan-approval-gating for mutating tasks.
-9. **Crash & cancellation paths**: `executeTeamRun` catch-all ensures the manifest/tasks transition to terminal on unhandled error (avoids "running forever"); `background-runner` has an `unhandledRejection` guard that writes `async.failed` before exit; `parent-guard` so the background runner dies when its parent dies.
-10. **Very broad test coverage** for both happy paths and edge cases (yield, atomic-write retry, mergeTaskUpdates, mailbox validation, cancellation, model fallback...).
-11. **Config**:
-    - Schema validation via TypeBox with fuzzy suggestions for misspelled keys.
-    - **Sanitize project-level config** (`sanitizeProjectConfig`): strips sensitive keys (`executeWorkers`, `runtime.mode`, `worktree.setupHook`, `otlp.headers`, `agents.overrides`, …) from the project config, accepting them only from user config. This is an essential safeguard for an injected repo.
-
----
-
-## 2. Bugs / Issues found
-
-> Classification: **HIGH** (can cause data loss / incorrectness), **MED** (correctness corner case / DX), **LOW** (improvement).
-
-### HIGH
-
-**H1. `event-log.ts` — silent loss when exceeding `MAX_EVENTS_BYTES` (50MB)**
-```ts
-// src/state/event-log.ts ~ appendEventInsideLock
-if (fs.existsSync(eventsPath) && fs.statSync(eventsPath).size > MAX_EVENTS_BYTES) {
-    logInternalError(...);
-    return { ...fullEvent, metadata: { ...(fullEvent.metadata ?? {seq:0,...}), appended: false } };
-}
-```
-- Problem: the event is dropped immediately (including terminal events like `run.failed`, `task.completed`) and `appendCounter` is also not incremented → `compactEventLog` (which only runs every 100 appends) is not triggered when it is needed most. Consequence: once the threshold is crossed, the log is "locked" silently until the next 100 appends trigger a rotation.
-- Suggestion: when the threshold is hit, call `compactEventLog(eventsPath)` immediately, or rotate first then append; also prioritize letting terminal events (TERMINAL_EVENT_TYPES) through, since those events are part of the durable contract.
-
-**H2. `mailbox.ts` — `appendMailboxMessage` has no cross-process lock**
-```ts
-fs.appendFileSync(mailboxFile(manifest, complete.direction, complete.taskId), `${JSON.stringify(...)}\n`, "utf-8");
-```
-- Problem: `appendFileSync` is not atomic across processes on Windows. Two background runners + foreground steering at the same time can interleave JSON lines → `parseMailboxMessage` skips them, messages are lost silently (reported later via `validateMailbox`).
-- Suggestion: use the existing `withEventLogLockSync` pattern for the mailbox, or use `atomicWriteFile` to rewrite (slower but atomic). At minimum, add atomic `O_APPEND` on POSIX (only guaranteed up to PIPE_BUF) and a lock on Windows.
-
-**H3. `atomic-write.ts` — fallback `writeFileSync` has no symlink guard**
-```ts
-try { renameWithRetry(tempPath, filePath); }
-catch (renameError) {
-    try { fs.writeFileSync(filePath, content, "utf-8"); } // BYPASSES symlink guard
-    catch { throw renameError; }
-}
-```
-- Problem: if rename fails with EPERM on Windows, the fallback goes directly to `writeFileSync(filePath)` — if `filePath` becomes a symlink between the `isSymlinkSafePath` check (top of function) and the fallback, the write follows the link. The time window is small but could be exploited by an adversary on a multi-user host.
-- Suggestion: before the fallback, re-check `fs.lstatSync(filePath).isSymbolicLink()`. Or open an fd with `O_NOFOLLOW` and `O_TRUNC` then write.
-
-**H4. `team-runner.ts` — function named `__test__mergeTaskUpdates` is used in production**
-```ts
-// Re-exported and documented as test-only:
-export function __test__mergeTaskUpdates(...) { ... }
-// but called in executeTeamRunCore:
-tasks = __test__mergeTaskUpdates(tasks, results);
-```
-- Problem: the `__test__` convention implies only tests should import it; this is actually the runner's core merge logic. Another developer might "clean up" this helper or change its behavior thinking it only affects tests → silent regression.
-- Suggestion: rename to `mergeTaskUpdatesPreservingTerminal()` (or similar), keep `__test__mergeTaskUpdates` as an export-only alias for tests, add a comment.
-
-### MED
-
-**M1. `task-runner.ts` — `transcriptPath` reused across model fallback attempts**
-- Each attempt appends to the same transcript file. `parsePiJsonOutput(fs.readFileSync(transcriptPath, "utf-8"))` parses everything → final text/usage may be mixed across attempts. `resultArtifact.content` takes `parsedOutput?.finalText`, which could be the final text of attempt 1 (which failed) if attempt 2 has no valid message_end.
-- Suggestion: either use `transcripts/${task.id}.attempt-${i}.jsonl` per attempt, or clear the file at the start of each attempt if the policy is "last attempt wins".
-
-**M2. `task-runner.ts` — reads the entire transcript into memory for `transcriptArtifact`**
-```ts
-content: fs.readFileSync(transcriptPath, "utf-8"),
-```
-- For long-running tasks the transcript can be tens of MB. Combined with compactChildPiEvent already reducing size, it is still unbounded. `MAX_CAPTURE_BYTES` only applies to in-memory `stdout/stderr`, not to the on-disk transcript.
-- Suggestion: cap the transcript file size (rotate when exceeding a threshold) or have the artifact use a reference (path) instead of copying content.
-
-**M3. `cleanup.ts` — `fs.statSync(worktreePath).isDirectory()` has no race guard**
-```ts
-for (const entry of fs.readdirSync(worktreeRoot)) {
-    const worktreePath = path.join(worktreeRoot, entry);
-    if (!fs.statSync(worktreePath).isDirectory()) continue;
-```
-- If the entry is deleted between `readdirSync` and `statSync`, it throws uncaught.
-- Suggestion: wrap in `try { fs.statSync... } catch { continue; }` or use `fs.readdirSync(worktreeRoot, { withFileTypes: true })` then `entry.isDirectory()`.
-
-**M4. `worktree-manager.ts` — `runSetupHook` parses JSON only from the last line**
-```ts
-const lastLine = lines[lines.length - 1] ?? trimmed;
-const parsed = JSON.parse(lastLine);
-```
-- If the hook outputs multi-line JSON (pretty-printed), only the last line is parsed → `syntheticPaths` are silently lost. There is a log warning, but it is silent from the caller's side.
-- Suggestion: try parsing `trimmed` first, fall back to the last line. Or define a clear protocol (one-line JSON, terminator marker).
-
-**M5. `worktree-manager.ts` — `linkNodeModulesIfPresent` does not warn when `symlinkSync` fails**
-```ts
-try { fs.symlinkSync(...); return true; } catch { return false; }
-```
-- On Windows without the right to create symlinks (requires SeCreateSymbolicLinkPrivilege), it fails silently, the agent runs without `node_modules` — module resolution may fail but the caller does not know.
-- Suggestion: log the reason for failure (especially for non-admin Windows) via `logInternalError`, or return `{ linked, reason }`.
-
-**M6. `child-pi.ts` — `forcedFinalDrain` forces `exitCode: 0`**
-```ts
-const finalExitCode = forcedFinalDrain && !timeoutError ? 0 : exitCode;
-```
-- This logic (already explained in a comment) converts some exit ≠ 0 into 0 after the child sends the final assistant event. Edge case: child crashes during cleanup after the final event → still reports success. This could mask a memory leak or crash in the child Pi.
-- Suggestion: add telemetry/metrics counting how often `forcedFinalDrain → 0` happens to detect regressions. Currently there is only a lifecycle event "final_drain" but no conversion metric.
-
-**M7. `background-runner.ts` — `process.exit(130)` in the interrupt guard does not await flush**
-```ts
-if (last?.type === "interrupt" && last?.acknowledged !== true) {
-    appendEvent(...);
-    process.exit(130);
-}
-```
-- `process.exit` runs the `'exit'` handler but does not await async ops (e.g., a pending `appendEventBuffered` Promise). `flushEventLogBuffer` registered on `'exit'` is sync so it's OK, but `terminateLiveAgentsForRun` is not. It could leak a live agent.
-- Suggestion: `await terminateLiveAgentsForRun(...)` before exiting, or use `process.exitCode = 130` + return so cleanup runs normally.
-
-**M8. `state-store.ts` — manifest cache TTL invariant**
-- The cache key is `stateRoot`, TTL 5 minutes. Path validation guards against manifest paths changing. But if the file mtime + size do not change (extremely rare but possible with coalesced atomic writes when the size & content are the same), the cache serves stale content.
-- Suggestion: add a `contentHash` (cheap to stat → a fingerprint like the first 32 bytes) to the cache key, or invalidate the cache in the `atomicWriteJsonCoalesced` flush callback.
-
-**M9. `event-log.ts` — `sequenceCache` not invalidated when the file is truncated externally**
-- If an external tool truncates `events.jsonl` (manual rotation), the cached `seq` stays high, making `nextSequence` produce wrong seqs (there is a fallback: `cached.size === stat.size`). OK for the same-size race, but if truncation happens between `statSync` and `appendFileSync`, two appends will have the same seq.
-- Suggestion: persistSequence already uses atomic write, you can trust it in the race. Add an integration test for external truncation.
-
-**M10. `runtime-resolver` / config — `executeWorkers=false` default fallback path**
-- `handleResume` has complex logic to re-evaluate `runtime.mode` when resuming scaffold runs. The 3-way logic (`resumeManifest.runtimeResolution?.safety === "explicit_dry_run"` + env var checks) easily leads to an edge case where the user expects actual workers but resume is still scaffold. Hard to test.
-- Suggestion: refactor into a clear state machine `resolveResumeRuntime({ original, override, env })` with unit tests covering the full truth table.
-
-### LOW
-
-- **L1. `package.json` missing a `lint` script**; the global `AGENTS.md` has a convention `eslint --max-warnings=0`. Currently it only relies on `tsc strict`. Consider adding ESLint or Biome.
-- **L2. Many `JSON.stringify(value, null, 2)` for metadata artifacts**. Pretty-printing 50+ artifact/task files costs I/O. Consider minified JSON for metadata; pretty only for summary/progress that users read.
-- **L3. `task-runner.ts` creates ~13 artifacts per task** (prompt, result, inputs, coordination, skill, packet, verification, startup, permission, capability, prompt-pipeline, log, transcript, diff, diff-stat, output-validation). Each is an `atomicWriteFile` syscall. In a large run (50+ tasks), consolidating into fewer sub-artifacts would significantly reduce I/O.
-- **L4. `registerYieldTool()` runs at module top level** (`task-runner.ts` line 35). Side effect on import — if the module is imported twice (e.g., jiti vs strip-types), `subprocessToolRegistry` could be duplicated. Check whether `subprocess-tool-registry.ts` is idempotent.
-- **L5. `atomic-write.ts` `atomicWriteJsonCoalesced`** — the API has a significant caveat (read-after-write within the buffer window reads stale content). Large risk surface if a future dev forgets to call `flushPendingAtomicWrites()`. Consider adding a dedicated read API `readJsonFileWithCoalesceFlush()`.
-- **L6. Cancellation paths have no counting metric**. There are observability events but no gauge for the number of tasks cancelled per run.
-- **L7. `management.ts` `handleUpdate` rename+write** sequence has no rollback if writeFileSync fails after rename (a backup exists, but the user must manually restore). Could wrap in try/catch + auto-restore from backup.
-- **L8. `child-pi.ts` mock paths read env `PI_TEAMS_MOCK_CHILD_PI`** — there should be a guard preventing accidental production activation (check `process.env.NODE_ENV === "test"` or a clear test flag).
-- **L9. `worktree-manager.ts` `findGitRoot` throws** if cwd is not a git repo. `prepareTaskWorkspace` calls it before checking workspaceMode; actually workspaceMode is checked at the top of the function, OK. But the git error message ("not a git repository") propagates to the user — not user-friendly.
-- **L10. The naming `crewRoot` vs `.crew/` vs `.pi/teams/`** is documented but easy to confuse. `projectCrewRoot` has three branches (existing `.crew` → `.crew`; existing `.pi` → `.pi/teams`; else → `.crew`). Tests cover it but a new dev reading the code can easily misunderstand.
-- **L11. Some `let task: TeamTaskState = ...` is reassigned multiple times in `task-runner.ts`**. Hard to reason about. Consider refactoring into a reducer pattern.
-- **L12. `update-references-for-rename` only updates team→agent and team.defaultWorkflow**, does not cover workflow→step.role or agent references in test fixtures. The comment acknowledges this. Still worth fixing so renames are safe.
-
----
-
-## 3. Security review
-
-| Item | Status | Notes |
-|---|---|---|
-| Path traversal | OK | `assertSafePathId`, `resolveContainedPath`, `resolveRealContainedPath` cover it fairly thoroughly. |
-| Symlink escape | OK (corner case H3) | `O_NOFOLLOW`, `lstatSync`, post-open `fstatSync`. One fallback path skips the check (H3). |
-| Secret leak | OK | Redaction applied at the event log, transcript, mailbox, artifact inputs. Env sanitization before spawning the child. |
-| Code injection via setup hook | Mitigated | `runSetupHook` validates the file exists, uses `shell: false`, allow-lists env, 30s timeout. But it still executes user-provided code. Must trust the user. |
-| Untrusted project config | OK | `sanitizeProjectConfig` strips sensitive keys before merging. |
-| Process tree leak (zombie child Pi) | OK | `terminateActiveChildPiProcesses` + `parent-guard` + Windows `taskkill /T /F`. |
-| DoS via concurrency | OK | Default hard-cap; `allowUnboundedConcurrency=true` requires explicit opt-in + emits an event. |
-| Event log injection | Mitigated | JSON.stringify per line; readEvents skips parse errors. There is a risk of corrupted JSON lines due to an `appendFileSync` race (H2 in mailbox, but the event log has a lock). |
-| Dependency surface | Small | Only runtime deps: typebox, cli-highlight, diff, jiti. |
-
-In summary: the security posture is **good**. The biggest issue is H2 (mailbox has no lock) — stale state can occur if multiple processes race.
-
----
-
-## 4. Performance review
-
-- **Atomic write coalescer** (50ms window) has reduced I/O for high-frequency state writes.
-- **Manifest cache** with mtime+size key avoids re-parsing when unchanged.
-- **Lazy import boundaries** reduce import cost ~1.4s.
-- **`projectRootCache` TTL 30s** reduces 14 `existsSync` × ancestor levels per render tick.
-
-Areas with optimization potential:
-1. Each completed task produces ~13 artifacts (L3). 50 tasks = 650 atomic writes for metadata. Consider batching.
-2. `progress.md` and `summary.md` are rewritten multiple times per batch (writeProgress in a loop). Coalescing is fine but `atomicWriteJsonCoalesced` could be used.
-3. `parsePiJsonOutput(fs.readFileSync(transcriptPath))` runs each attempt, parsing the full transcript. Stream parsing is cheaper for large transcripts.
-4. `aggregateUsage(tasks)` runs O(n) over tasks on each summary write.
-
----
-
-## 5. DX / Maintainability
-
-| Aspect | Note |
-|---|---|
-| TS strict | OK, `noImplicitAny` enforced. |
-| Naming `__test__*` | Some mixing of pure test utils and production helpers (H4). |
-| File size | `team-runner.ts` (694 lines), `task-runner.ts` (440+ lines), `register.ts` (1k+ lines), `live-session-runtime.ts` (~750 lines) are all > 500 lines. AGENTS.md says "prefer small modules". |
-| Comment quality | Good — there are "WHY" markers, version tags (`// 2.10`, `// H4`, `// 3.1`). |
-| Test layout | `test/unit/*.test.ts` + `test/integration/*.test.ts`. Reasonable concurrency. |
-| Hard-coded magic numbers | Mostly centralized in `config/defaults.ts`. |
-| Error reporting | `logInternalError` is consistent — best-effort, does not throw. |
-| Docs sync | `docs/architecture.md` matches the code (except some next-upgrade-roadmap items not yet implemented). |
-
----
-
-## 6. Test-matrix gaps (candidates for new tests)
-
-- Cross-process race on mailbox append (H2).
-- Event log overflow recovery (H1) — ensure terminal events are still persisted when exceeding 50MB.
-- `forcedFinalDrain` does not mask a real child crash (M6).
-- Resume with mixed `runtime.mode` overrides (M10).
-- Atomic-write coalesced + read-after-write within the window — ensure documented behavior matches reality.
-- `linkNodeModulesIfPresent` Windows non-admin fallback (M5).
-- `runSetupHook` multi-line JSON output (M4).
-
----
-
-## 7. Suggested priorities (sorted)
-
-1. **Fix H1** (event-log overflow): rotate immediately when the threshold is crossed + prioritize terminal events.
-2. **Fix H2** (mailbox lock): apply the `withEventLogLockSync` pattern to mailbox append.
-3. **Fix H3** (atomic-write symlink TOCTOU): re-check lstat before the `writeFileSync` fallback.
-4. **Fix H4** (rename `__test__mergeTaskUpdates` → `mergeTaskUpdates`, keep alias).
-5. **M1/M2** transcript per-attempt + cap size.
-6. **M3** race-safe `statSync` in cleanup.
-7. **M6** add a metric `crew.child.final_drain_force_zero_total`.
-8. **L1** add ESLint or Biome for consistency (global AGENTS.md requires it).
-9. **L3** batch artifact writes for metadata.
-10. **L12** expand `updateReferencesForRename` for workflow→step + agent references.
-
----
-
-## 8. Verification
-
-```
-npx tsc --noEmit                                  → PASS
-node --experimental-strip-types -e "..."         → PASS (strip-types import ok)
-node --test test/unit/*.test.ts                  → 1596 pass / 2 skip / 0 fail / 90s
-```
-
-There is no lint command in the project (only `tsc strict`); no `.eslintrc*` file was found.
-
----
-
-## 9. Conclusion
-
-`pi-crew` is a **mature, highly disciplined** codebase, with many defensive layers against TOCTOU, races, and mid-write crashes. Test coverage is broad, the architecture is clear. The issues found are mainly edge-case correctness and hardening; there is no serious "broken core flow" vulnerability.
-
-**Recommendation**: prioritize fixing H1–H4 and expanding tests for cross-process races (mailbox + event-log overflow). Next, consider adding a linter, batching metadata artifact writes, and refactoring some large orchestrator files (`register.ts`, `team-runner.ts`, `live-session-runtime.ts`) into sub-modules.