From Controlled Experiments to Trial Use

Working plan, updated 2026-09-22; Pi stock-UI status added 2026-10-11; content-model phase and ordered next steps updated 2026-10-26. This document tracks implementation evidence and engineering priorities; its Next Steps section is the current hand-off list. Agreed semantics are recorded in the protocol drafts.

Current Assessment

The codec, SDK, terminal Session, and experimental xterm renderer form an executable path. Fixed single-round and multi-round applications run through Windows bundled ConPTY. The pre-trial checklist below is implemented, with recorded tests for each item.

Following the Pi architecture assessment, the Pi session experiment connects the pinned Pi SDK and one read-only tool through SDK bytes, Windows ConPTY, and the experimental xterm host. Both local fixtures and a finite OpenAI subscription trial have browser evidence for completion/search and cancellation. The live source uses SSE after a recorded model WebSocket failure whose root cause remains unresolved. The trial uses a separate plain-text frontend; Pi’s editor and extension UI remain integration work. Other terminals need their own rendering/history integration.

A separate paired Pi reading comparison uses fixed actual Pi sessions and captured pre-PTY output. Both frontends preserved reading during tail streaming. In the tested earlier-tool shrink and resize cases, the protocol frontend preserved reading/selection where Pi’s regular frontend did not. Neither path showed duplication of the checked text.

The entered-prompt multi-round Pi frontend completes the bounded third-stage interactive trial: one in-memory Pi conversation with separate display Contexts per turn. Local-provider ConPTY/xterm checks cover follow-up, assistant/tool cancellation then continuation, old reading/selection/copy, retained search, and orderly exit. Pi’s public stop-after-turn hook avoids preparing another model request after tool cancellation; genuine errors still stop the connection. A separate four-prompt subscription checkpoint observed live context retention and assistant cancellation then continuation.

The coding trial adds a generated project with two readable files, one editable source, and a fixed test command. Local-provider and live subscription runs reproduced three failures, applied a quantity fix, passed all six tests, and repeated the tests in a second turn. Earlier failure output remained searchable and copyable.

The content-model phase is complete. RFC 0001, RFC 0002 (text/styled), and RFC 0003 (text/lines) are Accepted, with protocol drafts for styled text and line layout text. Both types run through the protocol, terminal, and SDK modules. In the Pi stock-UI trial, Pi’s assistant answers travel as text/lines and the terminal lays them out at every width beside Pi’s own editor and footer; the layout experiment records why baking layout at one width fails.

Completed Work and Evidence

The linked records provide scenario details, measurements, commands, and limits for each dated checkpoint.

Work	Recorded result	Evidence
Update of the Block being read, 2026-09-14	Replacement-start viewport policy; seven Node and three browser cases	Anchored Update
Full-Block eviction and render failure	Reject mutation of evicted content; stop after injected partial rendering failure	Eviction and containment
Finite multi-round use, 2026-09-15	Three commanded rounds and orderly mid-round quit; separate application checks	Multi-round example
Local queue accumulation, 2026-09-16	Ordering alone does not bound pending pushes; local batch waiting reduces the measured backlog	Ingress pressure
Browser consumption credits, 2026-09-16	Opt-in PTY pause/resume and finite completion; watermark overshoot observed	PTY pressure
Producer waiting, 2026-09-17–18	Synchronous writes waited during paused reading and overlapped the composed browser hold	Isolated probe, composed run
Permanent consumer stall, 2026-09-19	Stop forwarding, request child termination, observe exit, and fail the connection	Stall experiment
Styled text content, 2026-10-16–19	text/styled end to end; browser paint, copy, and search checks; ANSI conversion on recorded Pi output	Styled text draft
Renderer-baked layout, 2026-10-19	Neither a current-width nor a wide render survives a width change under cell reflow	Layout experiment
Line layout content, 2026-10-19–24	text/lines matches Pi’s own layout at every width from 20 to 100 columns for a Chinese and nested-list sample; real-Pi browser checks pass at 36 and 60 columns	Line layout draft, Pi trial
Long-session retention, 2026-10-27	Twenty real Pi rounds in one Tabby tab; 20 Contexts and 42 sealed Blocks; zero retained Session snapshots; resize and sequential-SDK checks; measured browser/renderer memory	Tabby long-session evidence

The pressure experiments observed producer waiting even with zero stdout drain events, and queues could exceed their high watermark. After partial rendering failure, the host stops with the partial state retained. The anchored-Update experiment uses a terminal-chosen policy; below one screen of content, viewport clamping loses separate off-tail reading intent.

Pre-trial Checklist Completed on 2026-09-19

1. Cleanup failures. Fault-injection tests exercise missing/late exit, failed kill, unresponsive socket closure, trailing output, and failed exit notification. The shared bridge keeps its child slot until both exit and socket closure are observed. Fake events and timers test failure ordering; the real stalled-consumer browser run supplies separate bundled-ConPTY evidence.

2. Resource accounting. Trial budgets bound selected retained content, identity/replay structures, and owned pending input. Content overflow rejects atomically; identity/replay exhaustion stops execution rather than forgetting protocol meaning. Without explicit reclamation, closed and evicted records remain charged. Hosts opt into these local limits; closed-Context reclamation and long-session memory measurements are recorded separately.

3. Application failure handling. Lifecycle tests distinguish unsupported/silent startup negotiation from failure after protocol output starts. Tested runtime failures stop later sends without fallback; cleanup restores input mode and removes handlers. These tests inject failures through synthetic streams.

4. Content samples. The sample report records seven Node and four browser cases for literal code, Chinese, long lines, selected Unicode sequences, and unsupported Tab mapping. Assertions inspect stored Buffer text and Session content; glyph shaping and native interaction for these Unicode sequences need further tests.

That checkpoint passed type checking, 224 Node tests, four affected browser builds, 73 browser endpoint scenarios, two single-round and two multi-round browser checks, and the permanent-consumer-stall check. The latter three fixtures use local Windows bundled ConPTY. Normal examples select the trial budgets but still omit the pressure fixtures’ consumption credits/watchdog.

Next Steps

Ordered by current priority, following the demo-first strategy in the adoption path (revised 2026-10-26). State at 2026-10-27: pnpm typecheck, 471 Node tests, and the documentation check pass on main.

1. A runnable demo terminal. First, research whether the receiver side can ship as a plugin of an existing terminal built on xterm.js (for example Hyper or Tabby): whether their plugin APIs expose the terminal instance, its buffer, and the PTY byte stream, verified from their official documentation or source. A plugin in a terminal people already use is a stronger demonstration. Otherwise, build an installable desktop program (for example Electron with xterm.js, node-pty, and the terminal module) that runs the real Pi and an ordinary shell in one window, with the protocol host built in. Either way, an ordinary terminal cannot show the protocol: it ignores the capability query, so a protocol-enabled Pi falls back to its stock rendering there. It replaces the browser test pages as the thing people run. The demonstration must retain protocol Blocks and ordinary output in one terminal history, with enough robustness for a long demo session. A terminal vendor’s native integration can control its own buffer directly rather than reuse a plugin’s xterm.js adapter.

   Progress, 2026-10-27: the plugin approach is feasible and the Tabby vertical slice is complete. It loads in Tabby 1.0.238 and verifies ordinary shell output, an SDK round trip, real Pi stock-UI rounds, resize recovery, and sequential independent SDK applications in one tab. Request IDs are namespaced per SDK client, so later applications cannot receive an earlier application’s cached closed Context. The single-history plugin retains its private history adapter, guarded by a host-version declaration and private-structure check before activation. Incompatible hosts leave the capability query unanswered and notify once, allowing ordinary application fallback.

   Closed-Context reclamation and full-eviction projection cleanup now support the planned live-demo scope. One real Pi process in one Tabby tab completed 20 rounds with 20 Contexts and 42 sealed Blocks, no retained Session snapshots, and no protocol errors. A resize round trip and two sequential SDK applications also passed. The long-session record includes the measurement method and browser/renderer memory table. This is sufficient for the planned demonstration, not an unlimited-session guarantee: open/invalidated recovery, the 1,024-result replay cap, slow consumers, and other platforms remain limitations.

2. A side-by-side demonstration. The same Pi session in an ordinary terminal and in the demo terminal: layout after resize, updates to content already in scrollback, a stable reading position, and copy and search on logical text. A scripted walkthrough and a recording, plus Pi’s unmodified fallback in the ordinary terminal.

   Progress, 2026-10-27: the side-by-side walkthrough runs one Pi runtime behind a stock view and a protocol view in a real Tabby split, with one tool call, and its automated check passes for the tool update, reading position, resize, search, and copy. A presentation-quality recording is still pending; the verification recording stays local because its frames include setup output and machine paths.

3. A terminal vendor kit. What a terminal maker needs to evaluate and embed the receiver side: a concise protocol summary, the terminal module as an embeddable reference implementation under its Apache-2.0 license, a host-adapter integration guide, and the conformance checks to run.

4. Vendor conversations, only after 1–3, with dated, reproducible evidence. A vendor’s own integration then becomes the independent second terminal-side implementation.

Supporting work, scheduled when the demo needs it:

• Emit layout attributes from the application renderer. The Pi trial reads layout intent back from rendered shapes (lines-from-render.ts), so tables and other constructs get only word wrapping.

• Relayout without an application redraw. In region mode the host relies on Pi’s resize redraw and clear recovery to re-materialize text/lines Blocks; an application that does not redraw keeps cell-reflowed rows.

• Long-session behavior: closed-Context reclamation and full-eviction projection cleanup are implemented, with retention semantics and 20-round memory evidence. Longer steady-state behavior and a slow-consumer policy remain open.

• Propose public history-line editing in xterm.js, long term. Research on 2026-10-27 found related discussion but no public API covering this need: the current IBuffer exposes read access, not arbitrary history insertion, deletion, or replacement. In #2105, maintainers rejected direct Buffer editing because of required post-actions and the static-scrollback assumption. The open contributor issue #5999 proposes encapsulating Buffer.lines, including a spliceLines method; it is not an accepted public extension API. Other contributors discuss a controlled setLine and _voffset consistency and stable identity across circular-buffer trimming. Before drafting an upstream proposal, define atomic row replacement, marker and viewport preservation, selection/search invalidation, reflow, capacity trimming, and redraw behavior; merely exposing CircularList would skip those requirements. This project has not filed an upstream proposal. This could remove the Tabby plugin’s private adapter later, but is not a current demo blocker.

• Platforms: only Windows bundled ConPTY is verified; macOS, Linux, SSH, and tmux are untested.

Remaining Work and Decision Points

• Pi integration scope: the entered-prompt trial and one generated-project coding workflow are complete, and stock-UI reuse is verified: the Pi stock-UI trial runs Pi’s stock interactive UI with a protocol-owned transcript through terminal-host region ownership; its browser checks pass (four on 2026-10-03, six including text/lines layout on 2026-10-24). Real repository access needs a selected project, explicit permissions, and execution isolation. A full fallback frontend and an upstream proposal remain follow-up choices; broader adoption is scoped in the adoption path.

• Capacity and retention: closed-Context reclamation has 20-round evidence, and full-eviction projection cleanup has focused tests. Partial-Block or unmanaged-row eviction, open/invalidated reclamation, and longer steady-state behavior remain open. Full-Block eviction follows the existing semantics.

• Failure and pressure: automatic rollback/recovery, whole-process memory bounds, fairness, and a policy for slow-but-progressing consumers remain open. See the host contract.

• Compatibility: wider Unicode interaction, arbitrary terminal controls, Unix, SSH/tmux, and other terminals need targeted evidence from actual integration requirements. A second, independent terminal-side implementation is the cold-start constraint recorded in the adoption path.