pi-crew 0.9.50 → 0.9.52

package/docs/decisions/2026-07-24-oidc-trusted-publishing.md

@@ -1,112 +0,0 @@
-# ADR: OIDC Trusted Publishing for npm
-
-**Date**: 2026-07-24
-**Status**: PROPOSED — not yet active (requires npm-side configuration)
-**Distilled from**: oh-my-pi@c84e9c020 `CONTRIBUTING.md:313-317` + `.github/workflows/release.yml` (GPL-3.0 — pattern only, not code)
-
-## Context
-
-pi-crew currently publishes to npm manually via `npm publish` using a long-lived `NPM_TOKEN` (npm user `bom0792`). This has two supply-chain weaknesses:
-
-1. **Token theft surface**: a long-lived npm token stored as a GitHub secret can be exfiltrated via a compromised dependency or workflow `pull_request_target` misuse. The token grants full publish access until manually rotated.
-2. **No build attestation**: published packages carry no cryptographic proof of *what CI built and published them*. Consumers cannot verify a `pi-crew@x.y.z` tarball came from this repo's CI.
-
-The v0.9.3 mid-CI-publish incident class (publishing mid-run rather than from a dedicated gated workflow) is a third motivator: a dedicated release workflow moves publishing out of the general CI run and into a controlled, test-gated path.
-
-## Decision
-
-Adopt **npm Trusted Publishing (OIDC)** + **provenance attestation**, following the pattern oh-my-pi@c84e9c020 uses (`id-token: write`, no `NPM_TOKEN`, `--provenance`):
-
-1. Eliminate the long-lived `NPM_TOKEN`. Instead, GitHub Actions exchanges an OIDC token for a short-lived npm publish credential at publish time. No token to steal.
-2. Attach **provenance** (Sigstore-signed build attestation) to every published tarball. Consumers can verify origin with `npm audit signatures`.
-
-## Implementation steps (external + code)
-
-### A. npm-side (manual, one-time — cannot be done from code)
-
-1. Go to `https://www.npmjs.com/package/pi-crew/access`
-2. Under **Publishing access**, switch to **Require two-factor authentication and disallow tokens** (or set up Trusted Publishing if available for the account).
-3. Alternatively, use `npm token create --cidr` to scope a publish-only token to GitHub Actions IPs (weaker than OIDC but simpler).
-4. For full OIDC: configure the npm-side Trusted Publishing link to `baphuongna/pi-crew` + the `release.yml` workflow.
-
-### B. Code-side (when OIDC is configured)
-
-1. Add `.github/workflows/release.yml` (sample below) — **manual trigger only** (`workflow_dispatch`) until proven stable.
-2. Do **NOT** add `provenance=true` to a global `.npmrc` — that breaks local `npm publish` with "requires CI environment". Provenance must be a `--provenance` flag inside the CI workflow only.
-
-### Sample `release.yml` (MIT-licensed, pi-crew style — not copied from oh-my-pi)
-
-```yaml
-name: Release
-
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Version to publish (must match package.json)'
-        required: true
-        type: string
-
-permissions:
-  contents: write
-  id-token: write  # OIDC for trusted publishing
-
-concurrency:
-  group: release-${{ github.ref }}
-  cancel-in-progress: false
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    environment: release  # requires manual approval via GitHub environment protection
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
-
-      - run: npm ci
-
-      - name: Verify version matches input
-        run: |
-          PKG_VERSION=$(node -p "require('./package.json').version")
-          if [ "$PKG_VERSION" != "${{ inputs.version }}" ]; then
-            echo "Version mismatch: package.json=$PKG_VERSION input=${{ inputs.version }}"
-            exit 1
-          fi
-
-      - run: npm run typecheck
-      - run: npm run test:critical
-      - run: npm run build:bundle
-
-      - name: Publish with provenance
-        run: npm publish --provenance --access public
-        # No NPM_TOKEN env — OIDC trusted publishing exchanges the job's
-        # id-token for a short-lived credential automatically.
-
-      - name: Create GitHub release
-        uses: softprops/action-gh-release@v2
-        with:
-          tag_name: v${{ inputs.version }}
-          generate_release_notes: true
-```
-
-## What this prevents
-
-- **Token exfiltration**: no long-lived `NPM_TOKEN` secret to steal.
-- **Unverified publishes**: every tarball carries a signed attestation linking it to this repo's CI.
-- **Accidental publishes**: `workflow_dispatch` + `environment: release` (protected) requires manual approval before publish runs.
-
-## Why not active yet
-
-- npm-side Trusted Publishing / token-lockdown must be configured at `npmjs.com/package/pi-crew/access` first.
-- The `environment: release` protection rule (required reviewers) must be configured in GitHub repo settings.
-- Until both are done, keep the manual `npm publish` + GitHub release flow.
-
-## Trade-off
-
-OIDC trusted publishing is slightly less convenient than a long-lived token (each publish goes through a workflow dispatch + approval). The supply-chain hardening is worth it for a package with 700+ files shipping to public npm.

package/docs/decisions/README.md

@@ -1,26 +0,0 @@
-# Decisions
-
-Decision records explain why important product, architecture, or harness choices were made.
-
-Add a decision when:
-- Runtime mode changes (child-process vs live-session)
-- State format changes
-- New dependency introduced
-- API contract changes
-- Security hardening applied
-- Validation requirements added/removed/changed
-
-Current decisions derived from 9 review rounds and 13 bug fixes.
-
-## Index
-
-| ID | Title | Status |
-|----|-------|--------|
-| 0001 | Durable state as source of truth | Accepted |
-| 0002 | Child-process for async runners | Accepted |
-| 0003 | Depth guard for nested live-session | Accepted |
-| 0004 | execFileSync over execSync | Accepted |
-| 0005 | No TypeScript parameter properties | Accepted |
-| 2026-07-21-broker-windows-perms | Windows broker named-pipe permissions | Accepted |
-| 2026-07-21-broker-phase4-default-on | Phase 4 — do **not** flip default to true (interim) | **Superseded** by `2026-07-22-broker-phase4-gated-on` |
-| 2026-07-22-broker-phase4-gated-on | Phase 4 — flip `broker.enabled` default to true | Accepted (default-on) |

package/docs/deep-review-report.md

@@ -1,384 +0,0 @@
-# pi-crew Deep Review Report
-
-**Project:** pi-crew  
-**Version:** v0.5.2 *(historical — current version is v0.9.0)*  
-**Review Date:** 2026-05-28  
-**Updated:** 2026-05-29  
-**Reviewers:** Security Reviewer, Code Reviewer, Documentation Reviewer
-
----
-
-## Executive Summary
-
-pi-crew is a substantial multi-agent orchestration extension (~327 source files, ~307 test files) with impressive breadth of features: workflow state machines, DAG-based task scheduling, background runners, live-session management, observability pipelines, mailbox coordination, crash recovery, and more. The codebase shows strong engineering discipline but has **critical security issues, several data-loss bugs, and significant technical debt**.
-
-### Status Update (2026-05-29)
-
-**✅ FIXED:** 14 critical/high issues resolved:
-- C1: Secret credential exposure (env allowlist) ✅
-- C2: Mock mode bypass ✅
-- C3: Worktree hooks on Windows (safer execution) ✅
-- C4: Duplicate error key + Promise type mismatch ✅
-- C5: Decision ledger truncates file ✅
-- C6: Event-loop blocking (partial - lock uses sleepSync but with timeout) ⚠️
-- H1: ajv dependency missing ✅ (installed ajv)
-- H2: Race condition in foreground interrupt ✅
-- H3: Terminal events buffered (now bypass buffer) ✅
-- H4: Authorization (already has policy-based + session checks) ℹ️
-- H5: File descriptor leak ✅
-- H6: Module-level mutable state (Map iteration is safe) ℹ️
-- H9: Stale cache TTL (reduced to 30s) ✅
-- H10: Non-atomic transcript writes (appendFileSync is atomic for small writes) ℹ️
-- TypeScript compilation errors (7 source errors) ✅
-- Skills verification (35/35 pass) ✅
-
-**ℹ️ Notes:**
-- H4/H6/H10 are lower risk than initially assessed
-- C6 (sleepSync) is deeply integrated and would require async rewrite to fully fix
-
-### Risk Overview
-
-| Severity | Found | Fixed | Assessed Low Risk |
-|----------|-------|-------|-------------------|
-| 🔴 CRITICAL | 6 | 5 | 1 |
-| 🟠 HIGH | 12 | 7 | 5 |
-| 🟡 MEDIUM | 14 | 0 | 0 |
-| 🟢 LOW | 8 | 0 | 0 |
-
-### Build Status ✅
-- `npx tsc --noEmit` → 0 source errors
-- `node scripts/check-all-skills.ts` → 35/35 pass
-
----
-
-## 🔴 CRITICAL ISSUES (Fixed ✅ / Remaining 🚨)
-
-### ✅ C1. Secret Credential Exposure via Child Pi Env Allow-List — FIXED
-
-**File:** `src/runtime/child-pi.ts:93-117`
-
-**Fixed:** Removed dangerous wildcards `"*_API_KEY"`, `"*_TOKEN"`, `"*_SECRET"` and replaced with explicit provider keys:
-```typescript
-"ANTHROPIC_API_KEY", "OPENAI_API_KEY", "GOOGLE_API_KEY", etc.
-```
-
----
-
-### ✅ C2. Mock Mode Bypass Without Warning — FIXED
-
-**File:** `src/runtime/child-pi.ts`
-
-**Fixed:**
-- Added `PI_CREW_ALLOW_MOCK=1` requirement alongside `PI_TEAMS_MOCK_CHILD_PI`
-- Added console warnings when mock mode is active
-- All mock responses now prefixed with `[MOCK]` for visibility
-
----
-
-### 🚨 C3. Arbitrary Code Execution via Worktree Hooks on Windows
-
-**File:** `src/worktree/worktree-manager.ts:133`
-
-**Issue:** On Windows, worktree setup hooks execute with `shell: true`, enabling command injection.
-
-**Fix Needed:** Remove `shell: true` on Windows. Execute hooks directly.
-
----
-
-### ✅ C4. Duplicate `error` Key + Promise Type Mismatch — FIXED
-
-**File:** `src/runtime/task-runner.ts:1016-1019`
-
-**Fixed:**
-- Removed duplicate `error` key
-- Changed async IIFE to synchronous `verificationEvidence` variable
-- Added `VerificationEvidence` import from types
-
----
-
-### ✅ C5. Decision Ledger Truncates All Entries on Write — FIXED
-
-**File:** `src/state/decision-ledger.ts:243-256, 283-293`
-
-**Fixed:** Created `overrideLastEntry()` helper that reads all entries, updates the last one, and writes all entries back instead of truncating.
-
-**Impact:** Security-sensitive operations return fake data without any indication.
-
-**Fix:** Require dual env vars + add startup warning banner.
-
----
-
-### C3. Arbitrary Code Execution via Worktree Hooks on Windows
-
-**File:** `src/worktree/worktree-manager.ts:133`
-
-**Issue:** On Windows, worktree setup hooks execute with `shell: true`, enabling command injection.
-
-**Fix:** Remove `shell: true` on Windows. Execute hooks directly.
-
----
-
-### C4. Duplicate `error` Key + Promise Type Mismatch
-
-**File:** `src/runtime/task-runner.ts:1016-1019`
-
-```typescript
-error,
-error,  // ← TS1117: Duplicate key
-verification: (async () => { ... })(),  // ← Promise assigned to non-Promise type
-```
-
-**Impact:** Verification logic falsified — `task.verification.satisfied` returns `Promise` object (always truthy).
-
-**Fix:** `await` the IIFE or change type to `Promise<VerificationEvidence>`.
-
----
-
-### C5. Decision Ledger Truncates All Entries on Write
-
-**File:** `src/state/decision-ledger.ts:243-256, 283-293`
-
-```typescript
-// CORRECT: append-only
-appendEntry(runId, entry);  // uses flag: "a"
-
-// WRONG: truncates entire file
-writeFileSync(getLedgerPath(runId), JSON.stringify(overridden) + "\n");
-//                    ↑ defaults to "w" (truncate)
-```
-
-**Impact:** All previous ledger entries destroyed. Data loss bug.
-
-**Fix:** Use append flag or rewrite entire file.
-
----
-
-### C6. Synchronous Event-Loop Blocking via Busy-Wait Lock
-
-**File:** `src/state/event-log.ts:55-92`
-
-```typescript
-while (!acquired) {
-  sleepSync(10);  // ← BLOCKS ENTIRE EVENT LOOP
-}
-```
-
-**Impact:** Up to 5 seconds of event-loop freeze. `AbortSignal` handlers cannot fire.
-
-**Fix:** Use async lock or write queue.
-
----
-
-## 🟠 HIGH PRIORITY ISSUES
-
-| # | Issue | Location | Impact |
-|---|-------|----------|--------|
-| H1 | Missing `ajv` dependency — schema validation silently disabled | `yield-handler.ts:10` | JSON Schema validation never runs |
-| H2 | Race condition in foreground interrupt (read-modify-write) | `foreground-control.ts:76-83` | Lost interrupt requests |
-| H3 | Buffered events lost on crash | `event-log.ts:228-254` | Terminal events like `task.failed` can be lost |
-| H4 | No authorization on team tool actions | `team-tool.ts` | Destructive actions accessible to any caller |
-| H5 | File descriptor leak (`logFd` never closed) | `background-runner.ts:75-89` | Resource exhaustion over time |
-| H6 | `PowerbarPayloadShape` missing `id` field | `powerbar-publisher.ts:209,217,247` | TypeScript errors, missing UI updates |
-| H7 | Module-level mutable state with concurrent access | `live-agent-manager.ts:69` | Race conditions in agent registration |
-| H8 | `verification-gates.ts` missing `durationMs` property | `runtime/verification-gates.ts:340` | Type inconsistency |
-| H9 | Stale cache serving outdated manifest (up to 5 min) | `state-store.ts:37-49` | Wrong task status, duplicate execution |
-| H10 | Non-atomic transcript writes | `child-pi.ts:351` | Malformed JSONL, usage data loss |
-| H11 | TOCTOU in temp directory creation | `pi-args.ts:80-96` | Symlink attack window |
-| H12 | All decision-ledger I/O is synchronous | `decision-ledger.ts` | Event-loop blocking |
-
----
-
-## 🟡 MEDIUM PRIORITY ISSUES
-
-### Code Quality
-
-| # | Issue | Location |
-|---|-------|----------|
-| M1 | `runTeamTask` function is ~1200 lines | `task-runner.ts` |
-| M2 | `executeTeamRunCore` is ~450 lines | `team-runner.ts` |
-| M3 | 377 bare `catch {}` blocks | Multiple files |
-| M4 | 50+ `// TODO:` comments | Multiple files |
-| M5 | `any` type usage: 200+ instances | Multiple files |
-| M6 | No comprehensive error typing | Multiple files |
-
-### Testing Gaps
-
-| # | Issue |
-|---|-------|
-| M7 | No integration tests for child-pi spawning |
-| M8 | No integration tests for background runner |
-| M9 | No tests for concurrent run isolation |
-| M10 | Mock/stub usage needs cleanup |
-
-### Documentation
-
-| # | Issue |
-|---|-------|
-| M11 | 19/35 skills (54%) missing `triggers` frontmatter field |
-| M12 | 13/35 skills (37%) are "minimal" tier — lacking examples/diagrams |
-| M13 | Skills use inconsistent section naming (TRIGGERS vs When to Use, etc.) |
-| M14 | No migration guide for v0.4 → v0.5 breaking changes |
-
----
-
-## 🟢 LOW PRIORITY OBSERVATIONS
-
-| # | Issue |
-|---|-------|
-| L1 | Inline function comments over inline JSDoc |
-| L2 | `npx tsc --noEmit` produces warnings (not errors) |
-| L3 | Some agent names have inconsistencies |
-| L4 | No dedicated performance profiling |
-| L5 | Logging level inconsistency (log/info/debug) |
-| L6 | Hardcoded timeouts could be configurable |
-| L7 | No dedicated deprecation policy |
-| L8 | Changelog could use more detail per version |
-
----
-
-## TypeScript Compilation
-
-```bash
-$ cd pi-crew && npx tsc --noEmit
-```
-
-**Expected errors (7):**
-1. `task-runner.ts:1016` — Duplicate `error` key
-2. `task-runner.ts:1019` — Promise type mismatch
-3. `powerbar-publisher.ts:209,217,247` — Missing `id` property
-4. `verification-gates.ts:340` — Missing `durationMs` property
-
-**Warnings (50+):**
-- Various unused variables
-- Implicit `any` types
-- Missing null checks
-
----
-
-## Recommendations
-
-### Immediate (Before Next Release)
-
-1. **Fix C1-C6** — Critical security and data-loss bugs
-2. **Add `ajv` dependency** or remove schema validation code
-3. **Fix H1-H5** — High-priority reliability issues
-
-### Short Term (Next Sprint)
-
-4. Decompose `runTeamTask` (~1200 lines) into smaller functions
-5. Standardize skill frontmatter (`triggers` field required)
-6. Add missing `Anti-Patterns` sections to minimal-tier skills
-7. Replace synchronous I/O in `decision-ledger.ts`
-
-### Medium Term
-
-8. Implement authorization checks on team tool actions
-9. Add comprehensive integration tests
-10. Create migration guide v0.4 → v0.5
-11. Replace `any` types with proper types (~200 instances)
-
----
-
-## Files Requiring Immediate Attention
-
-| Priority | Files |
-|----------|-------|
-| **Critical** | `src/runtime/child-pi.ts`, `src/state/decision-ledger.ts`, `src/runtime/task-runner.ts`, `src/state/event-log.ts` |
-| **High** | `src/runtime/yield-handler.ts`, `src/runtime/foreground-control.ts`, `src/extension/team-tool.ts`, `src/runtime/background-runner.ts`, `src/ui/powerbar-publisher.ts`, `src/runtime/live-agent-manager.ts` |
-| **Medium** | `src/runtime/team-runner.ts`, `src/state/state-store.ts`, `skills/*/SKILL.md` |
-
----
-
-## Conclusion
-
-pi-crew is a well-architected extension with strong fundamentals. The critical issues center on:
-1. **Security**: Over-broad env allow-lists, missing authorization
-2. **Data integrity**: Synchronous blocking, file truncation, buffered event loss
-3. **Type safety**: TypeScript errors, Promise type mismatches
-4. **Documentation**: Inconsistent skill formatting
-
-Addressing the 6 critical issues should be the highest priority before any production deployment.
-
----
-
-## 📊 Final Status (2026-05-29)
-
-### Documentation ✅
-
-| # | Issue | Status |
-|---|-------|--------|
-| M11 | 35/35 skills now have `triggers` frontmatter | ✅ Fixed |
-| M12 | 13/35 skills minimal tier | ⚠️ Partial (Enforcement sections added) |
-| M13 | Skills inconsistent section naming | ✅ Improved |
-| M14 | No migration guide | 📋 TODO |
-
-### TypeScript Compilation ✅
-
-```bash
-$ cd pi-crew && npx tsc --noEmit
-```
-
-**Result:** ✅ 0 source errors, 0 test errors (was 7+ source + 20+ test errors)
-
----
-
-## Summary
-
-| Category | Fixed | Total | Progress |
-|----------|-------|-------|----------|
-| 🔴 CRITICAL | 5 | 6 | 83% |
-| 🟠 HIGH | 7 | 12 | 58% |
-| 🟡 MEDIUM | 11 | 14 | 79% |
-| 🟢 LOW | 2 | 8 | 25% |
-| **TOTAL** | **25** | **40** | **62.5%** |
-
-### Files Changed
-- **61 files** modified (+967/-525 lines)
-
-### Build & Skills ✅
-- `npx tsc --noEmit` → 0 source errors
-- `node scripts/check-all-skills.ts` → 35/35 pass
-- All skills have `triggers:` frontmatter
-
-### Critical Fixes Applied
-1. ✅ Secret credential exposure (env allowlist)
-2. ✅ Mock mode bypass security
-3. ✅ Worktree hooks Windows security
-4. ✅ Decision ledger data loss
-5. ✅ Race conditions (foreground interrupt)
-6. ⚠️ Event-loop blocking (partial - sleepSync remaining)
-
-### Remaining Work
-- C6: Event-loop blocking (needs async rewrite)
-- M14: Migration guide → ✅ Created `docs/migration-v0.4-v0.5.md`
-- L*: Low priority improvements
-
----
-
-## 🟢 LOW PRIORITY STATUS (2026-05-29)
-
-| # | Issue | Status |
-|---|-------|--------|
-| L1 | Inline function comments over inline JSDoc | ✅ By design |
-| L2 | `npx tsc --noEmit` produces warnings | ✅ 0 warnings now |
-| L3 | Some agent names have inconsistencies | ⚠️ Minor |
-| L4 | No dedicated performance profiling | ⚠️ Not critical |
-| L5 | Logging level inconsistency (log/info/debug) | ⚠️ Debug logs in background-runner.ts |
-| L6 | Hardcoded timeouts could be configurable | ⚠️ Not critical |
-| L7 | No dedicated deprecation policy | ⚠️ Not critical |
-| L8 | Changelog could use more detail per version | ✅ v0.5.3 detailed |
-
-### Additional Work Completed (v0.5.3)
-
-- **CHANGELOG.md**: Updated with v0.5.3 entry
-- **Migration Guide**: Created `docs/migration-v0.4-v0.5.md`
-- **Test Fixes**: Fixed TypeScript errors in 6 test files
-- **Skills**: All 35 skills have `triggers:` frontmatter
-
-### Verification ✅
-
-```bash
-npx tsc --noEmit        # 0 source errors, 0 test errors
-node scripts/check-all-skills.ts  # 35/35 pass
-npx tsx test/unit/decision-ledger.test.ts  # 10/10 pass
-```