Fix helper read-screen terminal materialization

Closed
AZ
2mo ago
+1039-69

Fixes https://github.com/manaflow-ai/cmux/issues/1472

Summary:

  • surface.read_text stays non-materializing by default.
  • Explicit CLI read entrypoints pass start_if_needed: true and retry the transient terminal_not_ready error while cold helper terminals start.
  • Non-demand reads, including find-window --content and legacy tmux HUD metadata sniffing, pass start_if_needed: false so scans do not spawn hidden PTYs.
  • Terminal read readiness now lives at the terminal lifecycle boundary via ensureTerminalSurfaceReadyForRead.
  • Added V2 contract coverage for terminal_not_ready and start_if_needed, plus a live CLI regression for cold background helper panes.

Red/green:

  • Red test commit: 698a2fa2cd test: cover helper read-screen materialization
  • Fix commit: 20e704c97d fix: materialize helper terminals for read-screen
  • Before fix: first explicit read-screen against a cold background helper could fail with internal_error: Failed to read terminal text; a later manual retry worked after the PTY appeared.
  • After fix: read-screen, capture-pane, and pipe-pane materialize separate cold helper surfaces, while tmux pane-command metadata probing remains non-materializing.

Checks run after rebasing onto current origin/main:

  • swift test --package-path Packages/CmuxControlSocket
  • swift test --package-path Packages/CmuxTerminal --filter TerminalSurfaceRestoreSpawnSchedulerTests
  • python3 -m py_compile tests_v2/test_cli_background_terminal_helpers_read_screen_starts_pty.py
  • python3 scripts/swift_file_length_budget.py --budget .github/swift-file-length-budget.tsv
  • ./scripts/lint-ios-package-conventions.sh
  • ./tests/test_ci_pbxproj_test_wiring.sh
  • ./scripts/check-pbxproj.sh
  • git diff --check
  • ../../scripts/reload-cloud.sh --tag hread (no builder fleet configured; fell back to local tagged build)
  • CMUX_SOCKET_PATH=/tmp/cmux-debug-hread.sock CMUXTERM_CLI="$HOME/Library/Developer/Xcode/DerivedData/cmux-hread/Build/Products/Debug/cmux DEV hread.app/Contents/Resources/bin/cmux" python3 tests_v2/test_cli_background_terminal_helpers_read_screen_starts_pty.py
  • CMUX_SOCKET_PATH=/tmp/cmux-debug-hread.sock CMUXTERM_CLI="$HOME/Library/Developer/Xcode/DerivedData/cmux-hread/Build/Products/Debug/cmux DEV hread.app/Contents/Resources/bin/cmux" python3 tests_v2/test_cli_background_terminal_helpers_start_pty.py
  • /Users/abdulazizalbahar/Dev/Manaflow/cmuxterm-hq/skills/autoreview/scripts/autoreview --mode branch --base origin/main

Tagged proof:

  • Tag: hread
  • The rebased tagged app responded on /tmp/cmux-debug-hread.sock and was moved to LG HDR 4K.
  • Rebased cold-background proof: cmux-assets/issue-helper-terminal-lifecycle/rebased-hread-20260615-232646/transcript.txt shows read-screen materializing surface:18 while in_window=false, sending HREAD_REBASED_1781591206, reading the token output back, and top reporting zsh/gitstatus processes for the helper surface.
  • Visible web-helper proof: cmux-assets/issue-helper-terminal-lifecycle/rebased-hread-web-helper-20260615-233344/transcript.txt shows a focus-false helper pane (surface:19) in the live hread workspace accepting the same-worktree web dev-server command, starting local Postgres, applying migrations, reaching Next.js Ready, and then exiting visibly because local Stack secret keys are missing. Final surface-health keeps surface:19 in_window=true and top reports zsh/gitstatus processes for it.
  • Caller workspace proof previews: workspace:52, pane:105, surface:304 for the cold-background transcript and surface:305 for the visible web-helper transcript.
  • /cmux-assets was read-only on this machine, so durable artifacts use the worktree fallback under cmux-assets/issue-helper-terminal-lifecycle/.
  • Visual screenshot proof remains blocked locally: screencapture produced a black image and Computer Use could not attach to the tagged CG window. Socket/read-screen proof is complete.

No merge until explicit dogfood approval.