Improve project action terminal readiness

[Quicksaver]

Summary

This PR implements terminal-backed project actions that route each project script through a stable action-specific terminal, wait for the target terminal to look input-ready before writing the command, and avoid reusing terminals that are still running non-shell subprocesses.

The current branch-local diff against upstream/main is limited to the terminal-backed project action surface: terminal selection/readiness helpers, ChatView command routing, terminal busy/idle inspection, action terminal labels, terminal UI availability guards, and focused tests.

Branch Update Status

• Generated from merge head 581766c495c688bb54f7d38e80323b34282a6e6a, which merged upstream/main at a9b1190a11276927caf573d92c33c5346fc4c076 into split/terminal-backed-project-actions; parent refs during the update were origin/main 32d8580bf4cc1a80b782b3b13507320e511b1976 and root main 72200a3c363da256b8d839b8337728b94d884bd5.
• After the upstream merge and terminal-UI availability guard follow-up, committed branch diff versus upstream/main is 29 ahead / 0 behind, covering 11 files with 1893 insertions and 85 deletions.
• Merge result: upstream/main merged cleanly with no Git conflicts. Incoming upstream behavior added desktop parallel WSL plus Windows backends with a mode picker, desktop-local backend registration and settings, and browser preview automation/recording stabilization.
• Conflict/compatibility note: no branch-owned terminal action files conflicted, but the upstream environment/backend expansion made terminal launch availability more important. apps/web/src/components/ChatView.tsx, apps/web/src/components/RightPanelTabs.tsx, apps/web/src/components/ProjectScriptsControl.tsx, and apps/web/src/components/chat/ChatHeader.tsx now keep project-action and terminal-surface run controls disabled unless an active project exists and the active environment is connected.
• New fork customization from the update: project action execution remains terminal-backed and reusable, while project action run controls now separate run availability from edit availability. The top-level run button is disabled while disconnected, dropdown rows no-op and show Unavailable, and the edit button remains reachable for existing actions.
• Retired/obsolete notes: none. Upstream did not reimplement reusable project action terminals, readiness waits, busy subprocess avoidance, launch reservations, structured attach causes, action terminal labels, collision-resistant IDs, or conservative POSIX busy detection.
• Remaining tech debt: terminal support is still inferred locally from active project plus connected environment because upstream does not yet advertise a dedicated terminal capability. If upstream adds an explicit terminal capability later, fold it into the local terminalUiAvailable decision instead of expanding protocol shape in this branch.

What Changed

• Added apps/web/src/projectScriptTerminals.ts to resolve stable encoded action-* terminal IDs, allocate numeric fallback instances when a primary action terminal is busy, detect prompt-like terminal output, and wait for project-action terminal input readiness with typed readiness failures.
• Added apps/web/src/state/projectActionTerminal.ts so the UI can track and strictly probe project-action terminal readiness while a command is being prepared.
• Updated apps/web/src/components/ChatView.tsx to route project actions through the action-terminal flow, prefer reusable idle terminals for the same project/worktree, probe shell-labeled busy action terminals before reuse, wait again after opening in case the session restarted, respect interrupted readiness probes, and fall back to a fresh action terminal when readiness cannot be proven.
• Updated terminal server subprocess inspection so POSIX shells can be treated as idle only when process-tree inspection proves there is no active non-shell descendant, while remaining conservative when inspection fails.
• Added readable action terminal labels, including parenthesized fallback instances such as Action: build (2).
• Added focused tests for action terminal ID selection, fallback collision avoidance, terminal prompt readiness, project-action command routing, metadata-only shell-terminal probing including Windows cmd.exe, POSIX idle-shell detection, conservative process-inspection fallback behavior, and action terminal labels.
• Hardened attach failure mapping, attach-after-open readiness, prompt detection, strict shell-readiness probing for metadata-only terminal state, Windows shell label handling, interrupted probe handling, post-open readiness waiting, and POSIX login-shell normalization.
• Hardened review follow-ups so in-flight project action launches reserve the selected terminal until open/probe/write finishes, preventing concurrent launches from selecting the same shell while preserving ready/probeable terminal reuse; attach subscription failures also preserve the structured Effect cause on ProjectActionTerminalAttachError.
• Hardened terminal UI compatibility with the upstream desktop-local backend work so terminal toggles, right-panel terminal surfaces, shortcuts, and project-action runs require an active connected project environment, while existing project actions can still be edited from ProjectScriptsControl when running them is unavailable.

Why

Project actions can open or reuse a terminal before the shell is actually ready to receive input. Writing the command too early can drop the action or target a terminal that is already busy. This PR makes the action path wait for an input-ready prompt, separates action terminal IDs from script IDs, and keeps terminal reuse conservative when busy/idle state cannot be proven.

Validation

• pnpm exec vp test related apps/web/src/components/ChatView.tsx apps/web/src/components/RightPanelTabs.tsx apps/web/src/components/ProjectScriptsControl.tsx apps/web/src/components/chat/ChatHeader.tsx --passWithNoTests passed with 1 file and 4 tests.
• pnpm exec vp test run apps/web/src/projectScriptTerminals.test.ts apps/server/src/terminal/Manager.test.ts packages/shared/src/terminalLabels.test.ts --passWithNoTests passed with 3 files and 95 tests.
• pnpm exec vp check passed with existing warnings outside the touched files.
• pnpm exec vp run typecheck passed.
• git diff --check passed.

Proof

• No screenshots, screencasts, or log files were added.

---

Note

Medium Risk
Changes terminal busy/idle semantics on POSIX and adds concurrent script-launch orchestration; behavior is heavily tested but misclassification could still affect reuse or metadata labels.

Overview
Project scripts no longer pick a generic thread terminal and write immediately. Each script gets a stable action-* terminal id (with numeric fallbacks when busy), the client classifies sessions by cwd/worktree and shell vs real subprocesses, reserves the chosen id for the whole open/probe/write flow, and waits for prompt-like output (strict probe + best-effort write path) before sending the command.

On the server, POSIX subprocess polling now loads comm= from ps, walks the tree, and treats an interactive shell child (including -bash) as idle when there is no non-shell descendant—reporting the first real descendant (e.g. pnpm) when present. If tree inspection fails, shell children stay busy (conservative).

UI disables running scripts and opening/splitting terminals when the environment is not connected; action-* tabs get readable Action: labels. New projectScriptTerminals helpers and projectActionTerminal commands wire readiness into ChatView.

^{Reviewed by Cursor Bugbot for commit e020f82. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Gate terminal UI on environment connectivity and improve project action terminal readiness detection

• Adds typed error classes (ProjectActionTerminalReadinessTimeoutError, ProjectActionTerminalAttachError) and readiness-wait effects in projectScriptTerminals.ts that detect shell prompts across Unix, PowerShell, and cmd, with timeout and best-effort variants.
• Improves POSIX subprocess inspection in Manager.ts to classify idle login shells as having no running subprocess, reporting the first non-shell descendant instead.
• Reworks runProjectScript in ChatView.tsx to select a ready terminal via resolveProjectActionTerminalId, track launch reservations, wait for prompt readiness before writing, and fall back to a new terminal on failure.
• Gates all terminal UI actions (open, split, create, right-panel add) behind terminalUiAvailable, which requires an active project with a connected environment.
• Adds human-friendly labels for action-* terminal IDs in terminalLabels.ts, decoding URL-encoded parts and formatting instance indices.
• Behavioral Change: terminal keyboard shortcuts and panel controls now no-op when the project host is not connected.

^{Macroscope summarized e020f82.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 76b0011e-2461-498c-89fd-59769440db8a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces significant new terminal readiness detection capability (~1900 additions) that changes when and how project scripts execute in terminals. The new prompt detection patterns, process tree inspection, and waiting mechanisms represent substantial runtime behavior changes that warrant human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[macroscopeapp]

One error-modeling convention violation found in the changed scope. See the inline comment.

^{Posted via Macroscope — Effect Service Conventions}