macOS first-run onboarding blockers: Spark preflight timeout false blocker, Codex lane app-server missing, Apple FM readiness unclear

[thrillerxx]

Summary

First-time install/run on macOS surfaced multiple onboarding blockers before Autopilot became usable.
This report captures the full sequence from install through recovery so first-run UX can be hardened.

Environment

• Device: MacBook Air (Apple Silicon)
• OS: macOS 26.2.0
• Repo: OpenAgentsInc/openagents
• Observed on: March 23-24, 2026
• Install path used:
  • repo: ~/audit/openagents
  • runtime binaries: ~/apps/openagents-local/runtime/bin/*

What happened (chronological)

1. Codex lane unavailable on launch

   • UI/logs repeatedly showed:
     • Codex lane startup failed: failed to spawn codex app-server
     • Codex lane unavailable
   • Root cause: no codex / codex-app-server executable present in PATH.

2. Apple FM bridge missing initially

   • Needed explicit bridge build (swift/foundation-bridge/build.sh) and explicit bridge path wiring.
   • Once bridge binary existed and env var was set, bridge health became reachable.

3. Apple FM still not ready after bridge was running

   • Bridge health initially reported:
     • unavailable_reason: apple_intelligence_not_enabled
   • After enabling Apple Intelligence in System Settings, health moved to:
     • unavailable_reason: model_not_ready
   • Later eventually became ready (model_available=true).

4. Spark preflight blocker kept appearing

   • Preflight/UI showed:
     • Spark network status timed out after 15s
   • This blocked mode transitions despite eventual wallet recovery.
   • SPARK_ACTION_TIMEOUT is fixed at 15s in apps/autopilot-desktop/src/spark_wallet.rs.
   • Logs showed Spark sometimes takes much longer due to transient DNS/operator path delays, then recovers.

5. After stabilization

   • Provider eventually reached online.
   • Wallet connected.
   • Apple FM ready.
   • However, startup path still presents confusing/false-negative blockers.

Why this is a problem

• First-run experience appears broken even when system can recover.
• Multiple independent prerequisites are not clearly surfaced in priority order.
• A hard 15s Spark timeout can produce a blocker that looks terminal but is often transient.

Requested improvements

1. Spark timeout hardening

   • Make Spark preflight timeout configurable (env + UI-safe default).
   • Increase default for first-run/warm-start scenarios.
   • Distinguish transient timeout vs terminal failure in blocker severity.

2. Codex lane prerequisite handling

   • If codex / codex-app-server is missing, show explicit actionable setup guidance.
   • Degrade gracefully without noisy repeated errors in chat pane.

3. Apple FM readiness UX

   • Keep current bridge health checks, but improve staged messaging:
     • bridge missing
     • Apple Intelligence disabled
     • model downloading/not ready
     • ready
   • Avoid presenting this as ambiguous runtime degradation.

4. First-run diagnostics panel

   • Single “Onboarding checks” view with pass/fail + exact fix commands/settings.

Relevant evidence snippets

• Codex lane startup failed: failed to spawn codex app-server
• Spark network status timed out after 15s
• Apple FM health:
  • unavailable_reason: apple_intelligence_not_enabled
  • then unavailable_reason: model_not_ready
  • eventually model_available=true

Candidate file references

• apps/autopilot-desktop/src/spark_wallet.rs (SPARK_ACTION_TIMEOUT=15s)
• apps/autopilot-desktop/src/codex_lane.rs
• crates/codex-client/src/client.rs (app-server command resolution)
• apps/autopilot-desktop/src/apple_fm_bridge.rs

[AtlantisPleb]

Fixed on main in a319364cf.

This landed the concrete first-run hardening from this report:

• explicit Codex install guidance when codex / codex-app-server is missing
• human-readable Apple FM readiness states for bridge missing, Apple Intelligence disabled, unsupported device, and model-not-ready/downloading
• Spark startup timeout hardening/retry so transient wallet startup no longer trips a false blocker as aggressively

Verified with cargo check -p autopilot-desktop and cargo test -p codex-client --lib.