Open source Grok Bot alternative, Bring your own agent and subscription: message Claude Code, Codex, Gemini CLI, Cursor, Copilot and 40+ AI agents as bots on your own computer, from iPhone, Mac, Windows, Linux or terminal. Agent-agnostic and free. Also a Muse and Dots alternative. Built in Rust.
Rust acpagent-client-protocolai-agentsai-assistantclaudeclaude-codecodexcoding-agentscursorgeminigemini-cligrok-bot-alternativeiosiphonelinuxmacosmcpopen-sourcerustself-hosted
test: drive desktop e2e with Playwright and phones with Maestro
leepokai3d3c8014c69c
diff --git a/.agents/skills/after-change/SKILL.md b/.agents/skills/after-change/SKILL.mdindex a36ddde4..1c624829 100644--- a/.agents/skills/after-change/SKILL.md+++ b/.agents/skills/after-change/SKILL.md@@ -52,7 +52,7 @@ Give one tester (or yourself) the final change, exact flows and E2E mode. Read t- Stop only this task's old app/host processes before rebuilding or installing. Never stop the shared Codync Dev, production app, or another session's sandbox. Track what you start.- Prefer `npm run dev` in `apps/desktop` in the change's isolated worktree. When testing from the shared checkout, use its documented sandbox mode. Restart for main-process/preload changes. Package only when the flow needs capabilities unavailable unpackaged.- When `host/` is unchanged, reuse a compatible built host through `CODYNC_HOST_BIN` as the development guide describes. When it changed, build the correct host for this worktree. Apple build output stays in this checkout's `build/dd`.-- Walk the changed flows with available Computer Use tools on the actual apps. iPhone checks use the worktree's own iOS Simulator (`Codync <sandbox name>`: `npm run dev` prints its udid, or the command that creates it when there is none yet; `npm run dev -- --prune` deletes it) through Device Hub; Android checks use the shared `codync_worktree` emulator (never `codync_api36`, the maintainer's), one test at a time under its lock, with `pm clear` and the notification grant first ([test devices](../../../docs/guides/dev-app.md#worktree-sandboxes)). Builds and unit tests do not substitute for UI checks. No changed client UI here means no UI parity work.+- Walk the changed flows on the actual apps as the [test stack](../../../docs/guides/test-stack.md) says: the desktop with Playwright (`npm run e2e` against `npm run dev -- --cdp`), the phones with one Maestro run under the Maestro lock (`apps/maestro`, `--shard-all`), adding or updating the spec or flow each changed flow needs, and Computer Use only for the native steps that guide lists. iPhone checks use the worktree's own iOS Simulator (`Codync <sandbox name>`: `npm run dev` prints its udid, or the command that creates it when there is none yet; `npm run dev -- --prune` deletes it); Android checks use the shared `codync_worktree` emulator (never `codync_api36`, the maintainer's), one test at a time under its lock, with `pm clear` and the notification grant first ([test devices](../../../docs/guides/dev-app.md#worktree-sandboxes)). Builds and unit tests do not substitute for UI checks. No changed client UI here means no UI parity work.- Minimal E2E covers this computer's platform. Full E2E also covers installed Lima Linux and UTM Windows VMs; report absent VMs rather than creating them. Validate affected clients as required by repository instructions, and report unavailable tools/devices explicitly.- Walk each flow once, using short bot messages. Record `platform`, `flow`, `result` (`pass`, `fail`, `preexisting`, `not_run`), and observed evidence or reason. Use `preexisting` only with evidence it fails without this change; otherwise retain the uncertainty as a failure. Never disturb another worktree to prove a baseline.diff --git a/.claude/workflows/after-change.js b/.claude/workflows/after-change.jsindex 37e9131a..fe024bdf 100644--- a/.claude/workflows/after-change.js+++ b/.claude/workflows/after-change.js@@ -116,7 +116,7 @@ ${JSON.stringify(refactors, null, 2)}const walk = (flows, round) => agent(`End-to-end test a code change on the real apps, ${e2e} e2e as CLAUDE.md "End-to-end test every change" defines it (minimal: only this computer's platform; full: also Lima Linux and the UTM Windows VM, skipping and reporting a VM that isn't installed).${scope}${flows}-Walk each flow once, as a person would, until it clearly passes or fails, and note what you saw; don't explore beyond the listed flows. Keep it quick: short messages to bots, no sleeps or long-running tasks to stretch a turn, and when \`host/\` is unchanged start \`npm run dev\` with \`CODYNC_HOST_BIN\` pointing at an already built host instead of building one (docs/guides/dev-app.md). A failure the change didn't cause (the same without it) is \`preexisting\`, not \`fail\`. Stop the old build before installing the new one. In this worktree \`npm run dev\` in apps/desktop runs an isolated sandbox (docs/guides/dev-app.md#worktree-sandboxes); never stop or replace the shared Codync Dev, the production Codync app or another session's sandbox. In a worktree every client signs into the sandbox's Clerk test account, never the maintainer's: the sandbox runs with \`--cloud\`, and the iPhone and Android apps are seeded with \`npm run phone-account -- --ios <udid>\` / \`-- --android <serial>\` on the worktree's test devices: the iPhone on its own simulator \`Codync <sandbox name>\`, never one signed into the maintainer's account (\`npm run dev\` prints its udid, or the command that creates it when there is none yet; \`--prune\` deletes it later), Android on the shared \`codync_worktree\` emulator (never \`codync_api36\`, the maintainer's), one test at a time under its lock, with \`pm clear\` and the notification grant first (docs/guides/dev-app.md#worktree-sandboxes). When done, leave this worktree's \`npm run dev\` running (it is stopped after the merge) but stop anything else you started. A change with nothing to walk (CI, tools, docs) reports one not_run check saying so.`,+Walk each flow once, as a person would, until it clearly passes or fails, and note what you saw; don't explore beyond the listed flows. Drive them as docs/guides/test-stack.md says: the desktop with Playwright (\`npm run e2e\` in apps/desktop against \`npm run dev -- --cdp\`), the phones with one Maestro run under the Maestro lock (\`apps/maestro\`, \`--shard-all\`), adding or updating the spec or flow each changed flow needs; Computer Use (cluadex) only for the native steps that guide lists. Keep it quick: short messages to bots, no sleeps or long-running tasks to stretch a turn, and when \`host/\` is unchanged start \`npm run dev\` with \`CODYNC_HOST_BIN\` pointing at an already built host instead of building one (docs/guides/dev-app.md). A failure the change didn't cause (the same without it) is \`preexisting\`, not \`fail\`. Stop the old build before installing the new one. In this worktree \`npm run dev\` in apps/desktop runs an isolated sandbox (docs/guides/dev-app.md#worktree-sandboxes); never stop or replace the shared Codync Dev, the production Codync app or another session's sandbox. In a worktree every client signs into the sandbox's Clerk test account, never the maintainer's: the sandbox runs with \`--cloud\`, and the iPhone and Android apps are seeded with \`npm run phone-account -- --ios <udid>\` / \`-- --android <serial>\` on the worktree's test devices: the iPhone on its own simulator \`Codync <sandbox name>\`, never one signed into the maintainer's account (\`npm run dev\` prints its udid, or the command that creates it when there is none yet; \`--prune\` deletes it later), Android on the shared \`codync_worktree\` emulator (never \`codync_api36\`, the maintainer's), one test at a time under its lock, with \`pm clear\` and the notification grant first (docs/guides/dev-app.md#worktree-sandboxes). When done, leave this worktree's \`npm run dev\` running (it is stopped after the merge) but stop anything else you started. A change with nothing to walk (CI, tools, docs) reports one not_run check saying so.`,{ label: `e2e:${round}`, phase: 'E2E', schema: CHECKS })phase('E2E')diff --git a/AGENTS.md b/AGENTS.mdindex c51d2040..ae6f8997 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -36,7 +36,7 @@ Keep only the latest build: in this checkout, Apple builds go to `build/dd` only## End-to-end test every change-After every change, test it end to end on the real apps, not just builds and unit tests: install the new build (old one stopped first) and walk through the changed flow. Drive the desktop app with Computer Use, and the iPhone app on an iOS Simulator through Device Hub (Xcode's `DeviceHub.app`). Report any check that could not run and why. The target split (Playwright for desktop, Maestro for phones, Computer Use only for `@native` gaps) is in [test stack](docs/guides/test-stack.md); until its harness is checked in, the Computer Use route above stays.+After every change, test it end to end on the real apps, not just builds and unit tests: install the new build (old one stopped first) and walk through the changed flow. Drive the desktop app with Playwright (`npm run e2e` against the sandbox) and the iPhone app (iOS Simulator) and Android app (emulator) with one Maestro run (`apps/maestro`); Computer Use only for the native steps they can't reach: [test stack](docs/guides/test-stack.md). Report any check that could not run and why.- **Minimal e2e** (default): only the platform of the computer you test on (on the Mac: macOS).- **Full e2e** (large changes: platform code, packaging, the desktop main process; or when asked): macOS, Linux (Lima `codync-linux`) and Windows (UTM, [Windows testing](docs/guides/windows-testing.md)). A platform whose VM isn't installed is skipped and reported, not set up.diff --git a/CLAUDE.md b/CLAUDE.mdindex fea35117..38888af3 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -62,7 +62,7 @@ Keep only the latest build: in this checkout, Apple builds go to `build/dd` only## End-to-end test every change-After every change, test it end to end on the real apps, not just builds and unit tests: install the new build (old one stopped first) and walk through the changed flow. Drive the desktop app with Computer Use, the iPhone app on an iOS Simulator through Device Hub (Xcode's `DeviceHub.app`), and the Android app on an emulator (`adb`). Report any check that could not run and why. The target split (Playwright for desktop, Maestro for phones, Computer Use only for `@native` gaps) is in [test stack](docs/guides/test-stack.md); until its harness is checked in, the Computer Use route above stays.+After every change, test it end to end on the real apps, not just builds and unit tests: install the new build (old one stopped first) and walk through the changed flow. Drive the desktop app with Playwright (`npm run e2e` against the sandbox) and the iPhone app (iOS Simulator) and Android app (emulator) with one Maestro run (`apps/maestro`); Computer Use only for the native steps they can't reach: [test stack](docs/guides/test-stack.md). Report any check that could not run and why.- **Minimal e2e** (default): only the platform of the computer you test on (on the Mac: macOS).- **Full e2e** (large changes: platform code, packaging, the desktop main process; or when asked): macOS, Linux (Lima `codync-linux`) and Windows (UTM, [Windows testing](docs/guides/windows-testing.md)). A platform whose VM isn't installed is skipped and reported, not set up.- **Desktop build to use**: develop and e2e with `npm run dev` in `apps/desktop` (renderer reloads on save, restart it after `src/main` or preload changes; nothing packaged or signed). In a linked worktree it runs a [sandbox](docs/guides/dev-app.md#worktree-sandboxes) beside the main checkout's Codync Dev (own host build, port and data); `--sandbox` does the same from the main checkout when another session's Codync Dev is running. In the main checkout, after a host change run `node tools/native-host.mjs dev` there first: `npm run dev` prefers that build over `host/target/debug`. Package `npm run dist:mac:dev` (about 45 s) only for what an unpackaged run lacks: the bundled host install, Codync Screen / computer use, system permissions. `dist:*:main` (universal, timestamped, minutes) only to check the production app.diff --git a/apps/desktop/.gitignore b/apps/desktop/.gitignoreindex 2783f80f..44ab4efb 100644--- a/apps/desktop/.gitignore+++ b/apps/desktop/.gitignore@@ -1,6 +1,7 @@node_modules/out/dist/+test-results/# SF Symbols masks: generated on macOS at build time (npm run icons), never committed.src/renderer/public/symbols/native/speech-macos/.build/diff --git a/apps/desktop/e2e/playwright.config.ts b/apps/desktop/e2e/playwright.config.tsnew file mode 100644index 00000000..75b59e98--- /dev/null+++ b/apps/desktop/e2e/playwright.config.ts@@ -0,0 +1,14 @@+import { defineConfig } from '@playwright/test'++// Desktop e2e attaches to this worktree's running sandbox (`npm run dev -- --cdp`) instead of+// launching Electron itself: the sandbox owns the host, data and sign-in, and one app runs per+// worktree, so one worker here. Worktrees run in parallel with each other.+export default defineConfig({+ testDir: '.',+ testMatch: '**/*.spec.ts',+ workers: 1,+ timeout: 30_000,+ reporter: [['list']],+ outputDir: '../test-results',+ use: { trace: 'retain-on-failure' },+})diff --git a/apps/desktop/e2e/sandbox.ts b/apps/desktop/e2e/sandbox.tsnew file mode 100644index 00000000..859b777c--- /dev/null+++ b/apps/desktop/e2e/sandbox.ts@@ -0,0 +1,35 @@+import { chromium, type Browser, type Page } from '@playwright/test'+import { readFileSync } from 'node:fs'+import { homedir } from 'node:os'+import { basename, join, resolve } from 'node:path'+import { SANDBOX_PREFIX, sandboxName } from '../src/shared/dev-sandbox.ts'++// Playwright loads specs as CommonJS here (the package has no "type": "module").+const root = resolve(__dirname, '../../..')++/** This worktree's sandbox: its name, host port and DevTools port (`npm run dev -- --cdp` opens port + 10000). */+export function sandbox() {+ const name = sandboxName(basename(root))+ const record = join(homedir(), SANDBOX_PREFIX + name, 'sandbox.json')+ let port: number+ try {+ port = (JSON.parse(readFileSync(record, 'utf8')) as { port: number }).port+ } catch {+ throw new Error(`No sandbox for ${root}: run \`npm run dev -- --cdp\` in apps/desktop first.`)+ }+ return { name, port, cdp: port + 10000 }+}++/** Attaches to the sandbox app's main window over the DevTools protocol. */+export async function attach(): Promise<{ browser: Browser; page: Page }> {+ const { cdp } = sandbox()+ const browser = await chromium.connectOverCDP(`http://127.0.0.1:${cdp}`).catch(() => {+ throw new Error(`The sandbox app isn't listening on ${cdp}: start it with \`npm run dev -- --cdp\`.`)+ })+ const page = browser+ .contexts()+ .flatMap((context) => context.pages())+ .find((p) => !p.url().startsWith('devtools://'))+ if (!page) throw new Error('The sandbox app has no window open.')+ return { browser, page }+}diff --git a/apps/desktop/e2e/smoke.spec.ts b/apps/desktop/e2e/smoke.spec.tsnew file mode 100644index 00000000..9e2ad334--- /dev/null+++ b/apps/desktop/e2e/smoke.spec.ts@@ -0,0 +1,19 @@+import { test, expect } from '@playwright/test'+import type { HostSnapshot } from '../src/shared/ipc.ts'+import { attach, sandbox } from './sandbox.ts'++test('the sandbox app renders and runs against its own host', async () => {+ const { browser, page } = await attach()+ try {+ await expect(page.locator('#root')).not.toBeEmpty()+ const host = await page.evaluate(+ () => (window as unknown as { codync: { host: { snapshot(): Promise<HostSnapshot> } } }).codync.host.snapshot(),+ )+ // The sandbox host, never Codync Dev's shared one on 19223.+ expect(host.state.kind).toBe('running')+ expect(host.dev).toBe(true)+ expect(host.local?.baseURL).toBe(`http://127.0.0.1:${sandbox().port}`)+ } finally {+ await browser.close()+ }+})diff --git a/apps/desktop/package-lock.json b/apps/desktop/package-lock.jsonindex d8a05c75..4a86b6b8 100644--- a/apps/desktop/package-lock.json+++ b/apps/desktop/package-lock.json@@ -12,6 +12,7 @@"electron-updater": "^6.8.9"},"devDependencies": {+ "@playwright/test": "1.64.1","@types/node": "^24.0.0","@types/qrcode": "^1.5.6","@types/react": "^19.3.0",@@ -1292,6 +1293,22 @@"node": ">=14.18.0"}},+ "node_modules/@playwright/test": {+ "version": "1.64.1",+ "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.64.1.tgz",+ "integrity": "sha512-IaYGml/nSOiZWROfPtuIL7neuu9qDOZ3TNvNljUIrhDMxiGTgPjzj/g9p9RxpS2tSepPDRY+UwAaEeiKtUvIAg==",+ "dev": true,+ "license": "Apache-2.0",+ "dependencies": {+ "playwright": "1.64.1"+ },+ "bin": {+ "playwright": "cli.js"+ },+ "engines": {+ "node": ">=20"+ }+ },"node_modules/@rolldown/pluginutils": {"version": "1.0.0-rc.3","resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.3.tgz",@@ -4567,6 +4584,35 @@"url": "https://paulmillr.com/funding/"}},+ "node_modules/playwright": {+ "version": "1.64.1",+ "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.1.tgz",+ "integrity": "sha512-HCrVhHr5QQuwYoswEUGTb7gGp522yflbv/ST8nF4sFWGuLjQCt17Q/EubpGGSNKYn1tsTCPZxqHhHCfVURu7UA==",+ "dev": true,+ "license": "Apache-2.0",+ "dependencies": {+ "playwright-core": "1.64.1"+ },+ "bin": {+ "playwright": "cli.js"+ },+ "engines": {+ "node": ">=20"+ }+ },+ "node_modules/playwright-core": {+ "version": "1.64.1",+ "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.1.tgz",+ "integrity": "sha512-BC4s8y6SEVA6Q1rSxZTto8hI1KUI3xXlHGZgvGqP4IqPdI/a6FX9H29IDNz7vKo9l21b6LfYosScPL6M3xxyDQ==",+ "dev": true,+ "license": "Apache-2.0",+ "bin": {+ "playwright-core": "cli.js"+ },+ "engines": {+ "node": ">=20"+ }+ },"node_modules/plist": {"version": "3.1.0","resolved": "https://registry.npmjs.org/plist/-/plist-3.1.0.tgz",diff --git a/apps/desktop/package.json b/apps/desktop/package.jsonindex c5ab0e03..14e95fbc 100644--- a/apps/desktop/package.json+++ b/apps/desktop/package.json@@ -18,6 +18,7 @@"build:demo": "vite build --config vite.demo.config.ts && mv ../../web/public/demo/desktop/index.html ../../web/public/demo/desktop.html","typecheck": "tsc --noEmit -p tsconfig.json","test": "node --test --experimental-strip-types src/shared/*.test.ts src/renderer/lib/*.test.ts src/renderer/store/*.test.ts src/renderer/views/*.test.ts src/renderer/views/thread/*.test.ts src/renderer/views/routines/*.test.ts src/renderer/views/call/*.test.ts src/renderer/views/marketplace/*.test.ts",+ "e2e": "playwright test -c e2e/playwright.config.ts","icons": "swift tools/export-symbols.swift","dist:mac:dev": "node tools/account-config.mjs dev && node tools/native-host.mjs dev && node tools/native-screen.mjs dev && electron-vite build && CSC_NAME=\"Pokai Lee (6KFK5J2LB4)\" electron-builder --mac --config tools/dev-builder.cjs","dist:mac:main": "node tools/account-config.mjs main && node tools/native-host.mjs main && node tools/native-screen.mjs main && electron-vite build && electron-builder --mac",@@ -27,6 +28,7 @@"dist:win:main": "node tools/account-config.mjs main && node tools/native-host.mjs main && electron-vite build && electron-builder --win"},"devDependencies": {+ "@playwright/test": "1.64.1","@types/node": "^24.0.0","@types/qrcode": "^1.5.6","@types/react": "^19.3.0",diff --git a/apps/desktop/tsconfig.json b/apps/desktop/tsconfig.jsonindex 227c787a..b12a43f6 100644--- a/apps/desktop/tsconfig.json+++ b/apps/desktop/tsconfig.json@@ -17,5 +17,5 @@"types": ["node"],"paths": { "@shared/*": ["./src/shared/*"] }},- "include": ["src", "electron.vite.config.ts", "vite.demo.config.ts"]+ "include": ["src", "e2e", "electron.vite.config.ts", "vite.demo.config.ts"]}diff --git a/apps/maestro/welcome.yaml b/apps/maestro/welcome.yamlnew file mode 100644index 00000000..fa3bfac8--- /dev/null+++ b/apps/maestro/welcome.yaml@@ -0,0 +1,22 @@+# A fresh install opens on the welcome screen with every sign-in choice.+# One flow for iPhone and Android; run it on both at once (docs/guides/test-stack.md):+# maestro --device "<simulator udid>,<adb serial>" test --shard-all 2 apps/maestro+appId: com.pokai.Codync.ios.dev+---+- runFlow:+ when:+ platform: iOS+ commands:+ - launchApp:+ appId: com.pokai.Codync.ios.dev+ clearState: true+- runFlow:+ when:+ platform: Android+ commands:+ - launchApp:+ appId: com.pokai.Codync.android.dev+ clearState: true+- assertVisible: "Your coding agents,\\s+as teammates\\."+- assertVisible: "Continue with Google"+- assertVisible: "Continue with GitHub"diff --git a/docs/guides/test-stack.md b/docs/guides/test-stack.mdindex b2ad486c..742b7426 100644--- a/docs/guides/test-stack.md+++ b/docs/guides/test-stack.md@@ -1,41 +1,48 @@# Test stack-Target design for the end-to-end (e2e) checks. **Status: not installed yet.** Playwright and Maestro are not in the repo, and the Electron tool is still open (see [Open items](#open-items)). Until the harness below is checked in, every e2e check keeps using Computer Use through cluadex, as [CLAUDE.md](../../CLAUDE.md#end-to-end-test-every-change) says.+How the end-to-end (e2e) checks drive the apps: Playwright for the desktop app, Maestro for the iPhone and Android apps, and Computer Use only for the native steps neither can reach. Unit and component tests stay as they are (`npm run typecheck && npm test`, `cargo test`, the Swift tests in `apps/ios/Kit`, the Gradle checks).-## Tiers+## Desktop: Playwright-1. **Unit and component**: unchanged. `npm run typecheck && npm test` (desktop), `cargo test` (host), Swift tests (`apps/ios/Kit`), Gradle checks (Android).-2. **E2E per platform**:- - **Electron desktop**: Playwright through `_electron` (renderer over CDP). Playwright's Electron support is documented as experimental, so it is one of two candidates. The other is WebdriverIO with `wdio-electron-service`, which reaches the main process and can load the electron-vite entry through `appEntryPoint`. Spike both on Electron 44 before choosing.- - **iPhone**: Maestro flows on the worktree's own simulator (`Codync <sandbox name>`, created by `npm run dev`). XCUITest is optional for iOS-only checks that Maestro cannot express.- - **Android**: Maestro on the shared `codync_worktree` emulator, under its lock as the [after-change skill](../../.agents/skills/after-change/SKILL.md) describes.- - **Native gaps**: Computer Use through cluadex, only for the steps tagged `@native`.+Playwright attaches to the worktree's running sandbox over the DevTools protocol. It doesn't launch Electron itself: the sandbox already owns the host, data, sign-in and single-instance lock, and an app launched without them would open against the shared Codync Dev.-## What Computer Use covers+```sh+cd apps/desktop+npm run dev -- --cdp # the worktree's sandbox, DevTools on its port + 10000+npm run e2e # in a second shell: e2e/*.spec.ts against that sandbox+```++`e2e/sandbox.ts` finds the sandbox from its `sandbox.json` and attaches to its main window; `e2e/smoke.spec.ts` checks the app renders and runs against the sandbox's own host. A spec reaches the main process only through the `window.codync` bridge, as the renderer does. One worker per worktree, since one app runs per sandbox; worktrees run in parallel with each other.++## Phones: Maestro++One flow in `apps/maestro/` serves both phones: it launches the iPhone or Android Dev app by platform (`runFlow` with `when: platform`) and asserts the same copy, since the apps match screen for screen. Run every phone in one Maestro process:-Only these steps go to Computer Use. Everything else uses Playwright or Maestro.+```sh+maestro --device "<simulator udid>,<adb serial>" test --shard-all 2 apps/maestro+```-- **Desktop**: the tray or menu bar icon and its menu; the global shortcut (approval island); system notification banners; macOS privacy prompts (screen recording, notifications); the Clerk sign-in in the system browser and the `codync-dev://` callback back into the app; features that need the packaged `Codync Dev.app` (Codync Screen, computer use, `SMAppService` registration).-- **Phones**: how system alerts and notification banners look on the simulator or emulator; the desktop QR pairing, where Computer Use reads the QR on the Mac screen and Maestro completes the pairing on the phone; widgets, Live Activity and the Dynamic Island.+The devices are the worktree's own simulator `Codync <sandbox name>` and the shared `codync_worktree` emulator, under its lock ([worktree sandboxes](dev-app.md#worktree-sandboxes)). Install the worktree's builds first: `xcodebuild … -scheme "iOS Dev" -configuration DevDebug -derivedDataPath build/dd` for the simulator, `./gradlew :app:assembleDebug` for the emulator.++**One Maestro process per Mac.** Two at once break each other: with Maestro 2.1.0, an iPhone run beside an Android run made the Android driver refuse connections on port 7001 in three of three tries, and two runs starting in the same second removed each other's log folder in `~/Library/Logs/maestro`. Shard inside one run instead. Across worktrees, take the lock folder `/private/tmp/claude-$(id -u)/maestro.lock` the way the emulator lock works: `mkdir` it (it fails while another run holds it), write your worktree's path into `owner`, `rm -r` it when done; one older than an hour, or whose worktree is gone, is stale.++## What Computer Use covers-**Covered by neither**, so check on a physical device and say so in the report: microphone and voice-call audio; real APNs delivery (the simulator can only simulate it with `xcrun simctl push`).+Computer Use (cluadex, in the background) checks only these steps. Tag them `@native` in the change's e2e list. Everything else uses Playwright or Maestro. If cluadex fails, stop and ask the user to reconnect it with `/mcp`; don't switch to cua-driver.-## Parallelism+- **Desktop**: the tray or menu bar icon and its menu; the approval island's global shortcut; system notification banners; macOS privacy prompts (screen recording, notifications); Clerk sign-in in the system browser and the `codync-dev://` callback back into the app; anything that needs the packaged `Codync Dev.app` (Codync Screen, computer use, `SMAppService`).+- **Phones**: how system alerts and notification banners look; the desktop QR pairing (Computer Use reads the QR on the Mac, Maestro finishes on the phone); widgets, Live Activity and the Dynamic Island.-- **Playwright and Maestro run in parallel.** Each worker gets its own instance: its own sandbox (port 19300–19399), simulator or emulator, Clerk test account and Electron `userDataDir`. Tests must not depend on each other's state.-- **Maestro sharding**: start with the device count that is stable on this Mac. One team reported freezes above four simulators on virtualized CI, and seven running on native Mac hardware. Measure here before raising the count.-- **Computer Use runs in one lane.** One CU task at a time, in the background, never in the foreground. If cluadex fails, stop and ask the user to reconnect with `/mcp`. Do not silently switch to cua-driver.-- Tag CU steps `@native` so a regression run can skip them and the release run includes them.+**Covered by none of them**, so check on a physical device and say so in the report: microphone and voice-call audio, and real APNs delivery (a simulator only simulates it with `xcrun simctl push`).## Rules-- Each changed flow names the tier that covers it. A `@native` step names the single native action it checks.-- Do not use Computer Use for anything Playwright or Maestro can express. It is slower and cannot run in parallel.-- Report every check that did not run and why, as the existing e2e rule requires.+- Each changed flow names the tool that covers it, and a changed flow that Playwright or Maestro can express gets a spec or flow in the same change.+- Computer Use never runs two tasks at once. Playwright and the one Maestro run go beside it.+- Report every check that didn't run and why.-## Open items+## Why these tools-- Choose the Electron tool (Playwright or WebdriverIO) through a spike on Electron 44.-- Check Maestro's behavior on several simulators at once here, and record the stable count.-- Install the chosen tools and check in the first flows. Wire them into CI.-- Once the harness exists, update [CLAUDE.md](../../CLAUDE.md), [AGENTS.md](../../AGENTS.md), the `after-change` workflow (`.claude/workflows/after-change.js`) and the [after-change skill](../../.agents/skills/after-change/SKILL.md) to this split. Until then they stay on Computer Use.+- Playwright's Electron launch (`_electron`) is documented as experimental, and launching the app directly bypasses the sandbox. Attaching over the DevTools protocol uses the sandbox as `npm run dev` starts it, and matches where Playwright's Electron support is heading.+- Maestro runs one YAML flow on both phones, which fits the rule that every iPhone change lands on Android and is checked on both. XCUITest stays available for iOS-only checks Maestro can't express.+- Computer Use is slower and holds the one screen and cursor, so it covers only what no in-app driver can reach.