pi-crew 0.1.45 → 0.1.49

package/CHANGELOG.md

@@ -2,6 +2,103 @@
 
 ## Unreleased
 
+## 0.1.49
+
+### Added
+
+- **Caveman output contracts** — Role-based output validation framework with `output-validator.ts`: regex-based format checking for explorer, executor, reviewer, verifier, security-reviewer roles. Non-blocking: validation failures emit `task.output_validation` events + set `needs_attention` but do NOT fail the task.
+- **Prose compressor** — `prose-compressor.ts` compresses verbose worker output for token-sensitive contexts (role-aware compression levels).
+- **Sensitive paths** — Word-boundary-aware token matching in `sensitive-paths.ts` prevents false positives (e.g. `secretary.ts` no longer flagged as `secret`).
+- **Symlink-safe I/O** — Artifact and shared output paths reject traversal attempts and symlinked root escapes.
+- **Output contract eval harness** — 19 unit tests covering three-arm evaluation (contract vs terse vs baseline), format compliance, token savings, regex safety (no `/g` lastIndex state leak).
+
+### Changed
+
+- **Delegation policy rewritten** — Replaced advisory "you should consider" text with a mandatory decision table: concrete thresholds (>3 files read OR >2 files edit = MUST delegate), explicit YES/NO cases per task type, conflict-safe task splitting rules. Injected into every session via `before_agent_start` hook.
+- **Powerbar dedup** — `powerbar-publisher.ts` now skips `powerbar:update` emit when segment data is unchanged (inspired by pi-powerbar's `segmentEquals` pattern). Combined with existing 200ms coalescing for minimal unnecessary renders.
+- **UI responsiveness** — `task-runner.ts` now emits `streamBridge` event immediately after `task.started`, giving the widget agent status within ~100ms instead of 2-5s (child process startup delay).
+- **"spawning…" indicator** — Widget shows "spawning…" for agents < 5 seconds old with no tool activity, distinguishing from "thinking…" for long-running agents.
+
+### Fixed
+
+- **H1: MCP proxy fallback** — `mcp-proxy.ts` now falls back to `enableMcp: true` when `createMcpProxyTools()` returns empty, so child sessions self-discover MCP instead of losing all access.
+- **H2: parallel-utils throw undefined** — `mapConcurrent` now throws the actual error instead of `throw undefined`.
+- **H3: Semaphore over-release** — `release()` guard against `#current > 0` prevents over-release corruption.
+- **M1: IRC tool TOCTOU** — `irc-tool.ts` wraps `sendIrcMessage`/`broadcastIrcMessage` in try-catch.
+- **M2: submit-result ordering** — Builds response string before calling `onYield`, wrapped in try-catch.
+- **M3: Sensitive paths false positives** — Word-boundary-aware token matching replaces substring matching.
+- **M4: atomic-write sleepSync** — Added WARNING comment about blocking main thread.
+- **M7: URL regex trailing punctuation** — Precise regex excludes trailing punctuation from URL matches.
+- **L1: parent-guard comment** — Corrected misleading comment about `process.kill` on Windows.
+- **Yield handler DRY** — Extracted `extractYieldDataFromArgs` helper, `isObjectRecord`/`isStringRecord` type guards, safe `find()` pattern.
+- **Event-log-rotation TOCTOU** — `compactEventLog` re-reads file after initial read to merge concurrent appends; `readEvents` skips corrupt JSON lines.
+- **Ghost agent dedup** — Fixed duplicate agent records in `crew-agent-records` after crash recovery.
+
+### Research
+
+- `docs/research/AGENT-EXECUTION-ARCHITECTURE.md` — Detailed comparison of 3 execution modes (oh-my-pi in-process, pi-crew child-process, pi-crew live-session).
+- `docs/research/UI-RESPONSIVENESS-AUDIT.md` — Root cause analysis for 2-5s agent spawn visibility delay, 5 proposed fixes with priority matrix.
+- `docs/research/DEEP-RESEARCH-PI-POWERBAR.md` — Deep analysis of pi-powerbar architecture (producer/consumer pattern, rendering, settings, comparison with pi-crew's powerbar publisher).
+
+## 0.1.48
+
+### Added
+
+- **Yield-based completion contract** — Workers can call `submit_result` tool to return structured results; task-runner warns on workers that don't yield.
+- **Typed event channels** — `RunEventBus` supports 5 channels (`worker:progress`, `worker:lifecycle`, `worker:stream`, `run:state`, `ui:invalidate`) with `onChannel`/`onChannelForRun` subscriptions and auto-classification.
+- **Human-readable task names** — `generateTaskName()` produces AdjectiveNoun names (14,400 combinations); `displayName` field on `TeamTaskState`.
+- **SubprocessToolRegistry** — Extensible tool event handling with `register`/`extractAll`/`shouldTerminate` pattern; wired into event-stream-bridge.
+- **Event log rotation/compaction** — Auto-compacts event logs over 5MB/50k events, keeping last 1000 events; atomic file replacement.
+- **Incremental JSONL reader** — `readLinesSince`/`readJsonlSince` for seek-based file reading; wired into `readEventsCursor` with `fromByteOffset`.
+
+### Fixed
+
+- Fixed `readBlob`/`readBlobMetadata` crash on missing files — now returns `undefined`.
+- Fixed `readSseJson` crash on non-JSON SSE data — now skips malformed events.
+- Fixed wrong value `"long_running"` → `"active_long_running"` in agent-control.
+- Fixed `consecutiveFailures` type bypass — added to `CrewAgentProgress` interface.
+- Fixed `streamBridge.dispose()` memory leak — now in try/finally.
+- Fixed blob-store redundant ternary `typeof x === "string" ? x : x`.
+- Fixed team-runner non-null assertion on potentially empty array.
+- Fixed event-log silent error swallowing — now logs via `logInternalError`.
+- Fixed team-tool switch case indentation.
+- Removed dead code `expandIcon` in agent-management-overlay.
+
+### Changed
+
+- Moved 6 research .md files from repo root to `docs/research/`.
+- `discoverAgents`/`discoverSkills` silent catches now log via `logInternalError`.
+- `executeHook` accumulates non-blocking diagnostics instead of short-circuiting.
+- `CancellationToken.heartbeat` wired into `collectRuns` and `pruneFinishedRuns`.
+- `CapabilitySource` extended with `"git"` to match `ResourceSource`.
+
+## 0.1.47
+
+### Added
+
+- **Typed hook lifecycle** — 8 of 9 hooks wired: `before_run_start`, `before_task_start`, `task_result`, `before_cancel`, `before_forget`, `before_cleanup`, `before_publish`, `run_recovery`. Hooks are opt-in, blocking/non-blocking, with audit events.
+- **Event-first UI bus** — `RunEventBus` emits on every `appendEvent` call; dashboard, crew widget, sidebar, and snapshot cache subscribe for event-driven invalidation instead of polling.
+- **Shared scan cache** — `SharedScanCache` caches manifest reads and active-run entries with TTL, mtime/size invalidation, and LRU eviction.
+- **Capability inventory** — `buildCapabilityInventory()` enumerates teams, workflows, agents, and skills with stable `kind:name` IDs; supports policy disable and shadowing detection.
+- **Skills in capability inventory** — `discoverSkills()` reads SKILL.md frontmatter; skills appear with kind=`skill` and source=`package`/`project`.
+- **Mailbox kind-separated breakdown** — `RunUiMailbox` tracks `steerUnread`/`followUpUnread`/`responseUnread`/`messageUnread`; mailbox pane shows urgency indicators.
+- **Run recovery hook** — `applyRecoveryPlan` fires `run_recovery` hook; blocked recovery emits `crew.run.recovery_blocked` event.
+- **Synthetic tool cancellation evidence** — Cancelled in-flight tasks receive `tool`-level terminal evidence alongside `worker`-level.
+- **CancellationToken wired into production loops** — `collectRuns` and `pruneFinishedRuns` use `CancellationToken.heartbeat(stage)` for progress diagnostics.
+- **Blob artifact store** — SHA-256 content-addressed storage with metadata sidecars.
+- **Run event provenance** — Event metadata includes `parentEventId`, `attemptId`, `branchId`, `causationId`, `correlationId`.
+- **Control channel reservation** — `ControlReservation` before worker spawn with deterministic `controllerId`.
+- **Release smoke test** — `npm run smoke:release` automates tarball install + version consistency check.
+- **Width-safety tests** — Crew widget rendering verified at widths 1/40/200/empty/multiple.
+
+### Changed
+
+- `handleCancel`, `handleForget`, `handleCleanup`, `handlePrune`, `handleExport` converted to async for hook execution.
+- `before_cancel`/`before_forget`/`before_cleanup` hooks can block their respective operations.
+- `before_publish` hook fires before run export.
+- `task_result` hook fires before `task.completed`/`task.failed` events.
+- Dashboard, widget, and sidebar auto-invalidate on `RunEventBus` events.
+
 ## 0.1.45
 
 ### Added

package/README.md

@@ -195,11 +195,11 @@ Supported config:
     "widgetPlacement": "aboveEditor",
     "widgetMaxLines": 8,
     "powerbar": true,
-    "dashboardPlacement": "right",
-    "dashboardWidth": 56,
+    "dashboardPlacement": "center",
+    "dashboardWidth": 72,
     "dashboardLiveRefreshMs": 1000,
     "autoOpenDashboard": false,
-    "autoOpenDashboardForForegroundRuns": true,
+    "autoOpenDashboardForForegroundRuns": false,
     "showModel": true,
     "showTokens": true,
     "showTools": true
@@ -252,8 +252,8 @@ Safety notes:
 UI notes:
 
 - `widgetPlacement`/`widgetMaxLines` keep the persistent active-run widget compact.
-- `dashboardPlacement: "right"` is the default for `/team-dashboard`; automatic overlay opening is opt-in because Pi custom overlays can be modal/focus-capturing in some terminals.
-- `autoOpenDashboard`/`autoOpenDashboardForForegroundRuns` control whether the live sidebar opens automatically.
+- `dashboardPlacement: "center"` is the default for `/team-dashboard`; set it to `"right"` only when you want a right-sidebar dashboard.
+- `autoOpenDashboard`/`autoOpenDashboardForForegroundRuns` control whether the live sidebar opens automatically. Both default to false so the compact widget above the input remains the primary live UI.
 - `dashboardLiveRefreshMs` controls the live sidebar refresh cadence.
 - `showModel`, `showTokens`, and `showTools` show worker model attempts, token usage, and tool activity in dashboard agent rows.
 

package/agents/analyst.md

@@ -1,11 +1,11 @@
----
-name: analyst
-description: Analyze requirements, ambiguity, and hidden constraints
-model: claude-sonnet-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls
----
-
-You are a requirements analyst. Identify what is known, unknown, risky, ambiguous, or underspecified. Produce clarifying assumptions and acceptance criteria.
+---
+name: analyst
+description: Analyze requirements, ambiguity, and hidden constraints
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls
+---
+
+You are a requirements analyst. Identify what is known, unknown, risky, ambiguous, or underspecified. Produce clarifying assumptions and acceptance criteria.

package/agents/critic.md

@@ -1,11 +1,11 @@
----
-name: critic
-description: Challenge plans and designs before execution
-model: claude-sonnet-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls
----
-
-You are a critical reviewer. Find flaws, missing steps, unsafe assumptions, overengineering, underengineering, and verification gaps. Return concrete fixes to the plan.
+---
+name: critic
+description: Challenge plans and designs before execution
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls
+---
+
+You are a critical reviewer. Find flaws, missing steps, unsafe assumptions, overengineering, underengineering, and verification gaps. Return concrete fixes to the plan.

package/agents/executor.md

@@ -1,11 +1,11 @@
----
-name: executor
-description: Implement planned code changes
-model: claude-sonnet-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls, bash, edit, write
----
-
-You are an implementation specialist. Follow the provided plan, make targeted changes, keep edits minimal, and report changed files plus validation status. Do not broaden scope without explaining why.
+---
+name: executor
+description: Implement planned code changes
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write
+---
+
+You are an implementation specialist. Follow the provided plan, make targeted changes, keep edits minimal, and report changed files plus validation status. Do not broaden scope without explaining why.

package/agents/explorer.md

@@ -1,11 +1,11 @@
----
-name: explorer
-description: Fast codebase discovery and file/symbol mapping
-model: claude-haiku-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls
----
-
-You are a fast codebase explorer. Map relevant files, symbols, data flow, and constraints. Do not modify files. Return concise findings with paths and evidence.
+---
+name: explorer
+description: Fast codebase discovery and file/symbol mapping
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls
+---
+
+You are a fast codebase explorer. Map relevant files, symbols, data flow, and constraints. Do not modify files. Return concise findings with paths and evidence.

package/agents/planner.md

@@ -1,11 +1,11 @@
----
-name: planner
-description: Create an execution plan with clear sequencing and risk notes
-model: claude-sonnet-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls
----
-
-You are a planning specialist. Convert the goal and discovery notes into a concrete, ordered plan. Identify dependencies, risks, validation steps, and handoff instructions for implementers.
+---
+name: planner
+description: Create an execution plan with clear sequencing and risk notes
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls
+---
+
+You are a planning specialist. Convert the goal and discovery notes into a concrete, ordered plan. Identify dependencies, risks, validation steps, and handoff instructions for implementers.

package/agents/reviewer.md

@@ -1,11 +1,11 @@
----
-name: reviewer
-description: Review code changes for correctness, maintainability, and regressions
-model: claude-sonnet-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls, bash
----
-
-You are a code reviewer. Review the implementation for bugs, regressions, maintainability issues, missing tests, and project-rule violations. Return prioritized findings with evidence.
+---
+name: reviewer
+description: Review code changes for correctness, maintainability, and regressions
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash
+---
+
+You are a code reviewer. Review the implementation for bugs, regressions, maintainability issues, missing tests, and project-rule violations. Return prioritized findings with evidence.

package/agents/security-reviewer.md

@@ -1,11 +1,11 @@
----
-name: security-reviewer
-description: Review changes for security vulnerabilities and trust-boundary issues
-model: claude-sonnet-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls, bash
----
-
-You are a security reviewer. Look for injection, authn/authz flaws, insecure defaults, secret exposure, unsafe filesystem/network behavior, and dependency risks. Return severity and remediation.
+---
+name: security-reviewer
+description: Review changes for security vulnerabilities and trust-boundary issues
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash
+---
+
+You are a security reviewer. Look for injection, authn/authz flaws, insecure defaults, secret exposure, unsafe filesystem/network behavior, and dependency risks. Return severity and remediation.

package/agents/test-engineer.md

@@ -1,11 +1,11 @@
----
-name: test-engineer
-description: Design and implement test strategy for a change
-model: claude-sonnet-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls, bash, edit, write
----
-
-You are a test engineer. Identify the right test level, add or adjust tests when asked, detect flaky assumptions, and report exact validation commands and results.
+---
+name: test-engineer
+description: Design and implement test strategy for a change
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write
+---
+
+You are a test engineer. Identify the right test level, add or adjust tests when asked, detect flaky assumptions, and report exact validation commands and results.

package/agents/verifier.md

@@ -1,11 +1,11 @@
----
-name: verifier
-description: Verify that implementation satisfies the requested goal
-model: claude-sonnet-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls, bash
----
-
-You are a verification specialist. Check whether the work is complete, correct, tested, and aligned with project constraints. Prefer evidence over assumptions. Return PASS or FAIL with reasons.
+---
+name: verifier
+description: Verify that implementation satisfies the requested goal
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash
+---
+
+You are a verification specialist. Check whether the work is complete, correct, tested, and aligned with project constraints. Prefer evidence over assumptions. Return PASS or FAIL with reasons.

package/agents/writer.md

@@ -1,11 +1,11 @@
----
-name: writer
-description: Write concise documentation, migration notes, and summaries
-model: claude-haiku-4-5
-systemPromptMode: replace
-inheritProjectContext: true
-inheritSkills: false
-tools: read, grep, find, ls, edit, write
----
-
-You are a documentation specialist. Produce clear, concise, maintainable docs and summaries. Preserve technical accuracy and avoid marketing fluff.
+---
+name: writer
+description: Write concise documentation, migration notes, and summaries
+model: false
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, edit, write
+---
+
+You are a documentation specialist. Produce clear, concise, maintainable docs and summaries. Preserve technical accuracy and avoid marketing fluff.