feat(tui): add shared workspace registry protocol

[lawrencecchen]

Adds the shared workspace registry and attach lifecycle needed by detached/custom cmux TUI frontends.

What it adds

• stable workspace keys with monotonic compare-and-swap revisions
• empty workspace creation plus terminal and browser materialization
• revisioned create, rename, move, and close operations
• staged attach visibility, initial sizing, bounded rollback, and exact browser resize completion
• protocol v9 with legacy protocol-v6 compatibility
• Rust, TypeScript, Python, Go, and Java SDK support
• exact cmux and Ghostty artifact revision stamps

Correctness work

• maintains authoritative workspace ID and key indexes
• serializes create, apply-layout, move, and close operations per workspace
• retries stable-key close resolution to prevent ABA races
• registers pending surfaces before spawn so concurrent close cannot miss them
• scopes attach rollback invalidation to participating clients and surfaces
• bounds browser rollback waits without reinstalling failed claims or retaining waiter threads
• preserves fragmented identify responses across nonblocking read timeouts

Verification

• canonical branch autoreview clean on final head, confidence 0.9
• cargo test -p cmux-tui-core: 221 unit, 7 browser-runtime, 26 PTY, and 9 WebSocket tests
• cargo test -p cmux-tui: 268 unit and 5 CLI integration tests
• clippy clean for both Rust crates
• TypeScript SDK: 40 tests and build
• Python SDK: 18 tests
• Rust SDK: 15 tests
• Go SDK tests with race detector
• Java build, JSON, and wire-capture tests
• exact-head cmux-tui CI: https://github.com/manaflow-ai/cmux/actions/runs/29691291694
• exact-head tagged cloud build: https://github.com/manaflow-ai/cmux/actions/runs/29691303255
• tagged runtime preflight: registry revisions 0 through 6, stable-key create/rename/move/close, empty-workspace terminal materialization, 64x16 render attach, and detached TUI rendering

Final reviewed head: 7b0288a3b55dd9596f0f4d42543deb4992b065cc

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
cmux	Canceled		Jul 18, 2026 8:57am
cmux-staging	Building	Preview, Comment	Jul 18, 2026 8:57am

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The TUI adds stable workspace keys and monotonic revisions across mux state, commands, snapshots, events, and language bindings. Workspace mutations gain key selection and revision guards. Attachment sizing, failed-attach cleanup, terminal-event preservation, build metadata, and related tests are updated.

Changes

Workspace registry and protocol

Layer / File(s)	Summary
Workspace identity and revision runtime cmux-tui/crates/cmux-tui-core/src/model.rs, cmux-tui/crates/cmux-tui-core/src/mux.rs	Workspace state, indexes, revisions, placements, materialization, lifecycle mutations, and workspace deltas use stable keys and revision checks.
Workspace command and tree protocol cmux-tui/crates/cmux-tui-core/src/server.rs, cmux-tui/spec/*	Commands resolve numeric or key selectors, enforce expected revisions, return mutation metadata, and serialize revisioned snapshots and lifecycle events.
Workspace client bindings cmux-tui/bindings/go/*, cmux-tui/bindings/java/*, cmux-tui/bindings/python/*, cmux-tui/bindings/rust/*, cmux-tui/bindings/typescript/*	Go, Java, Python, Rust, and TypeScript clients expose workspace creation, terminal placement, registry mutations, attachment sizing, and revision-aware decoding.
Workspace and protocol validation cmux-tui/crates/cmux-tui-core/tests/*, cmux-tui/bindings/*/tests/*, cmux-tui/crates/cmux-tui/src/app.rs, cmux-tui/crates/cmux-tui/src/cli.rs	Tests validate stable keys, revision conflicts, materialization, placement results, lifecycle event payloads, drag destinations, and attachment-size encoding.

Runtime event and attachment behavior

Layer / File(s)	Summary
Terminal event preservation cmux-tui/crates/cmux-tui-core/src/event_bus.rs	Empty mailbox events preserve bounded surface-exit and workspace-closed events while clearing coalesced state.
Initial attachment sizing cmux-tui/crates/cmux-tui-core/src/server.rs, cmux-tui/crates/cmux-tui/src/cli.rs	Attach requests support paired dimensions, viewer sizing, and cleanup across render, browser, and VT failure paths.
Build metadata reporting cmux-tui/crates/cmux-tui/src/main.rs, ghostty	Identify and version responses can report cmux and Ghostty commits, and the Ghostty reference is updated.

Estimated code review effort: 5 (Critical) | ~100 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant ControlServer
  participant Mux
  Client->>ControlServer: Send workspace command with key and expected_revision
  ControlServer->>Mux: Resolve selector and apply guarded mutation
  Mux-->>ControlServer: Return workspace metadata and revision
  ControlServer-->>Client: Return JSON response and tree event

Loading

Possibly related PRs

• manaflow-ai/cmux#7886: Related TypeScript protocol typings, client plumbing, and attach-surface behavior.
• manaflow-ai/cmux#8031: Related protocol-v7 attachment and tree-delta machinery.
• manaflow-ai/cmux#8294: Related build-commit and Ghostty-commit metadata plumbing.

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 2 warnings)

Check name	Status	Explanation	Resolution
Cmux User-Facing Error Privacy	❌ Error	main.rs version output prints ghostty {commit}, and server identity adds ghostty_commit; both expose an upstream vendor in user-visible output.	Remove Ghostty/vendor labels from user-visible version and identity responses; keep the commit only in internal logs or generic build metadata.
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.36% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Description check	⚠️ Warning	The description covers summary and verification, but it misses the required Testing, Demo Video, Review Trigger, and Checklist sections.	Add the missing template sections: Testing, Demo Video, Review Trigger, and Checklist, and align the header to the required Summary format.

✅ Passed checks (22 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.
Cmux Swift Actor Isolation	✅ Passed	PASS: The PR diff contains no Swift source changes, so it cannot introduce or worsen Swift actor-isolation issues.
Cmux Swift Blocking Runtime	✅ Passed	No Swift files were changed in the diff, so the Swift blocking-runtime rule is not applicable.
Cmux Browser Automation Off-Main	✅ Passed	The PR doesn’t touch the rule-covered browser automation files; changed files only adjust workspace/attach docs and CLI sizing, with no browser.* main-actor routing changes.
Cmux Expensive Synchronous Load	✅ Passed	No Swift files are changed in the PR diff, so there’s no new main-actor sync agent-history load to flag.
Cmux Cache Substitution Correctness	✅ Passed	PASS: The TS changes only extend protocol types and request/response wiring; I found no persistence/history/undo/snapshot path swapping fresh reads for cached or opportunistic values.
Cmux No Hacky Sleeps	✅ Passed	No new sleep/timer/polling code appears in production TS runtime diffs; the only fixed 50ms wait is in the e2e test harness, which is allowed.
Cmux Algorithmic Complexity	✅ Passed	No new asymptotic hotspot: workspace lookups use hash maps, moves rebuild indexes linearly, and the attach/event scans are bounded or reused existing reducers.
Cmux Swift Concurrency	✅ Passed	No .swift files appear in the changed set or diff, so the Swift concurrency modernization rule doesn’t apply.
Cmux Swift @Concurrent	✅ Passed	No Swift files are changed in this PR diff, so the Swift concurrency annotation rule is not applicable.
Cmux Swift Package Boundaries	✅ Passed	No Swift sources or Package.swift files changed in the diff, so the Swift package-boundary rule is not applicable.
Cmux Swiftpm Lockfiles	✅ Passed	PR diff has no .gitignore, Package.swift/resolved, Xcode, or workflow changes, so the SwiftPM lockfile rule isn’t triggered.
Cmux Swift Logging	✅ Passed	PR diff vs main contains no .swift files, so no production Swift logging changes are in scope.
Cmux Full Internationalization	✅ Passed	No localized Swift/web surfaces were changed; the diff only touches protocol docs/specs, bindings, and tests, with no web/messages or locale files updated.
Cmux Swiftui State Layout	✅ Passed	PR changes only Rust/Go/TS/Java/docs; no SwiftUI files or state-layout patterns are present, so the rule is not applicable.
Cmux Architecture Rethink	✅ Passed	PR changes no Swift files, so the Swift architectural-rethink rule doesn’t apply; diff only touches Rust/Go/Java/Python/TS/docs.
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	No Swift source files were changed; the diff only touches Go/Java/TS/Rust/docs, so the auxiliary-window close-shortcut rule is not applicable.
Cmux Source Artifacts	✅ Passed	All changed paths are intentional source/docs/tests; no artifact, cache, build, or scratch directories were added. ghostty is a submodule gitlink update.
Cmux No Test Or Debug Seam In Production Source	✅ Passed	No changed files match Swift production Sources/ paths, so the no-test/debug-seam rule is not applicable.
Cmux No Ambient Global State	✅ Passed	No Swift files were changed in this PR, so the ambient-global-state Swift rule is not applicable.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding shared workspace registry protocol support.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/cmux-tui-workspace-registry

---

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

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[lawrencecchen]

Greptile Go Argv finding is intentionally not changed. The protocol distinguishes omitted argv, which selects the default shell, from explicitly supplied empty argv, which is invalid. Adding omitempty would collapse those two states. commandMap already removes nil values, while TestCreateTerminalPreservesExplicitlyEmptyArgv protects the explicit-empty case; exact-head Go and full cmux-tui CI are green.