Stream effective PTY geometry to embedded clients

[myobie]

Summary

• add a stream-ordered GEOMETRY protocol packet for the daemon's authoritative shared grid
• deliver effective geometry to writable ATTACH and read-only PEEK output streams before affected SCREEN/DATA
• update SessionConnection, server-mode testing Session, and attachPty() to resize their emulators from authoritative geometry rather than requested size
• preserve writable-only min-wins arbitration and zero-viewer last-size behavior

Closes #134.

Ordering and compatibility

On an effective-size transition, the daemon resizes its emulator, queues GEOMETRY to attached output streams, then resizes the child PTY. Output caused by the resize therefore follows the geometry packet on each stream. A newly attached client receives current geometry before its initial screen.

GEOMETRY uses message type 10; types 8 and 9 remain reserved for the independent activity/guarded-send drafts. Existing packet readers remain compatible because framed unknown messages are ignored without losing the following DATA packet; this is covered by regression.

Validation

• npm run typecheck
• npm run build
• npm run verify-docs — 13/13
• focused protocol/geometry/connection/integration/TUI resize suite — 108/108
• expanded relevant suite — 155 passed; only the two documented host Nano terminfo failures
• new real-PTY effective-geometry suite — 6/6, repeated five times
• git diff --check

Draft only: no merge or deployment.

[schickling-assistant]

The ordered GEOMETRY direction looks sound: effective min-wins remains unchanged, the daemon emits geometry before resizing the child, and the requested/effective split avoids a ptyView feedback loop. I found two compatibility/ordering blockers before this can safely be treated as an authoritative reconstruction contract:

1. New client against an older daemon. attachPty.resize() now waits for GEOMETRY before resizing its local xterm. An older daemon never sends that packet, so its child accepts the resize while the new client keeps parsing at the old width. Likewise, SessionConnection.effectiveRows/effectiveCols remain initialized to the requested size and appear authoritative even when no authoritative packet was observed. Since a new daemon guarantees initial GEOMETRY before SCREEN, receiving SCREEN without prior geometry can identify legacy mode without a timeout. That path should retain historical optimistic local resize behavior and expose that authoritative geometry is unavailable.

2. Live output or exit can overtake the delayed initial screen. An attaching socket participates in broadcast() immediately, while SCREEN may be delayed by 80 ms. The stream can therefore be GEOMETRY, DATA/EXIT, SCREEN and, if the child exits during the delay, potentially a second EXIT from sendScreen(). Embedded clients parse the early delta and then reset on SCREEN. Either gate/queue a client until an exact snapshot cut and then drain later deltas, or narrow the PR claim to geometry packet ordering rather than reconstructable snapshot-plus-delta state.

Two bounded follow-ups would complete the proof:

• make attachPty() readiness packet-driven by the initial screen/geometry path rather than treating 100 ms as success;
• add cross-axis min-wins coverage plus new-client/legacy-daemon tests, including an own-resize after connection.

These concerns do not challenge the geometry packet itself or the existing writable-only arbitration policy; they are about making the new public guarantee truthful across initial synchronization and mixed versions.

Posted on behalf of @schickling

field	value
agent_name	co1-sage
agent_session_id	ed878dac-3735-4276-b3e0-ea1b1cd65291
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	dotfiles/schickling/2026-07-20-cos-misc
machine	dev3
tooling_profile	dotfiles@0fb7e03

[schickling-assistant]

Thank you, Nathan — both for the implementation and for pressure-testing the contract with us. The ordered effective-geometry primitive gives the downstream work a much cleaner foundation.

Posted on behalf of @schickling

field	value
agent_name	co1-sage
agent_session_id	ed878dac-3735-4276-b3e0-ea1b1cd65291
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	dotfiles/schickling/2026-07-20-cos-misc
machine	dev3
tooling_profile	dotfiles@0fb7e03