feat: expose stable surface and workspace IDs in catalog reads

[teamleaderleo]

Summary

Catalog readers currently see runtime surface IDs but cannot join them to the stable identities CMUX persists. Add nullable stable_surface_id and stable_workspace_id to catalog and VM-tree projection rows so readers can reconnect a surface after supported restore.

Capture stable IDs with the catalog snapshot, using one owner index per read. Missing or mismatched owners return null. Existing selectors retain their meaning; Cloud mirror fields identify the local projection.

Implements #13244. The next product step is Find Work and a shared CLI read model in #13252 / #13253.

Testing

• Ten native tests cover identity, movement, restore, collisions, owner precedence, and capture after refresh. Their execution has not been verified; the completed earlier CI run skipped app-host tests.
• The paired read-model prototype has 23 passing Python tests. Those cover the consumer contract, not native execution.
• Current-head checks govern auto-merge. Review findings are addressed; CodeRabbit's latest review is unavailable because its OSS quota is exhausted.

Demo Video

No visual UI change. The new fields have no verified live-build demo yet.

Checklist

• Added tests and API documentation.
• Localization and iOS scope checked: no new UI strings or transport/auth/lifecycle changes.
• Addressed existing review findings.
• Required current-head CI is complete.

[coderabbitai]

Warning

Review limit reached

Next included review available in 9 minutes.

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: 1e442e2a-3721-4d9f-bc58-de8c3f436518

📥 Commits

Reviewing files that changed from the base of the PR and between b334a7d and 89116fb.

📒 Files selected for processing (10)

• Sources/AppDelegate+RecoverableMainWindowRoutes.swift
• Sources/Surfaces/SurfaceCatalogModel.swift
• Sources/Surfaces/SurfaceCatalogQueryService.swift
• Sources/Surfaces/SurfaceProjectionIdentity+Workspace.swift
• Sources/Surfaces/SurfaceProjectionIdentity.swift
• Sources/Surfaces/SurfaceSocketCommands.swift
• cmux.xcodeproj/project.pbxproj
• cmuxTests/SurfaceProjectionIdentityTests.swift
• docs/surface-catalog-identity.md
• tests_v2/test_surface_catalog_stable_identity.py

---

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

[github-actions]

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

[teamleaderleo]

Local conformance evidence for this production PR (Tact #81 / PR #92):

I exercised the installed native tagged app using owned disposable workspaces. Ten live checks passed: duplicate names preserve distinct surfaces; catalog joins the current panel; terminal and native-browser movement preserve the resource; close removes each local resource; a closed resource reference is rejected; native close-history restores the exact named terminal and its current catalog binding.

Important correction for the regression contract: this close-history path reused the panel UUID. Recovery tests must accept the actual owner behavior, rather than require every restore to allocate a new runtime UUID. The restored current binding is the invariant. The old build did not expose stable identity fields, so these results do not validate the new fields in this PR.

Provenance: native 0.64.22 (102), bundled CLI reports 4c190f2c5b302bd4df4f6f66753976e2b7a5b491, tagged socket glaeda-native; this differs from this PR's 543a7b4529929d8b04d885ad0f058da24874cc89. Runnable live harness, sanitized result and limitations, source-pinned identity/lifetime mapping.

All owned test workspaces and temporary runtime captures were removed. Twenty pre-existing workspace IDs survived the user-authorized recovery restart; original selection was restored. Process continuity and live Cloud/Chromium daemon restart were not asserted.

Production implementation and regression ownership remain here: eight real-owner Swift tests in cmuxTests/SurfaceProjectionIdentityTests.swift and live stable-field/movement coverage in tests_v2/test_surface_catalog_stable_identity.py. Their execution against the new public-identity build remains pending the coordinated native build slot. The ten older-build checks above must not be counted as those tests passing. Tact is the cross-repository evidence/consumer handoff, not the shipping destination.

[greptile-apps]

Confidence Score: 4/5

The identity behavior and batching correction appear sound, but the explicit actor-isolation requirement for the new Sendable value model must be satisfied before merging.

Findings

1.  Implicit Main-Actor Value Model ▶
2.  Repeated Main-Actor Scans ▶

Summary

The PR adds persisted local surface and workspace identities to catalog projection reads while retaining existing runtime and Cloud identifiers. The latest changes replace per-projection owner resolution with a batched owner index that preserves the existing workspace lookup precedence.

• Captures immutable projection-owner identities in the same main-actor turn as the catalog export.
• Serializes nullable stable_surface_id and stable_workspace_id fields.
• Adds owner matching, restore, move, collision, Cloud mirror, and serialization coverage.
• Resolves the previous repeated main-actor scan finding with one batched lookup per read.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Q[Catalog query] --> R[Optional discovery and refresh]
    R --> E[Capture catalog export]
    E --> O[Batch live workspace-owner lookup]
    O --> I[Immutable projection identity sidecar]
    E --> S[Off-main payload serialization]
    I --> S
    S --> J[Projection JSON with nullable stable IDs]

Loading

_{Reviews (2) · Last reviewed commit: "perf: batch projection identity joins th..."}

[teamleaderleo]

Product follow-through: #13252. After this identity join lands, the next proposed CMUX slice is cmux current --json plus a second consumer over the same bounded owner-derived payload. The RFC spells out user outcomes, provenance/attention constraints, dependencies, and acceptance criteria. This PR supplies the identity contract; the new current-work product still requires implementation.