refactor(server): threads without a project run through a ScratchWorkspace service

[juliusmarminge]

#13612 started threads without a project from inline code in the ws.ts WebSocket handler. Agents, scheduled tasks and the MCP server couldn't reach it, and only the client's first-turn path got a per-thread folder. This moves it into a ScratchWorkspace service, so every V2 launch path, and MCP, goes through one place.

Stacked on #14504 (the main merge, which stubs projects.ensureScratch). Both merge together.

Design

apps/server/src/project/ScratchWorkspace.ts, a Context.Service with make/layer, imported as a namespace everywhere:

• root: Effect<Option<string>>: the folder at <baseDir>/scratch. It is offered only when the data dir is outside a Git checkout. Like feat: start threads without a project #13612, it's probed once and cached, and an interrupted probe clears the cache.
• ensureProject: Effect<{ projectId }, ScratchWorkspaceError>: creates one "No project" project per environment on ProjectService.bootstrap, with the dashed-bubble icon set only at create.
  • bootstrap looks up the root before it takes the workspace lock, so concurrent first calls do race. The loser's ProjectConflictError names the winner, and the service returns that project.
  • The folder is re-created on every call.
• folderForThread({ projectId, threadId, text }): Some only for the Scratch project.
  • It claims a fresh <date>-<first words>-<id tail> folder under the root, using feat: start threads without a project #13612's naming and its fallback from the short id to the full id.
  • The short name uses the id's tail, because V2 thread ids share prefixes such as thread:….
• Errors are Schema.TaggedErrors, ScratchWorkspaceUnavailableError, ScratchWorkspaceFolderError and ScratchWorkspaceProjectError, with bounded messages and cause kept.

Where threads get their folder. ThreadLaunchService.launch claims a folder when a Scratch thread is launched with the root workspace strategy, and binds it the way it binds an existing worktree (worktreePath on create, then preparation runs there). That covers:

• web and mobile first turns (orchestration.launchThread);
• MCP t3_thread_launch;
• scheduled tasks;
• ACP session import;
• startup auto-bootstrap.

A retried launch keeps the folder its first attempt bound. Threads in other projects, and non-root strategies, are untouched.

Two paths don't go through the launch service:

• the bare thread.create command, which web uses only for "implement plan in a new thread" (it copies the parent's worktreePath);
• MCP create_threads, which inherits the parent's folder.

Both run in an existing folder, as in #13612.

ws.ts is now a few lines:

• projects.ensureScratch calls ensureProject;
• the config answer adds scratchWorkspaceRoot from root.

MCP. t3_thread_launch takes scratch: true, which resolves the project with ensureProject and then launches at the root, so the thread gets its own folder. Combining it with projectId or workspaceStrategy is rejected.

Layer. The service is provided in runtimeLayer.ts next to ProjectService, for ThreadLaunchService, ws.ts and the MCP handlers.

Docs. The user docs #13612 added (thread-sidebar.md, keybindings.md) still describe the behaviour. The MCP doc gains one sentence on scratch: true.

Verification

• tsc --noEmit -p apps/server: exit 0, with no error TS or warning TS.
• Inside unshare -U -p (112 passed):
  • ScratchWorkspace.test.ts (new): real ProjectService on SQLite, real Git detection, real temp folders.
    • Scratch is offered outside a checkout and refused inside a git init'd one.
    • Eight concurrent ensureProject calls give one titled, iconed project.
    • The folder is re-created after deletion, both for ensureProject and for folderForThread.
    • Two threads with the same message get distinct folders named from it.
    • A pasted blob stays one bounded path segment.
    • A thread in another project gets no folder.
  • ThreadLaunchService.test.ts: a new test checks that a root launch in the Scratch project binds its folder and runs setup there, that a retry claims no second folder, and that another project gets none.
  • mcp/toolkits/project/handlers.test.ts: a new test checks that scratch: true launches into the Scratch project and that scratch plus projectId is refused.
  • Also core.test.ts, ws.test.ts, ScheduledTaskService.test.ts and runtimeLayer.test.ts, and OrchestratorReplayFixtures.integration.test.ts before the rebase.
• Mutation checks:
  • dropping the conflict handling fails the race test;
  • always offering Scratch fails the checkout test;
  • not passing the folder to preparation fails the launch test.
• vp lint on the touched files: no new warnings (the existing ws.ts and test warnings are on the base). vp fmt --check is clean, and vp run knip:check is clean.
• The namespace audit (ns-audit.py) finds 0 violations in the touched files.
• Not run: a live client pass, and the full suites.

Model: Claude Opus 5.5 (Claude Code)

🤖 Generated with Claude Code

---

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This change adds a cross-cutting ScratchWorkspace capability with persistent project and filesystem provisioning, new MCP and WebSocket behavior, and retry-aware orchestration integration. Its substantial new service and runtime surface go beyond a bounded additive option.

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

[github-actions]

Thread transfer impact

✅ Thread transfer remains within every enforced ceiling.

ℹ️ No successful main baseline artifact is available yet. This run establishes the initial measurement.

Provider	Metric	Main baseline	This PR	Impact	PR ceiling
Codex	Total thread wire	—	4.9 KiB	—	6.8 KiB	✅
Codex	Thread snapshot wire	—	3.7 KiB	—	4.9 KiB	✅
Codex	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Codex	Live turn WebSocket decoded	—	20.4 KiB	—	29.3 KiB	✅
Codex	Live turn messages	—	2	—	8	✅
Claude	Total thread wire	—	4.9 KiB	—	6.8 KiB	✅
Claude	Thread snapshot wire	—	3.7 KiB	—	4.9 KiB	✅
Claude	Live turn WebSocket wire	—	1.2 KiB	—	2.0 KiB	✅
Claude	Live turn WebSocket decoded	—	20.8 KiB	—	29.3 KiB	✅
Claude	Live turn messages	—	2	—	8	✅

Baseline: unavailable · PR result: d17305f · 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.