# Task: Implement PI-060 event projector and recovery ## Identity - Task ID: 20260823-pi-event-projector-91c6a7e4 - Mode: Feature - Branch: codex/20260823-pi-event-projector-91c6a7e4-pi-event-projector - Worktree: D:\Datas\OthersProjects\makelore-pi-event-projector-91c6a7e4 - Base commit: e79aeffffab16c4c5570971e24d1a20997be681d - Owner: codex - Status: Completed — planner Pass ## Scope - Implement `PI-060 — Event projector, hydration, and recovery` on top of PI-050 commit `e79aeffffab16c4c5570971e24d1a20997be681d`. - Own Main-private Pi live-event projection, persisted active-branch hydration, durable reconciliation, generation/sequence envelopes, and recovery snapshot integration. - Add exact-version fixtures and focused tests for the event/session projector seam without wiring Host API or Renderer consumers owned by later tickets. ## Intent And Constraints - Follow planner task `20260822-pi-runtime-spec-b6e2c9a4`, ticket `PI-060`, and Spec sections 10, 11, and 18. - Keep Pi wire event, message, and entry types inside Electron Main. Product callers consume only the PI-010 `ConversationSnapshot` / patch contracts. - Preserve stable live UI IDs during durable entry reconciliation; never use a timestamp or array position as identity. - Treat only `agent_settled` as authoritative idle. `agent_end`, compaction retry, and queue continuation must not release the run early. - Recover only the target Conversation, hydrate the new generation, and never replay an uncertain prompt or alter an unreadable session file. - Real external Provider verification remains Explicitly Waived / Accepted Risk with `realTurnVerified=false`; macOS remains deferred to `PI-150`. - Keep the implementation surgical: no Host API/Renderer wiring, OpenCode compatibility layer, feature flag, or unrelated refactor. ## Project Context Loaded - Concurrent Task Gate: Passed. The task owns feature worktree `D:\Datas\OthersProjects\makelore-pi-event-projector-91c6a7e4`, branch `codex/20260823-pi-event-projector-91c6a7e4-pi-event-projector`, at base `e79aeffffab16c4c5570971e24d1a20997be681d`. - Planning Gate: Passed after reading the required project positioning, integrated state, decisions, architecture, domain, evidence, reflection, commitments, stale-items, planner, PI-050, and all registered peer scopes. - The canonical positioning file is still a placeholder and integrated state predates the Pi feature chain, so the task-scoped cutover Spec/tickets and completed PI task records are authoritative for this implementation. - No peer owns the PI event/session projector. Older undefined OpenCode partner model tasks do not own projector behavior and this task does not change model switching semantics; no semantic conflict was found. - Likely modules: `electron/coding-runtime/contracts.ts`, `electron/coding-runtime/conversation-reducer.ts`, `electron/coding-runtime/pi/runtime.ts`, new Main-private projector modules, and focused tests/fixtures. - Unknowns to resolve from source before implementation: exact Pi 0.84.2 live event and persisted-entry shapes, and the smallest existing PI-050 generation replacement seam. These are code/fixture questions, not product decisions. ## Plan 1. Inspect PI-010/PI-050 contracts and exact Pi event/entry shapes; fix the projector seam. 2. Use vertical red-green slices for live event projection. 3. Use vertical red-green slices for active-branch hydration, reconciliation, generation/gap handling, and recover integration. 4. Run focused and full repository verification, then synchronize evidence to the planner task for independent review. ## Outcome - Planner review of candidate `3599064` returned **Needs Fix** with two local, deterministic P1 gaps: same-generation hydration regressed `cursor.seq` to zero, and retry failure/summary-retry Pi 0.84.2 events were not completely projected. PI-060 was reopened; PI-070 remains locked until re-review. - The follow-up closes both findings: same-generation hydration preserves the current cursor while a genuinely new generation starts at zero; listener envelopes remain strictly monotonic across checkpoint/settle. Exact Pi 0.84.2 failed auto-retry and all three summarization-retry events now project bounded retry traces and redacted failure state, with `agent_settled` preserving `terminalReason: failed`. - Planner re-review of cumulative HEAD `4bbe3f8b1eb383f4b49caa9ad6d3577a955c619d` returned **Pass** with no remaining Standards or Spec finding. PI-060 is Done; the unchanged 18-node/31-edge graph now exposes PI-070 as the only Ready Frontier. - Added a Main-private `PiEventProjector` for exact Pi 0.84.2 live RPC shapes. It projects stable message/content-index streams, cumulative tool output, authoritative `toolResult`, retry/turn/compaction boundaries, queue, interaction, usage, context, and authoritative `agent_settled` idle patches. - Added a pure `projectPiSessionSnapshot` seam for authoritative `entries + leafId` traversal, latest-compaction retained-tail semantics, abandoned-branch exclusion, tool/result reconstruction, large-image attachment projection, context recalculation state, and stable live-to- durable ID reconciliation. - Integrated per-Conversation serial projection into `PiConversationRuntime`. Initial prepare/fork hydrates persisted state, `agent_end` creates a non-idle checkpoint, `agent_settled` creates the final idle snapshot, and worker replacement/recovery reopens and hydrates only the target generation. - Added recoverable fail-closed handling for unreadable session trees. The last good nodes remain in memory, no source-session write occurs, sibling Conversations remain unchanged, and a later corrected recovery succeeds. - Extended the product contract/reducer only for the already-modeled turn boundary patch and `context.recalculating`; no Pi wire type escaped Main. - Added a named exact-version fixture for `@earendil-works/pi-coding-agent@0.84.2` and focused regression coverage for live/cold equivalence, compaction/retry/queue settling, tool partials, attachment references, target-only recovery, and corrupt sessions. ## Verification - `corepack pnpm run lint:check` — passed with 0 errors; the repository's 6 pre-existing React warnings remain outside this task. - `corepack pnpm run typecheck` — passed. - `corepack pnpm test` — passed after the review fixes, 195 files / 2184 tests. - `corepack pnpm run build:vite` — passed for Renderer, Electron Main, Preload, and release utility outputs; existing chunk-size/dynamic-import warnings remain. - `corepack pnpm run test:electron:windows` — passed, 1 file / 3 tests. - `corepack pnpm run probe:pi-runtime` — command passed against staged Pi 0.84.2 production closure, local session/reopen/isolation probes, and ready budgets. Probe result remains `partial-pass / incomplete` because `realTurnVerified=false`; real Provider validation is Explicitly Waived / Accepted Risk. macOS execution remains deferred to PI-150 and is not Pass. - Focused projector/runtime suite — passed, including all 15 `pi-*.test.ts` files / 81 tests after an isolated Windows temporary-file `rename EPERM` was rerun successfully; the later full suite passed without recurrence. - `git diff --check` — passed. - Planner independent re-review — passed: targeted 14/14, all Pi 81/81, typecheck, commit whitespace, and project-docs gates. Independent probes observed `seq 7 -> hydrate 7 -> patch 8`, ordinary retry `retrying -> error/failed -> idle/failed`, and summary retry `compacting -> retrying -> compacting -> error/failed -> idle/failed` with no raw Provider error in Snapshot or diagnostics. ## Follow-ups - PI-070 is the next and only Ready Frontier. PI-100 remains locked until PI-070 is Done. - PI-070 owns registered extension tool-detail schemas and interaction response behavior; PI-060 deliberately keeps unknown/custom payloads hidden or in bounded metadata-only diagnostics. - Later Host/runtime assembly must supply the `projectImage` persistence hook so live/session image bytes become product attachment IDs in production. - PI-150 owns the deferred macOS matrix. Real Provider compatibility, concurrency, credential isolation, and protocol behavior remain accepted unverified risks under the explicit user waiver. ## Promotion Candidates - None. The durable rules implemented here are already canonical in the Pi cutover Spec and PI-060 ticket; no duplicate architectural prose is needed.