Preserve live background terminals through first renderer mount

[nwparker]

	Files	Added	Deleted	Net
Test	3	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​241	$\color{#cf222e}{\Huge{\mathbf{−}}}$​15	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​226
Prod	4	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​167	$\color{#cf222e}{\Huge{\mathbf{−}}}$​9	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​158

ELI5

Opening the desktop window must attach to the agent and Setup terminals already running in the background. It must not discard their live connections or start them again.

What Changed

Preserve a host-owned PTY when the incoming renderer leaf has the same workspace, tab and pane identity but has not bound that PTY yet. Require one live owner, reject conflicting claims, and retain inactive panes only when the renderer published that exact identity. Reload preservation now also requires the same workspace.

Why

A temporarily empty renderer graph is incomplete evidence, not permission to retire a host-owned process. Adopt the narrow projection approach from #23749, also addressing #23785. Adversarial review found and fixed cross-workspace reuse during reload. The fake Codex launcher now answers version probes without recording them as agent launches.

Linked Issue

Addresses part of #21489. Replacement for #23749 and #23785; leave originals open until this merges.

Visual Proof

Native macOS validation after reload, with input reaching the original Setup and agent PTYs:

These are validation images. Current main also passes the native flow; the reproducible failures are in the deterministic host-graph tests, so there is no native before/after failure claim.

Testing

• Relevant failures reproduced before their fixes; automated regressions retained. Rebase-specific failures and fixes are described below.
• Rebased assembled application tree: 6,117 tests passed (four skips); full typecheck and changed-code quality passed, with zero findings across 151 changed files.
• Fresh app and CLI builds; four hidden macOS flows passed: open/edit/save, first-mount agent/Setup PTY identity, GUI last-host archive, and separate CLI last-host archive. The final main refresh changes only CI files; the application tree is identical to this tested tree.
• The new ten-shard CI planner from main passes all 82 focused tests.
• Earlier-base isolated native Windows and Linux runs passed the same four flows: Windows, Linux. These are historical evidence, not verification of this rebased head.
• Required CI for rebased head 573a597645dc; wait for current-head checks before merging.

Review

Compared with #23749 and #23785. The earlier projection could reuse a PTY from another workspace; exact workspace/tab/pane identity and one live unclaimed owner are now required. The native oracle verifies PID, PTY incarnation, input, and no second launch across reload. Short viewport tokens prevent Windows line wrapping from invalidating the oracle. Real shell fixtures run in Node rather than Bun. Main also passes the native flow; deterministic graph regressions provide the red reproduction.

The series includes local/direct SSH isolation, folder workspaces, and remote authority coverage. Real Windows+WSL reproduction of the original damaged profile and a native nested SSH recovery/save journey remain unverified. #25938 and the independent CI memory fix #26049 are merged.

Rebased onto main 00984ccb2504, including #24863 and #26088. Exact workspace/tab/pane matching, captured PTY incarnation, and conflicting-owner rejection remain intact. The fresh hidden macOS run retains the same running agent/Setup PTYs without a second launch. Low risk once current-head CI passes.

Agent skill upstream boundary

• Not applicable.

Checklist

• Explained user-facing behavior, mechanism, and tradeoffs.
• Visual proof attached above, or N/A with reason.
• Self-reviewed correctness, data preservation, and performance.
• Cross-platform, SSH, folder-workspace, and compatibility impact considered.
• Current-head CI is green before merge.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 63973a56-8b24-4642-971e-ffcb005a48ab

📥 Commits

Reviewing files that changed from the base of the PR and between 510642b and 573a597.

📒 Files selected for processing (1)

• config/scripts/vitest-node-runtime-files.mjs

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

Runtime graph synchronization now resolves and projects eligible runtime-owned PTYs for terminal panes. It also preserves qualifying published panes and retains reload-time handling for PTYs with a handle or matching incarnation. Runtime tests cover projection, pane changes, and orphan reporting. Test harness updates adjust Codex probing, E2E setup, and Node and SQLite runtime test selections.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 573a5

The PR aims to preserve live terminals through the renderer’s first mount. The supplied review evidence establishes no specific failure, so it presents no evidence-based merge blocker.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.18% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 7 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The only directly linked issue provided is #26049. Issue #26049 is closed and completed, so it supplies historical context only. No active directly linked issue imposes coding requirements for this pu…
Out of Scope Changes check	✅ Passed	The changes remain within the pull request scope. The runtime projection changes preserve host-owned PTYs during renderer mount and reload. The new tests cover ownership, workspace identity, pane rete…
Title check	✅ Passed	The title clearly and concisely describes the primary change: preserving live background terminals through the renderer's first mount.
Description check	✅ Passed	The description includes the required sections, explains the user-facing behavior and implementation, identifies linked issues, provides visual proof, documents testing, and addresses compatibility an…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[nwparker]

Compared with #23749 and #23785. The earlier projection could reuse a PTY from another workspace; exact workspace/tab/pane identity and one live unclaimed owner are now required. The native oracle verifies PID, PTY incarnation, input, and no second launch across reload. Short viewport tokens prevent Windows line wrapping from invalidating the oracle. Real shell fixtures run in Node rather than Bun. Main also passes the native flow; deterministic graph regressions provide the red reproduction.

Final assembled verification: 6,313 tests pass (five skips) in 563 suites, plus 48 upstream authority tests and 81 serial compatibility tests. Typecheck and changed-code quality pass (147 files, zero findings). Fresh hidden macOS and isolated Windows/Linux each pass all four native flows. Windows: https://github.com/stablyai/orca/actions/runs/37556420437. Linux: https://github.com/stablyai/orca/actions/runs/37557129429. Current-head CI is green on 510642b1d92e; merge recommended. Contributor originals remain open until their replacements merge.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to GitHub limitations.

⚠️ Outside diff range comments (1)

🟠 Major · Track the exact-leaf layout PTY as published. · runtime-owned-terminal-projection.ts:43-52

src/main/runtime/runtime-owned-terminal-projection.ts:43-52
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Track the exact-leaf layout PTY as published.

When tab.ptyId is null, the renderer can publish the PTY through tab.parentLayout.ptyIdsByLeafId[tab.leafId]. This collector then classifies the pane as empty and omits that PTY from boundPtyIds. Graph sync can therefore retain an old runtime PTY and miss the layout PTY claim.

Suggested fix

-      if (tab.ptyId) {
-        boundPtyIds.add(tab.ptyId)
+      const publishedPtyId =
+        tab.ptyId || tab.parentLayout?.ptyIdsByLeafId?.[tab.leafId]
+      if (publishedPtyId) {
+        boundPtyIds.add(publishedPtyId)

---

ℹ️ Review info

⚙️ Run configuration

• Configuration used: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 64c35931-4855-4ad1-a0ee-acbcdb406dc1

📥 Commits

Reviewing files that changed from the base of the PR and between b051d6c and 510642b.

📒 Files selected for processing (3)

• config/scripts/vitest-node-runtime-files.mjs
• config/scripts/vitest-sqlite-database-runtime-files.mjs
• tests/e2e/live-background-terminal-mount-authority.spec.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

[nwparker]

Adversarial self-review of rebased head 573a597645dc.

Rebased onto main 00984ccb2504, including #24863 and #26088. Exact workspace/tab/pane matching, captured PTY incarnation, and conflicting-owner rejection remain intact. The fresh hidden macOS run retains the same running agent/Setup PTYs without a second launch. Low risk once current-head CI passes.

Validation of the assembled rebased application tree: 6,117 tests passed (four skips), full typecheck, zero changed-code quality findings across 151 files, fresh app/CLI builds, and all four hidden macOS flows. The final main refresh is CI-only and its 82 planner tests pass. Earlier Windows/Linux native runs were on the previous base; current-head CI must pass before merge.

Contributor references and coauthor trailers are preserved. The original damaged Windows+WSL profile and a native nested SSH recovery/save journey remain unverified; this does not justify closing #21489. No PRs were merged or superseded contributor PRs closed during this rebase.