Validate Codex Desktop and app-server compatibility #34

Objective

Validate Codex Desktop and app-server compatibility earlier in the MVP sequence so later overlays target the right session, thread, and API boundaries.

Finish Line

Codex Lab has a concrete app-server/Desktop compatibility gate before bridge, review, or automation overlays depend on it.

Current Status

State: Waiting on #42 before merge. PR #41 remains open and conflict-mergeable, but it is not green: codex-lab-app / Build macOS ARM64 Codex Lab app is failing on the macOS self-hosted runner.

What is complete:

• PR Document app-server Desktop compatibility gate #41 documents the Desktop/app-server compatibility gate in codex-rs/app-server/README.md.
• The branch is clean at 4dd9ed06358b9012513c65b362818b94b7f446e8; the net PR diff is README-only.
• Review agents checked the gate; fixes were applied for schema command location, untracked schema files, protocol-test wording, TOC discoverability, initialization originator coverage, successful resume coverage, and copy-paste error propagation.
• Local validation passed:
  • just write-app-server-schema plus tracked and untracked schema zero-diff checks.
  • just test -p codex-app-server-protocol (226 passed).
  • Targeted codex-app-server compatibility tests (11 passed, 816 skipped).
  • just test -p codex-cli strict_config_rejects_unknown_config_fields_for_app_server (1 passed, 269 skipped).
  • just fmt completed with the known existing Ruff/TOML exclude-newer = "7 days" parser warnings.
  • git diff --check passed.
• GitHub CI passed on the latest SHA: Codex exec harness, spelling, build-test, and cargo-deny.

Blocker:

• Fix macOS app-build sqlx_macros LINKEDIT failure #42 tracks the macOS app-build/toolchain failure.
• Failure signature: generated proc-macro dylib libsqlx_macros-86319056f56012e5.dylib fails to dlopen with mis-aligned LINKEDIT string pool, followed by unresolved imports from sqlx.
• This does not appear branch-related; PR Document app-server Desktop compatibility gate #41 is README-only and the same failure reproduces on fresh local /tmp release targets.

Cleanup and experiments already tried:

• Used the PR watcher retry budget: 3 failed-check retries.
• Quarantined only the runner's sqlx_macros release artifacts and reran.
• Quarantined the self-hosted runner's whole codex-rs/target/release directory and reran.
• Tried a short CARGO_TARGET_DIR workflow workaround; it did not fix the app build and was reverted from the PR.
• Fresh local /tmp release builds reproduce the malformed proc-macro dylib.
• Cargo profile override experiments for sqlx-macros/build override did not resolve the failure.
• Local toolchain evidence points at macOS 27.0 / Xcode 27.0 / SDK 27.0 fresh release proc-macro output; an older cached loadable dylib was built with SDK 26.4.

Next action:

• Fix Fix macOS app-build sqlx_macros LINKEDIT failure #42 by pinning/fixing the macOS self-hosted app-build toolchain, likely by using a known-good Xcode/SDK 26.x Rust compile environment or another verified linker/toolchain fix.
• Rerun PR Document app-server Desktop compatibility gate #41 after Fix macOS app-build sqlx_macros LINKEDIT failure #42 is fixed.
• Merge PR Document app-server Desktop compatibility gate #41 and close Validate Codex Desktop and app-server compatibility #34 once the app-build check is green.

Scope

In:

• App-server v2 compatibility checks.
• Desktop startup/probe/version assumptions.
• Thread lifecycle and resume behavior.
• codex exec --json / resume event stream compatibility where Desktop or tooling depends on it.
• Schema fixture drift checks.

Out:

• No app-server v1 development.
• No Desktop bundle renaming decision; that remains related to Codex Lab identity and channel naming #4.
• No Code Bridge implementation in this slice.

Acceptance Criteria

• just write-app-server-schema produces zero unexpected diff when schema is unchanged.
• Relevant app-server protocol tests pass.
• Desktop-facing startup/version/thread assumptions are documented with evidence.
• Any compatibility gap becomes a focused implementation issue before bridge/browser/control work begins.

Relationships

Child of #28. Related to #4 for identity/channel naming and to #1 for overlay capability mapping.

Validation

Run app-server protocol tests and schema generation checks scoped to changed surfaces.

Decisions

App-server v2 is the active API surface for new work; compatibility should be validated before Code Bridge and automation overlays.

Open Questions

Which Desktop checks can be automated locally versus requiring a manual app-server/Desktop smoke test?