Skip to content

docs(tui): align protocol contracts with runtime - #11403

Closed
lawrencecchen wants to merge 3 commits into
mainfrom
feat-tui-docs-contract-wave189
Closed

lawrencecchen wants to merge 3 commits into
mainfrom
feat-tui-docs-contract-wave189

Conversation

@lawrencecchen

@lawrencecchen lawrencecchen commented Sep 1, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Correct move-tab clamping, no-op, and cross-pane behavior in the command contract.
  • Document strict versus optional dimension-pair handling.
  • Align terminal-host v4 inventory and resize decoder documentation.
  • Clarify client lifecycle events for legacy and resource attachment streams.

Testing

  • git diff --check
  • python3 cmux-tui/scripts/check-spec-inventory.py
  • python3 -m unittest cmux-tui/scripts/test_check_spec_inventory.py
  • Canonical local autoreview, gpt-5.6-sol high, clean.

Scope

  • Documentation and inventory only. No runtime code changed.

Summary by cubic

Updates the TUI protocol docs and inventory so they match the runtime implementation. No runtime code changes.

Scope

  • Corrects move-tab clamping, no-op, and cross-pane behavior in the command contract.
  • Documents strict versus optional dimension-pair handling for size-aware commands.
  • Marks terminal-host inventory as v4 implemented, with v1-v3 negotiation still supported.
  • Clarifies client-attached and client-detached events for legacy and resource attachment streams.

Written for commit b02f174. Summary will update on new commits.

Review in cubic

Summary by CodeRabbit

  • Documentation
    • Clarified terminal sizing behavior, including errors for incomplete dimensions.
    • Documented move-tab behavior for clamped indexes, no-op moves, and pane cleanup.
    • Clarified when client attach and detach events are emitted.
    • Updated terminal host compatibility and rendering specifications to reflect v4 support and legacy negotiation.

@cursor

cursor Bot commented Sep 1, 2026

Copy link
Copy Markdown

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.

@vercel

vercel Bot commented Sep 1, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
cmux166 Ready Ready Preview Sep 1, 2026 5:19pm UTC
cmux41 Ready Ready Preview Sep 1, 2026 5:19pm UTC

@coderabbitai

coderabbitai Bot commented Sep 1, 2026 •

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 8fbf17f9-973f-4375-b068-a715f94f08da

📥 Commits

Reviewing files that changed from the base of the PR and between 2b07f89 and b02f174.

📒 Files selected for processing (4)
  • cmux-tui/spec/commands.md
  • cmux-tui/spec/events.md
  • cmux-tui/spec/inventory.json
  • cmux-tui/spec/programmability.md

Included review availability: Your plan provides up to 10 included reviews per hour; 0 remain after this review.


📝 Walkthrough

Walkthrough

The specification updates document stricter incomplete-size handling, verified move-tab behavior, control-connection event semantics, and terminal-host-v4 resize replay support with legacy negotiation compatibility.

Changes

Protocol specification

Layer / File(s) Summary
Command behavior contracts
cmux-tui/spec/commands.md
Documents strict cols and rows requirements for selected commands and verified move-tab clamping, no-op, pane-collapse, and error behavior.
Connection lifecycle events
cmux-tui/spec/events.md
Defines when client-attached and client-detached events are emitted.
Terminal-host-v4 compatibility
cmux-tui/spec/inventory.json, cmux-tui/spec/programmability.md
Updates terminal-host support to v4, documents negotiated v1-v4 resize payloads, and retains legacy v1-v3 negotiation support.

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

Merge Risk: ⚪ Minimal · up to b02f1

This change updates TUI protocol documentation and inventory without changing runtime behavior; no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 15
✅ Passed checks (15 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: aligning TUI protocol contracts with runtime behavior.
Description check ✅ Passed The description includes a clear summary, testing details, and scope that match the pull request objectives. The demo video is not needed for this documentation-only change. The review trigger and che…
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
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 complete PR range from 717f357 to b02f174 changes only four cmux-tui specification files. The diff contains no Swift paths and no production code changes, so it cannot introduce or wors…
Cmux Swift Blocking Runtime ✅ Passed PASS: The pull request diff from its documented base (HEAD~3) changes only four documentation/specification files: cmux-tui/spec/commands.md, events.md, inventory.json, and `programmability.md…
Cmux Browser Automation Off-Main ✅ Passed PASS: The pull request changes only four files under cmux-tui/spec/: commands.md, events.md, inventory.json, and programmability.md. The complete PR diff contains no browser automation, WebK…
Cmux Expensive Synchronous Load ✅ Passed PASS: The pull request changes only four documentation/specification files: cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. The exact PR range contains no Swift f…
Cmux Cache Substitution Correctness ✅ Passed PASS: The pull-request range from base 717f357 to HEAD changes only cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. The diff contains no Swift, TypeScript, or …
Cmux No Hacky Sleeps ✅ Passed PASS: The pull request diff from its base contains only four documentation/inventory files: cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. It introduces no TypeS…
Cmux Algorithmic Complexity ✅ Passed PASS: The pull request changes only four documentation/specification files: three Markdown files and one JSON inventory file. The verified diff contains no Swift, TypeScript, JavaScript, shell, or run…
Cmux Swift Concurrency ✅ Passed PASS: The cumulative PR diff from 717f357 changes only four documentation/spec files: cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. It contains no Swift paths or Swi…
Cmux Swift @Concurrent ✅ Passed PASS: The pull-request diff from HEAD~3 to HEAD changes only four documentation/specification files under cmux-tui/spec/: two Markdown files and one JSON inventory plus another Markdown file. It…
Cmux Swift Package Boundaries ✅ Passed PASS: The pull request diff contains only four documentation/specification files: cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. No .swift source, SwiftPM mani…
Full details: Description check

Explanation

The description includes a clear summary, testing details, and scope that match the pull request objectives. The demo video is not needed for this documentation-only change. The review trigger and checklist sections are omitted, but the description is otherwise mostly complete.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (4 skipped: 4 unsupported.)

Full details: Cmux Swift Actor Isolation

Explanation

PASS: The complete PR range from 717f357 to b02f174 changes only four cmux-tui specification files. The diff contains no Swift paths and no production code changes, so it cannot introduce or worsen Swift actor-isolation mistakes.

Full details: Cmux Swift Blocking Runtime

Explanation

PASS: The pull request diff from its documented base (HEAD~3) changes only four documentation/specification files: cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. It contains no Swift files and introduces no semaphores, blocking waits, sleeps, delayed dispatch, polling, main-queue synchronization, or manual locks. The check's production Swift-change failure condition is therefore not applicable.

Full details: Cmux Browser Automation Off-Main

Explanation

PASS: The pull request changes only four files under cmux-tui/spec/: commands.md, events.md, inventory.json, and programmability.md. The complete PR diff contains no browser automation, WebKit, socket policy, router, or policy-test paths. Therefore it introduces no browser.* routing or worker-lane behavior covered by the check, and it does not worsen existing browser automation debt.

Full details: Cmux Expensive Synchronous Load

Explanation

PASS: The pull request changes only four documentation/specification files: cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. The exact PR range contains no Swift files and no production source paths. Therefore, it does not add or move an expensive synchronous agent-history load onto the main actor or an interactive path.

Full details: Cmux Cache Substitution Correctness

Explanation

PASS: The pull-request range from base 717f357 to HEAD changes only cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. The diff contains no Swift, TypeScript, or JavaScript production changes, and it does not substitute a cache for an authoritative read.

Full details: Cmux No Hacky Sleeps

Explanation

PASS: The pull request diff from its base contains only four documentation/inventory files: cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. It introduces no TypeScript, JavaScript, shell, or build/runtime script changes. The no-hacky-sleeps check is therefore not applicable, and the diff introduces no covered delay or sleep.

Full details: Cmux Algorithmic Complexity

Explanation

PASS: The pull request changes only four documentation/specification files: three Markdown files and one JSON inventory file. The verified diff contains no Swift, TypeScript, JavaScript, shell, or runtime code, so it cannot introduce the algorithmic-complexity failures defined by this check.

Full details: Cmux Swift Concurrency

Explanation

PASS: The cumulative PR diff from 717f357 changes only four documentation/spec files: cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. It contains no Swift paths or Swift concurrency changes. Therefore, it does not introduce or expand any prohibited legacy async pattern.

Full details: Cmux Swift `@Concurrent`

Explanation

PASS: The pull-request diff from HEAD~3 to HEAD changes only four documentation/specification files under cmux-tui/spec/: two Markdown files and one JSON inventory plus another Markdown file. It contains no .swift paths or Swift concurrency tokens. Therefore, it introduces no @concurrent or nonisolated async violation and no changed UI-isolated async call site.

Full details: Cmux Swift Package Boundaries

Explanation

PASS: The pull request diff contains only four documentation/specification files: cmux-tui/spec/commands.md, events.md, inventory.json, and programmability.md. No .swift source, SwiftPM manifest, or Xcode project file changed. The Swift package-boundary check is therefore not applicable.

✨ Finishing Touches 💡 1
🛠️ Fix failing CI checks 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat-tui-docs-contract-wave189

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

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

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 4 files

You’re at about 96% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.

Re-trigger cubic

@lawrencecchen

Copy link
Copy Markdown
Contributor Author

Superseded by #11418, which contains the same documentation contract changes plus follow-up corrections and is based on current main.

This branch was successfully deployed

2 active deployments
Preview – cmux41 — b02f1741 Deployed Sep 1, 2026 by vercel[bot]
Preview – cmux166 — b02f1741 Deployed Sep 1, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant