wangxuming/makelore
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
68e676cb628b5c7ad3cafeff997ca5813f9b00a8
makelore/.project-docs/30-worklog/tasks/20260823-pi-event-projector-91c6a7e4.md

8.4 KiB
Raw Blame History

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: e79aeffffa
  • 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.