Gate live output until initial screen snapshot

[schickling-assistant]

Why

A geometry-changing ATTACH delays its SCREEN snapshot for up to 80 ms while the child redraws. The socket currently joins live broadcasts immediately, so DATA or EXIT can arrive before SCREEN. An EXIT during that window is also sent again after SCREEN.

There is an additional parser boundary: xterm processes Terminal.write asynchronously. Merely suppressing a DATA broadcast during the delay can lose it if SCREEN is serialized before xterm parses that write.

What

Treat each ATTACH or PEEK as an initial synchronization phase:

• continue sending effective GEOMETRY immediately;
• suppress pre-cut broadcast DATA and EXIT while the redraw settles;
• at snapshot time, enqueue an empty xterm write as an ordered parser marker;
• serialize SCREEN in the marker callback;
• preserve DATA and EXIT arriving after the marker in a per-client ordered queue, then flush it after SCREEN;
• synthesize a pre-cut EXIT only after any final queued DATA;
• invalidate stale cuts when the same socket re-attaches or changes mode.

Rationale

The xterm write callback defines an exact cut: every earlier write is represented in SCREEN, while every later broadcast is replayed after SCREEN. node-pty drains PTY data before its public exit event, so a queued EXIT is already ordered after final DATA. An EXIT suppressed before the cut is synthesized after the post-cut queue. This preserves output order and emits exactly one EXIT.

Validation

Current head: fef0f14

• CI=1 npm run build
• CI=1 npm run typecheck
• focused synchronization and mode-switch tests: 7 passed
• complete integration suite after rebasing onto current main / merged Allow duplicate display names with unambiguous resolution #139: 60 passed
• npm run verify-docs: 13/13 passed

The tests deterministically hold xterm writes to reproduce parser backlog, verify SCREEN/DATA reconstruction without loss, verify both post-cut and pre-cut EXIT ordering, and cover same-socket pending re-ATTACH plus ATTACH-to-PEEK switching.

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	pty/schickling-assistant/2026-07-31-initial-attach-sync
machine	dev3
tooling_profile	dotfiles@0fb7e03

[schickling-assistant]

Thank you, Nathan — especially for pushing us to make the snapshot contract precise instead of papering over resize timing. The parser-cut + ordered post-cut queue is a much better foundation for every attached client.

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	pty/main
machine	dev3
tooling_profile	dotfiles@0fb7e03