fix(examples): show custom description in Project Worktrees sidebar

[tk1475]

Summary

• The Project Worktrees example sidebar (com.example.cmux.sidebar.project-worktrees) always used the branch as the row subtitle and ignored workspace.customDescription, so descriptions set with cmux new-workspace --description never showed up.
• The row subtitle now prefers the trimmed custom description and falls back to the branch, matching the idiom already used by the Attention Queue and Dev Server examples. The helper is renamed from branchSubtitle to rowSubtitle since it is no longer branch-only.

This builds on the approach in #9625 by @austinywang, thank you. This version keeps the change to the example package and its unit tests.

Closes #4889

Testing

• Added ProjectWorktreeSidebarTests.swift (modeled on AttentionQueueSidebarTests.swift): description wins over branch for a grouped row, description wins for a pinned row, and a whitespace-only description falls back to the branch.
• Two commits: on the test-only commit the two description cases fail (subtitle was the branch); on the fix commit all pass.
• swift test --package-path Examples/CmuxExtensionSidebarExamples: 16 tests, 0 failures.
• No user-facing strings added or changed (only precedence between existing dynamic workspace fields), so no localization changes.

Checklist

• I tested the change locally
• I added or updated tests for behavior changes
• I updated docs/changelog if needed
• I requested bot reviews after my latest commit (copy/paste block above or equivalent)
• All code review bot comments are resolved
• All human review comments are resolved

🤖 Generated with Claude Code

---

Summary by cubic

Fixes the Project Worktrees example sidebar so row subtitles show a workspace's custom description instead of always defaulting to the branch.

• Subtitle prefers the trimmed custom description and falls back to the branch when the description is blank, matching the Attention Queue and Dev Server examples.
• Renames the helper from branchSubtitle to rowSubtitle since it's no longer branch-only.
• Adds unit tests covering description precedence for pinned and grouped rows plus the blank-description fallback.

^{Written for commit 43e6c08. Summary will update on new commits.}

Summary by CodeRabbit

• Bug Fixes
  • Workspace rows in the sidebar now show a custom description when one is available, for both pinned and regular workspaces.
  • If the description is blank or contains only whitespace, the row continues to show the branch summary instead.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[coderabbitai]

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

Warning

Review limit reached

Next included review available in 1 minute.

Check out review usage here.

View limit details

Limit details: You’ve used all 10 included reviews currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 6af482e9-2c17-43ac-be3e-9e3ed79ed263

📥 Commits

Reviewing files that changed from the base of the PR and between 42d24ea and 43e6c08.

📒 Files selected for processing (2)

• Examples/CmuxExtensionSidebarExamples/Sources/CmuxExtensionSidebarExamples/ProjectWorktreeSidebar.swift
• Examples/CmuxExtensionSidebarExamples/Tests/CmuxExtensionSidebarExamplesTests/ProjectWorktreeSidebarTests.swift

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: eb8a6caa-003c-4a34-8b14-0fdaef6e173c

📥 Commits

Reviewing files that changed from the base of the PR and between c307ab0 and 42d24ea.

📒 Files selected for processing (2)

• Examples/CmuxExtensionSidebarExamples/Sources/CmuxExtensionSidebarExamples/ProjectWorktreeSidebar.swift
• Examples/CmuxExtensionSidebarExamples/Tests/CmuxExtensionSidebarExamplesTests/ProjectWorktreeSidebarTests.swift

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

---

📝 Walkthrough

Walkthrough

Pinned and project-grouped workspace rows now display a trimmed custom description when present. Otherwise, they display the trimmed branch summary. Tests cover both row types and the fallback.

Changes

Workspace subtitles

Layer / File(s)	Summary
Subtitle selection and coverage Examples/CmuxExtensionSidebarExamples/Sources/CmuxExtensionSidebarExamples/ProjectWorktreeSidebar.swift, Examples/CmuxExtensionSidebarExamples/Tests/CmuxExtensionSidebarExamplesTests/ProjectWorktreeSidebarTests.swift	Pinned and project-grouped rows use the shared subtitle helper. It returns a trimmed custom description when present and otherwise returns the trimmed branch summary. Tests cover custom descriptions for regular and pinned workspaces, plus fallback for a whitespace-only description.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 42d24

The sidebar change appears ready to merge after normal checks.

🚥 Pre-merge checks | ✅ 23 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description clearly explains the problem, resulting behavior, implementation scope, tests, and localization result. It omits the required Changelog section and a demo video or screenshot for this …	Add a Changelog section with a present-tense user-facing entry, and add a short demo video or screenshot showing the custom description and branch fallback behavior. Preserve the existing testing details and checklist updates.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 6 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (23 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: showing custom descriptions in the Project Worktrees sidebar.
Linked Issues check	✅ Passed	Issue #4889 requires the Project Worktrees sidebar to show a nonempty custom description and to fall back to the branch summary. The implementation uses trimmed workspace.customDescription first and…
Out of Scope Changes check	✅ Passed	The changes stay within issue #4889. The helper rename and the added tests directly support the subtitle behavior. No unrelated product behavior or files are identified in the pull request summary.
Cmux Cloud Persistent Session And Early Input	✅ Passed	PASS: The pull request changes only Project Worktree sidebar subtitle rendering and its unit tests. The diff adds no Cloud terminal creation, cmux-tui client, transport, PTY or shell readiness, render…
Cmux Swift Actor Isolation	✅ Passed	PASS. The production diff only renames an existing private subtitle helper and changes its value-selection logic to read customDescription before branchSummary. It adds no actor, model, service pr…
Cmux Swift Blocking Runtime	✅ Passed	The production diff only renames branchSubtitle to rowSubtitle and selects between trimmed strings. It adds no semaphore, blocking wait, sleep, delayed dispatch, polling, main-queue sync, timer, o…
Cmux Browser Automation Off-Main	✅ Passed	PASS: The pull request changes only the Project Worktrees example sidebar and its tests. The diff contains no browser.* socket commands, WebKit callbacks, main-actor routing, worker routing, or brow…
Cmux Expensive Synchronous Load	✅ Passed	The changed production Swift file only renames the subtitle helper and selects customDescription or branchSummary from the already supplied snapshot. The diff adds no agent-history/session-store l…
Cmux Cache Substitution Correctness	✅ Passed	PASS — The diff changes only ProjectWorktreeSidebar rendering: it selects workspace.customDescription before workspace.branchSummary from the existing CmuxSidebarProviderWorkspace snapshot and t…
Cmux No Hacky Sleeps	✅ Passed	PASS: The pull request changes only Swift production code and Swift XCTest code. The diff adds no sleeps, timers, polling, delays, or wall-clock waits. The checked rule applies to non-Swift runtime ch…
Cmux Algorithmic Complexity	✅ Passed	PASS. The production diff only changes the per-workspace subtitle helper. It trims customDescription and, when absent, trims branchSummary; each operation is local to one workspace and does not sc…
Cmux Swift Concurrency	✅ Passed	PASS. The diff only changes synchronous subtitle selection in ProjectWorktreeSidebar.swift and adds XCTest coverage. It introduces no DispatchQueue, Task, Combine, completion-handler, async, o…
Cmux Swift @Concurrent	✅ Passed	PASS. The PR changes only synchronous render(snapshot:) and the synchronous rowSubtitle helper. The diff adds no async, nonisolated, @concurrent, or actor-isolation changes. The helper only …
Cmux Swift Package Boundaries	✅ Passed	PASS: The production change is confined to Examples/CmuxExtensionSidebarExamples, which already has a standalone SwiftPM target in Package.swift and depends on CmuxSidebarProviderKit. The change…
Cmux Swiftpm Lockfiles	✅ Passed	PASS. The PR changes only ProjectWorktreeSidebar.swift and its test file. It does not change a Package.swift, any Package.resolved, .gitignore, workflow, or Xcode project package reference. Th…
Cmux Swift Logging	✅ Passed	PASS: The pull request changes only subtitle selection in production Swift and adds unit tests. The diff adds no print, debugPrint, dump, NSLog, file/stdout diagnostics, Logger declarations, o…
Cmux User-Facing Error Privacy	✅ Passed	PASS: The diff updates a Project Worktrees sidebar row subtitle, not a user-facing error, alert, command error, API error body, or recovery message. It displays the existing user-configured `customDes…
Cmux Full Internationalization	✅ Passed	The pull request changes only subtitle selection and adds tests. It does not add or edit user-facing literal Swift text, string catalogs, Info.plist entries, web UI, metadata, API responses, rendered …
Cmux Swiftui State Layout	✅ Passed	PASS: The diff changes a CmuxSidebarProvider value-rendering function and adds XCTest coverage. It does not add SwiftUI views, ObservableObject, @Published, GeometryReader, lazy/list row store…
Cmux Architecture Rethink	✅ Passed	PASS. The diff is a small local correctness fix. It changes both sidebar sections to use one private rowSubtitle helper, which reads the workspace snapshot and applies the clear invariant: trimmed `…
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	PASS: The PR changes only ProjectWorktreeSidebar subtitle rendering and adds unit-test fixtures. The diff adds no NSWindow, NSPanel, NSWindowController, SwiftUI Window, WindowGroup, or standalone wind…
Cmux Source Artifacts	✅ Passed	The PR changes only the intentional Swift source file Examples/CmuxExtensionSidebarExamples/Sources/CmuxExtensionSidebarExamples/ProjectWorktreeSidebar.swift and its unit test `Examples/CmuxExtensio…
Cmux No Test Or Debug Seam In Production Source	✅ Passed	PASS — The production diff only renames the private branchSubtitle helper to rowSubtitle and adds description-first product behavior. It adds no #if DEBUG or test-build guard, no debug/test-name…

Full details: Description check

Explanation

The description clearly explains the problem, resulting behavior, implementation scope, tests, and localization result. It omits the required Changelog section and a demo video or screenshot for this UI behavior change.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Create a new PR

---

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

[teamleaderleo]

Review (merge-train). Straightforward and consistent with the rest of the examples. Nothing to change.

Review

1. It matches what the sibling providers already do. AttentionQueueSidebar.swift:82 and DevServerSidebar.swift:79 both already render customDescription as the subtitle. ProjectWorktreeSidebar was the odd one out, showing only branchSummary. So this is consistency rather than a new product call, and it does not need a design decision.

2. The precedence and the fallback are both right. customDescription first, branchSummary when it is absent, and trimmed applied to both, so a description of " \n" falls back instead of rendering an empty subtitle. Renaming branchSubtitle to rowSubtitle is the right call now that it is no longer branch-only.

3. Both call sites were updated, the pinned section at :26 and the per-project sections at :54. Easy one to half-apply; it is not half-applied here.

4. Test coverage is the right three cases: description wins over branch, the pinned section uses it too, and a whitespace-only description falls back to the branch. ProjectWorktreeSidebarTests.swift is new, so this provider had none before.

Fixed: nothing to fix.

Left: nothing.

What I did: same as your other PR, the branch was behind main and Web complexity was red on stale content hashes for files this change never touches. Merged current main in (clean, no conflicts) so the checks run against what actually lands.

Merging on green. Thanks :)

[teamleaderleo]

Correcting what I said earlier about merging on green: there is no green to merge on yet, and that is on our side rather than yours.

This is a fork PR, so the substantive workflows are all sitting at action_required waiting for a maintainer to approve them — CI, CI fast guards, Web validation and Testbox broker guard. The ten checks showing green on the PR are only the CLA, Socket, complexity and AI-reviewer bots. So nothing has actually compiled or run your new test.

I read both files end to end looking for anything that would make approving the run risky, and there is nothing: no workflow or build-script changes, and the new test spawns bash with a stubbed PATH inside a tempdir. I do not have permission to approve fork workflow runs from this session, though, so I am handing that to Leo rather than merging on bot-only checks.

Nothing needed from you. The review I posted still stands and the change still looks right to me. :)

[teamleaderleo]

Reviewed the focused diff and three tests. Custom descriptions correctly take precedence for pinned and grouped rows, with whitespace-only values falling back to the branch. Approving.

[teamleaderleo]

...Thank you very much! :)

[github-actions]

Merge receipt for 43e6c089d6: every check was green at merge (14 verified; 18 skipped by policy). Full suite runs on main after merge.