design-portable-pi — WorksGood live mirror

Metadata

Status	done
Assigned	`agent-861`
Created	2026-07-26T08:20:18.268235812+00:00
Started	2026-07-26T08:20:24.677994138+00:00
Completed	2026-07-26T08:31:27.441814633+00:00
Tokens	8526258 in / 18368 out

Description

Research question

Pi worker logs are preserved as raw events, but WG's overview/TUI translation is materially less legible than Pi's own visualization. Determine how to obtain Pi-quality rendering when Pi is installed without making persisted WG logs unreadable or making non-Pi executors depend on Pi.

Investigation

Reproduce the current Pi overview failure with representative real logs: assistant text/deltas, reasoning, tool start/update/end, nested tools, errors, usage/cost, and turn boundaries. Compare the same semantic flow in direct Codex.
Trace WG's current Pi capture pipeline (raw_stream.jsonl, canonical stream.jsonl, session summary, overview/TUI consumers) and identify exactly where information or presentation quality is lost.
Read the relevant installed Pi documentation and examples completely, following referenced docs, for JSON/RPC event schemas, extensions, TUI/rendering APIs, transcript export, and compatibility/versioning. Determine whether Pi exposes a supported structured renderer or whether its visualization is internal-only.
Evaluate three approaches: (A) improve WG's provider-neutral canonical translator; (B) optional Pi-installed renderer producing a neutral RenderTree/Markdown cache; (C) scraping/replaying Pi terminal output. Reject fragile ANSI/TUI scraping unless no supported API exists.
Design storage with immutable native raw events, portable canonical semantic events, and a disposable/versioned rendered cache. Historical Pi logs must remain legible when Pi is later absent; direct Codex/Claude logs must never require Pi.
Specify feature detection, Pi/plugin compatibility handshake, failure fallback, renderer provenance/version, and re-render behavior after upgrades.
Recommend whether rendering happens during capture, on view, or both, and quantify any additional Pi dependency.

Do not modify production code. Produce an evidence-backed design artifact with file/line references and a small neutral RenderTree schema/example.

Validation

Current degradation is reproduced and localized to a concrete capture/translation/render stage.
Relevant Pi docs/examples are read fully and supported APIs are distinguished from internal implementation details.
Recommendation preserves viewability without Pi while enabling Pi-quality enhancement when available.
Direct Codex remains an independent control path with no Pi dependency.
Design covers schema/version drift, tool events, errors, usage, and historical re-rendering.
Artifact includes an incremental implementation/test plan and a credential-free fixture strategy.

## Research question
Pi worker logs are preserved as raw events, but WG's overview/TUI translation is materially less legible than Pi's own visualization. Determine how to obtain Pi-quality rendering when Pi is installed without making persisted WG logs unreadable or making non-Pi executors depend on Pi.

## Investigation
- Reproduce the current Pi overview failure with representative real logs: assistant text/deltas, reasoning, tool start/update/end, nested tools, errors, usage/cost, and turn boundaries. Compare the same semantic flow in direct Codex.
- Trace WG's current Pi capture pipeline (`raw_stream.jsonl`, canonical `stream.jsonl`, session summary, overview/TUI consumers) and identify exactly where information or presentation quality is lost.
- Read the relevant installed Pi documentation and examples completely, following referenced docs, for JSON/RPC event schemas, extensions, TUI/rendering APIs, transcript export, and compatibility/versioning. Determine whether Pi exposes a supported structured renderer or whether its visualization is internal-only.
- Evaluate three approaches: (A) improve WG's provider-neutral canonical translator; (B) optional Pi-installed renderer producing a neutral RenderTree/Markdown cache; (C) scraping/replaying Pi terminal output. Reject fragile ANSI/TUI scraping unless no supported API exists.
- Design storage with immutable native raw events, portable canonical semantic events, and a disposable/versioned rendered cache. Historical Pi logs must remain legible when Pi is later absent; direct Codex/Claude logs must never require Pi.
- Specify feature detection, Pi/plugin compatibility handshake, failure fallback, renderer provenance/version, and re-render behavior after upgrades.
- Recommend whether rendering happens during capture, on view, or both, and quantify any additional Pi dependency.

Do not modify production code. Produce an evidence-backed design artifact with file/line references and a small neutral RenderTree schema/example.

## Validation
- [ ] Current degradation is reproduced and localized to a concrete capture/translation/render stage.
- [ ] Relevant Pi docs/examples are read fully and supported APIs are distinguished from internal implementation details.
- [ ] Recommendation preserves viewability without Pi while enabling Pi-quality enhancement when available.
- [ ] Direct Codex remains an independent control path with no Pi dependency.
- [ ] Design covers schema/version drift, tool events, errors, usage, and historical re-rendering.
- [ ] Artifact includes an incremental implementation/test plan and a credential-free fixture strategy.

Depends on

(none)

Required by

open .flip-design-portable-pi

✉ Messages 2 messages (2 unread)

#1user2026-07-26T08:20:36.582971024+00:00read

Keep this research-only. Do not re-enable evaluation/FLIP settings or modify product code. Prioritize supported Pi APIs and a portable fallback over terminal/ANSI scraping.

#2design-portable-pi2026-07-26T08:20:45.243211643+00:00read

Acknowledged — keeping this research-only, leaving evaluation/FLIP and production code untouched, and prioritizing supported Pi APIs plus a portable fallback; ANSI/TUI scraping will be evaluated only as a rejected last resort.

Log

2026-07-26T08:20:18.255254809+00:00 Task paused
2026-07-26T08:20:23.802650323+00:00 Task published
2026-07-26T08:20:24.753184359+00:00 Spawned by coordinator --executor pi --model openai-codex:gpt-5.6-sol --isolation required-worktree
2026-07-26T08:20:39.829340616+00:00 Starting research: reproduce/trace Pi pipeline, inspect installed Pi supported APIs and internals, compare Codex control, then write evidence-backed design artifact. FANOUT_DECISION: stay inline — findings are tightly coupled into one design document and no production files will be modified.
2026-07-26T08:27:19.565504069+00:00 Reproduced/localized on real logs: Pi agent-690 raw=30,896,955B (43 turns, 58 correlated tools, 136 updates, 4 errors, .871119) becomes 22,376B canonical with IDs/args/results/updates/boundaries/native timestamps lost; TUI separately parses raw and discards updates/boundaries/usage and anonymous tool ends break parallel correlation. Direct Codex control agent-552 retains command+output+status in each finalized item, though its parser still drops file-change/usage records. Pi 0.82 supported offline export produced standalone 923,346B HTML from the 491,564B session snapshot.
2026-07-26T08:30:54.587925681+00:00 Design artifact complete: supported Pi APIs versus internals, real Pi/direct-Codex reproduction, hybrid neutral semantic renderer + supported offline Pi HTML cache, immutable/canonical/cache storage, RenderTree v1, compatibility/fallback/re-render policy, dependency budget, and fixture/implementation plan.
2026-07-26T08:31:13.625846959+00:00 Validated: all task-specific research criteria met; artifact paths/references exist; Markdown/design contains real-log reproduction, supported-vs-internal API analysis, portability and Codex independence, drift/tool/error/usage/history policy, RenderTree example, and credential-free incremental plan. git diff --check and artifact assertions pass. No production code changed; cargo build/test not applicable.
2026-07-26T08:31:13.668894172+00:00 Committed: b9a27f54 — pushed to remote
2026-07-26T08:31:27.441819113+00:00 Task marked as done