pi-crew 0.8.14 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,341 @@
 # Changelog
 
+## [v0.9.1] — Windows essentials fix + cross-platform CI green (2026-06-22)
+
+Patch release. No new features. Fixes a real Windows bug reported by a user,
+plus the cross-platform CI failures that followed.
+
+### fix(windows): `${APPDATA}` npm-global resolution failure (root cause)
+
+Reported symptom (Windows): running pi-crew created a phantom literal
+`${APPDATA}/npm/` directory in the project root (containing `node_modules`,
+`pi-crew`, `pi-crew.cmd`, `pi-crew.ps1`) and leaked a literal `${APPDATA}`
+line into `.gitignore`.
+
+Root cause: pi-crew's subprocess env sanitization used explicit allowlists
+that stripped **all Windows-essential env vars** (`APPDATA`, `LOCALAPPDATA`,
+`USERPROFILE`, `SystemRoot`, `ComSpec`, `TEMP`, `TMP`). When a child pi
+process (or npm inside it) tried to resolve the npm-global prefix on Windows,
+it used `%APPDATA%` (cmd expansion) / `${APPDATA}` (bash expansion), but
+`APPDATA` was missing from the env — so the shell left the literal
+`${APPDATA}` in place and operations created/ignored paths under that
+literal name.
+
+Fix: added the 7 Windows essentials to all 7 subprocess env allowlists
+(child-pi, async-runner, verification-gates, post-checks, iteration-hooks,
+worktree/cleanup, worktree/worktree-manager). (commit `a7ddc50`)
+
+### refactor(env): centralize Windows essentials + regression guard
+
+The same 7 vars were duplicated inline across 9 call sites — easy to forget
+on a new allowlist, with nothing preventing a future site from omitting them.
+
+- New single source of truth: `WINDOWS_ESSENTIAL_ENV_VARS` in
+  `src/utils/env-allowlist.ts` (with full root-cause documentation).
+- All 9 call sites now spread the constant instead of inlining (net −42/+19
+  lines, behavior unchanged).
+- New regression test `test/unit/env-allowlist.test.ts`: scans ALL
+  `src/**/*.ts` files and fails if any hardcodes the 7 vars inline (the only
+  allowed location is the constant file). This catches any new allowlist that
+  forgets the constant — the exact regression that caused the bug.
+(commit `6a0284c`)
+
+### fix(ci): cross-platform CI green (ubuntu + macOS + Windows)
+
+Three distinct containment/path bugs that only surfaced on non-ubuntu CI:
+
+1. **Windows 8.3 short-name paths** — `resolveWindowsCanonical()` used
+   non-native `realpathSync`, preserving the `RUNNER~1` vs `runneradmin`
+   form mismatch. A legitimately-contained dynamic workflow file was
+   rejected as "outside the allowed directories". Fixed by using
+   `realpathSync.native` (canonical long-name form) as the primary resolver.
+   (commit `e9e7137`)
+
+2. **ESM `file://` URLs** — two integration tests passed raw Windows paths
+   (`D:\…`) to native `import()`, which Node rejects on Windows
+   (`ERR_UNSUPPORTED_ESM_URL_SCHEME: protocol 'd:'`). Wrapped with
+   `pathToFileURL(…).href`. (commit `e9e7137`)
+
+3. **macOS symlink-ancestor** — `isSymlinkSafePath()` walked up the temp
+   path and hit `/var` (a symlink → `/private/var`). The old check compared
+   the resolved `/private/var` against the tmpdir
+   `/private/var/folders/…/T` — `/private/var` is an **ancestor**, not a
+   descendant, so it was wrongly rejected (5 macOS worker-atomic-writer
+   failures). Fixed by accepting a symlink whose target is a safe root, is
+   UNDER a safe root, OR is an ANCESTOR of a safe root. Added two behavioral
+   regression tests (symlink-ancestor accept + symlink-attack reject).
+   (commit `e9e7137`)
+
+4. **macOS `/var` containment** — `resolveContainedPath()` only
+   canonicalized paths on win32; on POSIX it compared raw paths, so base
+   (`/private/var`) vs target (`/var`) diverged → false "outside" rejection
+   (macOS dwf-setresult failure). Added platform-agnostic
+   `resolveCanonicalPath()`. Added a darwin-only regression test for the
+   real `/var` divergence. (commit `4821bb1`)
+
+5. **Windows wakeup timing** — `subagent-manager` polls the child run
+   manifest every 1000ms. On the slower Windows CI runner, child-process
+   spawn + first poll exceeded the test's 10s deadline (failed at 11.6s).
+   Bumped the mock-test deadline to 30s. (commit `4821bb1`)
+
+### Verification
+
+- tsc: 0
+- Full test suite: 5207 tests, 0 fail on **all three** platforms (ubuntu,
+  macOS, Windows)
+- CI run `27955398241`: success across ubuntu-latest, macos-latest,
+  windows-latest
+- Regression tests added: env-allowlist scan, worker-atomic-writer symlink
+  ancestor/attack, safe-paths darwin `/var` divergence
+
+### Breaking changes
+
+None. All fixes are additive or behavior-preserving. Windows users who hit
+the `${APPDATA}` bug should upgrade.
+
+---
+
+## [v0.9.0] — goal loops + dynamic workflows (2026-06-18)
+
+Two new features, both built on a shared `runKind` background-dispatch discriminator.
+
+### Phase 1.5 #4: TDZ fix — dynamic-workflow runs end-to-end via full pi pipeline (RFC 17 fix)
+
+Live `team action='run' workflow='<dynamic>'` was failing with
+`Dynamic workflow 'X' must export a default async function(ctx).` even
+though the .dwf.ts loaded correctly via direct jiti. Root cause was NOT
+in `dynamic-workflow-runner.ts` — it was a Temporal Dead Zone race in
+`team-tool/run.ts` when loaded via the full pi extension pipeline
+(`index.ts → register.ts → registration/team-tool.ts → team-tool.ts →
+run.ts`).
+
+**Race details**: jiti loads each .ts file inside an `async function
+_module(...)` wrapper. Static `import { X } from "..."` statements
+become `var _x = require(...)` calls. When a destructured `import` is
+referenced inside a hoisted function before its `let` declaration line
+runs, the reference hits TDZ.
+
+**Fixes**:
+- `src/extension/team-tool/run.ts`:
+  - `crewInitPromise`: `let` → `var` (avoids TDZ)
+  - `expandParallelResearchWorkflow`, `validateWorkflowForTeam`,
+    `normalizeSkillOverride`: convert to lazy dynamic imports at call site
+- `src/state/crew-init.ts`:
+  - `CREW_README`: `const` → `function buildCrewReadme(): string` (function
+    declarations are fully hoisted)
+  - `updateGitignore`: convert usage to lazy dynamic import at call site
+
+**New test**: `test/integration/run-via-full-pipeline.test.ts` loads
+`index.ts` via `jiti.import()` the way pi does, invokes `handleRun` with a
+dynamic workflow params, and asserts no TDZ / ReferenceError is thrown.
+Fails without the fix, passes with it.
+
+**Verification**:
+- 108 unit tests pass (goal, dwf, redaction, verification, worker-writer)
+- New integration test passes
+- Direct simulation of pi pipeline → `Dynamic workflow 'demo-hello'
+  completed` (was: `failed: must export a default async function`)
+
+Closes RFC 17 §4 round-trip / investigated residual. See
+`research-findings/goal-workflow/17-PHASE1.5-CRASH-INVESTIGATION-RFC.md`
+for the full 8-attempt investigation log (gdb, strace, V8 report, sync
+workarounds, worker-thread atomic writer, auto-downgrade — none
+identified the real bug because they all skipped the full pi load path).
+
+### Phase 1.5 #3: V8 diagnostic report infrastructure + crash investigation closed
+
+`PI_CREW_BG_REPORT_ON_FATAL=1` makes the background goal-loop runner spawn
+with `--report-on-fatalerror --report-compact`. When V8 considers the
+process state fatal, it writes a diagnostic report (native stack, JS stack,
+libuv handles, environment) — crucial info that application-level signal
+handlers cannot capture.
+
+**Investigation result** (RFC 17, 5+ reproduction attempts): the multi-step
+goal-wrap crash does NOT produce a V8 report. Combined with prior findings
+(no signal via strace, no coredump, no OOM, parent process alive) the crash
+signature is consistent with a V8/libuv internal abort that bypasses all
+Node.js reporting mechanisms. Cannot be diagnosed or fixed at the
+application level.
+
+**Decision**: ship with the existing auto-downgrade safety net
+(commit `6de5270`). Multi-step workflows silently run as normal team-runs
+(no goal-wrap layer); single-step workflows (implementation) continue to
+goal-wrap end-to-end. The `--report-on-fatalerror` infrastructure remains
+in place for future investigation if a Node.js version change alters the
+crash behavior.
+
+See `research-findings/goal-workflow/17-PHASE1.5-CRASH-INVESTIGATION-RFC.md`
+for the full 8-attempt investigation log and re-opening criteria.
+
+### Phase 1.5 #2: git-worktree verification sandbox (closes round-trip + invoked-script tamper)
+
+`PI_CREW_VERIFICATION_WORKTREE=1` runs verification commands in a pristine
+`git worktree` at the T_snap commit SHA. Closes the two remaining Med-High
+tampering residuals from RFC 13 §6 that P1a manifest hashing cannot detect:
+
+- **Round-trip manifest tamper (MAJ#2)**: worker edits `package.json`, runs
+  `npm test` (passes), reverts before T_verify_done → hash matches →
+  tamper undetected. With worktree: verification runs at original SHA →
+  worker edits invisible → tamper BLOCKED.
+- **Invoked-script tampering**: worker rewrites a script the verification
+  command invokes; only MANIFEST_FILES are hashed → invisible. With
+  worktree: script is at original SHA → tamper BLOCKED.
+
+Graceful fallback when ANY precondition fails (logged via
+logInternalError "goal-loop.worktreeSandboxBypassed"): opt-out env,
+not-a-git-repo, dirty index, git unavailable. NEVER blocks the goal loop.
+
+Implementation:
+- `src/runtime/verification-worktree.ts` (NEW, pure leaf module):
+  `isWorktreeSandboxEnabled`, `checkWorktreeSandboxAvailable`,
+  `prepareVerificationWorktree` (git worktree add --detach),
+  `withVerificationWorktree` (RAII cleanup, idempotent, finally-safe).
+- `src/runtime/verification-gates.ts`: `executeVerificationCommands`
+  accepts optional `worktreeCwd` — spawns commands with that cwd.
+- `src/runtime/goal-loop-runner.ts`: verification call site prepares
+  worktree at T_snap SHA when available; finally block always cleans up.
+- `src/runtime/async-runner.ts`: PI_CREW_VERIFICATION_WORKTREE env
+  inherited by bg-runner.
+
+Tests: 12 new unit tests in `test/unit/verification-worktree.test.ts`
+(flag opt-in, not-a-repo fallback, dirty-index fallback, clean-repo success,
+pristine-checkout property = the security guarantee, RAII cleanup on success
++ on exception, idempotent cleanup). All pass.
+5200 unit + 115 integration tests; no regression; tsc clean.
+
+RFC: `research-findings/goal-workflow/16-PHASE1.5-WORKTREE-SANDBOX-RFC.md`
+
+### Phase 1.5 #1: sanitized-env verification (opt-in info-disclosure mitigation)
+
+`PI_CREW_VERIFICATION_SANITIZE_ENV=1` strips model-provider secrets (and
+everything else not in the essential-vars allowlist) from the env passed to
+verification commands (`npm test`, `pytest`, etc.). Closes the info-disclosure
+residual at the SOURCE — P1f redaction at artifact-write + judge-bound is
+regex-best-effort against adversarial workers; this never gives the
+verification process the secret in the first place.
+
+Escape hatch: `PI_CREW_VERIFICATION_PRESERVE_ENV=KEY1,KEY2,...` lets users
+explicitly opt specific env vars back in (audited via the env-filter.ts
+allowlist validator). Essential non-secret vars (PATH, HOME, USER, SHELL,
+LANG, XDG_*, NPM_CONFIG_*, etc.) are always preserved.
+
+AllowList: 25 essential vars. NO model-provider keys by default.
+Inherited by bg-runner via async-runner.ts env allowlist.
+
+Tests: 7 new unit tests in test/unit/verification-env-sanitize.test.ts
+(3 flag checks + 4 integration tests spawning real `printenv` subprocesses).
+All pass. 5188 unit + 115 integration tests; no regression.
+
+### SAFETY: goal-wrap auto-downgrades multi-step workflows (no hidden crashes)
+
+Multi-step workflows (default: 4 steps, fast-fix: 3 steps) crash
+non-deterministically when run as goal-wrap worker turns in the background
+goal-loop process — V8/libuv race during event-loop yields in team-runner
+batch transition (see commit a9f6e09, RFC 15). Sync fs workarounds regress;
+worker-thread isolation doesn't help.
+
+When a user has goal-wrap enabled in config but the workflow is multi-step,
+the team-run handler now **auto-downgrades**: skips the goal-wrap layer and
+runs the workflow via the normal team-run path (foreground `executeTeamRun`
+or background `spawnBackgroundTeamRun`, depending on `async`). The user gets
+the run they asked for — no error, no hang, no need to remove config.
+
+The bypass reason is logged via `logInternalError("team-tool.run.goalWrapBypassed", ...)`
+for traceability (findable in debug logs / `internal-error.json`).
+
+Single-step workflows (e.g. `implementation`, only the adaptive `assess`
+step) continue to be goal-wrapped end-to-end.
+
+Implementation:
+- `shouldGoalWrap(cwd, workflow)` — pure decision function returning
+  `{enabled: true}` or `{enabled: false, reason, message}`. Reasons:
+  `config-off` (not enabled), `invalid-config` (malformed), `multi-step`
+  (more than `GOAL_WRAP_MAX_STEPS = 1` step).
+- `run.ts` calls `shouldGoalWrap` after `isGoalWrapEnabled`; if disabled,
+  falls through to normal team-run path. The original `isGoalWrapEnabled`
+  fast path (config check only) is kept as a cheap pre-filter.
+- 5 new unit tests in `test/unit/goal-wrap.test.ts` cover all 4 decisions
+  (config-off / invalid-config / multi-step refuse / single-step accept)
+  + the GOAL_WRAP_MAX_STEPS value invariant.
+
+### Phase 1.5: worker-thread atomic writer (opt-in, infrastructure)
+
+`PI_CREW_WORKER_ATOMIC_WRITER=1` routes `atomicWriteFileAsync` and
+`appendEventAsync` through a dedicated worker thread that performs SYNC fs
+ops with no internal yields. Implementation: `src/state/worker-atomic-writer.ts`.
+9 unit tests; 5169 existing tests pass; no regression.
+
+**Test result**: worker writer does NOT fix the multi-step crash (verified
+end-to-end with `default` workflow). The crash is NOT in fs writes — worker
+writes complete successfully but the process still dies during batch
+transition. Root cause is some other async operation yielding the main
+event loop. See `research-findings/goal-workflow/15-PHASE1.5-WORKER-WRITER-RFC.md`
+for full investigation notes.
+
+The worker writer is kept as **infrastructure** — opt-in, well-tested, no
+regression. It may help with future variants or concurrent-write contention.
+
+### Resolution: multi-step goal-wrap crash (3/3 tasks now complete end-to-end)
+
+The silent crash at `atomicWriteFileAsync` of the inner turn's `manifest.json`
+(size=7417) — which caused `team action='run' workflow='fast-fix'` (and other
+multi-step builtins) to hang at "1/3" forever — is **resolved** as a side
+effect of commit `d52cb81` ("fix(goal-wrap): persist async.pid on OUTER
+goal-loop manifest"). The extra `atomicWriteJson(manifestPath, asyncGoalManifest)`
+call in `startGoalWrappedRun` after `spawnBackgroundTeamRun` shifts timing
+enough to avoid the underlying race condition.
+
+Verified end-to-end with 3 consecutive runs of goal-wrapped fast-fix
+(`fix test.js so npm test passes`): all completed 3/3 tasks in ~120s with
+`npm test` PASS. The original deep-dive investigation (commit `a9f6e09`) is
+preserved as a reference; the proximate crash trigger is a Node.js / V8 /
+filesystem-level race that is not reliably reproducible in either direction.
+
+The user-facing symptom (must kill pi to recover from 1/3 hang) is also
+resolved: even if a future regression reintroduces the crash, async-notifier
+will detect the dead background-runner within ~30s and emit `async.died` —
+the user sees "Goal failed: Background runner died unexpectedly" instead of
+an infinite "running" state.
+
+
+
+### `goal` — autonomous goal loop (P0a + P0 + P1)
+
+- `team action='goal' config.subAction='start|status|pause|resume|stop|step|clear'`.
+- A worker does a turn (`executeTeamRun`), then a separate LLM judge (synthesized
+  `goal-judge` AgentConfig with `disableTools:true` → Pi `--no-tools`) evaluates the
+  transcript + evidence and returns `{achieved, reason, evidenceRefs}`. On
+  not-achieved, the `reason` is composed into the next turn's `manifest.goal`.
+- One manifest PER turn (status-transition invariants block reuse). Budget via
+  `collectRunMetrics`. `GoalLoopState` persisted at `<crewRoot>/state/goals/<goalId>.json`.
+- Slash command `/team-goal`. Hooks: `before_goal_step`, `before_goal_abort`.
+- Spec-driven: `research-findings/goal-workflow/00-SPEC.md` + `07-PLAN.md` v3.
+
+### `workflow` — dynamic workflow scripts (P2 + P3)
+
+- `.dwf.ts` scripts orchestrate subagents via `ctx.agent()` / `ctx.fanOut()` with
+  JS loops/branch/cross-review; only `ctx.setResult()` reaches the main context.
+- Full `WorkflowCtx`: `agent`, `fanOut`, `review`, `retry`, `mail`, `gatherReplies`,
+  `renderTemplate`, `vars`, `setResult`.
+- `team action='workflow-{create,get,list,save,delete}'`. `workflow-create`/`-delete`
+  ACE-gated via `destructive-gate.ts` (`confirm:true`, user-initiated only, path-
+  allowlisted via `resolveRealContainedPath`, content-validated).
+- Capability-locked `WorkflowCtx` (Object.freeze + vm.runInNewContext);
+  `isolated-vm` deferred to v1.5.
+- Slash command `/workflows`. Example: `workflows/examples/hello.dwf.ts`.
+
+### Shared infra (P0a)
+
+- `manifest.runKind?: 'team-run' | 'goal-loop' | 'dynamic-workflow'` discriminator;
+  background-runner.ts dispatches to `executeTeamRun` / `runGoalLoop` /
+  `runDynamicWorkflow`. Default `'team-run'` (backward-compatible).
+
+### Other
+
+- `AgentConfig.disableTools?: boolean` — pushes Pi `--no-tools` (capability-locked agents).
+- `TEAM_EVENT_TYPES` += `goal.*` + `dwf.*` namespaces.
+- New agent-config field, new event types, new hooks — all additive, no breaking changes.
+
 ## [0.8.12] — `team action=cleanup` now reverses `init` (Issue #35) (2026-06-17)
 
 `team action=cleanup` gained a **project-level mode** that reverses what
@@ -2653,3 +2989,33 @@ user's project-instructions file was out-of-scope and unnecessary.
 
 +4 regression tests (init does NOT create/modify AGENTS.md; API fields removed).
 typecheck clean; full suite 2972/0.
+
+## [Unreleased] — dead-dep cleanup + non-blocking fallow CI (2026-06-18)
+
+Spotted by running `fallow` (deterministic Rust codebase intelligence) against
+the repo. Two genuine wins, plus an informational CI job that never blocks.
+
+### Removed (dead dependencies, verified unused)
+- **`typebox`** (`package.json:89`) — dead duplicate of `@sinclair/typebox`
+  (which 10 source files actually import). `typebox` (plain) had **zero**
+  imports anywhere in `src/`.
+- **`acorn`** (`package.json:84`) — **zero** runtime references in `src/`,
+  `scripts/`, or `*.mjs`. Verified the only other package referencing it
+  (`jiti`) lists it under its own `devDependencies` (for jiti's own tests), so
+  it is not a runtime transitive need. `npm ls acorn` confirmed `pi-crew` was
+  its sole parent.
+
+  Both removals verified: typecheck clean, full suite 2965/0.
+
+### CI: added `fallow-audit` job (non-blocking)
+- New job in `.github/workflows/ci.yml`: ubuntu-only, `continue-on-error: true`
+  so it **never fails the build**.
+- Runs `fallow audit` (changed-code diff vs base ref) in JSON + human summary,
+  uploads `fallow-audit-report` artifact (14-day retention).
+- Surfaced findings (dead code, circular deps, duplication, complexity
+  hotspots, dependency hygiene) are for human/agent review, NOT a merge gate.
+- Rationale for non-blocking: fallow has high out-of-the-box noise (254 clone
+  families, 379 hotspots) + a false positive on the tsx/jiti path-loading
+  pattern (`jiti` flagged unused but is used via runtime path-loading). A
+  blocking gate would create an unpaid maintenance backlog unsuitable for a
+  solo-maintained extension.

package/README.md

@@ -1,5 +1,35 @@
 # pi-crew
 
+> ## ⚠️ IMPORTANT — Read before using
+>
+> **pi-crew is a sub-agent orchestration layer that was developed almost entirely
+> by AI, for the author's own workflow.** It is **not** a hardened, audited
+> product. Here's the honest framing:
+>
+> - **AI-generated code, limited human review.** The vast majority of pi-crew
+>   was written and iterated on by autonomous AI agents. While every change
+>   goes through static review + runtime tests, I (the author) have not
+>   line-by-line verified everything. There will be bugs, edge cases, and
+>   behaviors I haven't anticipated.
+> - **It can spawn processes, run shell commands, and write files on your
+>   behalf.** Dynamic workflows (`.dwf.ts`) and goal loops run with the same
+>   privileges as your Pi session — treat any `.dwf.ts` like `node script.js`
+>   you downloaded from the internet.
+> - **Built for *my* needs, not yours.** This scratches a personal itch. It
+>   likely won't fit every workflow, team setup, or risk tolerance — and
+>   that's fine.
+>
+> **If that sounds too risky, don't use it** — no hard feelings.
+>
+> **If you still want to use it**, the safest path is to **fork it, read the
+>   parts you'll touch, and adapt it to your own setup.** If you find a bug,
+>   a footgun, or a sharp edge, please open an issue or send a note — your
+>   feedback is genuinely appreciated. Thanks. ✌️
+>
+> See also: [SECURITY-ISSUES.md](SECURITY-ISSUES.md),
+> [docs/dynamic-workflows.md](docs/dynamic-workflows.md#security-model-important)
+> (trust model), and the [Known limitations](#known-limitations) section below.
+
 **Coordinate AI agent teams inside [Pi](https://github.com/nicekate/pi-coding-agent).**
 
 pi-crew is a Pi extension that orchestrates autonomous multi-agent workflows — research, implementation, review, testing, and more — with durable state, parallel execution, worktree isolation, and safe defaults.
@@ -9,13 +39,52 @@ npm: pi-crew
 repo: https://github.com/baphuongna/pi-crew
 ```
 
-**v0.8.11**: See [CHANGELOG.md](CHANGELOG.md).
+**v0.9.0**: See [CHANGELOG.md](CHANGELOG.md).
 
-### Highlights (v0.6.4 → v0.8.11)
+### Highlights (v0.6.4 → v0.9.0)
 
 A long arc of **trust, cliff-resilience, and robustness** work. Principle: *build
 trust and cliff-resilience, stay lean, delete before adding.*
 
+#### v0.9.0 — goal loops + dynamic workflows (2026-06-18)
+Two new features, both modeled on Claude Code, built on a shared `runKind`
+background-dispatch discriminator.
+
+- **🎯 Autonomous goal loops** — `team action='goal'` runs a self-directed
+  multi-turn loop: a **worker** does a turn, a separate **LLM judge**
+  (capability-locked, no tools) evaluates the transcript + verification against
+  the objective, and on "not-achieved" the reason is fed into the next turn's
+  prompt. Stops on `achieved` / `maxTurns` / budget / `BLOCKED:` / user `stop`.
+  See [docs/goals.md](docs/goals.md).
+- **📜 Dynamic workflows (`.dwf.ts`)** — author orchestration as a TypeScript
+  script (JS loops/branch/cross-review) instead of a static step list. Runs in
+  the background, spawns subagents via `ctx.agent()`/`ctx.fanOut()`, holds
+  intermediate results in JS variables, and only `ctx.setResult()` reaches the
+  main context. `workflow-create`/`-delete` are ACE-gated (`confirm:true`,
+  user-confirmed). See [docs/dynamic-workflows.md](docs/dynamic-workflows.md).
+- **🛡️ Goal-wrap** (RFC v0.5 vision) — apply the goal completion-guarantee to
+  existing builtin workflows (`implementation`, `fast-fix`, `default`) via
+  per-workflow `.crew/config.json` toggle. Single-step workflows goal-wrap
+  end-to-end; multi-step workflows auto-downgrade to a normal team-run because
+  they crash non-deterministically under the V8/libuv event-loop (see [Known
+  limitations](#known-limitations)).
+- **🔐 Phase 1 integrity hardening** (P1a–P1g) — verification bookend snapshots,
+  anti-oscillation (`stuck` non-terminal + resumable), budget enforcement
+  (required or explicit opt-out), nonce-token feedback sanitization, secret
+  redaction at artifact-write (O(n) fix), global worker cap + workspace lock
+  (O_EXCL, startTime-safe). B2 confused-deputy (auto-detecting verification
+  commands) refused — user must declare verification explicitly.
+- **🧪 Phase 1.5 fast-follow** — opt-in mitigation toggles for residual risks:
+  `PI_CREW_VERIFICATION_SANITIZE_ENV=1` (strip provider secrets from the
+  verification subprocess), `PI_CREW_VERIFICATION_WORKTREE=1` (run verification
+  in a pristine git worktree at the T_snap commit SHA),
+  `PI_CREW_BG_REPORT_ON_FATAL=1` (V8 diagnostic report on fatal).
+- **🐛 TDZ fix** (Phase 1.5 #4) — live `team action='run' workflow='<dynamic>'`
+  was failing with a misleading "must export a default async function" error.
+  Root cause was a Temporal Dead Zone race in `team-tool/run.ts` when loaded via
+  the full Pi extension pipeline (`index.ts → … → run.ts`). Fixed by
+  `let`→`var` on the latch + lazy dynamic imports at call sites.
+
 #### v0.8.x — hardening & reliability (2026-06-17)
 - **🛠️ Split-scope install fix (v0.8.11)** — `team` runs no longer crash with
   `Cannot find module '@earendil-works/pi-coding-agent'` when pi-crew and pi
@@ -75,6 +144,8 @@ trust and cliff-resilience, stay lean, delete before adding.*
 - **Scheduled runs** — `schedule`/`scheduled` actions with cron, interval, and one-shot support; spawned runs tracked and auto-cancelled on job removal
 - **Plugin system** — framework-aware context injection (Next.js, Vite, Vitest) via plugin registry
 - **Health scoring** — penalty-based run health with time-series snapshots
+- **Autonomous goal loops** (P0/P1) — `team action='goal'` runs an autonomous multi-turn loop: a worker does a turn, a separate LLM judge evaluates the transcript+evidence against the goal, and on "not-achieved" the reason is fed into the next turn's prompt. Stops on achieved / maxTurns / budget / blocked. Claude-Code-style `/goal`. See `docs/goals.md`.
+- **Dynamic workflows** (P2/P3) — author orchestration as a `.dwf.ts` script (JS loops/branch/cross-review) instead of a static step list. The script runs in the background, calls subagents via `ctx.agent()`/`ctx.fanOut()`, holds intermediate results in JS variables, and only `ctx.setResult()` reaches the main context. `workflow-create`/`-delete`/`-save` require `confirm:true` at the tool-call layer (the only gate — a malicious agent that passes `confirm:true` programmatically bypasses it; this is postinstall-equivalent trust, not a human-in-the-loop dialog). See `docs/dynamic-workflows.md`.
 
 ---
 
@@ -582,6 +653,8 @@ Stats: **366 source files** (70K lines) · **506 test files** (66K lines) · **4
 | [docs/troubleshooting.md](docs/troubleshooting.md) | Common errors, recovery, and error-code reference (E001–E012) |
 | [docs/architecture.md](docs/architecture.md) | Internal architecture + run flow |
 | [docs/runtime-flow.md](docs/runtime-flow.md) | Runtime execution details |
+| [docs/goals.md](docs/goals.md) | **v0.9.0** Autonomous goal loops (`team action='goal'`) |
+| [docs/dynamic-workflows.md](docs/dynamic-workflows.md) | **v0.9.0** `.dwf.ts` script runtime + trust model |
 | [docs/live-mailbox-runtime.md](docs/live-mailbox-runtime.md) | Mailbox + live-session runtime |
 | [docs/publishing.md](docs/publishing.md) | Release & publish process |
 | [docs/next-upgrade-roadmap.md](docs/next-upgrade-roadmap.md) | Future upgrade roadmap |
@@ -591,6 +664,43 @@ Research docs (not in package): [`docs/pi-crew-research/`](https://github.com/ba
 
 ---
 
+## Known limitations
+
+This is AI-developed software built for a personal workflow. These are the
+sharp edges I'm aware of — there are almost certainly others I'm not.
+
+- **Multi-step goal-wrap crashes non-deterministically.** Goal-wrapping
+  multi-step builtin workflows (`fast-fix`, `default`) can hit a V8/libuv
+  event-loop race that kills the background process with no signal, no core,
+  and no V8 diagnostic report (8 investigation attempts: gdb, strace, perf,
+  `--report-on-fatalerror`, sync-fs workarounds, worker-thread atomic writer —
+  see `research-findings/goal-workflow/17-PHASE1.5-CRASH-INVESTIGATION-RFC.md`).
+  **Mitigation:** multi-step workflows silently auto-downgrade to a normal
+  team-run (no goal-wrap layer); single-step workflows (`implementation`)
+  goal-wrap end-to-end.
+- **`.dwf.ts` scripts are NOT sandboxed in v1.** The `WorkflowCtx` is
+  `Object.freeze()`d, but the script runs in plain module scope with full
+  `require`/`import`/`process` access (postinstall-equivalent trust).
+  `isolated-vm` (real V8 isolate) is planned for a future release. Only place
+  `.dwf.ts` files you have reviewed. See
+  [docs/dynamic-workflows.md#security-model-important](docs/dynamic-workflows.md#security-model-important).
+- **Editor/agent file caching.** After editing a loaded pi-crew source file,
+  restart the Pi session for changes to take effect (jiti in-memory cache).
+  Editing a `.dwf.ts` in place while a run is mid-flight can serve a stale
+  module body; rename the file or restart Pi to force a fresh load.
+- **Verification integrity is best-effort against adversarial workers.** The
+  bookend snapshot (P1a) and git-worktree sandbox (Phase 1.5 #2, opt-in)
+  raise the bar, but a worker in the same process can still tamper with files
+  outside the snapshot window. Full isolation requires the planned sandbox.
+- **Single maintainer + AI review.** Every change ships after 2+ consecutive
+  clean static-review rounds + runtime tests, but there's no independent human
+  audit. Fork and read before trusting anything that touches your data.
+
+If you hit any of these — or a new one — please
+[open an issue](https://github.com/baphuongna/pi-crew/issues).
+
+---
+
 ## Acknowledgements
 
 `pi-crew` builds on ideas and selected MIT-licensed implementation patterns from `pi-subagents` and `oh-my-claudecode`, with conceptual inspiration from `oh-my-openagent`.

package/docs/FEATURE_INTAKE.md

@@ -1,6 +1,6 @@
 # Feature Intake
 
-Mọi implementation prompt phải đi qua intake gate trước khi code changes.
+Every implementation prompt must pass through the intake gate before code changes.
 
 ## Intake Flow
 

package/docs/HARNESS.md

@@ -1,11 +1,12 @@
 # Harness
 
-pi-crew là một Pi extension cho multi-agent orchestration. Harness này giúp
-agents và humans phối hợp phát triển pi-crew một cách reliable, inspectable,
-và dễ steer.
+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.
 
-Product là pi-crew chính nó. Harness là môi trường operating để agents hiểu
-product, classify work, track decisions, và validate changes.
+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
 
@@ -36,26 +37,26 @@ Human intent (issue, prompt, request)
   Next intent
 ```
 
-Mỗi task có 2 outputs:
+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 đọc theo thứ tự:
+Agents read in this order:
 
-1. `AGENTS.md` — operating rules và important paths
-2. `docs/HARNESS.md` — file này, collaboration model
-3. `docs/FEATURE_INTAKE.md` — trước khi biến request thành work
+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 và completed stories
+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 đã có validation commands:
+pi-crew already has validation commands:
 
 | Level | Command | What it proves |
 |-------|---------|----------------|
@@ -68,14 +69,14 @@ Agents **must not** claim validation passes without running the actual command.
 
 ## Growth Rule
 
-Harness grows từ friction. Khi agent:
-- Bị confused về expected behavior
-- Phải repeat manual reasoning
-- Thiếu validation command
-- Discover missing rule
-- Thấy recurring failure pattern
+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
 
-→ Agent must improve harness directly hoặc propose trong `docs/HARNESS_BACKLOG.md`.
+→ The agent must improve the harness directly or propose changes in `docs/HARNESS_BACKLOG.md`.
 
 ## Working Conventions