Unify launch env resolution on the server + introduce project/worktree/thread env vars

[tarik02]

What Changed

Server now owns T3CODE_* launch env for terminal and provider child processes.

• Added LaunchEnv to resolve home, project, thread, and worktree context from server state.
• Terminals resolve launch env on open/restart/attach, including draft-thread opens with a supplied projectId.
• Provider sessions use the same env path, with managed T3CODE_* keys stripped from inherited and client-supplied env.
• Web/mobile stop synthesizing T3CODE_*; they send cwd/worktree context plus projectId when needed.

Closes #3003

Why

Make t3code provide T3CODE_PROJECT_ROOT / T3CODE_WORKTREE_PATH (and related launch context) from one authoritative server path. Unified environment resolution between terminal and provider child processes, with managed-key filtering so parent/custom/client env cannot override or leak extra T3CODE_* values.

UI Changes

No UI changes.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes (N/A)
• I included a video for animation/interaction changes (N/A)

Note

Unify launch environment resolution on the server and introduce project/worktree/thread env vars

• Introduces a new LaunchEnv DI service (LaunchEnv.ts) that resolves T3CODE_HOME, T3CODE_PROJECT_ROOT, T3CODE_PROJECT_ID, T3CODE_THREAD_ID, and T3CODE_WORKTREE_PATH from server config and projection queries, replacing ad-hoc client-side env construction.
• TerminalManager.open, .restart, and .attach now pre-resolve worktreePath and env via LaunchEnv before spawning, mapping lookup failures to TerminalCwdError or TerminalSessionLookupError.
• ProviderCommandReactor passes a LaunchEnv-derived env map to providerService.startSession, so provider sessions (Claude, Codex, Cursor, Grok, OpenCode) receive authoritative context env.
• All provider adapters now merge per-session env via mergeProviderSessionEnvironment, which strips managed T3CODE_* keys from the base process env before applying overrides.
• Client-side code (ChatView, ThreadTerminalDrawer, ProjectSetupScriptRunner, mobile ThreadRouteScreen) no longer builds or sends runtimeEnv; only a projectId is forwarded and managed keys are stripped from any custom env before transmission.
• isManagedRuntimeEnvKey and stripManagedRuntimeEnvKeys are added to @t3tools/shared/launchEnv and used throughout to enforce the boundary between managed and user-defined env keys.
• Risk: TerminalManager now requires a LaunchEnv provider in its options; existing callers that do not provide one will fail to compile.

^{Macroscope summarized f189f37.}

---

Note

Medium Risk
Touches terminal spawn, provider child processes, and env merging across adapters; wrong resolution could break scripts/agents, but behavior is covered by new LaunchEnv and integration tests.

Overview
Server-authoritative T3CODE_* launch env replaces client-built runtime env for terminals, setup scripts, and provider sessions.

A new LaunchEnv service resolves T3CODE_HOME, project root/id, thread id, and worktree path from ServerConfig and projection snapshots. resolveForThread loads thread/project from the server (ignoring client projectId when the thread exists) and only accepts client projectId for draft threads not yet in the projection.

TerminalManager resolves env on open/restart/attach before PTY spawn; clients send projectId, cwd, and worktree path instead of full env. ProviderCommandReactor passes LaunchEnv-derived env into startSession; adapters merge it via mergeProviderSessionEnvironment.

Managed-key policy: @t3tools/shared/launchEnv adds stripManagedRuntimeEnvKeys / isManagedRuntimeEnvKey; server merges strip client T3CODE_* overrides and provider spawns strip inherited managed keys. projectScriptRuntimeEnv is removed from shared; web/mobile only forward non-managed custom env when needed.

Contracts add optional projectId on terminal open/restart/attach and optional env on provider session start. Effect layer wiring pulls LaunchEnvLive into terminal, reactors, and integration harnesses.

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

[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: fda8f6bd-4f87-4e6e-8282-393433b5aa50

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 and usage tips.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a new server-side LaunchEnv service that centralizes environment variable resolution, changing where and how runtime context (project, thread, worktree) is propagated to terminals and AI providers. This architectural change affects multiple subsystems and warrants human review.

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