perf(desktop): reuse the prepared shell environment in the local backend

[Yash-Singh1]

Problem

On macOS, desktop startup loads the login-shell environment, then the local backend synchronously starts another login shell to hydrate PATH. The child already inherits the prepared environment, so the second probe adds an avoidable startup wait and blocks the backend event loop.

Change

Pass an optional shellEnvironmentPrepared flag through the existing desktop bootstrap contract. The local POSIX backend skips its duplicate PATH probe while retaining the HOME fallback. Standalone servers, older desktops, and WSL backends still hydrate their own environment; Windows retains its Node availability check and environment repair.

Use the existing shared shell candidate helper in the desktop so a GUI launch without SHELL still reads the account's configured shell before the platform fallback. Desktop probes collect output and wait for a successful exit in the same bounded scope; failed or timed-out probes continue to the next candidate. The existing standalone server probes keep their implementation, exit-code checks, and timeouts.

Scope and approval

This is maintainer-requested desktop startup performance work. Author Yash-Singh1 is listed in the upstream contribution-triage exemptions. The handoff applies to the desktop's local backend, which inherits the prepared environment. The one-class timeline focus-ring correction fixes the lint failure inherited from main.

Verification

The measurements below compare baseline b707eeb052 with the handoff implementation at 708dff9761. Values are medians of three launches per condition, measured from process spawn. The current revision keeps that handoff, removes the shared asynchronous probe rewrite, and fixes desktop shell selection and exit validation. These desktop timing samples predate those corrections; the final revision has not been rebenchmarked.

Shell scenario	Milestone	Baseline	This branch	Reduction
Real login shell	Backend HTTP ready	2.875 s	2.195 s	0.680 s / 23.6%
Real login shell	First visible window	3.741 s	3.109 s	0.632 s / 16.9%
Real login shell	Usable UI	4.262 s	3.682 s	0.580 s / 13.6%
Fixed 1-second shell	Backend HTTP ready	3.257 s	2.523 s	0.735 s / 22.6%
Fixed 1-second shell	First visible window	4.162 s	3.301 s	0.861 s / 20.7%
Fixed 1-second shell	Usable UI	4.699 s	3.878 s	0.820 s / 17.5%

The real-shell usable-UI range was 4.095 to 4.646 s at baseline and 3.587 to 4.114 s on this branch. With the fixed-delay shell, it was 4.664 to 5.376 s at baseline and 3.606 to 3.918 s on this branch. Quit remained around 2.1 s.

Measurements used macOS Electron 44.4.5 development builds with a bundled renderer and no compile cache. Each launch had fresh isolated state copied from an 840 KB database with 10 projects, no threads, and no pending work. Runs were sequential, with no concurrent builds or tests. Windows stayed unfocused on the built-in laptop display, with background throttling disabled consistently. The fixed-delay shell sleeps for one second before executing the environment capture command. These samples do not establish packaged warm-launch timings or performance with full production history; native Windows/Linux launches were not measured.

• 113 focused tests passed across the shared shell, server PATH hydration, CLI configuration, desktop bootstrap configuration, and desktop shell environment tests. New cases cover a missing SHELL on macOS and Linux, account-shell fallback, rejecting valid PATH output from a shell that exits with code 7, preserving HOME fallback, Windows repair, and leaving the handoff absent for WSL.
• Headless native macOS checks exercised actual subprocesses. A shell exiting with code 7 was rejected. A shell that closed stdout but kept running timed out after five seconds, received SIGTERM, and was rejected before fallback.
• Desktop, server, and contracts typechecks passed with Effect diagnostics enabled. Targeted lint, formatting, and git diff --check passed.
• Native Windows and Linux desktop launches were not run for this revision.

Individual timing samples, in seconds

Shell	Version	Trial	Backend HTTP ready	First window	Usable UI	Quit
Real	baseline	10	2.875	3.741	4.262	2.074
Real	baseline	11	3.293	4.116	4.646	2.081
Real	baseline	12	2.545	3.513	4.095	2.092
Real	shell	10	2.179	3.109	3.682	2.093
Real	shell	11	2.195	3.013	3.587	2.126
Real	shell	12	2.552	3.468	4.114	2.076
Fixed	baseline	10	3.238	4.151	4.664	2.077
Fixed	baseline	11	3.866	4.695	5.376	2.087
Fixed	baseline	12	3.257	4.162	4.699	2.083
Fixed	shell	10	2.229	3.128	3.606	2.163
Fixed	shell	11	2.523	3.301	3.878	2.084
Fixed	shell	12	2.575	3.309	3.918	2.081

Quit is measured from the quit request to OS process exit. Trials 10 through 12 are the final laptop-display batch; interrupted earlier samples are excluded.

Agents: Claude Sonnet 5.5 via T3 Code; gpt-6.1-sol via the Codex harness in T3 Code.

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ The exact PR base did not have a successful artifact. Baseline uses the latest successful main measurement shown below.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	5.0 KiB	4.9 KiB	−23 B (−0.5%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	−23 B (−1.9%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.9 KiB	20.8 KiB	−41 B (−0.2%)	29.3 KiB	✅
Codex	Live turn messages	2	1	−1 (−50.0%)	8	✅
Claude	Total thread wire	5.0 KiB	5.0 KiB	0 B (0.0%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.8 KiB	3.8 KiB	0 B (0.0%)	4.9 KiB	✅
Claude	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Claude	Live turn WebSocket decoded	21.2 KiB	21.2 KiB	0 B (0.0%)	29.3 KiB	✅
Claude	Live turn messages	2	2	0 (0.0%)	8	✅

Baseline: c1f21e5 · PR result: 55e2da8 · Source CI: success

Scenario and decoded snapshot size

10 historical turns, 5 command tools per turn, 878.9 KiB retained MCP result per historical turn, and a 1.05 MiB retained result in the measured turn.

• Codex decoded thread snapshot: 108.5 KiB
• Claude decoded thread snapshot: 108.8 KiB

Updated in place by a trusted workflow. PR artifacts are strictly validated and never executed.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes desktop startup and the backend bootstrap contract: the local server skips its POSIX PATH probe based on propagated state, while desktop shell probing and fallback behavior are also modified. It also adds a line-level static-analysis suppression in a test, warranting direct human review of the cross-process behavior and diagnostic override.

Notes:

• All code in this push has already been reviewed. Approvability was decided on eligibility alone.

^{You can add or adjust custom eligibility rules. Learn more.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Path: .coderabbit.config.ts
• Review profile: CHILL
• Plan: Team
• Run ID: 7248c8da-0e19-4673-8905-f28aba262667

---

---

📥 Commits

Reviewing files that changed from the base of the PR and between c4872b3 and 55e2da8.

---

---

📒 Files selected for processing (1)

• apps/web/src/components/chat/TimelineSystemDivider.tsx

---

---

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

---

---

---

📝 Walkthrough

📝 Walkthrough

Walkthrough

The desktop marks prepared shell environments in its bootstrap. The server passes this marker to fixPath, which skips POSIX PATH hydration when the marker is true while continuing to hydrate HOME. Desktop shell command output with a nonzero exit status is rejected.

Changes

Shell environment handoff

Layer / File(s)	Summary
Desktop shell setup apps/desktop/src/shell/DesktopShellEnvironment.ts, apps/desktop/src/shell/DesktopShellEnvironment.test.ts	Desktop shell candidate selection uses the shared helper. Command output is accepted only after a successful exit. Tests cover account-shell selection and unsuccessful commands.
Bootstrap marker propagation packages/contracts/src/desktopBootstrap.ts, apps/desktop/src/backend/DesktopBackendConfiguration.ts, apps/desktop/src/backend/DesktopBackendConfiguration.test.ts, apps/server/src/config.ts, apps/server/src/cli/config.ts, apps/server/src/cli/config.test.ts	The bootstrap schema adds the optional marker. The Windows primary bootstrap sets it to true, and server configuration preserves it when defined. Tests cover omitted and explicit marker values.
Server PATH handling apps/server/src/os-jank.ts, apps/server/src/os-jank.test.ts, apps/server/src/server.ts	fixPath skips POSIX PATH hydration when the marker is true, while continuing to hydrate HOME. The server passes the configured marker to fixPath; Windows PATH handling is unchanged.

Timeline focus ring

Layer / File(s)	Summary
Timeline action button focus ring apps/web/src/components/chat/TimelineSystemDivider.tsx	The action button’s focus-visible ring changes from outset to inset.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Other

Sequence Diagram(s)

sequenceDiagram
  participant DesktopApp
  participant resolveServerConfig
  participant fixPath
  DesktopApp->>resolveServerConfig: bootstrap with shellEnvironmentPrepared
  resolveServerConfig->>fixPath: pass configured shellEnvironmentPrepared
  fixPath->>fixPath: skip POSIX PATH hydration when true

Loading

Suggested reviewers: juliusmarminge

---

---

Merge Risk: ⚪ Minimal · up to 55e2d

The shell handoff does not remove a PATH recovery that previously succeeded, and the remaining described UI change only moves the focus ring inward. No concrete merge-blocking behavior is established.

Pre-merge checks | 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Title check		The title clearly and concisely describes the primary change: reusing the prepared shell environment in the local desktop backend.
Description check		The description includes complete Problem, Change, Scope and approval, and Verification sections. It explains the behavior, scope, approval basis, focused tests, performance measurements, limitations,…

---

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

---

---

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

---

---

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

---

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

[Yash-Singh1]

Note

Generated by GPT 6.1 Sol

This verdict is an automatic-approval eligibility decision, with no reported correctness defect. Human review of the startup handoff remains appropriate. Desktop environment preparation runs before the local child starts, and that child inherits the environment through extendEnv: true. Focused tests cover the bootstrap marker, prepared PATH and HOME, standalone hydration, the absent WSL marker, and Windows repair even with the marker set.

The diagnostic override is limited to the node:child_process import in os-jank.test.ts. The test spies on the existing synchronous probe to prove it is skipped without launching the user's login shell; production diagnostics remain enabled. The PR description now records the author's verified upstream triage exemption and scope. All required CI checks pass at 55e2da8.