Fix iOS terminal cold attach first paint

[austinywang]

Fixes #7163

Summary

• add failing-first iOS coverage for cold terminal attach so a live render-grid delta cannot become the first painted chunk before replay
• start mounted terminal output streams under a replay barrier, so cold attach holds live bytes/render-grid events until the authoritative replay is applied and acknowledged
• include the phone's reported viewport dimensions in mobile.terminal.replay, and have the Mac apply those params before capturing the replay frame
• release only cold-attach replay barriers after replay retries are exhausted, so a failed first replay cannot leave the terminal permanently blank
• stash the pre-barrier delivered high-water mark as a stale floor so a buffered out-of-order render-grid frame cannot bypass a recovery barrier and establish an outdated baseline; the floor re-bases on the next accepted authoritative delivery so a host-side sequence reset (surface recreate) still recovers

Scope

• Strictly scoped to iOS: terminal attach sits on a near-blank screen for a long time — stray status-line fragment renders alone before the mirror snaps in #7163: attach latency / blank first paint / stray-fragment gating.
• Does not implement or close iOS: garbled terminal during initial load — duplicated rows, stray rules, narrow-width re-wrap fragments; self-heals after load (render-grid replay race) #7159.
• Reviewed sibling PR Fix iOS render-grid load garble (#7159) #7171 (origin/issue-7159-ios-load-garble) after it became available. That branch fixes stale same-sequence render-grid replay replacement with terminalFullReplacementSeqBySurfaceID; this PR keeps to the cold-attach first-paint path with terminalColdAttachReplayBarrierTokensBySurfaceID plus viewport-sized replay capture. The fixes touch nearby code but keep distinct state and behavior.

Validation

• python3 scripts/swift_file_length_budget.py --budget .github/swift-file-length-budget.tsv
• git diff --check
• No local builds/tests per task instruction. CI should validate the two-commit regression shape: commit 1 adds coverage, commit 2 applies the fix.

Summary by CodeRabbit

• New Features
  • Improved terminal replay recovery for cold-attach and missing render-grid baseline scenarios, including event-driven render-grid delivery decisions.
  • Terminal replay requests now include viewport details and client identity when available.
• Bug Fixes
  • Refined replay-barrier lifecycle and ack reconciliation to clear the correct per-surface scenario state and retry counters.
  • Improved hybrid delivery behavior so bytes/render-grid updates are withheld or released based on baseline readiness.
• Tests
  • Added new cold-attach and missing-baseline replay test coverage, including retry budgeting and viewport reporting checks.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
cmux	Ready	Preview, Comment	Jul 2, 2026 6:14pm
cmux-staging	Building	Preview, Comment	Jul 2, 2026 6:14pm

[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

Adds cold-attach and missing-baseline replay tracking for iOS terminal delivery, threads viewport metadata into replay requests, tags viewport reports with distinct reasons, and expands tests for replay ordering and baseline recovery.

Changes

Cold-attach replay and render-grid baseline

Layer / File(s)	Summary
Replay state and lifecycle Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift, Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift	Adds per-surface cold-attach and baseline replay tracking, initializes and resets the new state, and clears it during replay barrier and terminal output lifecycle changes.
Viewport-aware replay requests Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift	Records viewport changes before remote-client gating and includes client ID plus viewport dimensions when building replay requests from tracked viewport state.
Render-grid delivery and barrier resolution Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift	Adds replay failure barrier resolution, missing-baseline replay requests, advisory render-grid decisions, baseline waiting branches, and follow-up barrier token reassociation.
Viewport reason tagging Sources/TerminalController.swift	Adds a reason parameter to viewport reporting and passes distinct replay and viewport reasons into mobile viewport limiting.
Test support updates Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/MobileShellRenderGridFrameTestSupport.swift, Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/MobileShellRenderGridLivenessTestSupport.swift	Adds render-grid and terminal-bytes frame helpers, polling support, and queued replay payload scripting for the new replay paths.
Cold-attach and missing-baseline tests Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift, Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalMissingBaselineReplayBudgetTests.swift, Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalReplayOutputQueueTests.swift, ios/cmuxPackage/Tests/cmuxFeatureTests/cmuxFeatureTests.swift	Adds async tests for cold-attach replay exhaustion, baseline recovery, follow-up replay handling, first-paint ordering, and viewport-bearing replay requests.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related issues

• iOS: terminal attach sits on a near-blank screen for a long time — stray status-line fragment renders alone before the mirror snaps in #7163: Matches the same iOS terminal attach and render-grid replay-barrier path, including cold-attach and missing-baseline handling.

Possibly related PRs

• manaflow-ai/cmux#6035: Both PRs modify iOS MobileShellComposite terminal output ACK handling, especially the terminalOutputDidProcess path in MobileShellComposite+TerminalOutputDelivery.swift.
• manaflow-ai/cmux#7098: Both PRs change iOS terminal replay-barrier delivery and ack handling in MobileShellComposite and MobileShellComposite+TerminalOutputDelivery.swift.

---

Important

Pre-merge checks failed

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

❌ Failed checks (2 errors, 1 warning)

Check name	Status	Explanation	Resolution
Cmux Swift Concurrency	❌ Error	FAIL: Sources/WorkspaceContentView.swift turns TmuxWorkspacePaneOverlayModel into ObservableObject with @Published state, introducing new Combine app-state tracking in production UI code.	Replace it with Observation (@Observable) or plain value state passed through SwiftUI; avoid new Combine-backed app-state models in this diff.
Cmux Full Internationalization	❌ Error	v2MobileTerminalReplay adds the new user-facing error "Invalid mobile viewport report" without a localized API or string-catalog entry.	Localize the new error with String(localized:defaultValue:) (or equivalent) and add matching catalog entries for every supported locale in the affected surface.
Description check	⚠️ Warning	The PR description covers summary, scope, and validation, but it omits required template sections like Testing, Demo Video, Review Trigger, and Checklist.	Add the missing template sections, especially Testing, Demo Video, Review Trigger, and Checklist, and fill them with the requested details.

✅ Passed checks (22 passed)

Check name	Status	Explanation
Title check	✅ Passed	It clearly summarizes the main change: iOS terminal cold-attach first paint handling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 touched production types are already @MainActor, and the new replay/viewport state stays on that actor; no new isolation hazards were introduced.
Cmux Swift Blocking Runtime	✅ Passed	PASS: production diffs add no blocking/sync primitives; the only new Task.sleep is the test-only pollUntil helper, which the policy explicitly allows.
Cmux Browser Automation Off-Main	✅ Passed	Browser waits/callbacks stay in socketWorkerMethods and worker router; only direct focus/open commands remain main-actor, with policy tests covering routing.
Cmux Expensive Synchronous Load	✅ Passed	Touched replay/viewport code only mutates in-memory state and params; no new RestorableAgentSessionIndex.load/Data(contentsOf:)/JSONDecoder call was added on a main/interactive path.
Cmux Cache Substitution Correctness	✅ Passed	PASS: the replay path still captures from live Ghostty surface; viewport dims are event-driven reports with reset/TTL handling, not an unguarded cache swap.
Cmux No Hacky Sleeps	✅ Passed	The diff adds no sleeps/polling/timers; touched non-Swift runtime hunks are API removals, not wait-based race fixes.
Cmux Algorithmic Complexity	✅ Passed	The new production paths are mostly O(1) map/set updates; the only scans are per-surface viewport-report recomputations over tiny client sets, not scalable full-collection rescans.
Cmux Swift @Concurrent	✅ Passed	No touched Swift code adds/misuses @concurrent or nonisolated async; new async work is actor-isolated (@MainActor/actor) or UI-bound test helpers.
Cmux Swift File And Package Boundaries	✅ Passed	Touched production files are existing oversized glue or a focused terminal-output package extension; new large files are test-only.
Cmux Swiftpm Lockfiles	✅ Passed	No SwiftPM/Xcode lockfile or dependency files are in scope, and ios/cmuxPackage/.gitignore does not ignore Package.resolved.
Cmux Swift Logging	✅ Passed	No print/debugPrint/dump/NSLog or file/stdout logging was added; the new logs use existing MobileDebugLog.anchormux with internal, non-sensitive state.
Cmux User-Facing Error Privacy	✅ Passed	The PR only adds a generic invalid mobile viewport report error and internal replay-barrier/debug logic; no vendor names, raw upstream messages, or secrets are exposed.
Cmux Swiftui State Layout	✅ Passed	Changed files are model/tests only; the stateful type is already @Observable, and no ObservableObject/@Published/GeometryReader/List/ForEach patterns were added.
Cmux Architecture Rethink	✅ Passed	Replay/barrier state stays within MobileShellComposite’s single owner; no new production timing/observer workaround was introduced, and polling is test-only.
Cmux Swift Auxiliary Window Close Shortcuts	✅ Passed	Only terminal replay/render-grid code and tests changed; no user-visible NSWindow/NSPanel/NSWindowController/WindowGroup or cmuxAuxiliaryWindowIdentifiers changes.
Cmux Source Artifacts	✅ Passed	Only submodule pointers changed in ghostty and vendor/bonsplit; no logs, caches, temp, build, or other artifact paths were added.
Cmux No Test Or Debug Seam In Production Source	✅ Passed	Touched Sources files only add production replay/viewport logic; no new DEBUG/test-only accessors or seam-like members were added.
Cmux No Ambient Global State	✅ Passed	New helpers/state live inside MobileShellComposite or existing methods; no new production file-scope func, mutable global, or singleton was added.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-7163-ios-terminal-attach-slow-load

---

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

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[greptile-apps]

Greptile Summary

This PR fixes a blank-first-paint bug on iOS cold terminal attach by wrapping output streams in a replay barrier until the authoritative replay is applied, and includes viewport dimensions in replay requests so the Mac captures the frame at the correct grid size.

• Cold-attach barrier: requestColdAttachTerminalReplay now marks each barrier token in terminalColdAttachReplayBarrierTokensBySurfaceID, and resolveTerminalReplayFailureBarrier force-clears cold-attach and missing-baseline barriers once retries are exhausted instead of leaving them active (which previously caused a permanently blank terminal).
• Stale-floor guard: stashTerminalPreBarrierDeliveredEndSeq captures the pre-barrier high-water mark so buffered out-of-order render-grid frames cannot bypass the recovery barrier; the floor is released once a live delivery catches up or the barrier resolves with an empty result.
• Viewport in replay: mobile.terminal.replay now accepts client_id/viewport_columns/viewport_rows and calls applyMobileViewportReport before capturing the frame, with a sticky-flag preservation fix to avoid downgrading a previously sticky report.

Confidence Score: 5/5

Safe to merge. The barrier lifecycle, stale-floor guard, and exhaustion-release path are all logically consistent with each other and validated by the new test suite.

All three production Swift files touch closely coordinated state machines (replay barriers, stale-floor seq tracking, missing-baseline budgets) and the logic holds up across the full retry/exhaustion/recovery path. The visibility widening of TerminalOutputTransport and related properties is justified by code moving to a separate extension file. The sticky-flag preservation in TerminalController.swift is a correct narrowing of a pre-existing overwrite bug. The new test coverage is comprehensive: cold-attach exhaustion, follow-up exhaustion, partial-frame budget isolation, full-frame bypass, transient failure recovery, stale-floor trimming, and output-queue regression. No correctness issues were found.

No files require special attention.

Important Files Changed

Filename	Overview
Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift	Adds deliverAuthoritativeTerminalRenderGrid, stale-floor staleness check, missing-baseline gating, and bypassLiveBaselineBarrier logic. The nil == nil bypass concern from a prior round was fixed upstream; the new logic requires activeReplayBarrierToken != nil.
Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalReplayLifecycle.swift	Adds resolveTerminalReplayFailureBarrier (clears cold-attach/missing-baseline barriers on exhaustion instead of preserving them), requestTerminalReplayForMissingRenderGridBaseline, stash/restore/rebase helpers for the pre-barrier floor, and proper per-surface-scenario cleanup in beginTerminalReplayBarrier and clearTerminalReplayBarrierIfCurrent.
Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift	Adds five new per-surface dictionaries for the barrier/floor/baseline tracking, widens TerminalOutputTransport and related properties from private to internal (justified: code moved to extension files), adds viewport snapshot to requestTerminalReplay, and correctly resets all new state in init/reset/register/unregister paths.
Sources/TerminalController.swift	mobile.terminal.replay now validates and applies viewport report fields before capturing the replay frame; applyMobileViewportReport preserves an existing sticky flag rather than overwriting it with false — a correct behavioural fix.
Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift	New test file covering cold-attach barrier exhaustion (raw bytes and render-grid transports), follow-up replay exhaustion, partial-frame budget isolation, full-frame baseline establishment, and missing-baseline transient/recovery paths.
Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalMissingBaselineReplayBudgetTests.swift	New test file covering missing-baseline budget exhaustion, replay-count preservation through follow-up barriers, and budget reset on baseline delivery.
Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalReplayOutputQueueTests.swift	New test verifying that a full render-grid event outside an active barrier does not reset the output queue/stream token — regression test for the nil == nil bypass fix.
Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalStaleFloorByteChannelTests.swift	New test verifying that byte chunks whose end-seq falls at or below the stale floor are rejected, and that chunks overlapping the floor are trimmed and delivered correctly.
Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalStaleFrameRecoveryBarrierTests.swift	New test verifying pre-barrier stash, floor gating for render-grid frames, floor restoration on empty barrier release, and rebase on surface-rebuilding resets.
ios/cmuxPackage/Tests/cmuxFeatureTests/cmuxFeatureTests.swift	Adds integration tests for viewport dimension reporting in mobile.terminal.replay: verifies that client_id, viewport_columns, and viewport_rows are forwarded on cold attach.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[terminalOutputStream called\ncold attach] --> B[registerTerminalOutput\nclears all per-surface state]
    B --> C[requestColdAttachTerminalReplay]
    C --> D{host supports\nterminal.replay.v1?}
    D -- yes --> E[beginTerminalReplayBarrier\nmarks terminalColdAttachReplayBarrierTokensBySurfaceID]
    D -- no --> F[requestTerminalReplay\nno barrier]
    E --> G[mobile.terminal.replay RPC\nwith viewport dimensions]
    G -- success --> H{accepted and has seq?}
    H -- yes --> I[rebaseTerminalReplayStaleFloor\nmark bytes delivered\nclear barrier on ack]
    H -- no/empty --> J[clearTerminalReplayBarrierIfCurrent\nrestorePreBarrierBaseline if needed]
    G -- failure --> K{retries < max 2?}
    K -- yes --> L[prepareTerminalReplayFailureRetry\nretry same barrier]
    L --> G
    K -- no --> M[resolveTerminalReplayFailureBarrier]
    M --> N{cold-attach or\nmissing-baseline barrier?}
    N -- yes --> O[clearTerminalReplayBarrierIfCurrent\nreleases live output]
    N -- no --> P[preserveTerminalReplayBarrierIfCurrent\nbarrier stays active]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[terminalOutputStream called\ncold attach] --> B[registerTerminalOutput\nclears all per-surface state]
    B --> C[requestColdAttachTerminalReplay]
    C --> D{host supports\nterminal.replay.v1?}
    D -- yes --> E[beginTerminalReplayBarrier\nmarks terminalColdAttachReplayBarrierTokensBySurfaceID]
    D -- no --> F[requestTerminalReplay\nno barrier]
    E --> G[mobile.terminal.replay RPC\nwith viewport dimensions]
    G -- success --> H{accepted and has seq?}
    H -- yes --> I[rebaseTerminalReplayStaleFloor\nmark bytes delivered\nclear barrier on ack]
    H -- no/empty --> J[clearTerminalReplayBarrierIfCurrent\nrestorePreBarrierBaseline if needed]
    G -- failure --> K{retries < max 2?}
    K -- yes --> L[prepareTerminalReplayFailureRetry\nretry same barrier]
    L --> G
    K -- no --> M[resolveTerminalReplayFailureBarrier]
    M --> N{cold-attach or\nmissing-baseline barrier?}
    N -- yes --> O[clearTerminalReplayBarrierIfCurrent\nreleases live output]
    N -- no --> P[preserveTerminalReplayBarrierIfCurrent\nbarrier stays active]

Loading

_{Reviews (16): Last reviewed commit: "Align replay tests with the merged cold-..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite`+TerminalOutputDelivery.swift:
- Around line 31-33: Route advisory replay handling through the missing-baseline
barrier instead of starting a replay directly from the alternate-screen path. In
MobileShellComposite+TerminalOutputDelivery, update the replay flow around
beginTerminalReplayBarrier/clearTerminalReplayBarrierIfCurrent so live deltas
stay blocked until the authoritative primary-screen replay or baseline resolves,
and ensure replay failures increment and respect the missing-baseline retry cap
even when deliveredTerminalByteEndSeqBySurfaceID already has an alternate-screen
seq.

In
`@Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift`:
- Around line 73-80: The test in TerminalColdAttachReplayBarrierTests is using
negative polling to prove nothing happened, which makes it timing-dependent
instead of causal. Update the assertions around the replay/barrier flow to wait
on an explicit drain/completion signal from the router, transport, or collector
after the render-grid event is delivered, then assert the delivered line is
absent and the replay/request count has not increased. Apply the same
causality-based fix to the other affected assertions in the same test.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 765c1d8f-7e98-460a-80a4-b58906d2d140

📥 Commits

Reviewing files that changed from the base of the PR and between 8850142 and 1b9d268.

📒 Files selected for processing (5)

• Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift
• Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift
• Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift
• Sources/TerminalController.swift
• ios/cmuxPackage/Tests/cmuxFeatureTests/cmuxFeatureTests.swift

[coderabbitai]

Actionable comments posted: 2

♻️ Duplicate comments (1)

Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift (1)

72-80: 🎯 Functional Correctness | 🟠 Major

Negative assertions still proven only by poll-timeout, not a causal signal.

pollUntil(attempts: 50) { collector.lines.contains(...) } followed by #expect(!delivered, ...) proves "nothing happened" purely by exhausting a fixed attempt/time budget. This is timing-dependent: a slow CI runner could still be mid-delivery at attempt 50 and pass for the wrong reason, and a race could theoretically resolve after the window closes. This is the same pattern already flagged on this file (previously at lines 73-80/162-165); it now also appears at 407-410 (partialAlternateRenderGridWaitingForBaselineSuppressesRawBytes).

As per path instructions, tests must "assert on causality, not latency" and must not rely on fixed/bounded polling as proof of absence before an assertion; wait for an explicit drain/settle signal from the router/collector after the event is delivered, then assert the count/state did not change.

Also applies to: 162-165, 407-410

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift`
around lines 72 - 80, The negative assertions in
TerminalColdAttachReplayBarrierTests are still based on poll timeout rather than
a causal settle signal. In the affected test cases around
partialDelivered/partialRequestedReplay and
partialAlternateRenderGridWaitingForBaselineSuppressesRawBytes, replace the
bounded poll-and-negate pattern with waiting for an explicit router/collector
drain or settle condition after the triggering event, then assert that the
expected replay/count/state did not change. Use the existing pollUntil,
router.count(of:), and collector.lines checks only after the event has fully
settled so the tests assert causality, not latency.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@ios/cmuxPackage/Tests/cmuxFeatureTests/cmuxFeatureTests.swift`:
- Around line 2552-2556: The first-paint wait in the test loop uses a `where`
clause that only skips the body, so it always burns the full 3-second budget
instead of exiting early. Update the polling logic in `cmuxFeatureTests` to
break out as soon as `collector.lines` becomes non-empty, matching the
early-return behavior used by `waitForRequestCount` and keeping the same 10ms
polling cadence only until the condition is met.

In
`@Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite`+TerminalOutputDelivery.swift:
- Around line 51-55: `markTerminalBytesDelivered` is clearing the replay barrier
token too early, which can cause `terminalOutputDidProcess` to lose the
missing-baseline identity before it re-associates follow-up barriers. Update the
token lifecycle so `terminalRenderGridBaselineReplayBarrierTokensBySurfaceID` is
preserved until the replay barrier ack is processed, and keep it in sync with
the related state in `terminalOutputDidProcess` and any follow-up handling
around the bypassed full render-grid frame.

---

Duplicate comments:
In
`@Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift`:
- Around line 72-80: The negative assertions in
TerminalColdAttachReplayBarrierTests are still based on poll timeout rather than
a causal settle signal. In the affected test cases around
partialDelivered/partialRequestedReplay and
partialAlternateRenderGridWaitingForBaselineSuppressesRawBytes, replace the
bounded poll-and-negate pattern with waiting for an explicit router/collector
drain or settle condition after the triggering event, then assert that the
expected replay/count/state did not change. Use the existing pollUntil,
router.count(of:), and collector.lines checks only after the event has fully
settled so the tests assert causality, not latency.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 06a435df-6c7f-40ea-851f-64b767ea9472

📥 Commits

Reviewing files that changed from the base of the PR and between 1b9d268 and 8005dd7.

📒 Files selected for processing (5)

• Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift
• Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift
• Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift
• Sources/TerminalController.swift
• ios/cmuxPackage/Tests/cmuxFeatureTests/cmuxFeatureTests.swift

[coderabbitai]

Actionable comments posted: 3

♻️ Duplicate comments (1)

Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift (1)

128-130: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

Route advisory baseline replays through the barrier helper.

Line 129 starts a replay without creating a replay barrier, so later live render-grid/byte output can still interleave before the authoritative primary-screen replay is applied. Use the missing-baseline helper so this path shares the same barrier token, retry budget, and failure-release behavior.

Proposed fix

             if requestReplay {
-                requestTerminalReplay(surfaceID: renderGrid.surfaceID)
+                requestTerminalReplayForMissingRenderGridBaseline(surfaceID: renderGrid.surfaceID)
             }

As per path instructions, terminal attach/replay barrier decisions are correctness-critical state and should not fall back to best-effort replay paths.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite`+TerminalOutputDelivery.swift
around lines 128 - 130, The replay path in
MobileShellComposite+TerminalOutputDelivery currently calls
requestTerminalReplay directly without establishing the replay barrier, which
can let later live output interleave before the authoritative baseline is
applied. Update this requestReplay branch to use the missing-baseline barrier
helper so it shares the same barrier token, retry budget, and failure-release
handling as other replay entry points. Keep the fix localized around
requestTerminalReplay and the barrier helper used for baseline replay
coordination.

Source: Path instructions

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift`:
- Around line 378-381: The replay-barrier test is proving absence with timeout
polling instead of using the causal completion signal. In the
`TerminalColdAttachReplayBarrierTests` flow, once `barrierCleared` settles the
recovery barrier, read the follow-up replay count directly and assert the
invariant from that settled state rather than using `pollUntil` to confirm
`!followUpRequested`; keep the same pattern in the nearby raw-bytes path only if
a real drain/flush signal is added later.

In
`@Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalMissingBaselineReplayBudgetTests.swift`:
- Around line 56-60: The negative assertion in
TerminalMissingBaselineReplayBudgetTests is still relying on a bounded poll
timeout via pollUntil(attempts:) instead of a logical completion condition.
Update the test around extraReplayRequested and the collector.lines check to
wait for an explicit invariant/signaling state from the replay flow or router
rather than assuming 50 attempts is enough, following the same approach used in
TerminalColdAttachReplayBarrierTests. Keep the final assertions tied to a
deterministic completion signal so the test proves the absence of extra replay
requests without timing dependence.

In `@Sources/TerminalController.swift`:
- Line 13650: Fail closed in the mobile.terminal.replay path when viewport
metadata is malformed: update the handler that calls applyMobileViewportReport
so it distinguishes truly absent viewport fields from present-but-unusable ones,
and returns invalid_params whenever any viewport field is supplied but cannot be
parsed or applied. Keep the current backward-compatible no-op only when all
viewport metadata is missing, and ensure the replay sizing logic in
TerminalController uses the validated viewport before capture so a bad first
frame is never emitted.

---

Duplicate comments:
In
`@Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite`+TerminalOutputDelivery.swift:
- Around line 128-130: The replay path in
MobileShellComposite+TerminalOutputDelivery currently calls
requestTerminalReplay directly without establishing the replay barrier, which
can let later live output interleave before the authoritative baseline is
applied. Update this requestReplay branch to use the missing-baseline barrier
helper so it shares the same barrier token, retry budget, and failure-release
handling as other replay entry points. Keep the fix localized around
requestTerminalReplay and the barrier helper used for baseline replay
coordination.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f2f1cf28-1951-400a-8227-8f40eaaf5cb9

📥 Commits

Reviewing files that changed from the base of the PR and between 8005dd7 and 3059c02.

📒 Files selected for processing (8)

• Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite+TerminalOutputDelivery.swift
• Packages/iOS/CmuxMobileShell/Sources/CmuxMobileShell/MobileShellComposite.swift
• Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/MobileShellRenderGridFrameTestSupport.swift
• Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/MobileShellRenderGridLivenessTestSupport.swift
• Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalColdAttachReplayBarrierTests.swift
• Packages/iOS/CmuxMobileShell/Tests/CmuxMobileShellTests/TerminalMissingBaselineReplayBudgetTests.swift
• Sources/TerminalController.swift
• ios/cmuxPackage/Tests/cmuxFeatureTests/cmuxFeatureTests.swift

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>