P0: Workbench fresh-Mac onboarding depends on unbundled Python and manual private-network setup

[100yenadmin]

P0: Workbench fresh-Mac onboarding depends on unbundled Python and manual private-network setup

Incident

The David/Jane setup attempt exposed that evaOS Workbench v2.1.32 is not self-contained for a new Mac. A prepared Mac can pass because Python, GUI packages, Tailscale/Headscale enrollment, CUA, grants, and TCC state already exist. A fresh Mac requires manual terminal/code assistance and can still appear locally or agent-ready before live VM-to-Mac tools work.

Parents: #480, #623
Related P0: #655
Affected release: evaos-beta-v2.1.32-evaos-beta

Proven Root Cause

• The app bundles bridge Python source, Peekaboo, and a native helper, but not a compatible Python runtime.
• The launcher assumes Python 3.10+ without validating or installing it; system Python 3.9 fails before connector startup.
• Workbench detects a private tailnet address but does not install/start/enroll the Mac network client.
• Headscale is the server-side control plane; the Mac still needs a Tailscale-compatible client.
• CUA is not bundled. Its absence should use Peekaboo fallback and must not block pairing.
• Released v2.1.32 could equate agent_paired with runtime tools ready; P0: require end-to-end proof for Mac control readiness #657 fixes that source defect but is not in the published artifact.
• Existing local/CI canaries were pre-provisioned and did not prove a virgin installation.

Required Customer Experience

From a supported pristine Mac, the customer should need only to:

1. Install Workbench from the public artifact.
2. Sign in.
3. Follow unavoidable macOS permission prompts for the correct signed identity.
4. Press a guided Connect action.
5. See each prerequisite repaired or named precisely.
6. Receive end-to-end ready only after canonical runtime tools pass.

No customer should install Python, pip packages, Homebrew, or manually exchange terminal commands.

Priority 1 Execution Order

1. Failing clean-host contract tests: reproduce no compatible host Python, incompatible system Python, no private-network client, stopped/unenrolled/wrong-network client, absent CUA, and no prior connector state.
2. Self-contained Bridge runtime: choose and document signed native packaging or a pinned relocatable runtime, then prove the installed app never depends on Homebrew, system Python, pip, or customer terminal work.
3. Guided private-network bootstrap: model missing, stopped, unenrolled, wrong-network, ACL-blocked, and online states; provide approved in-app install/open/enrollment actions without exposing enrollment material.
4. Truthful readiness integration: keep local prerequisites distinct and integrate with P0: Mac & iPhone readiness can appear ready before end-to-end broker runtime control works #655 so only exact active customer/device/grant live-tool proof can produce end-to-end ready.
5. Prepared-Mac non-regression: prove CUA-primary behavior when available, bundled Peekaboo fallback when absent, current TCC identity, and preservation of Matt-style working setups without touching Matt's Mac.
6. Pristine-Mac release gate: install the exact signed/notarized candidate on a genuinely clean supported Mac, complete one guided Connect flow, run canonical status/see/low-impact action/stop/revoke/kill-switch/reboot proof, then complete RC, distribution, public URL, and customer setup gates.

Implementation may split into child issues only after the first test/architecture slice establishes separately mergeable ownership boundaries. Do not create duplicate GitHub or Linear work items merely to parallelize the plan.

Current exact next action: create an isolated current-head worktree from evaos/beta-rc-20260612, preserve the dirty shared checkout, and land the failing clean-host packaging/onboarding tests before implementation.

Acceptance Criteria

• Workbench ships a self-contained signed bridge runtime, either native or with a pinned relocatable runtime and dependencies.
• Missing/incompatible Python on the host cannot prevent Mac Control.
• Workbench distinguishes network client missing, stopped, unenrolled, wrong network, ACL blocked, and online states.
• The product provides the approved in-app install/open/enrollment action for the private-network client, using short-lived broker material without exposing it.
• CUA is explicitly bundled/supported or explicitly optional; missing CUA automatically uses the bundled Peekaboo path without customer intervention.
• The UI keeps local runtime, permissions, private network, broker grant, VM configuration, agent plugin, and live runtime-tool proof separate.
• customer_mac_status, desktop_control_status, and desktop_see pass from the paired VM before the page reports end-to-end ready.
• Offline/stale/pending states never render as connected or end-to-end ready.
• One low-impact action, stop, revoke, and kill-switch pass with redacted audited proof.
• Reboot/relaunch retains only valid state and fails closed when the network or grant is unavailable.
• Release proof includes both a pristine-Mac first-install canary and the existing prepared-Mac upgrade/non-regression canary.
• Customer-facing copy provides a direct button or precise guided prompt at every recoverable step; no generic “private connector link” dead end.

Hard Boundaries

• Preserve broker-owned grants, customer isolation, Headscale ACLs, stop/revoke, kill-switch, diagnostics gating, app identity, update channel, release workflow, and no-ACP packaging.
• Do not expose connector URLs, tokens, preauth material, private addresses, customer data, or raw logs.
• Do not redesign transport or remove Peekaboo fallback merely to hide onboarding failures.
• Do not touch Matt's setup.
• No signed/public/customer release until the pristine-Mac gate and P0: Mac & iPhone readiness can appear ready before end-to-end broker runtime control works #655 exact-target end-to-end gate both pass.

Validation

• Unit/fixture tests for missing interpreter, incompatible interpreter, missing/stopped/unenrolled/wrong-network client, CUA absent, stale grants, and offline Mac.
• Package inspection proving the self-contained runtime and declared CUA/fallback identity.
• Disposable-user or clean-Mac first-install test from the public DMG.
• Exact installed-app canonical tool chain plus one approved low-impact action, stop/revoke, and kill-switch.
• Current-head review, macOS supported-version CI, signed/notarized artifact proof, RC canary, and distribution proof.

Evidence

Redacted root-cause packet: /Volumes/LEXAR/Codex/evidence/evaos-workbench-runtime-reliability-release-train/fresh-mac-onboarding-root-cause-20260712.md

Proof Boundary

Issue filing and diagnosis do not prove implementation or customer readiness.

[coderabbitai]

🔗 Related PRs

#391 - Restore beta3 Mac pairing baseline [merged]
#403 - fix: recover Mac control installed app states [merged]
#449 - Fix legacy app stale owner proof path [merged]
#462 - [codex] Document Workbench release proof lanes [merged]
#465 - Fix Mac connector readiness probe [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!