refactor(clients): share opening a machine's No project folder

[bmdavis419]

Web and mobile each ran their own copy of the same two steps for threads without a project: create or find a machine's "No project" project, then wait until it reaches the client store. Each also had its own check for whether a machine can host these threads. #15356 added a third web caller when it let these drafts switch machines.

This moves both pieces into client-runtime:

• projectEnvironment.openScratch creates or finds the "No project" project and resolves once it reaches the client store. It replaces ensureScratch and each client's own wait.
• availableScratchWorkspaceRoot decides whether a machine is connected and offers "No project" right now.

Web's useScratchProject (used by the new-thread entry points and #15356's machine switch) and mobile's start and switch-machine flows now use both. A failed machine switch on web now says "Could not switch machine" instead of "Could not start without a project". The sidebar guide now mentions that these drafts can switch machines before sending.

No visible change beyond that error title. The machine switch shipped in #15356, which replaced this PR's original implementation; this branch keeps only the shared code. The shortcut that cycles machines is in #15391, stacked on this PR.

Verification

• A client-runtime test that openScratch resolves once the project reaches the client store.
• Existing tests for the composer draft store, ChatView logic and BranchToolbar logic pass.
• Web, mobile and client-runtime typecheck pass on the merge with main. Lint for ChatView matches main.
• Not run in a browser or on a device.

Originally implemented with GPT 6.1 Sol through the Codex harness in T3 Code; the shared code is by Claude Opus 5.5 through Claude Code in T3 Code.

🤖 Generated with Claude Code

[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	4.9 KiB	4.9 KiB	0 B (0.0%)	6.8 KiB	✅
Codex	Thread snapshot wire	3.7 KiB	3.7 KiB	0 B (0.0%)	4.9 KiB	✅
Codex	Live turn WebSocket wire	1.2 KiB	1.2 KiB	0 B (0.0%)	2.0 KiB	✅
Codex	Live turn WebSocket decoded	20.4 KiB	20.4 KiB	0 B (0.0%)	29.3 KiB	✅
Codex	Live turn messages	2	2	0 (0.0%)	8	✅
Claude	Total thread wire	4.9 KiB	4.9 KiB	0 B (0.0%)	6.8 KiB	✅
Claude	Thread snapshot wire	3.7 KiB	3.7 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	20.8 KiB	20.8 KiB	0 B (0.0%)	29.3 KiB	✅
Claude	Live turn messages	2	2	0 (0.0%)	8	✅

Baseline: 8fb068c · PR result: 7586c42 · 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: 106.1 KiB
• Claude decoded thread snapshot: 106.4 KiB

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

[macroscopeapp]

Approvability

Verdict: Approved at 7586c42

Macroscope's review found this PR approvable — This is a bounded client-runtime refactor that consolidates the existing No project creation and store-readiness flow for web and mobile, with focused test coverage and no schema, infrastructure, security, billing, or default-setting changes. Runtime impact is limited to shared readiness handling and machine-switch error wording.

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

[juliusmarminge]

Note

This comment is posted by Julius' dot

Closing for missing UI verification. The description promises UI evidence later, but no before/after screenshots or recording are attached for switching a projectless draft between machines. The verification requirement applies when the PR is opened. Attach before/after images and a short recording showing machine switching while preserving the draft, then request reconsideration.

[bmdavis419]

The missing UI verification is now attached in the PR description. GitHub artifacts include before/after screenshots and a 21-second recording showing dropdown switching followed by Ctrl+Alt+H cycling back with the prompt and draft URL preserved. The artifacts are stored in an unpublished draft release, accessible to signed-in repository maintainers, rather than committed source files.

This used two real isolated development servers. The only transport fixture supplies Vite's missing cross-origin preflight headers; the app's real auth, WebSockets, scratch-project creation, and draft retargeting remain in use. Both UI flows completed without page errors. The source is still 77c35b2, with CI green and 378 focused tests passing.

Please reconsider the closure and reopen for review now that the requested evidence is available.

[bmdavis419]

@coderabbitai full review

The PR was reopened after attaching the requested before/after screenshots and recording. Please review the current commit 77c35b2.

[coderabbitai]

✅ Action performed

Full review finished.

[juliusmarminge]

Note

This comment is posted by Julius' dot

I verified that the draft release contains the four screenshots and recording, but I can't open those files through my current access. Could you attach them directly to this PR or provide accessible links so I can assess the UI verification? This is an access gap, not missing evidence; the PR stays open pending inspection.

[bmdavis419]

The access gap is fixed. These GitHub-hosted evidence links are public and work without sign-in:

• Before
• After
• Switched machine
• Cycled back
• 21-second recording

The screenshots are unchanged PNGs embedded in SVG containers. The recording is an animated GIF converted from the original MP4 and embedded in SVG. I verified the public screenshot URL renders in an unauthenticated headless browser. The PR description includes the images and recording inline.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: pingdotgg/t3code/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 61940462-807b-4602-9b00-80c65ed4ba92

📥 Commits

Reviewing files that changed from the base of the PR and between 1c395ac and 00356d3.

📒 Files selected for processing (13)

• apps/mobile/src/features/threads/NewTaskContextPickerScreens.tsx
• apps/mobile/src/features/threads/NewTaskRouteScreen.tsx
• apps/mobile/src/features/threads/new-task-flow-provider.tsx
• apps/mobile/src/state/projects.ts
• apps/web/src/components/ChatView.tsx
• apps/web/src/hooks/useScratchDraftEnvironment.test.tsx
• apps/web/src/hooks/useScratchDraftEnvironment.ts
• apps/web/src/hooks/useScratchProject.ts
• apps/web/src/state/projects.ts
• docs/user/thread-sidebar.md
• packages/client-runtime/src/operations/projects.ts
• packages/client-runtime/src/state/projectCommands.test.ts
• packages/client-runtime/src/state/projectCommands.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/user/thread-sidebar.md

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

---

📝 Walkthrough

Walkthrough

Scratch projects now open through a command that returns the loaded project. Web and mobile flows use this command. Web Scratch drafts can switch environments before sending, with environment availability and send behavior updated to support that flow.

Changes

Scratch Draft Machine Selection

Layer / File(s)	Summary
Scratch project loading packages/client-runtime/src/state/projectCommands.ts, apps/web/src/state/projects.ts, apps/mobile/src/state/projects.ts, packages/client-runtime/src/state/projectCommands.test.ts	projectEnvironment now accepts a project lookup and exposes openScratch. The command waits for the project to appear in the client store, then returns it or fails with ScratchProjectNotLoadedError. Web and mobile state provide the project lookup. A test checks the successful result.
Scratch project availability and opening packages/client-runtime/src/operations/projects.ts, apps/web/src/hooks/useScratchProject.ts, apps/mobile/src/features/threads/NewTask*, apps/mobile/src/features/threads/new-task-flow-provider.tsx	availableScratchWorkspaceRoot returns a configured root for connected environments. Web and mobile Scratch flows use openScratch and handle its returned project directly.
Scratch environment selection apps/web/src/hooks/useScratchDraftEnvironment.ts, apps/web/src/hooks/useScratchDraftEnvironment.test.tsx	The new hook lists eligible environments and opens a Scratch project before updating the draft’s project and thread context. Tests cover selection, pending state, cancellation, and failures.
Composer environment integration apps/web/src/components/ChatView.tsx, apps/web/src/components/BranchToolbar.tsx, apps/web/src/components/BranchToolbarEnvironmentSelector.tsx, apps/web/src/components/chat/ThreadDetailsPanel.tsx, docs/user/thread-sidebar.md	Scratch drafts use the hook’s environment list. Environment changes are blocked during sends, and sending is blocked during preparation. Automatic environment selection is disabled for Scratch drafts. Environment option props no longer require projectId; the sidebar instructions describe starting on the current machine and switching before sending.

Priority: ⬇️ Low

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

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant ChatView
  participant useScratchDraftEnvironment
  participant projectEnvironment
  participant DraftStore
  ChatView->>useScratchDraftEnvironment: select target environment
  useScratchDraftEnvironment->>projectEnvironment: openScratch for target environment
  projectEnvironment-->>useScratchDraftEnvironment: return loaded Scratch project
  useScratchDraftEnvironment->>DraftStore: update eligible draft project and thread context

Loading

Suggested reviewers: juliusmarminge, t3dotgg

Merge Risk: ⚪ Minimal · up to 00356

Scratch draft machine switching appears mergeable after normal checks; no actionable issue remains from the inspected paths.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 00356

Machine switching is limited to connected environments that offer Scratch, and safeguards prevent delayed selections from overwriting moved or sent drafts. No introduced security vulnerability was established. Some authorization and interrupted-operation recovery behavior remains unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The new web behavior expands the possible destination of an unsent Scratch draft across eligible connected environments. Its security-relevant scope is the preserved draft content and subsequent turn on the selected machine, not a newly exposed unauthenticated network endpoint.

Security Findings and Attack Paths

• observed — In the inspected mobile start flow, incoming shared content contributes a share ID to navigation, not an arbitrary workspace path or project ID to Scratch creation. A reservation-release failure prevents project selection from completing.

Trust Boundaries and Controls

• observed — The shared availability predicate requires a connected environment and a configured Scratch root. These are client eligibility controls; they do not establish server-side authorization. The inspected server handler delegates to managed Scratch preparation.
• observed — Project preparation reads the project atom scoped by the requested environment and returned project ID. Draft switching additionally checks request ownership and draft identity, containing delayed completion rather than allowing it to overwrite a moved or promoted draft.

Resilience and Maintainability Implications

• observed — Server Scratch preparation uses a configured root, recreates its folder when needed, and accepts the winning project when concurrent creation conflicts. The inspected behavior supports reusable environment-level persistence rather than a separate disposable project for every draft selection.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 26.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 19 files. (1 skipped:…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly describes the shared handling of opening a machine’s “No project” folder and uses a concise conventional-commit format.
Description check	✅ Passed	The description explains the problem, shared changes, and verification results, including checks not run. It does not provide the template’s requested scope-and-approval details, but the rest is suffi…

Full details: Docstring Coverage

Explanation

Docstring coverage is 26.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 15 functions across 19 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 2

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

⚔️ Resolve merge conflicts 💡

• Resolve merge conflict in branch t3code/select-machine-new-thread

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

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

Autopilot is currently an internal CodeRabbit preview.

---

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