24 24 - Web Pi session is independent and can run in parallel with terminal Pi.
25 25 - Web session is persistent and normal.
26 26 - Seed web session with full terminal active branch.
27 -- Use Pi fork semantics where possible.
27 +- Seed via exact active-branch extraction where possible; whole-tree fork is allowed only if explicitly chosen.
28 28 - Allow parallel edit races.
29 29 - Mobile support uses LAN HTTP + random token.
30 30 - Show QR code in terminal widget.
41 41 terminal pi session
43 - ├─ fork active terminal session branch into new persistent session
44 - ├─ spawn `pi --mode rpc --session <fork>` subprocess
43 + ├─ extract active terminal branch into new persistent session
44 + ├─ spawn `pi --mode rpc --session <seeded-session>` subprocess
45 45 ├─ start LAN HTTP/WebSocket server with random token
46 46 ├─ show terminal widget: OSC link, QR, ESC cancel, /ui off help
47 47 └─ keep terminal session independent
63 63 - token-authenticated browser app,
64 64 - WebSocket event channel,
65 65 - spawned Pi RPC subprocess,
66 -- forked persistent session file,
66 +- active-branch persistent session file,
67 67 - in-memory event store and replay buffer,
68 68 - telemetry aggregator,
69 69 - terminal TUI minimizer state.
89 -Use Pi session forking rather than ad-hoc JSON rewriting where possible.
89 +Use Pi `SessionManager` APIs rather than ad-hoc JSON rewriting.
91 +Preferred exact active-branch path:
94 94 source = terminal ctx.sessionManager.getSessionFile()
95 -forked = SessionManager.forkFrom(source, ctx.cwd)
96 -spawn pi --mode rpc --session forked
95 +leaf = terminal ctx.sessionManager.getLeafId()
96 +seededPath = terminal ctx.sessionManager.createBranchedSession(leaf)
97 +spawn pi --mode rpc --session seededPath
99 -The fork must preserve the full active branch: user messages, assistant messages, thinking blocks, tool calls, tool results, bash execution messages, custom messages, compaction summaries, model changes, thinking-level changes, and relevant branch summaries.
100 +Prototype result: `SessionManager.forkFrom(source, cwd)` copies the whole session tree into the new file. That keeps LLM context clean because the active branch path is clean, but it also brings abandoned branches into `/tree`, increases history size, and may expose old branch history. Therefore use `createBranchedSession(leaf)` for the default exact active-branch seed. Whole-tree `forkFrom` is acceptable only behind an explicit option or fallback with visible warning.
102 +The seeded session must preserve the full active branch: user messages, assistant messages, thinking blocks, tool calls, tool results, bash execution messages, custom messages, compaction summaries, model changes, thinking-level changes, and relevant branch summaries.
101 104 The web session header records the terminal session as parent. The web session gets a clear display name such as `ui: <terminal session name or cwd>`.
111 114 - do not pass `--no-extension`, `--no-skills`, or `--no-session`,
112 -- pass the forked session via `--session`,
115 +- pass the seeded active-branch session via `--session`,
114 117 - inherit normal environment,
115 118 - parse stdout strictly as JSONL split on LF only,
116 119 - capture stderr separately for diagnostics,
117 120 - restart only by explicit user action, not automatically,
118 -- expose RPC death as a stream error with fix instructions.
121 +- expose RPC startup, slow startup, and death as stream/terminal states with fix instructions.
123 +Prototype result: a normal RPC subprocess with full extensions can take longer than 8 seconds to answer first state requests. The browser and terminal widget must show an explicit “starting RPC” state instead of appearing frozen.
120 125 RPC commands used by the web UI:
491 496 - Mount each widget in a bounded visual block.
492 497 - Do not use iframe sandboxing or a separate permission wall for full JS.
493 498 - Use `iframe srcdoc`, Shadow DOM, or equivalent document/layout boundary only to keep CSS, layout, and lifecycle contained.
499 +- Prototype result: unsandboxed `iframe srcdoc` can call parent `window.pi` in system Chrome and Playwright Firefox.
500 +- Prototype result: a host-bounded iframe with intentionally over-wide/tall content can fit the stream on a 390px mobile viewport in system Chrome and Playwright Firefox when the host applies `width: 100%`, overflow containment, and capped height negotiation.
494 501 - Container gets fixed stream width, `max-width: 100%`, overflow boundary, and resize observer.
495 502 - Host applies a minimal reset and Nugu CSS variables.
496 503 - Widget document receives theme variables and container dimensions.
731 -- fork path selected when source session file exists,
732 -- full branch preserved,
738 +- `createBranchedSession(getLeafId())` selected when source session file exists,
739 +- exact active branch preserved,
740 +- whole-tree `forkFrom` fallback warns that abandoned branches are included,
733 741 - parent session recorded,
734 742 - display name set,
735 743 - ephemeral source fallback behaves as specified,
794 802 - `@` references and `!` bash parsing match Pi expectations,
795 803 - mobile layout hides nothing essential,
796 804 - iframe widget bridge exposes `window.pi`,
805 +- iframe widget layout does not create page-level horizontal overflow in Chrome or Firefox,
797 806 - widget height negotiation stays bounded.
805 814 - run `/ui`, obtain URL/token, open browser,
806 815 - QR URL and link route to same authenticated page,
807 -- initial snapshot shows forked session history,
816 +- initial snapshot shows exact active-branch seeded session history,
808 817 - send prompt from web, observe RPC events stream,
809 818 - invoke slash command,
810 819 - invoke `/skill:*`,
928 937 ##
Open implementation risks 930 939 - Extension APIs cannot truly replace the whole terminal UI; design intentionally minimizes terminal UI instead.
931 -- Exact full-branch seeding may require `SessionManager.forkFrom` availability and behavior verification.
940 +- Exact active-branch seeding should use `createBranchedSession(getLeafId())`; `forkFrom` copies the whole tree and should not be the default.
932 941 - RPC mode does not support some interactive-only UI methods; web must emulate or degrade.
933 942 - `!`/`!!` exact terminal semantics may need explicit web-side mapping to RPC `bash`.
934 943 - Full JS widgets are powerful and risky; attribution/audit is mandatory.
941 950 Suggested phases:
943 952 1. Extension command + terminal widget + LAN auth server + QR.
944 -2. Forked RPC subprocess + event bridge + basic web stream/composer.
953 +2. Active-branch RPC subprocess + event bridge + basic web stream/composer.
945 954 3. Pi syntax, commands, skills, keybindings, status, extension UI protocol.
946 955 4. Visual tools and full-JS widget bridge.
947 956 5. Telemetry digest and lifecycle detection.