🤖 feat: sync a per-project VS Code .code-workspace file with worktrees by ibetitsmike · Pull Request #3932 · coder/xum

ibetitsmike · 2026-08-23T09:22:47Z

Summary

Opt-in per-project sync of a VS Code .code-workspace file with the worktree runtime: set a workspace-file path for a project in Settings → Runtimes and xum keeps that file's folders array in sync with the project's active worktree workspaces, so all worktrees are browsable from one VS Code / code-server multi-root window.

Fixes#3722

Background

Worktrees live under ~/.xum/src/<project>/<workspace>, invisible from an editor window opened on the main checkout. The issue (approved) asks xum to manage worktree paths in a .code-workspace file. The feature is opt-in per project because most users won't want xum writing editor files unprompted.

Implementation

src/node/worktree/codeWorkspaceSync.ts: reconcile module with a managed-entry invariant: xum only adds/removes folder entries whose resolved path is under the project's managed worktree root (<srcDir>/<projectName>/). User-added folders, the seeded project-root entry, comments, and settings/extensions blocks are never touched (JSONC edits via jsonc-parser, atomic writes via write-file-atomic). Malformed files are skipped, never clobbered; no-op syncs don't rewrite the file. Sync never throws, so lifecycle operations and startup cannot fail because of it.
Desired set: active (non-archived) top-level worktree workspaces of the project (sub-agent children and taskIsolation: "none" excluded); multi-project workspaces contribute their per-project checkout path.
Wiring: WorkspaceService create/createMultiProject/fork/rename/remove/archive/unarchive, plus startup reconciliation to repair drift from lifecycle changes while the app was closed. Rename is currently API-only (the UI rename action is intentionally omitted upstream until a proper modal exists); the sync wiring covers it for when that lands.
Setting: codeWorkspaceSyncPath on ProjectConfigSchema; projects.setCodeWorkspaceSyncPath ORPC setter validates the .code-workspace extension (BAD_REQUEST with a user-visible message) and syncs immediately on save. Clearing the setting never deletes previously written files.
UI: "VS Code workspace file" field in Settings → Runtimes under the per-project scope, following the Instructions draft + Save pattern.
Docs: short section in docs/runtime/worktree.mdx.

Validation

20 new tests (codeWorkspaceSync.test.ts, router setter tests), including red-green on the managed-root invariant and on the client-visible validation error.
Remote dogfood UAT on dev.coder.com against the pushed SHA: PASS across the create/archive/unarchive/delete lifecycle, startup drift repair, relative-path resolution, user-content preservation, and disabled-by-default inertness. UAT's one in-scope finding (validation error surfaced as "Internal server error") is fixed here and covered by a regression test.

Risks

Low. The feature is inert unless a project opts in. The write path is scoped by the managed-root invariant, skips malformed files, and all sync failures degrade to a log line rather than failing workspace operations.

Generated with xum • Model: anthropic:claude-fable-5 • Thinking: xhigh

mintlify · 2026-08-23T09:22:50Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Mux	🟢 Ready	View Preview	Aug 23, 2026, 9:23 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

ibetitsmike · 2026-08-23T09:23:03Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:ae0d83e53f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

ibetitsmike · 2026-08-23T09:56:36Z

@codex review

All six findings addressed in 0602c0d; threads replied to and resolved. Please take another look.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:0602c0db98

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Security Review

Here are some automated security review suggestions for this pull request.

Reviewed commit:0602c0db98

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

You comment "@codex security review"
A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

ibetitsmike · 2026-08-23T10:32:23Z

@codex review

All five round-2 findings addressed in 1042b0d; threads replied to and resolved. Please take another look.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:1042b0d825

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Security Review

Here are some automated security review suggestions for this pull request.

Reviewed commit:1042b0d825

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

You comment "@codex security review"
A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

ibetitsmike · 2026-08-23T11:05:24Z

@codex review

All four round-3 findings addressed in e22dfea; threads replied to and resolved. Please take another look.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:e22dfea4cc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Security Review

Here are some automated security review suggestions for this pull request.

Reviewed commit:e22dfea4cc

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

You comment "@codex security review"
A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

ibetitsmike · 2026-08-23T11:52:00Z

@codex review

All six round-4 findings (including both security threads) addressed in 19a7aea; threads replied to and resolved. Also fixed the Test / Unit CI regression from the round-2 pre-removal capture. Please take another look.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:19a7aeac06

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

ibetitsmike · 2026-08-23T12:34:22Z

@codex review

chatgpt-codex-connector

💡 Codex Security Review

Here are some automated security review suggestions for this pull request.

Reviewed commit:253966103b

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

You comment "@codex security review"
A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:253966103b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

ibetitsmike · 2026-08-23T12:53:39Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:0247540cc5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Security Review

Here are some automated security review suggestions for this pull request.

Reviewed commit:0247540cc5

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

You comment "@codex security review"
A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

ibetitsmike · 2026-08-23T13:15:24Z

@codex review

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:feb51a2bee

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

ibetitsmike · 2026-08-23T13:37:52Z

@codex review

chatgpt-codex-connector · 2026-08-23T13:41:19Z

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit:9a5ec0dcaa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

ibetitsmike · 2026-08-23T13:57:25Z

@codex review

…rktrees Opt-in per project: set a .code-workspace path in Settings -> Runtimes and xum reconciles the file's folders with the project's active worktree workspaces on create/rename/fork/archive/unarchive/delete and at startup. Only entries under the project's managed worktree root are ever touched; user folders, comments, and settings blocks are preserved via jsonc edits. Fixes#3722

UAT found the oRPC handler's plain Error mapped to a generic "Internal server error" toast; throw ORPCError(BAD_REQUEST) so the extension hint reaches the user.

- derive managed roots from each workspace's runtimeConfig.srcBaseDir so custom/legacy roots (e.g. pre-rename ~/.mux/src) stay synced - derive per-project checkout paths for multi-project workspaces (primary included; namedWorkspacePath is the _workspaces symlink container) - serialize read-modify-write per canonical file path (two projects can share one file) - write through symlinked workspace files instead of replacing the link - bound startup reconciliation with raceWithAbortAndTimeout (10s) - inline the context method instead of manual useCallback (React Compiler)

- bound every sync internally (raceWithAbortAndTimeout, 10s) so lifecycle operations cannot hang on a stalled filesystem; startup keeps its outer cap - capture a deleted workspace's managed roots before config removal so custom/legacy-root entries are still cleaned up - sanitize non-string codeWorkspaceSyncPath at config load (matches customInstructions handling) so projects.list cannot be bricked - reconcile all projects targeting the same file together so same-basename projects sharing a managed root cannot erase each other's entries - cap file size (1 MiB) before the synchronous JSONC parse

- scope deletion-time extra roots per involved project (managedRootsByProject) so one project's file never gains removal rights under another's root - group shared-file participants by canonical (realpath) target so symlink aliases of one file reconcile together - treat a matching subProjectPath as project membership and sync the sub-project's file on lifecycle changes of workspaces assigned to it - surface sync failures from the explicit settings save (ORPCError) and roll the setting back so a broken integration is not silently retried

- one-pass folders reconcile (single jsonc edit) so repo-controlled files with thousands of entries cannot block the main thread quadratically - reject non-regular targets and read via one descriptor with a byte cap (a symlink to /dev/zero reported size 0 but never reached EOF) - derive desired state inside the per-file critical section so an older lifecycle snapshot cannot overwrite a newer write - bound every canonicalization realpath (1s) so another project's dead mount cannot stall an unrelated sync - guard the setter rollback so a concurrent newer save is never discarded - include devcontainer workspaces (host worktrees under the default root) - capture removed-workspace roots best-effort so removal never fails on it

mintlifyBotdeployed to staging - docs August 23, 2026 09:23 View deployment

This comment has been minimized.
Sign in to view