155 lines
8.4 KiB
Markdown
155 lines
8.4 KiB
Markdown
# 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.
|