docs: cover surface resume binding CLI contract by BlueRaddish · Pull Request #16473 · manaflow-ai/cmux

BlueRaddish · 2026-10-01T19:37:03Z

Summary

The CLI contract lists surface-resume but leaves out its selectors, command forms, guarded clear behavior, and output. Document the shipped surface resume/surface-resume family and add no-socket help probes for both spellings.

Fixes #15709.

Testing

python scripts/verify-local.py passed its selected checks (feature flags; no Swift files changed).
python scripts/localize_changes.py passed with 0 translation changes and 0 catalog parity errors; this English-only migration contract needs no locale entries.
tests/test_cli_contract_help.py parsed all 226 help probes, including the two new entries. The built macOS CLI probe run is left to CI because this worktree is on Windows.
git diff --check passed.

Changelog

none

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by cubic

Documents the surface resume/surface-resume command family in the CLI contract, covering the set/get/clear forms, selectors, guarded clear behavior, and output.

Adds no-socket help probes for both surface --help and surface-resume --help.
Fixes CLI contract omits the surface resume binding namespace #15709.

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

Summary by CodeRabbit

Documentation
- Documented surface resume and surface-resume commands for setting, viewing, and clearing resume bindings, including selector defaults, safeguards, launch commands, and output behavior.
- Added expectations for help probes that run without a socket.

github-actions · 2026-10-01T19:37:17Z

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

coderabbitai · 2026-10-01T19:37:55Z

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

Warning

Review limit reached

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

Next included review available in 48 seconds.

Check out review usage here.

View limit details

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

Learn how review limits work.

Review configuration:

⚙️ Run configuration

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

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 58981f8c-2103-4b27-a2cb-cc787b4abde7

📥 Commits

Reviewing files that changed from the base of the PR and between fff85b3 and f8dbe2a.

📒 Files selected for processing (1)

docs/cli-contract.md

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: baaac4e2-b97a-456c-ac57-b28e359ab9ef

📥 Commits

Reviewing files that changed from the base of the PR and between 15cf1ed and fff85b3.

📒 Files selected for processing (1)

docs/cli-contract.md

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

The CLI contract now documents surface resume and surface-resume commands, including binding operations, selector defaults, safeguards, output behavior, and no-socket help expectations.

Changes

Surface resume documentation

Layer / File(s)	Summary
Document surface resume commands `docs/cli-contract.md`	Documents set, show, get, and clear behavior, selector defaults, checkpoint and source safeguards, output behavior, and no-socket help probes.

Priority: ⬇️ Low

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

Change: Other

Suggested reviewers: austinywang

Merge Risk: ⚪ Minimal · up to fff85

The change documents existing surface resume behavior without changing runtime functionality. No actionable merge-blocking risk is established; merge after normal documentation and help-probe checks.

Architecture Summary

Architecture risk: 🔵 Low · up to fff85

The change affects 1 system.

Changed systems: docs

Architecture concerns
No architecture-level concerns identified.

Review details

Systems and components

observed — docs (service) was modified; 1 changed file maps to changed impact.

Before / after behavior

observed — Modified behavior in docs/cli-contract.md: The VM tools, ports, handoff, and template-promotion entries remain; the added section begins after them.
observed — Modified behavior in docs/cli-contract.md: Adds the surface resume and surface-resume contract: set stores a shell or structured argv launch command, with --checkpoint-id taking precedence over --checkpoint, --source defaulting to cli, and --cwd defaulting to the current directory. show (default) and get read the binding, with plain output distinguishing absent and hidden private commands; clear can guard removal by checkpoint and source. Selectors default to applicable caller context, and both help forms work without a socket.
observed — Modified behavior in docs/cli-contract.md: Adds no-socket help probe expectations for cmux surface resume set and cmux surface-resume show.

🚥 Pre-merge checks | ✅ 25

✅ Passed checks (25 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting the `surface resume` CLI contract.
Description check	✅ Passed	The description includes a clear summary, testing results, issue reference, and changelog entry. The demo video is not needed for a documentation-only change. The repository checklist is omitted, incl…
Linked Issues check	✅ Passed	Issue `#15709` requires contract documentation for the `surface resume` namespace. The PR adds documentation for `surface resume` and `surface-resume`, including set/read/clear operations, selectors, ch…
Out of Scope Changes check	✅ Passed	The reviewed change is limited to `docs/cli-contract.md`. The added command-family documentation and no-socket help probes directly implement issue `#15709`. The changes do not add unrelated product beh…
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…
Cmux Cloud Persistent Session And Early Input	✅ Passed	PASS: The pull request changes only `docs/cli-contract.md`. The diff adds documentation and no-socket help probes for `surface resume`; it does not change Cloud terminal creation, cmux-tui transport, …
Cmux Swift Actor Isolation	✅ Passed	PASS: The reviewed diff changes only `docs/cli-contract.md` (+13 lines). It contains no Swift files and no production code changes, so it cannot introduce or worsen Swift 6 actor-isolation mistakes.
Cmux Swift Blocking Runtime	✅ Passed	PASS: The pull request changes only `docs/cli-contract.md`. The authoritative diff contains no Swift files and no production synchronization or timing code. The Swift blocking-runtime check is therefo…
Cmux Browser Automation Off-Main	✅ Passed	PASS: The review-scoped diff changes only `docs/cli-contract.md`. It adds documentation and no-socket help probes for surface resume commands. It does not change browser automation, WebKit/AppKit acce…
Cmux Expensive Synchronous Load	✅ Passed	The pull request changes only `docs/cli-contract.md`. The authoritative diff contains documentation and no Swift or agent-history loading code. Therefore, it does not add or move an expensive synchron…
Cmux Cache Substitution Correctness	✅ Passed	PASS: The review range changes only `docs/cli-contract.md`. It adds CLI contract text and help-probe entries. No Swift, TypeScript, or JavaScript production files changed, so the cache-substitution co…
Cmux No Hacky Sleeps	✅ Passed	PASS: The pull request changes only `docs/cli-contract.md`. It adds CLI contract documentation and help-probe entries, with no TypeScript, JavaScript, shell, or runtime code changes. The patch contain…
Cmux Algorithmic Complexity	✅ Passed	PASS. The authoritative PR diff changes only `docs/cli-contract.md` (+13/−0). The additions are CLI contract prose, tables, and no-socket help probe entries. They add no Swift, TypeScript, JavaScript,…
Cmux Swift Concurrency	✅ Passed	PASS: The pull request changes only `docs/cli-contract.md`. The authoritative diff contains no Swift files or cmux-owned Swift code, so it does not introduce or expand any legacy Swift concurrency pat…
Cmux Swift `@Concurrent`	✅ Passed	PASS. The authoritative PR diff changes only `docs/cli-contract.md` (+13 lines) and contains no Swift files or Swift code. The `.github/review-bot-rules/swift-concurrent-annotation.md` criteria theref…
Cmux Swift Package Boundaries	✅ Passed	The pull request changes only `docs/cli-contract.md` (+13 lines). It changes no Swift files, package manifests, or app-target code. The Swift package-boundary rule therefore has no applicable producti…
Cmux Swiftpm Lockfiles	✅ Passed	PASS: The pull request changes only `docs/cli-contract.md`. It does not modify a SwiftPM package, `Package.swift`, `Package.resolved`, an Xcode project, `.gitignore`, a workflow, or dependency declara…
Cmux Swift Logging	✅ Passed	PASS: The review-scoped diff changes only `docs/cli-contract.md` (+13 lines). It adds no Swift source, logging statement, or runtime behavior, so the Swift logging rule does not apply.
Cmux User-Facing Error Privacy	✅ Passed	PASS. The pull request changes only `docs/cli-contract.md`; it adds CLI contract documentation and no-socket help probe entries. It does not change production user-facing errors, alerts, command outpu…
Cmux Full Internationalization	✅ Passed	PASS: The PR changes only `docs/cli-contract.md`. It adds an English CLI migration contract and no-socket help probes. No Swift user-facing strings, string catalogs, Info.plist entries, web UI/API dat…
Cmux Swiftui State Layout	✅ Passed	The reviewed range changes only docs/cli-contract.md. It contains no Swift or SwiftUI changes, so the SwiftUI state-layout failure conditions do not apply.
Cmux Architecture Rethink	✅ Passed	The pull request changes only `docs/cli-contract.md` (+13 lines). It adds CLI contract text and no-socket help probes. No Swift or implementation files changed, so the Swift architectural rethink fail…
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	The pull request changes only `docs/cli-contract.md` (+13 lines). The authoritative diff contains no Swift, Objective-C, XIB, or storyboard changes and introduces no window or panel code. The auxiliar…
Cmux Source Artifacts	✅ Passed	The PR changes only `docs/cli-contract.md`. The diff adds hand-written CLI contract documentation and help-probe entries. This is an intentional documentation reason under the rule. No local output, g…
Cmux No Test Or Debug Seam In Production Source	✅ Passed	The pull request changes only `docs/cli-contract.md` (+13 lines). The review-scoped diff contains no Swift files and no path under a production `Sources/` directory. Therefore, it cannot introduce a t…

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create a new PR

Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

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

No issues found across 1 file

_{Re-trigger cubic}

teamleaderleo · 2026-10-02T00:10:41Z

Taking this: verifying the resume-binding contract against the CLI, fixing a table-formatting issue, and checking CI and review. Thanks @BlueRaddish for documenting these commands.

OrchardSpoon g1 🌀
Run: run_cx_bl_outside_prs_20261002_0004
Session: cx-bl-outside-prs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge-main commit by scripts/merge-main.sh. Merged by scripts/merge-main.sh: origin/main at 8b8762a. Merge-main-previous-head: e049f82 Merge-main-base: 8b8762a Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

teamleaderleo · 2026-10-02T00:19:00Z

Thanks @BlueRaddish. Updated this with main at 8b8762a and removed the blank line that split the VM command table. Independent review found the resume-binding contract matches the CLI at f8dbe2a: selectors, checkpoint precedence, clear guards, private-command output, and both help aliases.

The contract-verb check, its CI guard test, and diff checks pass. CI is green; local executable help probes were unavailable because this checkout has no built CLI. Localization audit: repository CLI documentation and invariant command literals only, with no app or web message changes.

OrchardSpoon g1 🌀
Run: run_cx_bl_outside_prs_20261002_0004
Session: cx-bl-outside-prs

github-actions · 2026-10-02T00:29:36Z

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

0bfd027 test(cloud): fix the Cloud header and moved-panel focus tests that never ran (manaflow-ai#16539) c5c4345 localization: accept numbered placeholders in any order (manaflow-ai#16376) 456edeb fix(settings): replace custom sidebar mockups with real previews (manaflow-ai#16569) 98dc3ab Prototype: cmux Cloud as a remote MCP server (manaflow-ai#16568) 6c22525 test(remote): isolate tmux stale-surface fixture (manaflow-ai#16566) 3ec9918 Re-land "fix(coderouter): initialize Cloud VM account pools (manaflow-ai#16397)" (manaflow-ai#16572) 2b895a5 Fix browser paste routing with terminal text box beta (manaflow-ai#6380) (manaflow-ai#16560) 2bd3455 localization: check Swift defaultValue literals against their catalog en value (manaflow-ai#16396) c43086e test(cli): expect --mark-read to mark every listed inbox message (manaflow-ai#16537) fcda4f0 test(feed): wait for zero-wait Codex permission acceptance before checking attention (manaflow-ai#16536) 7d57a03 fix(remote): evict stale persistent SSH bridge leases (manaflow-ai#16558) d630cb8 docs: add protected-folder diagnostics for tmux sessions (manaflow-ai#12219) 7dceaac test: create cwd fixtures that new terminals now resolve on disk (manaflow-ai#16538) 28cc575 docs: cover surface resume binding CLI contract (manaflow-ai#16473) 5c7dca1 Fix idle zsh PR probes triggering chpwd hooks (manaflow-ai#16553) # Conflicts: # .github/workflows/ci-guards.yml

docs: cover surface resume binding CLI contract

fff85b3

cubic-dev-ai Bot reviewed Oct 1, 2026

View reviewed changes

teamleaderleo and others added 2 commits October 1, 2026 17:10

docs: preserve the VM command table

e049f82

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge main (8b8762a) into cx-bl-outside-prs-16473

f8dbe2a

Merge-main commit by scripts/merge-main.sh. Merged by scripts/merge-main.sh: origin/main at 8b8762a. Merge-main-previous-head: e049f82 Merge-main-base: 8b8762a Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

teamleaderleo merged commit 28cc575 into manaflow-ai:main Oct 2, 2026
54 checks passed

Navigation Menu

Repository navigation

docs: cover surface resume binding CLI contract - #16473

docs: cover surface resume binding CLI contract#16473
teamleaderleo merged 3 commits into
manaflow-ai:mainfrom
BlueRaddish:docs/15709-surface-resume-contract

BlueRaddish commented Oct 1, 2026 •

edited by cubic-dev-ai Bot

Loading

Uh oh!

github-actions Bot commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading

Review limit reached

Walkthrough

Changes

Uh oh!

cubic-dev-ai Bot left a comment

Uh oh!

teamleaderleo commented Oct 2, 2026

Uh oh!

teamleaderleo commented Oct 2, 2026

Uh oh!

Uh oh!

github-actions Bot commented Oct 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

BlueRaddish commented Oct 1, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Testing

Changelog

Summary by cubic

Summary by CodeRabbit

Uh oh!

github-actions Bot commented Oct 1, 2026

Uh oh!

coderabbitai Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review limit reached

Walkthrough

Changes

Architecture Summary

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

teamleaderleo commented Oct 2, 2026

Uh oh!

teamleaderleo commented Oct 2, 2026

Uh oh!

Uh oh!

github-actions Bot commented Oct 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BlueRaddish commented Oct 1, 2026 •

edited by cubic-dev-ai Bot

Loading

coderabbitai Bot commented Oct 1, 2026 •

edited

Loading