pi-crew 0.9.51 → 0.9.52

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 > **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.52] — Sprint 1-6: security hardening, durability, god-module refactor, tarball slim (2026-07-28)
+
+A full audit-driven upgrade pass — 6 sprints, ~60 findings from `REVIEW-UPGRADE-2026-07-27.md`, independently verified in `VERIFY-2026-07-27.md` (~22% of the original report's claims corrected: 4 false positives, count inflations, stale line refs). Test suite 6446 unit + 191 integration, 0 fail. CI green on ubuntu/macos/windows.
+
+### Sprint 1 — P0 security + durability + runtime (`47be124`)
+- **F-01 (RCE):** project `.dwf.ts` trust gate (`PI_CREW_TRUST_PROJECT_DWF=1`); builtin/user exempt.
+- **F-02 (RCE):** preStepScript project deny (discover-layer strip + runtime allowlist).
+- **R-01:** crash-recovery quarantines corrupt manifests (no more `stateRoot` delete on a single bad byte).
+- **CORE-1:** pendingUnits try/finally drain + `runController.signal` propagated to children.
+- **F-05 (ReDoS):** PEM regex bounded `{0,8192}?` + 2MB length guard + >100 BEGIN-count cap.
+- **D-01, C-02:** atomic-write POSIX rename; lock suffix disambiguation (`.mkdirlock` vs `.flock`).
+
+### Sprint 2 — broker P0 + worker cap (`ad6cde0`)
+- **F-06:** per-task broker token + `tokenRole` (orchestrator-only `steer.push`/`msg.send` — closed the self-declared-role privilege escalation).
+- **CORE-2:** global worker cap moved from the goal-loop coordinator to the actual `runChildPi` spawn sites (deadlock-safe under low caps).
+- **VAL-1:** `Value.Check` guard (downgraded P0→P2 — Pi framework already validates tool params).
+
+### Sprint 3 — 11 P1 quick wins (`b13036c`)
+A-01/A-02 (atomic-write dir fsync + fd-leak), F-2 (diag gate), F-9 (keyOf migration), CORE-7/10/11 (process-exit, detached spawn, AbortSignal into session.prompt), API-2 (3 missing action literals), CFG-3 (config precedence doc), DOC-1 (README bundle default), S-01 (schemaVersion validate).
+
+### Sprint 4 — 11 P1 medium (`e8e60a9`→`484a584`)
+DEP bump (@earendil-works/* 0.77→0.82), F-04 (per-user 0700 socket subdir), F-08 (migrate `resolveContainedPath` → hardened `resolveRealContainedPath`), CORE-13 (extract unified `runWorker()`), CORE-3 (per-task spawn budget), CORE-8 (unified `resolveRunDeadline` — closes inline-path zero-timeout), R-03 (rotation generation sidecar), C-01 (cross-process event-log lock, two-tier deadlock-safe).
+
+### Sprint 5 — god-module refactor (`c50b114`→`77daf87`)
+Characterization-test-first discipline (10 + 11 scenarios locked before refactor, held green across every extraction). **CORE-4:** `executeTeamRunCore` 1075→311 lines (8 extracted scheduler functions + `SchedulerContext`/`SchedulerDecision`). **CORE-5:** `runTeamTask` → `child-executor` + `pre-execution` + `post-execution`. **API-5:** 54-action mega-tool → 5-domain schema + dispatch facade (zero caller changes, `additionalProperties:true` Phase 1).
+
+### Sprint 6 — cleanup + tarball slim (`3884ae6`)
+CORE-6/17, F-1 (SIGWINCH teardown), F-21 (delete 454-LOC `tool-render.ts`), CI-4 (bundle size budget), CI-5 (pack→install→`node --check` smoke), **PKG-2/3/5 (tarball 16.0 → 4.8MB, −70%)**, API-1 (15 missing action docs), CFG-5 (17-section config reference).
+
+### CI hardening (`67d3e1c`→`400d780`)
+Format check, CI-5 `node --check`, P-02 structural (machine-independent), F-04 Windows named-pipe regex, H3 timer-race.
+
+### Deferred (follow-ups in `ROADMAP-2026-07-27.md`)
+F-26 (async `refreshIfStale`), C-03 (mailbox async cross-process lock), CORE-3 `retryableErrors` default subset, API-5 Phase 2 (`additionalProperties:false` tightening).
+
 ## [0.9.51] — Complete the UI animation audit + Windows coalescing fix (2026-07-26)
 
 Closes out the remaining deferred findings from `reports/ui-animation-audit-2026-07-24.md`

package/README.md

@@ -416,25 +416,221 @@ If preconditions are not met, a friendly error message is returned instead of cr
 
 ### Key Settings
 
-| Section | Keys | Default |
-|---------|------|---------|
-| **Runtime** | `mode`: `auto` \| `child-process` \| `scaffold` \| `live-session` | `auto` |
-| | `maxTurns`, `graceTurns`, `groupJoin`, `requirePlanApproval` | various |
-| **Concurrency** | `limits.maxConcurrentWorkers` | workflow-dependent |
-| | `limits.maxTaskDepth`, `limits.maxChildrenPerTask` | 2, 5 |
-| **Async** | `asyncByDefault` | `false` |
-| | `runtime.groupJoin`: `off` \| `group` \| `smart` | `smart` |
-| **Autonomy** | `profile`: `manual` \| `suggested` \| `assisted` \| `aggressive` | `suggested` |
-| | `autonomous.injectPolicy`, `preferAsyncForLongTasks` | true, false |
-| **UI** | `widgetPlacement`, `dashboardPlacement` | compact widget |
-| | `showModel`, `showTokens` | display controls |
-| **Reliability** | `autoRetry`, `autoRecover`, `deadletterThreshold` | opt-in |
-| **Observability** | `observability.enabled`, `observability.pollIntervalMs`, `otlp.enabled`/`otlp.endpoint` | opt-in |
-| **Worktree** | `worktree.setupHook`, `worktree.linkNodeModules`, `worktree.seedPaths` (mode is set via `workspaceMode: "worktree"` at run time) | disabled by default |
-
-> ⚠️ **Trust boundary**: project config cannot override sensitive execution controls (workers, runtime mode, autonomy, agent overrides). Set those in **user config** only.
-
-📖 Full config reference: [docs/commands-reference.md#team-settings--config-management](docs/commands-reference.md) and [schema.json](schema.json)
+A comprehensive reference of every config key. 🔒 marks keys that are
+**sensitive** — project config (`.crew/config.json`) cannot set them; they are
+silently ignored with a warning unless set in **user config**
+(`~/.pi/agent/pi-crew.json`). Cross-referenced against `src/config/types.ts`
+(`PiTeamsConfig`), `src/config/defaults.ts`, and the project-override sanitizer
+in `src/config/config.ts`.
+
+For machine-readable validation, see [schema.json](schema.json).
+
+#### Top-level
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `asyncByDefault` 🔒 | `boolean` | `false` | Detach every `run` by default (survives session switches). |
+| `executeWorkers` 🔒 | `boolean` | `true` | Spawn worker agents. `false` = dry-run planning only. |
+| `notifierIntervalMs` | `number` | `5000` | How often the completion notifier polls. |
+| `requireCleanWorktreeLeader` 🔒 | `boolean` | _(unset)_ | Require a clean git repo before starting a worktree-mode run. |
+| `ignoreMethod` | `"gitignore" \| "exclude"` | _(unset)_ | How run artifacts are ignored by git. |
+
+#### `autonomous.*` — Delegation & magic keywords
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `autonomous.profile` 🔒 | `manual \| suggested \| assisted \| aggressive` | `suggested` | How much the agent self-delegates to crew runs. |
+| `autonomous.enabled` 🔒 | `boolean` | `true` | Master switch for autonomous delegation. |
+| `autonomous.injectPolicy` 🔒 | `boolean` | `true` | Inject the delegation policy into prompts. |
+| `autonomous.preferAsyncForLongTasks` 🔒 | `boolean` | `false` | Auto-detach runs expected to be long. |
+| `autonomous.allowWorktreeSuggestion` 🔒 | `boolean` | `true` | Suggest worktree isolation for mutating goals. |
+| `autonomous.magicKeywords` | `Record<string, string[]>` | _(unset)_ | Trigger words mapped to team/workflow hints. |
+
+#### `limits.*` — Scheduling ceilings
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `limits.maxConcurrentWorkers` | `number` | workflow-dependent¹ | Hard cap on parallel workers. Ceiling 1024. |
+| `limits.allowUnboundedConcurrency` | `boolean` | `false` | Permit unbounded fan-out (dangerous). |
+| `limits.maxTaskDepth` | `number` | `100` | Max nesting depth of the task graph. |
+| `limits.maxChildrenPerTask` | `number` | `1000` | Max children a single task may spawn. |
+| `limits.maxRunMinutes` | `number` | `1440` | Wall-clock cap for a run (24 h). |
+| `limits.maxRetriesPerTask` | `number` | `100` | Max automatic retries per task. |
+| `limits.maxTasksPerRun` | `number` | `10000` | Max tasks allowed in a single run. |
+| `limits.heartbeatStaleMs` | `number` | `86400000` | Heartbeat staleness threshold (24 h). |
+| `limits.serializeOnPathOverlap` | `boolean` | `false` | Skip ready tasks whose `step.output` overlaps an in-flight task. |
+
+¹ Per workflow: `parallelResearch` 4, `research` 3, `implementation` 4, `review` 3, `default` 3 (fallback 2).
+
+#### `runtime.*` — Worker execution
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `runtime.mode` 🔒 | `auto \| scaffold \| child-process \| live-session` | `auto` | How workers are spawned. |
+| `runtime.preferLiveSession` 🔒 | `boolean` | _(unset)_ | Prefer in-process live-session workers. |
+| `runtime.allowChildProcessFallback` 🔒 | `boolean` | _(unset)_ | Fall back to child-process if live-session unavailable. |
+| `runtime.maxTurns` | `number` | `10000` | Max agent turns per task. |
+| `runtime.graceTurns` | `number` | `5` | Extra turns allowed after a stop signal. |
+| `runtime.taskTimeoutMs` | `number` | `0` | Per-task wall-clock timeout (0 = none). |
+| `runtime.inheritContext` 🔒 | `boolean` | `true` | Inherit parent context into workers. |
+| `runtime.promptMode` | `replace \| append` | `replace` | How the task prompt is applied. |
+| `runtime.groupJoin` | `off \| group \| smart` | `smart` | How grouped task results are joined. |
+| `runtime.groupJoinAckTimeoutMs` | `number` | `86400000` | Timeout for group-join acknowledgements. |
+| `runtime.requirePlanApproval` 🔒² | `boolean` | `false` | Pause for plan approval before mutating tasks. |
+| `runtime.completionMutationGuard` | `off \| warn \| fail` | `warn` | Guard against tasks mutating outside plan approval. |
+| `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. |
+
+² `requirePlanApproval` is sensitive only when set to `false` in project config
+(the sanitizer blocks *disabling* the gate from untrusted project config).
+
+#### `control.*` — Needs-attention gating
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `control.enabled` | `boolean` | _(unset)_ | Enable the needs-attention controller. |
+| `control.needsAttentionAfterMs` | `number` | _(unset)_ | Threshold before flagging a run as needing attention. |
+
+#### `worktree.*` — Git worktree isolation
+
+> Worktree **mode** is chosen at run time via `workspaceMode: "worktree"`, not
+> in config. These keys configure how a worktree is set up.
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `worktree.setupHook` 🔒 | `string` | _(unset)_ | Shell command run after worktree creation. |
+| `worktree.setupHookTimeoutMs` | `number` | _(unset)_ | Timeout for the setup hook. |
+| `worktree.linkNodeModules` | `boolean` | `false` | Symlink `node_modules` into the worktree. |
+| `worktree.seedPaths` | `string[]` | _(unset)_ | Extra paths to copy/symlink into the worktree. |
+
+#### `goalWrap.*` — Goal-completion workflows
+
+A per-workflow map (`Record<workflowName, GoalWrapWorkflowConfig>`) that applies
+the `goal` action's completion-guarantee loop to builtin workflows.
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `goalWrap.<name>.enabled` | `boolean` | _(unset)_ | Enable goal-wrap for this workflow. |
+| `goalWrap.<name>.maxTurns` | `number` (1–50) | _(unset)_ | Max iterations of the goal loop. |
+| `goalWrap.<name>.evaluatorModel` | `string` | _(unset)_ | Model used by the LLM judge. |
+| `goalWrap.<name>.verification.commands` | `string[]` | _(unset)_ | Commands run to verify completion. |
+| `goalWrap.<name>.budgetTotal` | `number` | _(unset)_ | Token budget for the goal loop. |
+| `goalWrap.<name>.budgetUnlimited` | `boolean` | _(unset)_ | Skip the token budget. |
+
+#### `agents.*` — Agent overrides
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `agents.disableBuiltins` 🔒 | `boolean` | `false` | Hide built-in agents. |
+| `agents.overrides` 🔒 | `Record<name, AgentOverride>` | _(unset)_ | Per-agent `model`, `fallbackModels`, `thinking`, `tools`, `skills`, `disabled`. |
+
+#### `tools.*` — Tool behaviour
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `tools.enableClaudeStyleAliases` | `boolean` | _(unset)_ | Accept Claude-style tool aliases. |
+| `tools.enableSteer` 🔒 | `boolean` | _(unset)_ | Enable the `steer` action. |
+| `tools.terminateOnForeground` 🔒 | `boolean` | _(unset)_ | Terminate background runs when foreground starts. |
+
+#### `telemetry.*`
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `telemetry.enabled` | `boolean` | `false` | Collect anonymous usage telemetry. |
+
+#### `policy.*` — Capability gating
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `policy.requireIntentForDestructiveActions` | `boolean` | _(unset)_ | Require explicit intent for deletes/forgets. |
+| `policy.disabledCapabilities` | `string[]` | _(unset)_ | Disable named capabilities. |
+
+#### `notifications.*`
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `notifications.enabled` | `boolean` | `false` | Enable run-completion notifications. |
+| `notifications.severityFilter` | `Severity[]` | `[warning, error, critical]` | Which severities to surface. |
+| `notifications.dedupWindowMs` | `number` | `30000` | De-duplicate notifications within this window. |
+| `notifications.batchWindowMs` | `number` | `0` | Batch notifications for this long before emitting. |
+| `notifications.quietHours` | `string` | _(unset)_ | Quiet-hours schedule (e.g. `"22:00-08:00"`). |
+| `notifications.sinkRetentionDays` | `number` | `7` | How long notification sinks retain data. |
+
+#### `observability.*`
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `observability.enabled` | `boolean` | _(unset)_ | Enable the periodic observability poller. |
+| `observability.pollIntervalMs` | `number` | _(unset)_ | Polling interval. |
+| `observability.metricRetentionDays` | `number` | _(unset)_ | How long metrics are retained. |
+
+#### `reliability.*` — Retry, recovery & validation
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `reliability.autoRetry` | `boolean` | `false` | Auto-retry failed tasks. |
+| `reliability.retryPolicy.maxAttempts` | `number` | _(unset)_ | Max retry attempts. |
+| `reliability.retryPolicy.backoffMs` | `number` | _(unset)_ | Base backoff between retries. |
+| `reliability.retryPolicy.jitterRatio` | `number` | _(unset)_ | Jitter fraction (0–1). |
+| `reliability.retryPolicy.exponentialFactor` | `number` | _(unset)_ | Exponential backoff multiplier. |
+| `reliability.retryPolicy.retryableErrors` | `string[]` | _(unset)_ | Error substrings considered retryable. |
+| `reliability.retryPolicy.maxTotalSpawns` | `number` | `0` | Flat per-task spawn budget (0 = auto). |
+| `reliability.autoRecover` | `boolean` | `false` | Auto-recover stuck/orphaned runs. |
+| `reliability.deadletterThreshold` | `number` | _(unset)_ | Attempts before a task is dead-lettered. |
+| `reliability.autoRepairIntervalMs` | `number` | `60000` | Periodic stale-run repair interval (0 = off). |
+| `reliability.cleanupOrphanedTempDirs` | `boolean` | `true` | Remove orphaned `/tmp/pi-crew-*` dirs. |
+| `reliability.forcePreflight` | `boolean` | `false` | Bypass the topology validator (audit-logged). |
+| `reliability.ambientStatusInjection` | `boolean` | `true` | Inject ambient crew-status note on every LLM call. |
+| `reliability.perWriteValidation` | `boolean` | `true` | Validate `write`/`edit` results (JSON v1). |
+| `reliability.scopeModels` | `boolean` | `false` | Enforce subagent models stay within the allowlist. |
+
+#### `otlp.*` — OpenTelemetry export
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `otlp.enabled` | `boolean` | _(unset)_ | Enable OTLP trace/metric export. |
+| `otlp.endpoint` 🔒 | `string` | _(unset)_ | OTLP collector endpoint. |
+| `otlp.headers` 🔒 | `Record<string, string>` | _(unset)_ | Auth headers sent to the collector. |
+| `otlp.intervalMs` | `number` | _(unset)_ | Export flush interval. |
+
+#### `ui.*` — Dashboard & widget
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `ui.widgetPlacement` | `aboveEditor \| belowEditor` | `aboveEditor` | Where the status widget renders. |
+| `ui.widgetMaxLines` | `number` | `8` | Max lines shown by the widget. |
+| `ui.powerbar` | `boolean` | `true` | Show the power bar. |
+| `ui.dashboardPlacement` | `center \| right` | `center` | Dashboard screen position. |
+| `ui.dashboardWidth` | `number` | `72` | Dashboard column width. |
+| `ui.dashboardLiveRefreshMs` | `number` | `1000` | Dashboard live-refresh interval. |
+| `ui.autoOpenDashboard` | `boolean` | `false` | Auto-open the dashboard. |
+| `ui.autoOpenDashboardForForegroundRuns` | `boolean` | `false` | Auto-open only for foreground runs. |
+| `ui.autoCloseDashboardMs` | `number` | _(unset)_ | Auto-close the dashboard after this long. |
+| `ui.showModel` | `boolean` | `true` | Show model names in the UI. |
+| `ui.showTokens` | `boolean` | `true` | Show token counts. |
+| `ui.showTools` | `boolean` | `true` | Show tool activity. |
+| `ui.transcriptTailBytes` | `number` | `1048576` | Bytes of transcript tail kept. |
+| `ui.mascotStyle` | `cat \| armin` | `cat` | Mascot character. |
+| `ui.mascotEffect` | `random \| none \| …` | `random` | Mascot animation effect. |
+
+#### `broker.*` — Inter-Pi broker
+
+> Default is **ON** since v0.9.47 (Linux + macOS). Disable via
+> `broker.enabled: false`, env `PI_CREW_BROKER=0`, or auto-off on Windows.
+
+| Key path | Type | Default | Description |
+|----------|------|---------|-------------|
+| `broker.enabled` | `boolean` | `true` | Master switch for the local socket broker. |
+| `broker.pathHashLen` | `number` (4–32) | `8` | SHA-256 prefix length in the socket filename. |
+| `broker.maxFrameBytes` | `number` (1024–1048576) | `262144` | Max NDJSON frame size (256 KiB). |
+| `broker.outboundQueueCap` | `number` (32–4096) | `256` | Per-connection outbound queue cap. |
+
+> ⚠️ **Trust boundary**: 🔒 keys are blocked from project config — set them in
+> **user config** only. The project config sanitizer silently drops them with a
+> warning so untrusted repos cannot escalate privileges or redirect telemetry.
+
+📖 Interactive config UI: [docs/commands-reference.md#team-settings--config-management](docs/commands-reference.md) · machine-readable: [schema.json](schema.json)
 
 ---
 
@@ -658,7 +854,7 @@ Your system prompt here.
 | `PI_CREW_BROKER=0` | **Disable the inter-pi broker entirely** (always wins over config). Use to opt out of cross-session messaging. |
 | `PI_CREW_BROKER=1` | Explicitly enable the broker (redundant under the v0.9.47 default-on; useful for overriding a config `broker.enabled: false`). |
 | `PI_CREW_BROKER_DIAG_UI=1` | Make the run-dashboard `handleInput` emit a `[PI-CREW-DIAG]` line to stderr per keystroke — for TUI keybinding probes. |
-| `PI_CREW_USE_BUNDLE=1` | Load via bundled `dist/index.mjs` (~5% faster cold-start). Default: strip-types. Requires `npm run build:bundle` to have produced `dist/`. Falls back to strip-types with a one-time warning if the bundle is missing. See `scripts/bench-cold-start.mjs`. |
+| `PI_CREW_USE_BUNDLE=1` | Force-load via bundled `dist/index.mjs` (~19% faster cold-start than strip-types). Default: bundle (since v0.9.17). Set `PI_CREW_USE_BUNDLE=0` to force strip-types fallback. Requires `npm run build:bundle` to have produced `dist/`. |
 | `PI_CREW_EXECUTE_WORKERS=0` | Disable child workers (scaffold mode) |
 | `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy disable flag |
 | `PI_TEAMS_MOCK_CHILD_PI=success` | Mock child worker for testing |