feat: pick worktree or current checkout per project

[t3dotgg]

I default to "new worktree" on 90%+ of my projects, but a few work better on the current checkout. The default was one global setting, so the minority projects needed a manual composer flip on every new thread.

Now the default resolves per project:

explicit composer pick > per-project setting > t3.json > global setting

• Settings → Projects gets a "New threads" section: New worktree / Current checkout / Default. The Default option shows what it currently inherits (t3.json or global). Built on the settings page from feat(web): overhaul project settings into a real settings page #5768.
• Projects accept an optional defaultThreadEnvMode via project.meta.update (null clears it). Stored in a new projection_projects column (migration 039).
• t3.json accepts an optional defaultThreadEnvMode ("worktree" | "local") for checked-in repo defaults. The published JSON schema picks the field up automatically.
• The priority chain lives in one shared resolver (@t3tools/shared/threadEnvMode) used by both web and mobile, so the platforms cannot disagree on the order. Web resolves at draft creation through the cached project-file query atom; mobile resolves reactively.
• All new fields are optional on the wire, so mixed-version servers and clients keep working.

Tests: decider/projector round trip (set, omit, clear), shared resolver priority order, t3.json schema decode, parseT3ProjectFile, plus updated projection and settings-search fixtures. Full repo typecheck, lint, and the affected package suites pass.

---

Change authored by Claude Fable 5 via Claude Code.

🤖 Generated with Claude Code

---

Note

Medium Risk
Touches orchestration persistence (new column + migration), draft/new-thread timing with async t3.json reads, and concurrent navigation guards; behavior changes for default workspace mode but fields stay optional on the wire for mixed versions.

Overview
Adds a layered default for where new threads start: per-project setting → t3.json → global server setting, with an explicit composer pick still winning. New threads no longer rely only on the global defaultThreadEnvMode.

Server & contracts: defaultThreadEnvMode is persisted on projects via project.meta.update (nullable clears the override), projected through decider/projector/SQL (migration 039 on projection_projects), and exposed on project shells. ThreadEnvMode moves to environment.ts to avoid import cycles; t3.json gains optional defaultThreadEnvMode.

Shared logic: @t3tools/shared/threadEnvMode centralizes resolveDefaultThreadEnvMode and isDefaultThreadEnvModeSettled so web and mobile agree; parseT3ProjectFile supports reading repo defaults without surfacing decode errors.

Web: Project settings add a New threads → Workspace control (inherit / worktree / local) with inherited source shown. useHandleNewThread resolves defaults asynchronously (cached t3.json read), resets stale stored-draft workspace context to current defaults, and adds race guards around concurrent new-thread navigation.

Mobile: New-task flow reads t3.json, uses the shared resolver, and delays worktree branch auto-selection until the default is settled so a provisional global default is not frozen before t3.json loads.

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

Note

Add per-project default thread workspace mode (worktree or local checkout)

• Adds a defaultThreadEnvMode field to projects, propagated through the full stack: contracts, event sourcing, projections, DB (migration 039), and API responses.
• Adds a UI control in ProjectSettingsPanel.tsx to set per-project new-thread workspace mode (inherit / worktree / local), overriding t3.json and the global default.
• Resolution priority in resolveDefaultThreadEnvMode is: per-project setting → t3.json defaultThreadEnvMode → global server default.
• Branch auto-selection for worktree mode is deferred via isDefaultThreadEnvModeSettled until the project file finishes loading to avoid persisting provisional values.
• Risk: the new async resolution path in useNewThreadHandler and NewTaskFlowProvider introduces guards against race conditions where concurrent route/draft changes could overwrite state.

^{Macroscope summarized f682eca.}

[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 Plus

Run ID: b6ab4cc3-fb29-4c49-aea7-0cdec6403a01

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

---

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

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	11.3 KiB	11.3 KiB	−8 B (−0.1%)	15.1 KiB	✅
Codex	Thread snapshot wire	5.5 KiB	5.5 KiB	−6 B (−0.1%)	7.3 KiB	✅
Codex	Live turn WebSocket wire	5.9 KiB	5.9 KiB	−2 B (−0.0%)	7.8 KiB	✅
Codex	Live turn WebSocket decoded	49.7 KiB	49.7 KiB	0 B (0.0%)	66.4 KiB	✅
Codex	Live turn messages	16	16	0 (0.0%)	21	✅
Claude	Total thread wire	11.3 KiB	11.3 KiB	+26 B (+0.2%)	15.1 KiB	✅
Claude	Thread snapshot wire	5.5 KiB	5.5 KiB	+1 B (+0.0%)	7.3 KiB	✅
Claude	Live turn WebSocket wire	5.8 KiB	5.9 KiB	+25 B (+0.4%)	7.8 KiB	✅
Claude	Live turn WebSocket decoded	50.6 KiB	50.6 KiB	0 B (0.0%)	66.4 KiB	✅
Claude	Live turn messages	16	16	0 (0.0%)	21	✅

Baseline: 886195e · PR result: f682eca · 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: 94.6 KiB
• Claude decoded thread snapshot: 95.4 KiB

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

[macroscopeapp]

Approvability

Verdict: Needs human review

New feature adding per-project thread environment mode with database migration, orchestration changes, and async thread creation logic. An unresolved comment identifies a potential race condition in the new thread handler.

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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f682eca. Configure here.}