pi-crew 0.9.56 → 0.9.58

package/AGENTS.md

@@ -10,7 +10,7 @@ Read in this order:
 2. `docs/HARNESS.md` for the human-agent collaboration model.
 3. `docs/FEATURE_INTAKE.md` before turning any request into work.
 4. `docs/product/` for current product contracts.
-5. `docs/ARCHITECTURE.md` for implementation shape.
+5. `docs/architecture.md` for implementation shape.
 6. `docs/stories/` for story packets and backlog.
 7. `docs/TEST_MATRIX.md` for proof status.
 8. `docs/decisions/` for why important choices were made.

package/CHANGELOG.md

@@ -3,6 +3,67 @@
 > **Note:** `atomic-write-v2.ts` / `AtomicWriter` mentioned in historical entries below was consolidated into `atomic-write.ts` as of v0.9.42. This changelog is preserved as historical record — the migration was completed (the v2 class was never adopted; v1 won on simplicity + symlink-safety + link+unlink atomicity). See `docs/migration/atomic-write-v2-migration.md` for the decision rationale.
 
 
+## [0.9.58] — fix load crash on stale hoisted typebox: defensive guard + bundle vendoring (survives `pi update`) + round-1/round-2 fixes (2026-08-04)
+
+### Bug fixes
+
+- **CRITICAL — extension failed to load after 0.9.57 update (`Cannot read properties of undefined (reading 'Set')`)**. `src/schema/team-tool-schema.ts` called `TypeRegistry.Set("StringEnum", …)` at module top-level. `TypeRegistry` only exists in `@sinclair/typebox@0.34.50+`, but pi-crew declared `^0.34.50`. Pi installs **all** extensions into **one** shared npm store with hoisted deps, and on update it only re-checks the extension's own `package.json` version — if pi-crew is already latest, it does **not** re-resolve transitive deps. So an install could land pi-crew@0.9.57 (needs `TypeRegistry`) over a stale hoisted `@sinclair/typebox@0.34.49` (no `TypeRegistry`). Under ESM↔CJS interop, `import { TypeRegistry }` then resolved to `undefined`, and the unguarded top-level `TypeRegistry.Set(…)` crashed extension load (the bundle path swallowed it and fell through to strip-types, where it was uncaught). `--force` only applies to self-update, not extensions, so the dirty dep tree was never healed.
+  - **Fix 1 — defensive guard (src / strip-types path)**: feature-detect `TypeRegistry` (`HAS_TYPE_REGISTRY`) and skip registration when absent. `buildStringEnum()` (renamed from the internal `stringEnum`, now exported) takes an injectable `hasRegistry` flag and falls back to a verbose-but-validating `Type.Union` of `Type.Literal`s when `TypeRegistry` is missing — so the extension **always loads** regardless of the store's typebox version. `Value.Check` works natively in both branches.
+  - **Fix 2 — vendor `@sinclair/typebox` into the bundle (`scripts/build-bundle.mjs`, removed from `external`)**: this is what makes pi-crew **run the correct/optimal version after `pi update --all|--extensions`**. The bundle now ships its own typebox (built-in ≥0.34.50) with **zero external `@sinclair/typebox` imports**, so pi-crew is fully immune to whatever stale typebox the shared store holds — under ANY update mechanism. The compact `StringEnum` path (not the verbose fallback) is always active. SAFE to bundle: host pi/pi-ai validate tools with the *unscoped* `typebox` package (not `@sinclair/typebox`), so pi-crew's vendored copy never overlaps pi-ai's instance — they were already separate. (Fix 1 stays as a safety net for the strip-types dev fallback.)
+  - Verified: `test/unit/schema/stringenum-typebox-guard.test.ts` exercises both `buildStringEnum` branches against real typebox `Value.Check`; all 95 `test/unit/schema/**` + 245 blast-radius tests green; `tsc --noEmit` clean; bundle-load 2/2; bundle has **zero external `@sinclair/typebox` imports** (self-contained); bundle 2.99 MB (budget 3.5 MB).
+  - User remedy: once 0.9.58 is published, just `pi update --extensions` (or `pi update --all`). The 0.9.57→0.9.58 version bump forces a reinstall, and the new bundle carries its own typebox — no manual store cleanup needed. (On an already-broken machine: start once with `pi -ne`, run the update, then restart normally.)
+
+### Also bundled in 0.9.58 (already on main, unreleased)
+
+- **Round-1 security hardening** (`ea03dd88`): strip `runtime.agentExtensions` from untrusted project config, harden untrusted-data fence injection (no `</untrusted-…>` escape), filter `PI_CREW_*` secrets from child-Pi env.
+- **Round-2 locking fixes** (`6a5d8d16`): PID-guarded `releaseOwnLock` (LOCK-1 — no longer deletes a stolen lock in the `finally`), and `handleResume` releases the resume `withRunLock` before the minutes-long `executeTeamRun` (LOCK-2).
+- **Round-3 correctness** (`ae36cd2a`): `taskTimeoutMs` no longer capped at 10s by the wrong `runtimeMaxTurns` ceiling (RT-NEW-1 — 5-minute timeouts silently disabled before); worktree dirty-snapshots pass `-c core.quotePath=false` so non-ASCII filenames are no longer silently dropped before `git clean -fd` (STATE-8 data-loss fix).
+- **Round-4 state recovery** (`7b7968d5`): corrupt `manifest.json`/`tasks.json` are now quarantined (`.corrupt-<ts>`) + logged instead of silently making a run invisible (STATE-3); the stale-reconciler and health-monitor use the recovery loaders instead of bare `JSON.parse` that silently skipped corrupt runs (NEW-R1/R2).
+- **Round-5 batch** (`59505265`, `26d07b76`, `a0fa1cb2`, `135dfc8b`): state/atomic (async `mode` option, compact `tasks.json`, hash-on-memory, atomic mailbox/subagent/gitignore writes, async-twin manifest quarantine), defense-in-depth (DI-1..DI-4, lazy yaml, bundle-mode warmup skip), TOCTOU `existsSync`+`readFileSync` fixes (NEW-P4), budget-abort drains in-flight units via shared `terminaliseRunWithDrain` (RT-NEW-2), benign signals no longer write terminal `async.failed` (RT-NEW-3), event-log tail-read for notifier/status (STATE-5), lazy `cli-highlight` + lazy `npm root -g` probe + provider-extension cache (PERF-1/2/3), themes mtime fast-path (PERF-7), `userPiRoot` cache keyed on home (NEW-P2 isolation fix).
+- **Bundle rebuild note**: `dist/index.mjs` was rebuilt after R3–R5 — the earlier 13:35 build contained only R1/R2 + the typebox vendoring. Verify the shipped bundle includes the R3+ markers before publishing.
+
+### Note on postinstall "bundle build FAILED" message
+
+- Harmless and expected on published installs: `scripts/build-bundle.mjs` is intentionally omitted from the npm tarball (`files` list) so the committed `dist/index.mjs` is used as-is. `postinstall.mjs` reports the script's absence as a red FAILED line; the install succeeds via the committed bundle. (No code change — documenting so the red line is not mistaken for the load crash.)
+
+### Late-0.9.58 additions — schema validation repair, prune dryRun, cleanup (post round-6)
+
+- **Schema — empty-string unset markers** (`9173c6c4`, `bb47191e`): `replyDeadline`, `interval`, `budgetWarning`, `budgetAbort`, `tokenBudget` now accept `""`. Calling models emit `""` for unset optional fields, and pi-ai `validateToolArguments` runs BEFORE the pi-crew handler — a bare `Type.Integer`/`Type.Number` rejected `""` → every team action returned `Validation failed for tool team` and the model looped. Added `Type.Literal("")` to each union.
+- **Schema — stringified numbers** (`9064343b`): pi-ai's tool-argument coercion stringifies a numeric value when the schema `Union` has a string-literal branch (e.g. `interval:0` arrived as `"0"`). Broadened the 5 numeric-union fields to also accept a numeric-string pattern branch, and added `normalizeLooseNumericFields()` in `handleTeamTool` to coerce the string form back to a real number (and treat `""` as unset) before domain routers read params. Without this, `team prune` and any call sending these optional numeric fields with value `0` failed validation.
+- **prune dryRun now a true non-destructive preview** (`85f657c6`, `d5d42032`): `handlePrune` ignored `params.dryRun` entirely — it only checked `confirm`, then deleted. A caller requesting a preview (`dryRun:true`) with `confirm:true` got runs DELETED instead of listed (data-safety bug). `pruneFinishedRuns` now takes a `dryRun` option (stops after the read-only safety check — no deletion, no worktree cleanup, no audit); `handlePrune` lets `dryRun` bypass `confirm`; the `tool_call` destructive gate now allows `prune dryRun=true` (previously only `cleanup` was exempt).
+- **forget resurrect fix** (`672a3d4d`): a still-alive background runner could land one final heartbeat write after the first `rmSync` in `handleForget` — `atomicWriteFile`'s `mkdirSync(recursive)` re-created the state dir, resurrecting `heartbeat.json` in a dir we just forgot. Now drains briefly (250ms) and re-removes any resurrected residue.
+- **Round-6 resource cleanup** (`9f81a081`): `stopAllWatchdogs()` exported + called in `cleanupRuntime`; `RunDeadline.timer` cleared in all 4 run paths (dwf/async/fg/inline); foreground-abort `removeEventListener`.
+- **CI green**: lint + format:check + full `npm test` pass on ubuntu/windows/macos (3 OSes). `2db4c6bc` fixed biome lint/format gaps; `9808f3b0` fixed a macOS-only path-divergence bug in the corrupt-index test.
+
+## [0.9.57] — provider-extension auto-discovery + team-tool schema repair + whole-project reorganization (2026-08-03)
+
+### New: provider extensions work in subagents (no hardcoding)
+- pi-crew spawns child-pi workers with `--no-extensions` (security posture from SEC-1), which made extension-registered providers (e.g. `pi-commandcode-provider`) unresolvable in subagents → their models fell back to a secondary provider (429 rate-limit deaths, 0 tool uses).
+- **Auto-discovery**: pi-crew now reads `~/.pi/agent/settings.json` `packages` (npm: specs only), resolves each to its extension entry point (`pi.extensions` → `index.ts` → `index.mjs` → `index.js` → `src/index.ts`), and merges the discovered paths into every builtin/user agent (`src/runtime/model/provider-extensions.ts` + `src/agents/discover-agents.ts`).
+- Result: **any provider package installed via `pi install npm:<pkg>` works automatically in subagents** — no manual per-extension config.
+- Optional explicit allowlist `runtime.agentExtensions: string[]` config added on top of auto-discovery.
+- SEC-1 preserved: project/project-pi agents never receive these extensions.
+- Verified end-to-end: `deepseek/deepseek-v4-flash` resolves to `commandcode/deepseek/deepseek-v4-flash` in a real subagent spawn and completes.
+
+### Bug fixes (team tool was broken live while tests stayed green)
+- **"Validation failed for tool team"**: pi-ai `validateToolArguments` validates tool args BEFORE the pi-crew handler runs, and rejected model-emitted empty-string defaults (`runId:""`, `workspaceMode:""`, `context:""`, `scope:""`, `budgetTotal:0`, `once:false`, `keep:false`) against Literal unions / patterns / minimums. Schema now accepts the unset markers (`Literal("")`, runId pattern `^$|^...`, `Literal(0)`, `Boolean` in unions); `allActionLiterals` filters the `""`.
+- **"Unknown type"**: `SkillOverride`/`FreeformConfig` used `Type.Unsafe({...})` WITHOUT a `[TypeBox.Kind]` symbol, so `Value.Check` threw "Unknown type" the first time a model sent `skill`/`config`. Switched to TypeBox-native `Type.Union`/`Type.Record`. Handler-side `normalizeTeamParams` drops empty strings before validation (defense-in-depth).
+- **chain-runner mis-split on arrows inside inline goals**: `parseChain` used `split("->")`, incorrectly splitting `"Change A -> B" -> "Analyze"` into 3 steps. New quote-aware `splitChainSteps()` splits only on top-level arrows (backward compatible).
+- These were caught by a new Tier 9 feature battery in the `real-test-pi-crew` skill (live team-tool action coverage), which is now documented there alongside the agent-unauthorized-edit anti-pattern surfaced during testing.
+
+### Whole-project reorganization (~92 commits)
+- `src/` clustered: `src/runtime/` → 15 subdirs (child-pi/, broker/, live-session/, recovery/, scheduling/, verification/, model/, output/, heartbeat/, process/, goal-workflow/, compaction/, task-runner/, custom-tools/, errors/), `src/state/` → 3 subdirs (event-log/, stores/, coordination/), plus ui/, config/, utils/, agents/, extension/ clusters. Cluster maps in `src/runtime/README.md`, `src/state/README.md`.
+- `test/unit/` mirrored: 561 of 712 flat `.test.ts` files moved into 35 subdirs matching `src/` (243 runtime/, 53 state/, 110 extension/, plus ui/, config/, utils/, etc.). 151 cross-cutting tests (round*, v0*, package-*, errors, i18n, bundle-*) stay at root by design. Map in `test/unit/README.md`.
+- **REAL bug fixed**: test runner now expands `**` globs — `test/unit/security/` (3 files, 36 tests) were invisible before. All 715 files now discovered (6732 tests, 0 fail).
+- `docs/` consolidated: 27 historical docs → `docs/archive/`; 20 living docs stay at root; new `docs/README.md` index; 5 categories of broken refs fixed (dead links in src/agents/discover-agents.ts, src/runtime/{chain-runner,anchor-manager,handoff-manager,auto-summarize}.ts, recovery/retry-runner.ts, SECURITY-ISSUES.md, ARCHITECTURE.md refs).
+- Root cleanup: 11 stray `.md` files at repo root → `docs/archive/` + `docs/bugs/`.
+- README updated: Repository layout section, provider-extension feature, `runtime.agentExtensions` config row, v0.9.57 Recent-changes entry, 3 broken doc links fixed.
+- Stale worktrees + 4 merged local branches cleaned; `git worktree list` main-only.
+
+### Verification
+- Full final gate: typecheck 0 · lint 0 err/warn · format:check clean · unit 6763/6760/0 · integration 200/199/0 · `test:critical` 98/0 · bundle-load + smoke(real-binary) green · bundle 2.70 MB (budget 3.5 MB) · conflict-markers/lazy-imports/bundle-staleness all OK.
+- Live feature battery (Tier 9): `team` action=list/run(sync)/run(async)/chain + `Agent`/`crew_agent`/`get_subagent_result` all green with `deepseek/deepseek-v4-flash` over commandcode; read-only actions (recommend/health/doctor/status/events/summary/get/explain/worktrees) all return clean.
+
 ## [0.9.56] — performance remediation + team-tool schema fix (2026-07-30)
 
 Follows the verified `performance-audit-2026-07-29.md` (16 findings addressed). Independently deep-reviewed by a 4-agent review team (explore/code-review/security-review/verify — no P0/P1), full unit 6486/0 + integration 190/0, CI green on ubuntu/macos/windows.

package/README.md

@@ -26,7 +26,7 @@
 >   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),
+> See also: [SECURITY-ISSUES.md](docs/bugs/SECURITY-ISSUES.md),
 > [docs/dynamic-workflows.md](docs/dynamic-workflows.md#security-model-important)
 > (trust model), and the [Known limitations](#known-limitations) section below.
 
@@ -70,6 +70,7 @@ repo: https://github.com/baphuongna/pi-crew
 - **Lossless-by-default output handling** (L4, v0.9.8) — worker output thresholds sized from measured data (100% of real outputs fit without compaction); when compaction is unavoidable it keeps head+tail (preserves closing code fences/headings) instead of head-only truncation. No more `[pi-crew compacted N chars]` markers eating the end of a worker's result.
 - **Inter-pi broker** (v0.9.47, default-on) — a Unix-domain-socket message bus that lets concurrently-running Pi sessions pass messages, steering notes, and task-status events to each other. **On by default** on Linux + macOS; auto-disabled on native Windows (no unix socket). Three independent kill switches: `broker.enabled: false` (config), `PI_CREW_BROKER=0` (env, always wins), Windows auto-disable. See [docs/decisions/2026-07-22-broker-phase4-gated-on.md](docs/decisions/2026-07-22-broker-phase4-gated-on.md).
 - **`test:critical` + `real-test-pi-crew` skill** (v0.9.47) — a curated 14-file / 97-test subset (`npm run test:critical`, ~20s) for fast in-loop verification, plus a bundled skill distilling the full 8-tier end-to-end verification discipline (unit → 3-path kill-switch proof → typecheck/bundle → live TUI probing → smoke team run). Prevents the verifier-worker hang that full `npm test` (>4 min) caused against the 300s worker timeout.
+- **Provider extensions in subagents** (v0.9.57) — pi-crew spawns child-pi workers with `--no-extensions` (security posture), which made extension-registered providers (e.g. `pi-commandcode-provider`) unresolvable inside subagents. pi-crew now **auto-discovers provider packages** from `~/.pi/agent/settings.json` `packages` (npm: specs) and loads them via `--extension` in every builtin/user subagent — so **all provider models work in subagents**. An explicit `runtime.agentExtensions: string[]` config is an optional extra allowlist on top of auto-discovery. **SEC-1 preserved:** project/project-pi agents never receive these (env-gate unchanged).
 
 ---
 
@@ -286,6 +287,16 @@ The advisory is **informational only** — there is no `force:true` flag needed
 
 ## Recent changes
 
+### v0.9.57: team-tool schema repair + provider-extension auto-discovery + post-reorg repo-layout consolidation
+
+- **Team tool repaired (was broken live while tests stayed green)**: calling models emit empty-string/boolean defaults for every schema key, which pi-ai's pre-handler `validateToolArguments` rejected (`Validation failed for tool team`) and `Type.Unsafe` schema fields without `[TypeBox.Kind]` made `Value.Check` throw (`Unknown type`). Schema now accepts unset markers natively; `SkillOverride`/`FreeformConfig` switched to TypeBox-native constructors; `normalizeTeamParams` drops empties in the handler. Chain-runner also fixed (quote-aware step splitting). Caught by a new **Tier 9 feature battery** in the [`real-test-pi-crew`](skills/real-test-pi-crew/SKILL.md) skill (live team-tool action coverage).
+- **Source reorg finalised (~90 commits)**: `src/` is now cluster-organised — `src/runtime/` (15 subdirs + ~77 flat files) and `src/state/` (3 subdirs + 12 root files), with the other top-level dirs (`extension/`, `ui/`, `config/`, `utils/`, `agents/`, …) cluster-honed too. See [Repository layout](#repository-layout) and the cluster maps [`src/runtime/README.md`](src/runtime/README.md) / [`src/state/README.md`](src/state/README.md).
+- **Tests mirrored into subdirs**: 566 flat `.test.ts` files now live in 35 leaf subdirectories mirroring `src/` (`test/unit/runtime/`, `test/unit/state/`, `test/unit/extension/`, …). 151 cross-cutting tests (`round*`, `v0*`, `package-*`, errors, i18n, bundle-*) stay at `test/unit/` root by design. See [`test/unit/README.md`](test/unit/README.md).
+- **Recursive-glob test-runner fix**: `scripts/test-runner.mjs` now expands `**` globs itself — Node v22's `--test` only expands single-level `*`, so subdir tests (e.g. `test/unit/security/`) were **invisible** to `npm test` before.
+- **Docs consolidated**: 47 flat docs at `docs/` root → 20 living docs kept at root, 27 historical moved to `docs/archive/` (flat); 11 stray root `.md` files moved to `docs/archive/` + `docs/bugs/`. New [`docs/README.md`](docs/README.md) indexes the living docs + subdirs.
+- **Provider extensions in subagents** (see [Features](#features)): auto-discovery of provider packages from `~/.pi/agent/settings.json` `packages` (npm: specs) + explicit `runtime.agentExtensions` allowlist. Implementation: `src/runtime/model/provider-extensions.ts` + merge in `src/agents/discover-agents.ts`. SEC-1 preserved (project/project-pi agents never receive these).
+- See [CHANGELOG.md](CHANGELOG.md) for the full reorg + feature log.
+
 ### v0.9.47 (2026-07-22): Inter-pi broker Phase 4 (default-on) + verifier-hang fix + verification skill
 
 - **Broker default-on**: `broker.enabled` flipped `false` → `true` on Linux + macOS. The inter-pi broker lets concurrent Pi sessions exchange messages, steering notes, and task-status events over a Unix-domain socket. Three kill switches remain: config `broker.enabled: false`, env `PI_CREW_BROKER=0` (always wins), Windows auto-disable.
@@ -315,7 +326,7 @@ The advisory is **informational only** — there is no `force:true` flag needed
 
 ### v0.9.42 – v0.9.44: 4-wave audit + flaky-CI fixes
 
-A 4-wave audit + fix pass was completed (see `UPGRADE_REVIEW.md` for the full 647-line report and `CHANGELOG.md` for the diff):
+A 4-wave audit + fix pass was completed (see `docs/archive/UPGRADE_REVIEW.md` for the full 647-line report and `CHANGELOG.md` for the diff):
 
 - **−481 KB** bundle size (externalized `acorn` + fixed `@sinclair/typebox` name).
 - **−31.1%** in `child-pi.ts` (1842 → 1270 lines via 6 decomposition steps).
@@ -481,6 +492,7 @@ For machine-readable validation, see [schema.json](schema.json).
 | `runtime.effectivenessGuard` | `off \| warn \| block \| fail` | `off` | Pre-flight topology validator enforcement mode. |
 | `runtime.isolationPolicy` 🔒 | `{ isolatedRoles?, defaultRuntime? }` | _(unset)_ | Per-role runtime selection for crash isolation. |
 | `runtime.excludeContextBash` | `boolean` | `false` | Exclude certain bash results from worker context. |
+| `runtime.agentExtensions` | `string[]` | _(unset)_ | Extra extension paths (file paths or npm entry points) loaded in **every** child-pi worker on top of auto-discovered provider packages (see [Features](#features)). Optional allowlist — auto-discovery already loads provider packages from `~/.pi/agent/settings.json` `packages`. Project/project-pi agents never receive these (SEC-1). |
 
 ² `requirePlanApproval` is sensitive only when set to `false` in project config
 (the sanitizer blocks *disabling* the gate from untrusted project config).
@@ -893,7 +905,39 @@ npm run ci           # full CI-equivalent check
 npm pack --dry-run   # package verification
 ```
 
-Stats: **477 source files** (108K lines) · **682 test files** (~6,500 tests) · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
+Stats: **476 source files** (112K lines) · **762 test files** (717 unit + 34 integration + 5 smoke + 3 functional + 2 platform + 1 manual) · **CI: Ubuntu ✅ macOS ✅ Windows ✅**
+
+---
+
+## Repository layout
+
+After the v0.9.x reorg (~90 commits) the repo is cluster-organised so related
+files live together — source, tests, and docs mirror each other.
+
+```
+src/                         # ~476 TS files
+├── runtime/                 # team-run execution machinery — 15 subdirs + ~77 flat files
+├── state/                   # persistent state layer — 3 subdirs + 12 root files
+├── extension/               # Pi extension surface (register, team-tool, ui glue)
+├── ui/                      # TUI, dashboard, overlays
+├── config/ · utils/ · agents/ · workflows/ · …   # supporting clusters
+test/
+└── unit/                    # mirrors src/ — 35 leaf subdirs + 151 cross-cutting tests at root
+    ├── runtime/ · state/ · extension/ · ui/ · config/ · …
+docs/                        # living docs at root; history in docs/archive/
+```
+
+- **`src/`** — each top-level dir has a cluster map; the two largest are
+  [`src/runtime/README.md`](src/runtime/README.md) (15 subdirs: child-pi,
+  broker, live-session, recovery, scheduling, verification, model, output,
+  heartbeat, process, goal-workflow, compaction, task-runner, custom-tools,
+  errors) and [`src/state/README.md`](src/state/README.md) (event-log,
+  stores, coordination).
+- **`test/unit/`** — mirrors `src/` 1:1; cross-cutting tests (`round*`,
+  `v0*`, `package-*`, errors, i18n, bundle-*) stay at the root by design.
+  See [`test/unit/README.md`](test/unit/README.md).
+- **`docs/`** — 20 living docs at the root; 27 historical docs moved to
+  `docs/archive/`. See [`docs/README.md`](docs/README.md).
 
 ---
 
@@ -912,7 +956,11 @@ Stats: **477 source files** (108K lines) · **682 test files** (~6,500 tests) ·
 | [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 |
+| [docs/README.md](docs/README.md) | Index of all docs/ (living + subdirs) |
+| [src/runtime/README.md](src/runtime/README.md) | Runtime source cluster map (15 subdirs) |
+| [src/state/README.md](src/state/README.md) | State source cluster map (3 subdirs) |
+| [test/unit/README.md](test/unit/README.md) | Unit-test cluster map (mirrors src/) |
+| [docs/archive/next-upgrade-roadmap.md](docs/archive/next-upgrade-roadmap.md) | Future upgrade roadmap |
 | [schema.json](schema.json) | Config JSON schema |
 
 Research docs (not in package): [`docs/pi-crew-research/`](https://github.com/baphuongna/pi-crew/tree/main/docs) — audits, deep research, distillation notes.
@@ -929,7 +977,7 @@ sharp edges I'm aware of — there are almost certainly others I'm not.
   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`).
+  see [CHANGELOG.md](CHANGELOG.md) § v0.9.0 "Phase 1.5 #3").
   **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.