Add framed machine attach stream

[schickling-assistant]

Builds on the ordered initial attach synchronization merged in #140; this branch is rebased onto that implementation rather than duplicating its server-side gating.

Why

Embedded terminal clients need effective geometry and terminal bytes on one ordered, machine-readable stream. Rendering raw bytes to stdout loses the GEOMETRY frame, while replacing stdout would also remove the controlling TTY used for input and resize negotiation.

What

• Add pty attach --attach-stream-fd-v1 for running sessions.
• Keep stdin/stdout as the controlling terminal, but write existing framed GEOMETRY, SCREEN, DATA, and EXIT packets to the inherited descriptor.
• Run the installed bin/pty launcher and CLI in one process, preserving all inherited descriptors without an option-specific forwarding layer or child process.
• Enforce GEOMETRY then SCREEN before DATA or EXIT on every initial connection and reconnect, rejecting pre-Gate live output until initial screen snapshot #140 partial daemons.
• Validate the descriptor before session resolution, surface stream failures as truncation on stderr, and fail streams that close without EXIT.
• Preserve one caller-owned stream across reconnects, with backpressure carried to each replacement socket.
• Model the FD as a required free-form completion argument in fish, bash, and zsh.
• Leave ordinary interactive attach behavior unchanged.

Contract

The descriptor must be writable and at least 3. pty flushes but never closes it; the caller owns EOF. stderr and terminal status text never enter the framed stream. Machine mode implies attach-only behavior and does not execute retained restart metadata.

Validation

• Typecheck and build pass.
• 103 focused tests pass, covering stream behavior, the installed launcher lifecycle, launchd argv preservation, protocol, geometry, stats, help, gc, and generated completions.
• A real Nix-packaged bin/pty attach through fd 3 produced GEOMETRY, SCREEN, DATA, EXIT in order with zero terminal output.
• Machine-stream tests cover fragmented/coalesced input, per-connection initial ordering, reconnect reset, real controlling-TTY geometry, zero stdout bytes, invalid and broken descriptors, caller FD ownership, truncation, and reconnects.
• Completion tests verify the FD is consumed before session completion and checked-in fish/bash/zsh artifacts match the generator.
• Full suite: 1474 tests pass; four host-interactive shell/editor startup tests time out under current host load. The representative zsh failure reproduces unchanged at the pre-launcher commit.
• Executable docs: 12 of 13 pass; the existing Vim example times out during host-interactive startup and is unrelated to this change.

Tradeoffs

A dedicated inherited descriptor is more explicit than multiplexing stdout and retains normal terminal ownership. Loading the CLI in the launcher process removes the prior child/signal-forwarding layer and preserves arbitrary inherited descriptors without parsing CLI options twice. The versioned flag leaves room for a future incompatible stream contract. Initial snapshot gating remains owned by #140 rather than being duplicated in the 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/schickling-assistant/2026-07-31-machine-attach-stream
machine	dev3
tooling_profile	dotfiles@0fb7e03

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[schickling-assistant]

Thank you, Nathan — the push to preserve PTY’s existing responsibilities while exposing one ordered machine stream led to a much simpler boundary: one CLI process, one framed descriptor, and no duplicated socket client in Fractal.

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