codeloop-mcp-server 0.1.88 → 0.1.91

package/dist/index.js

@@ -1495,6 +1495,7 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
     workspace_root: z.string().optional().describe("[Alias for project_dir] Same semantics; accepted because many agents reach for this conventional name. Pass either `project_dir` OR `workspace_root` — they're equivalent."),
     target_change_entry: z.string().optional().describe("0.1.52 C7 — verbatim display name of the change-manifest entry this screenshot exercises (e.g. 'datagrid_column: \"Product Code\"' or 'PhotometricConfigurations.ProductCode'). When present, the screenshot file is auto-anchored: the filename is prefixed with a slugged form of the entry so the change_coverage_evidence (C3) gate's screenshot scan can credit this evidence to the correct manifest entry without fuzzy matching. The value is also persisted alongside the screenshot path in the response so downstream tools (interaction_replay, gate_check) can use it."),
     target_type: z.string().optional().describe("Capture source. Omit for desktop/window capture (default). Set 'android_emulator' (or 'android') to capture the BOOTED Android emulator via adb, or 'ios_simulator' (or 'ios', macOS only) to capture the booted iOS simulator via simctl. Use this to screenshot a Flutter/native mobile app running on a simulator instead of the host desktop."),
+    device_id: z.string().optional().describe("Pinned mobile device for emulator/simulator capture: adb serial or simulator UDID. Defaults to the device the last journey/recording targeted, then adb default / simctl 'booted'."),
 }, async (params) => {
     const authResult = await withAuth(async () => {
         const { captureScreenshot } = await import("./runners/screenshot.js");
@@ -1543,7 +1544,14 @@ Returns: confirmation + the captured image as an MCP ImageContent block so you c
         const ttRaw = normalizeTargetType(params.target_type);
         const explicitTargetType = ttRaw === "android_emulator" || ttRaw === "ios_simulator" ? ttRaw : undefined;
         const isMobileCapture = explicitTargetType !== undefined;
-        const result = await captureScreenshot(screenshotsDir, finalScreenName, isMobileCapture ? undefined : targetApp, explicitTargetType, { desktopAppMode: isMobileCapture ? false : desktopApp });
+        // Pin the capture to the journey/recording device when known.
+        let captureDevice;
+        if (isMobileCapture) {
+            const { resolveDeviceId } = await import("./runners/active_target.js");
+            const vr = await import("./runners/video_recorder.js");
+            captureDevice = resolveDeviceId(params.device_id ?? vr.getActiveRecordingDevice() ?? undefined, cwd, explicitTargetType);
+        }
+        const result = await captureScreenshot(screenshotsDir, finalScreenName, isMobileCapture ? undefined : targetApp, explicitTargetType, { desktopAppMode: isMobileCapture ? false : desktopApp, device: captureDevice });
         // Photometry-DB E2E 8 follow-on: when we capture a desktop app
         // window, also resolve its on-screen bounds so the agent can
         // (a) compute window-relative coords from the returned image
@@ -2028,6 +2036,7 @@ App logs (stdout, logcat, simctl log) are automatically captured alongside the v
     target_type: targetTypeSchema.optional()
         .describe("Capture method. Auto-detected from project if omitted. desktop=ffmpeg screen, android_emulator=adb screenrecord, ios_simulator=simctl recordVideo, browser=ffmpeg/Playwright"),
     auto_launch: z.boolean().default(true).describe("When target_type=desktop and the app isn't already running, auto-launch it from the project's build output via evidence.target_app. Set false to skip (e.g. when the app is started by another process)."),
+    device_id: z.string().optional().describe("Pinned mobile device to record: adb serial (emulator-5554) or simulator UDID. Defaults to the device the last journey targeted, then the first booted device. The pinned device is persisted so follow-up codeloop_interact calls hit the same one."),
     project_dir: z.string().optional().describe("Absolute path to the project root. Defaults to CODELOOP_PROJECT_DIR env var or auto-discovered project directory. MUST be an actual project folder — passing the user's home directory is rejected. If your IDE launches the MCP server from the wrong cwd (common on Windows where Cursor uses C:\\Users\\<name> as cwd), set CODELOOP_PROJECT_DIR or pass this param explicitly."),
     workspace_root: z.string().optional().describe("[Alias for project_dir] Same semantics; accepted because many agents reach for this conventional name. Pass either `project_dir` OR `workspace_root` — they're equivalent."),
 }, async (params) => {
@@ -2125,6 +2134,7 @@ App logs (stdout, logcat, simctl log) are automatically captured alongside the v
         // concrete commands rather than letting it guess. CodeLoop does not boot
         // devices itself (heavy + can hijack the desktop), it directs the agent.
         let deviceReadinessDirective;
+        let recordingDevice;
         if (targetType === "android_emulator" || targetType === "ios_simulator") {
             try {
                 const { probeBootedDevices, detectMobileTargets, buildOpenSimulatorsDirective } = await import("./runners/device_probe.js");
@@ -2139,10 +2149,22 @@ App logs (stdout, logcat, simctl log) are automatically captured alongside the v
                         context: "recording",
                     });
                 }
+                else {
+                    // Pin the recording to ONE device: explicit param → persisted
+                    // active target → first booted device of this platform. Persist
+                    // the choice so follow-up codeloop_interact calls hit the same one.
+                    const { resolveDeviceId, saveActiveTarget } = await import("./runners/active_target.js");
+                    recordingDevice =
+                        resolveDeviceId(params.device_id, cwd, targetType) ??
+                            (targetType === "android_emulator" ? booted.android[0] : booted.ios_devices[0]?.udid);
+                    if (recordingDevice) {
+                        saveActiveTarget(cwd, { target_type: targetType, device_id: recordingDevice });
+                    }
+                }
             }
             catch { /* best-effort */ }
         }
-        const result = await startBackgroundRecording(videosDir, appName ?? "", params.max_duration_seconds, targetType);
+        const result = await startBackgroundRecording(videosDir, appName ?? "", params.max_duration_seconds, targetType, recordingDevice);
         if (autoLaunchSummary) {
             result.auto_launch = autoLaunchSummary;
         }
@@ -2930,14 +2952,18 @@ scroll works on desktop via CGEvent (macOS), user32 mouse_event (Windows), xdoto
   Falls back to arrow key presses if CGEvent fails (permissions).
 Browser-specific: Uses Playwright selectors (CSS/text) when target_type is "browser".
 Mobile-specific: swipe, back_button, home_button, deep_link, grant_permission, rotate_device,
-  biometric_auth, launch_app, clear_app_data, mock_location, simulate_network.
+  biometric_auth, launch_app, clear_app_data, mock_location, simulate_network,
+  push_notification (iOS: simctl push — package_id + value as APNs JSON or alert text),
+  status_bar (iOS: simctl status_bar — value as JSON or "time=9:41,batteryLevel=100", or "clear").
+  iOS (0.1.91): grant_permission → simctl privacy; mock_location → simctl location;
+  clear_app_data → simctl uninstall (REINSTALL needed after); rotate_device → Simulator Cmd+arrow.
 Maestro: maestro_flow — generate and run a Maestro YAML flow from high-level steps.
 Windows: win_ui_inspect, win_ui_automate — PowerShell UI Automation for UWP/WinUI apps.
 
 MANDATORY for web apps: You MUST type into form fields, fill login/signup forms, test
 validation errors, and click submit buttons. Just navigating pages is NOT enough.
 Wait 1-2 seconds between interactions so video frames capture state changes.`, {
-    action: z.string().describe("Action to perform: click, double_click, right_click, hover, type, keystroke, hotkey, scroll, drag_drop, long_press, type_and_submit, type_and_tab, fill_form, select_option, toggle, get_text, upload_file, navigate_url, navigate_back, navigate_forward, wait, sequence, swipe, back_button, home_button, deep_link, grant_permission, rotate_device, biometric_auth, launch_app, clear_app_data, mock_location, simulate_network, maestro_flow, win_ui_inspect, win_ui_automate"),
+    action: z.string().describe("Action to perform: click, double_click, right_click, hover, type, keystroke, hotkey, scroll, drag_drop, long_press, type_and_submit, type_and_tab, fill_form, select_option, toggle, get_text, upload_file, navigate_url, navigate_back, navigate_forward, wait, sequence, swipe, back_button, home_button, deep_link, grant_permission, rotate_device, biometric_auth, launch_app, clear_app_data, mock_location, simulate_network, push_notification, status_bar, maestro_flow, win_ui_inspect, win_ui_automate"),
     expect_contains: z.string().optional().describe("[get_text] Optional assertion: the read-back text must contain this substring (case-insensitive). When set, success is false if the substring is absent. Use to confirm an AI chatbot answer / dynamic response actually rendered the expected content."),
     target_type: targetTypeSchema.optional()
         .describe("Interaction target. Auto-detected if omitted. Accepts synonyms: `windows_desktop`/`mac_desktop`/`linux_desktop` → `desktop`; `web` → `browser`; `android` → `android_emulator`; `ios` → `ios_simulator`."),
@@ -2956,7 +2982,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
     direction: z.enum(["up", "down", "left", "right"]).optional().describe("Scroll/swipe direction"),
     amount: z.number().optional().describe("Scroll amount or other numeric value"),
     duration_ms: z.number().optional().describe("Duration for wait, long_press, swipe"),
-    value: z.string().optional().describe("Value for select_option, permission name, network mode, package ID"),
+    value: z.string().optional().describe("Value for select_option, permission name, network mode, package ID, push_notification payload (APNs JSON or alert text), status_bar overrides (JSON or key=value list, or \"clear\")"),
     file_path: z.string().optional().describe("File path for upload_file"),
     fields: z.array(z.object({
         selector: z.string(),
@@ -2979,6 +3005,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
         .describe("For win_ui_automate"),
     app_name: z.string().optional().describe("App name to bring to front before interaction. Auto-detected from active recording if omitted. Also used for launch_app, win_ui_inspect, win_ui_automate."),
     package_id: z.string().optional().describe("Package/bundle ID for mobile actions"),
+    device_id: z.string().optional().describe("Pinned mobile device: adb serial (e.g. emulator-5554) or iOS simulator UDID. When omitted, falls back to the device the last journey/recording targeted (.codeloop/active_target.json), then to adb's default / simctl 'booted'. Pass explicitly when several emulators/simulators are attached."),
     intent: z.string().optional().describe("Semantic label for what this interaction is doing — short verb-phrase like 'edit product row', 'confirm delete dialog', 'save form', 'create new range'. STRONGLY RECOMMENDED for desktop coordinate-based clicks (target_type='desktop' with only x/y) because the CRUD classifier in user_journey_evidence can't infer the meaning of a raw (x, y) pair the way it can from a Playwright selector or DOM aria_label. Without `intent`, a sequence of coordinate clicks that delete a record will score `delete_actions: 0` and fail the gate. The classifier reads `intent` (plus `description` / `purpose` / `step` as aliases) into the same target-text bucket as selectors and aria labels, so the SAME keywords that work for browsers (edit / delete / save / submit / create / new) also work here. Example: when clicking the 'Yes' button of a Windows MessageBox at (2640, 820), pass intent='confirm delete'."),
     description: z.string().optional().describe("[Alias for intent] Same semantics."),
     purpose: z.string().optional().describe("[Alias for intent] Same semantics."),
@@ -3015,6 +3042,19 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 tt = await detectTargetType(cwd);
             }
         }
+        // Pin mobile commands to one device: explicit device_id param →
+        // the device the active recording is capturing → the device the
+        // last journey persisted (active_target.json) → undefined (adb
+        // default / simctl "booted").
+        let deviceId;
+        if (tt === "android_emulator" || tt === "ios_simulator") {
+            const { resolveDeviceId } = await import("./runners/active_target.js");
+            deviceId = resolveDeviceId(params.device_id ?? vr.getActiveRecordingDevice() ?? undefined, cwd, tt);
+        }
+        // iOS sim input backend (CGEvent window mapping / idb) — simctl
+        // has NO tap/type/swipe; see runners/ios_sim_input.ts.
+        const sim = await import("./runners/ios_sim_input.js");
+        const iosUdid = deviceId || "booted";
         // For browser target, ensure Playwright headed browser is running
         if (tt === "browser" && action !== "wait") {
             await bi.ensureBrowserPage();
@@ -3161,10 +3201,13 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     success = await bi.browserClick(params.selector);
                 }
                 else if (tt === "android_emulator" && params.x != null && params.y != null) {
-                    success = await wm.adbTap(params.x, params.y);
+                    success = await wm.adbTap(params.x, params.y, deviceId);
                 }
                 else if (tt === "ios_simulator" && params.x != null && params.y != null) {
-                    success = await wm.simctlTap(params.x, params.y);
+                    const r = await sim.iosSimTap(params.x, params.y, iosUdid);
+                    success = r.success;
+                    detail = `click at (${params.x},${params.y}) — ${r.detail}`;
+                    break;
                 }
                 else if (params.selector) {
                     if (process.platform === "win32") {
@@ -3249,10 +3292,13 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     success = await bi.browserType(params.selector, params.text);
                 }
                 else if (tt === "android_emulator" && params.text) {
-                    success = await wm.adbType(params.text);
+                    success = await wm.adbType(params.text, deviceId);
                 }
                 else if (tt === "ios_simulator" && params.text) {
-                    success = await wm.simctlType(params.text);
+                    const r = await sim.iosSimType(params.text, iosUdid);
+                    success = r.success;
+                    detail = `type "${(params.text || "").substring(0, 50)}" — ${r.detail}`;
+                    break;
                 }
                 else if (params.text) {
                     success = await wm.typeText(params.text);
@@ -3279,7 +3325,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     // uiautomator hierarchy — lets the agent analyze a Flutter/native
                     // AI chatbot's answer without OCR. `selector` is treated as a
                     // text/resource-id substring filter when provided.
-                    extractedText = await wm.adbGetText(params.selector);
+                    extractedText = await wm.adbGetText(params.selector, deviceId);
                     success = extractedText !== null && extractedText.length > 0;
                     const preview = (extractedText ?? "").replace(/\s+/g, " ").trim().slice(0, 120);
                     detail = success
@@ -3287,11 +3333,14 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                         : "get_text (android) found no visible text — is the emulator booted and the app foregrounded?";
                 }
                 else if (tt === "ios_simulator") {
-                    // simctl has no UI-tree dump; the agent reads the answer from a
-                    // screenshot via its own vision. Point it there explicitly.
-                    success = false;
-                    detail =
-                        "get_text is not available for iOS simulators (simctl exposes no UI-tree dump). Call codeloop_capture_screenshot with target_type=\"ios_simulator\" and read the AI answer from the image with your vision.";
+                    // idb (when installed) exposes the accessibility tree; otherwise
+                    // the agent reads the answer from a screenshot via its own vision.
+                    extractedText = await sim.iosSimGetText(iosUdid);
+                    success = extractedText !== null && extractedText.length > 0;
+                    const preview = (extractedText ?? "").replace(/\s+/g, " ").trim().slice(0, 120);
+                    detail = success
+                        ? `get_text (ios via idb) → "${preview}${(extractedText ?? "").length > 120 ? "…" : ""}"`
+                        : "get_text on iOS needs idb (brew install idb-companion && pipx install fb-idb). Without it, call codeloop_capture_screenshot with target_type=\"ios_simulator\" and read the text from the image with your vision.";
                 }
                 else {
                     success = false;
@@ -3327,22 +3376,22 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                             up: "KEYCODE_DPAD_UP", down: "KEYCODE_DPAD_DOWN",
                             left: "KEYCODE_DPAD_LEFT", right: "KEYCODE_DPAD_RIGHT",
                         };
-                        success = await wm.adbKey(adbKeyMap[params.key.toLowerCase()] || `KEYCODE_${params.key.toUpperCase()}`);
+                        success = await wm.adbKey(adbKeyMap[params.key.toLowerCase()] || `KEYCODE_${params.key.toUpperCase()}`, deviceId);
                     }
                     else if (tt === "ios_simulator") {
-                        const simKeyMap = {
-                            enter: "return", tab: "tab", escape: "escape", backspace: "delete",
-                            delete: "forwardDelete", up: "up-arrow", down: "down-arrow",
-                            left: "left-arrow", right: "right-arrow", space: "space",
-                            home: "home", end: "end",
-                        };
-                        const mapped = simKeyMap[params.key.toLowerCase()];
-                        if (mapped) {
-                            success = await wm.simctlKey(mapped);
+                        // Named keys (return/tab/arrows/…) go through the shared
+                        // key-name map; single printable characters are typed.
+                        if (params.key.length === 1 && !/\s/.test(params.key)) {
+                            const r = await sim.iosSimType(params.key, iosUdid);
+                            success = r.success;
+                            detail = `keystroke "${params.key}" — ${r.detail}`;
                         }
                         else {
-                            success = await wm.simctlType(params.key);
+                            const r = await sim.iosSimKey(params.key, iosUdid);
+                            success = r.success;
+                            detail = `keystroke "${params.key}" — ${r.detail}`;
                         }
+                        break;
                     }
                     else {
                         success = await wm.sendKeyByName(params.key);
@@ -3370,15 +3419,20 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     const sx = params.x || 540, sy = params.y || 1200;
                     const ey = dir === "down" ? sy - 600 : dir === "up" ? sy + 600 : sy;
                     const ex = dir === "left" ? sx + 600 : dir === "right" ? sx - 600 : sx;
-                    success = await wm.adbSwipe(sx, sy, ex, ey, 300);
+                    success = await wm.adbSwipe(sx, sy, ex, ey, 300, deviceId);
                 }
                 else if (tt === "ios_simulator") {
                     const dir = params.direction || "down";
-                    const sx = params.x || 195, sy = params.y || 420;
-                    const dist = params.amount || 300;
+                    // Defaults are device PIXELS on a screenshot — centre-ish of a
+                    // modern iPhone (~1179×2556).
+                    const sx = params.x || 590, sy = params.y || 1280;
+                    const dist = params.amount || 600;
                     const ey = dir === "down" ? sy - dist : dir === "up" ? sy + dist : sy;
                     const ex = dir === "left" ? sx + dist : dir === "right" ? sx - dist : sx;
-                    success = await wm.simctlSwipe(sx, sy, ex, ey);
+                    const r = await sim.iosSimSwipe(sx, sy, ex, ey, 300, iosUdid);
+                    success = r.success;
+                    detail = `scroll ${dir} — ${r.detail}`;
+                    break;
                 }
                 else {
                     const t = translateXY(params.x || 500, params.y || 400);
@@ -3392,7 +3446,13 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 }
                 else if (params.x != null && params.y != null && params.x2 != null && params.y2 != null) {
                     if (tt === "android_emulator") {
-                        success = await wm.adbSwipe(params.x, params.y, params.x2, params.y2, params.duration_ms || 500);
+                        success = await wm.adbSwipe(params.x, params.y, params.x2, params.y2, params.duration_ms || 500, deviceId);
+                    }
+                    else if (tt === "ios_simulator") {
+                        const r = await sim.iosSimSwipe(params.x, params.y, params.x2, params.y2, params.duration_ms || 500, iosUdid);
+                        success = r.success;
+                        detail = `drag_drop — ${r.detail}`;
+                        break;
                     }
                     else {
                         const a = translateXY(params.x, params.y);
@@ -3404,7 +3464,13 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 break;
             case "long_press":
                 if (tt === "android_emulator" && params.x != null && params.y != null) {
-                    success = await wm.adbLongPress(params.x, params.y, params.duration_ms || 1000);
+                    success = await wm.adbLongPress(params.x, params.y, params.duration_ms || 1000, deviceId);
+                }
+                else if (tt === "ios_simulator" && params.x != null && params.y != null) {
+                    const r = await sim.iosSimLongPress(params.x, params.y, params.duration_ms || 1000, iosUdid);
+                    success = r.success;
+                    detail = `long_press at (${params.x},${params.y}) — ${r.detail}`;
+                    break;
                 }
                 else if (params.x != null && params.y != null) {
                     const t = translateXY(params.x, params.y);
@@ -3416,6 +3482,21 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 if (tt === "browser" && params.selector && params.text) {
                     success = await bi.browserTypeAndSubmit(params.selector, params.text);
                 }
+                else if (tt === "android_emulator" && params.text) {
+                    success = await wm.adbType(params.text, deviceId);
+                    if (success) {
+                        await new Promise(r => setTimeout(r, 100));
+                        success = await wm.adbKey("KEYCODE_ENTER", deviceId);
+                    }
+                }
+                else if (tt === "ios_simulator" && params.text) {
+                    const typed = await sim.iosSimType(params.text, iosUdid);
+                    success = typed.success;
+                    if (success) {
+                        await new Promise(r => setTimeout(r, 100));
+                        success = (await sim.iosSimKey("return", iosUdid)).success;
+                    }
+                }
                 else if (params.text) {
                     success = await wm.typeText(params.text);
                     if (success) {
@@ -3429,6 +3510,21 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 if (tt === "browser" && params.selector && params.text) {
                     success = await bi.browserTypeAndTab(params.selector, params.text);
                 }
+                else if (tt === "android_emulator" && params.text) {
+                    success = await wm.adbType(params.text, deviceId);
+                    if (success) {
+                        await new Promise(r => setTimeout(r, 50));
+                        success = await wm.adbKey("KEYCODE_TAB", deviceId);
+                    }
+                }
+                else if (tt === "ios_simulator" && params.text) {
+                    const typed = await sim.iosSimType(params.text, iosUdid);
+                    success = typed.success;
+                    if (success) {
+                        await new Promise(r => setTimeout(r, 50));
+                        success = (await sim.iosSimKey("tab", iosUdid)).success;
+                    }
+                }
                 else if (params.text) {
                     success = await wm.typeText(params.text);
                     if (success) {
@@ -3500,10 +3596,10 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                         success = await bi.browserNavigate(params.url);
                     }
                     else if (tt === "android_emulator") {
-                        success = await wm.adbDeepLink(params.url);
+                        success = await wm.adbDeepLink(params.url, deviceId);
                     }
                     else if (tt === "ios_simulator") {
-                        success = await wm.simctlOpenUrl(params.url);
+                        success = await wm.simctlOpenUrl(params.url, iosUdid);
                     }
                     else {
                         const { navigateDesktopBrowser } = await import("./runners/window_manager.js");
@@ -3514,7 +3610,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 break;
             case "navigate_back":
                 if (tt === "android_emulator") {
-                    success = await wm.adbBackButton();
+                    success = await wm.adbBackButton(deviceId);
                 }
                 else if (tt === "browser") {
                     success = await bi.browserGoBack();
@@ -3542,7 +3638,13 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 break;
             case "swipe":
                 if (tt === "android_emulator" && params.x != null && params.y != null && params.x2 != null && params.y2 != null) {
-                    success = await wm.adbSwipe(params.x, params.y, params.x2, params.y2, params.duration_ms || 300);
+                    success = await wm.adbSwipe(params.x, params.y, params.x2, params.y2, params.duration_ms || 300, deviceId);
+                }
+                else if (tt === "ios_simulator" && params.x != null && params.y != null && params.x2 != null && params.y2 != null) {
+                    const r = await sim.iosSimSwipe(params.x, params.y, params.x2, params.y2, params.duration_ms || 300, iosUdid);
+                    success = r.success;
+                    detail = `swipe from (${params.x},${params.y}) to (${params.x2},${params.y2}) — ${r.detail}`;
+                    break;
                 }
                 else if (params.x != null && params.y != null && params.x2 != null && params.y2 != null) {
                     success = await wm.dragDrop(params.x, params.y, params.x2, params.y2, params.duration_ms || 300);
@@ -3551,49 +3653,67 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 break;
             case "back_button":
                 if (tt === "android_emulator")
-                    success = await wm.adbBackButton();
+                    success = await wm.adbBackButton(deviceId);
                 detail = "back_button";
                 break;
             case "home_button":
                 if (tt === "android_emulator")
-                    success = await wm.adbHomeButton();
+                    success = await wm.adbHomeButton(deviceId);
                 detail = "home_button";
                 break;
             case "deep_link":
                 if (params.url) {
                     if (tt === "android_emulator")
-                        success = await wm.adbDeepLink(params.url);
+                        success = await wm.adbDeepLink(params.url, deviceId);
                     else if (tt === "ios_simulator")
-                        success = await wm.simctlOpenUrl(params.url);
+                        success = await wm.simctlOpenUrl(params.url, iosUdid);
                 }
                 detail = `deep_link "${params.url}"`;
                 break;
             case "grant_permission":
                 if (tt === "android_emulator" && params.package_id && params.value) {
-                    success = await wm.adbPermission(params.package_id, params.value, params.grant !== false);
+                    success = await wm.adbPermission(params.package_id, params.value, params.grant !== false, deviceId);
+                    detail = `grant_permission "${params.value}"`;
+                }
+                else if (tt === "ios_simulator" && params.package_id && params.value) {
+                    // P1.2: simctl privacy grant|revoke <service> <bundle>
+                    success = await wm.simctlPermission(params.package_id, params.value, params.grant !== false, iosUdid);
+                    detail = `grant_permission "${params.value}" → simctl privacy ${params.grant !== false ? "grant" : "revoke"} (services: photos, location, microphone, contacts, calendar, …)`;
+                }
+                else {
+                    detail = `grant_permission "${params.value}" — needs package_id + value (permission/service name)`;
                 }
-                detail = `grant_permission "${params.value}"`;
                 break;
             case "rotate_device":
                 if (tt === "android_emulator") {
-                    success = await wm.adbRotate(params.orientation === "landscape");
+                    success = await wm.adbRotate(params.orientation === "landscape", deviceId);
+                    detail = `rotate_device ${params.orientation}`;
+                }
+                else if (tt === "ios_simulator") {
+                    // P1.2: no simctl rotation exists — drive the Simulator app's
+                    // Device menu shortcut (Cmd+Left/Right) via CGEvent.
+                    const r = await sim.iosSimRotate(params.orientation === "landscape" ? "landscape" : "portrait", iosUdid);
+                    success = r.success;
+                    detail = `rotate_device ${params.orientation} — ${r.detail}`;
+                }
+                else {
+                    detail = `rotate_device ${params.orientation}`;
                 }
-                detail = `rotate_device ${params.orientation}`;
                 break;
             case "biometric_auth":
                 if (tt === "ios_simulator") {
-                    success = await wm.simctlBiometric(params.accept !== false);
+                    success = await wm.simctlBiometric(params.accept !== false, iosUdid);
                 }
                 detail = `biometric_auth ${params.accept !== false ? "accept" : "reject"}`;
                 break;
             case "launch_app":
                 if (tt === "android_emulator" && params.package_id) {
-                    const r = await import("./runners/base.js").then(m => m.runCommand("adb", ["shell", "am", "start", "-n", params.package_id], process.cwd()));
+                    const r = await import("./runners/base.js").then(m => m.runCommand("adb", wm.adbArgs(deviceId, "shell", "am", "start", "-n", params.package_id), process.cwd()));
                     success = r.exit_code === 0;
                     detail = `launch_app "${params.package_id}"`;
                 }
                 else if (tt === "ios_simulator" && params.package_id) {
-                    success = await wm.simctlLaunch(params.package_id);
+                    success = await wm.simctlLaunch(params.package_id, iosUdid);
                     detail = `launch_app "${params.package_id}"`;
                 }
                 else if (tt === "desktop") {
@@ -3624,21 +3744,83 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 break;
             case "clear_app_data":
                 if (tt === "android_emulator" && params.package_id) {
-                    success = await wm.adbClearData(params.package_id);
+                    success = await wm.adbClearData(params.package_id, deviceId);
+                    detail = `clear_app_data "${params.package_id}"`;
+                }
+                else if (tt === "ios_simulator" && params.package_id) {
+                    // P1.2: iOS has no `pm clear` — uninstall wipes data AND the
+                    // binary, so the app must be reinstalled before the next step.
+                    success = await wm.simctlUninstall(params.package_id, iosUdid);
+                    detail = success
+                        ? `clear_app_data "${params.package_id}": app uninstalled (data wiped). REINSTALL required — re-run codeloop_run_journey or \`flutter run\`/xcodebuild install before interacting again.`
+                        : `clear_app_data "${params.package_id}": simctl uninstall failed — is the bundle id correct and the simulator booted?`;
+                }
+                else {
+                    detail = `clear_app_data "${params.package_id}"`;
                 }
-                detail = `clear_app_data "${params.package_id}"`;
                 break;
             case "mock_location":
                 if (tt === "android_emulator" && params.latitude != null && params.longitude != null) {
-                    success = await wm.adbMockLocation(params.latitude, params.longitude);
+                    // P1.3: `adb emu geo` talks to the EMULATOR CONSOLE — it can
+                    // never work on physical hardware, so fail with a usable
+                    // directive instead of a cryptic adb error.
+                    if (!wm.isEmulatorSerial(deviceId)) {
+                        success = false;
+                        detail = `mock_location is emulator-only (\`adb emu geo\` drives the emulator console; "${deviceId}" is a physical device). On hardware: enable Developer options → "Select mock location app" and use a mock-location app, or test this journey on an emulator.`;
+                        break;
+                    }
+                    success = await wm.adbMockLocation(params.latitude, params.longitude, deviceId);
+                }
+                else if (tt === "ios_simulator" && params.latitude != null && params.longitude != null) {
+                    // P1.2: simctl location <udid> set <lat>,<lon>
+                    success = await wm.simctlSetLocation(params.latitude, params.longitude, iosUdid);
                 }
                 detail = `mock_location (${params.latitude},${params.longitude})`;
                 break;
             case "simulate_network":
                 if (tt === "android_emulator" && params.value) {
-                    success = await wm.adbNetworkCondition(params.value);
+                    // P1.3: `adb emu network` is emulator-console-only as well.
+                    if (!wm.isEmulatorSerial(deviceId)) {
+                        success = false;
+                        detail = `simulate_network is emulator-only (\`adb emu network\` drives the emulator console; "${deviceId}" is a physical device). On hardware: toggle airplane mode / Wi-Fi via adb shell, or test this journey on an emulator.`;
+                        break;
+                    }
+                    success = await wm.adbNetworkCondition(params.value, deviceId);
+                    detail = `simulate_network "${params.value}"`;
+                }
+                else if (tt === "ios_simulator") {
+                    // Honest unsupported: simctl has no network conditioner; the
+                    // status_bar override only changes the INDICATOR, not traffic.
+                    detail = `simulate_network is not supported on the iOS simulator (simctl has no network conditioner). Install Apple's "Network Link Conditioner" prefpane for host-level shaping, or use action "status_bar" to fake the indicator for screenshots.`;
+                }
+                else {
+                    detail = `simulate_network "${params.value}"`;
+                }
+                break;
+            case "push_notification":
+                // P1.2: simulated APNs push — iOS simulator only.
+                if (tt === "ios_simulator" && params.package_id && params.value) {
+                    const r = await wm.simctlPush(params.package_id, params.value, iosUdid);
+                    success = r.success;
+                    detail = `push_notification → ${r.detail}`;
+                }
+                else if (tt === "android_emulator") {
+                    detail = `push_notification is iOS-simulator-only (simctl push). On Android, drive the app's own notification trigger or use \`adb shell am broadcast\` for app-specific receivers.`;
+                }
+                else {
+                    detail = `push_notification needs package_id (bundle id) + value (APNs JSON payload or plain alert text).`;
+                }
+                break;
+            case "status_bar":
+                // P1.2: simctl status_bar override for demo-clean screenshots.
+                if (tt === "ios_simulator") {
+                    const r = await wm.simctlStatusBar(params.value ?? "", iosUdid);
+                    success = r.success;
+                    detail = `status_bar → ${r.detail}`;
+                }
+                else {
+                    detail = `status_bar is iOS-simulator-only (simctl status_bar). Value: JSON or "key=value,…" with time, dataNetwork, wifiMode, wifiBars, cellularMode, cellularBars, operatorName, batteryState, batteryLevel — or "clear".`;
                 }
-                detail = `simulate_network "${params.value}"`;
                 break;
             case "maestro_flow":
                 if (params.maestro_steps) {
@@ -3648,7 +3830,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                     if ("error" in genResult) {
                         return { success: false, action, detail: genResult.error };
                     }
-                    const runResult = await mg.runGeneratedFlow(genResult.flowPath, cwd);
+                    const runResult = await mg.runGeneratedFlow(genResult.flowPath, cwd, deviceId);
                     success = runResult.success;
                     detail = `maestro_flow (${params.maestro_steps.length} steps) → ${runResult.success ? "passed" : runResult.error}`;
                 }
@@ -3820,7 +4002,7 @@ Wait 1-2 seconds between interactions so video frames capture state changes.`, {
                 }
                 break;
             default:
-                detail = `Unknown action: "${action}". Available: click, double_click, right_click, hover, type, keystroke, hotkey, scroll, drag_drop, long_press, type_and_submit, type_and_tab, fill_form, select_option, toggle, upload_file, navigate_url, navigate_back, navigate_forward, wait, swipe, back_button, home_button, deep_link, grant_permission, rotate_device, biometric_auth, launch_app, clear_app_data, mock_location, simulate_network, maestro_flow, win_ui_inspect, win_ui_automate, sequence`;
+                detail = `Unknown action: "${action}". Available: click, double_click, right_click, hover, type, keystroke, hotkey, scroll, drag_drop, long_press, type_and_submit, type_and_tab, fill_form, select_option, toggle, upload_file, navigate_url, navigate_back, navigate_forward, wait, swipe, back_button, home_button, deep_link, grant_permission, rotate_device, biometric_auth, launch_app, clear_app_data, mock_location, simulate_network, push_notification, status_bar, maestro_flow, win_ui_inspect, win_ui_automate, sequence`;
                 return { success: false, action, detail };
         }
         await trackUsage(apiKey, "interaction");