preflite 1.0.1 → 1.1.1

package/dist/mcp/cli.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { access } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createPreflightMcpServer } from "./server.js";
 import { setupLocalMcp } from "./setup.js";
 // Prevent unhandled rejections / exceptions from crashing the server mid-session
@@ -17,11 +20,12 @@ if (command === "serve") {
 }
 else if (command === "setup") {
     const projectRoot = argValue("--project-root") ?? process.cwd();
+    const runtimeSourceRoot = argValue("--runtime-source-root") ?? await findPackageRoot();
     const agentBaseUrl = argValue("--agent-base-url") ?? process.env.AGENT_BASE_URL ?? "http://127.0.0.1:18998";
     const livePort = Number(argValue("--live-port") ?? process.env.MCP_LIVE_PORT ?? "18999");
     const runtimeRoot = argValue("--runtime-root") ?? process.env.AGENT_RUNTIME_ROOT?.trim() ?? undefined;
     const installRuntime = !process.argv.includes("--no-install-runtime");
-    const result = await setupLocalMcp({ projectRoot, agentBaseUrl, livePort, runtimeRoot, installRuntime });
+    const result = await setupLocalMcp({ projectRoot, runtimeSourceRoot, agentBaseUrl, livePort, runtimeRoot, installRuntime });
     console.log(JSON.stringify({ ok: true, ...result }, null, 2));
 }
 else {
@@ -34,3 +38,25 @@ function argValue(name) {
         return undefined;
     return process.argv[idx + 1];
 }
+async function findPackageRoot() {
+    let current = dirname(fileURLToPath(import.meta.url));
+    while (true) {
+        if (await exists(join(current, "package.json"))) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            throw new Error("Could not locate the preflite package root.");
+        }
+        current = parent;
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/mcp/exploration/index.js

@@ -53,7 +53,7 @@ export function registerExplorationTools(server, ctx) {
     // ---------------------------------------------------------------------------
     server.registerTool("exploration_get_page_summary", {
         title: "Get Page Summary",
-        description: "Get a natural language summary of the current screen, including layout type (fixed single-screen / scrollable long page / multi-tab / list). Call this first when entering a new page to understand its structure before acting. Use this INSTEAD of ai_act if you just want to observe — ai_act is for changing state, not for looking around.",
+        description: "Get a natural language summary of the current screen, including layout type (fixed single-screen / scrollable long page / multi-tab / list). Call this first when entering a new page to understand its structure before acting. The summary is saved internally; if you then call ai_act, it will be used as the before-state for change comparison. Use this INSTEAD of ai_act if you just want to observe — ai_act is for changing state, not for looking around.",
         inputSchema: {
             sessionId: z.string().describe("Session ID from exploration_start"),
         },
@@ -76,7 +76,7 @@ export function registerExplorationTools(server, ctx) {
     // ---------------------------------------------------------------------------
     server.registerTool("exploration_ai_act", {
         title: "AI Act",
-        description: "Perform a high-level UI interaction described in natural language. Examples: 'Go back', 'Tap the settings icon', 'Type text in the search box'. After execution, returns a summary of the new page state including whether the action actually changed anything.\n\nIMPORTANT: Use get_page_summary FIRST to check if the page is a fixed single-screen layout. If it is, do NOT request scroll actions — there is nothing to scroll to. Use ai_act only for meaningful interactions (tap, type, swipe between tabs), not for 'look around' or 'scroll to see more'. If the post-action summary reports that the page did not change, stop acting on this page and move on.",
+        description: "Perform a high-level UI interaction described in natural language. Examples: 'Go back', 'Tap the settings icon', 'Type text in the search box'. After execution, returns a summary of the new page state including whether the action actually changed anything.\n\nIMPORTANT: Use get_page_summary FIRST to check if the page is a fixed single-screen layout. If it is, do NOT request scroll actions — there is nothing to scroll to. Use ai_act only for meaningful interactions (tap, type, swipe between tabs), not for 'look around' or 'scroll to see more'. If the post-action summary reports that the page did not change, stop acting on this page and move on.\n\nNote on before/after comparison: The AI model is stateless — each summary only sees the current screenshot. To detect changes, ai_act internally captures a before-state description (either from your prior get_page_summary call, or by grabbing a quick snapshot before acting) and passes it to the after-summary for comparison. For richer change detection, call get_page_summary before ai_act.",
         inputSchema: {
             sessionId: z.string().describe("Session ID from exploration_start"),
             intent: z.string().describe("Description of what to do"),

package/dist/mcp/exploration/sessionManager.js

@@ -24,6 +24,7 @@ async function persistMeta(state, env) {
         resourceId: state.resourceId,
         platform: state.platform,
         env,
+        appRef: state.appRef,
         createdAt: state.createdAt,
         lastActivityAt: state.lastActivityAt,
     };
@@ -50,12 +51,13 @@ async function removeMeta(id) {
 // Session lifecycle
 // ---------------------------------------------------------------------------
 /** Create a new exploration session and persist metadata to disk. */
-export function createSession(id, resourceId, platform, session, env) {
+export function createSession(id, resourceId, platform, session, env, appRef) {
     const state = {
         id,
         resourceId,
         platform,
         session,
+        appRef,
         createdAt: Date.now(),
         lastActivityAt: Date.now(),
     };
@@ -88,6 +90,7 @@ export function storeSession(id, session, meta) {
         resourceId: meta.resourceId,
         platform: meta.platform,
         session,
+        appRef: meta.appRef,
         createdAt: meta.createdAt,
         lastActivityAt: Date.now(),
     };

package/dist/mcp/exploration/tools-intelligent.js

@@ -1,4 +1,65 @@
+import http from "node:http";
+import { execSync } from "node:child_process";
 import { resolveSession } from "./tools-session.js";
+import { getSession } from "./sessionManager.js";
+async function detectIosForegroundApp(session) {
+    if (session.platform !== "ios")
+        return null;
+    const { wdaHost, wdaPort } = session.target;
+    return new Promise((resolve) => {
+        const req = http.get(`http://${wdaHost}:${wdaPort}/wda/activeAppInfo`, { timeout: 3000 }, (res) => {
+            let body = "";
+            res.on("data", (chunk) => { body += chunk; });
+            res.on("end", () => {
+                try {
+                    const data = JSON.parse(body);
+                    if (data?.value?.bundleId) {
+                        resolve({ bundleId: data.value.bundleId, name: data.value.name });
+                    }
+                    else {
+                        resolve(null);
+                    }
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on("error", () => resolve(null));
+        req.on("timeout", () => { req.destroy(); resolve(null); });
+    });
+}
+function detectAndroidForegroundApp(session) {
+    if (session.platform !== "android")
+        return null;
+    const { serial, adbHost, adbPort } = session.target;
+    try {
+        const output = execSync(`adb -H ${adbHost} -P ${adbPort} -s ${serial} shell dumpsys window 2>/dev/null | grep -E 'mCurrentFocus|mFocusedApp'`, { encoding: "utf8", timeout: 5000 });
+        // Match patterns like:
+        //   mCurrentFocus=Window{... com.example.app/...}
+        //   mFocusedApp=AppWindowToken{... token=... appPackageName=com.example.app}
+        const focusMatch = output.match(/mCurrentFocus[=:].*?\s+([^\s/}]+)/);
+        const packageMatch = output.match(/appPackageName=([^\s}]+)/);
+        if (focusMatch)
+            return { bundleId: focusMatch[1] };
+        if (packageMatch)
+            return { bundleId: packageMatch[1] };
+    }
+    catch {
+        // adb not reachable or no foreground window
+    }
+    return null;
+}
+async function detectForegroundApp(session) {
+    if (session.platform === "ios")
+        return detectIosForegroundApp(session);
+    if (session.platform === "android")
+        return detectAndroidForegroundApp(session);
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Tool handlers
+// ---------------------------------------------------------------------------
 export function getPageSummaryHandler(ctx) {
     return async (input) => {
         const session = await resolveSession(input.sessionId, ctx);
@@ -8,7 +69,20 @@ export function getPageSummaryHandler(ctx) {
             "2) 是否有弹窗、广告或遮挡物？\n" +
             "3) 整体布局类型：固定单屏 / 可滚动长页面 / 多Tab / 列表\n" +
             "先判断布局类型，再逐一描述每个区域的内容。");
-        return { summary };
+        const state = getSession(input.sessionId);
+        const foregroundApp = await detectForegroundApp(session);
+        const appRef = state.appRef;
+        // Save for aiActHandler's before/after comparison
+        state.lastPageSummary = summary;
+        return {
+            summary,
+            app: {
+                platform: session.platform,
+                resourceId: state.resourceId,
+                ...(appRef ? { appRef } : {}),
+                ...(foregroundApp ? { foregroundApp } : {}),
+            },
+        };
     };
 }
 export function askAboutScreenHandler(ctx) {
@@ -21,13 +95,30 @@ export function askAboutScreenHandler(ctx) {
 export function aiActHandler(ctx) {
     return async (input) => {
         const session = await resolveSession(input.sessionId, ctx);
+        const state = getSession(input.sessionId);
+        // Before-state: reuse from get_page_summary if available, otherwise grab a quick one
+        const beforeSummary = state.lastPageSummary ?? await session.agent.aiAsk("用一句话描述当前页面的最关键特征：什么类型的页面（列表/表单/弹窗/首页等），最显著的内容是什么。");
         await session.agent.aiAct(input.intent);
-        const afterSummary = await session.agent.aiAsk("刚刚的操作已完成。请判断：\n" +
-            "1) 操作是否改变了页面内容？（新页面、弹窗、滚动到底部、输入框获得焦点等）\n" +
-            "2) 如果操作是滑动页面，是否滑到了底部或页面内容没有变化？\n" +
+        const afterSummary = await session.agent.aiAsk(`操作前的页面：${beforeSummary}\n` +
+            `执行的操作：${input.intent}\n` +
+            "请判断操作结果：\n" +
+            "1) 页面内容是否发生了变化？（进入了新页面、弹出弹窗、滚动到底部、输入框获得焦点等）\n" +
+            "2) 如果操作是滑动，是否已到达底部或页面没有变化？\n" +
             "3) 当前页面布局类型是固定单屏还是可滚动长页面？\n" +
-            "4) 当前页面出现的最关键变化是什么？\n" +
-            "如果你发现操作没有产生任何实际变化（比如反复滑动但没有新内容），请明确指出\"页面没有变化\"。");
-        return { ok: true, summary: afterSummary };
+            "4) 当前页面最关键的变化是什么？\n" +
+            "如果操作没有产生任何实际变化（比如反复滑动但没有新内容），请明确指出\"页面没有变化\"。");
+        // Update for next aiAct call
+        state.lastPageSummary = afterSummary;
+        const foregroundApp = await detectForegroundApp(session);
+        return {
+            ok: true,
+            summary: afterSummary,
+            app: {
+                platform: session.platform,
+                resourceId: state.resourceId,
+                ...(state.appRef ? { appRef: state.appRef } : {}),
+                ...(foregroundApp ? { foregroundApp } : {}),
+            },
+        };
     };
 }

package/dist/mcp/exploration/tools-session.js

@@ -241,25 +241,26 @@ export function getExplorationStartHandler(ctx) {
         }
         const session = await createMidsceneSessionFromResourceId(resourceId, runtimeEnv);
         const sessionId = generateSessionId();
-        createSession(sessionId, resourceId, platform, session, runtimeEnv);
+        const appRef = input.appRef;
+        createSession(sessionId, resourceId, platform, session, runtimeEnv, appRef);
         try {
-            if (input.appRef) {
-                if (isInstallableRef(input.appRef)) {
-                    await ctx.client.installApp(resourceId, input.appRef);
+            if (appRef) {
+                if (isInstallableRef(appRef)) {
+                    await ctx.client.installApp(resourceId, appRef);
                     return {
                         sessionId,
                         device: { platform, resourceId },
-                        note: `App installed from ${input.appRef}. Use exploration_ai_act to launch it.`,
+                        note: `App installed from ${appRef}. Use exploration_ai_act to launch it.`,
                     };
                 }
-                await session.agent.launch(input.appRef);
+                await session.agent.launch(appRef);
             }
         }
         catch (err) {
             await destroySessionById(sessionId).catch(() => { });
             throw err;
         }
-        return { sessionId, device: { platform, resourceId } };
+        return { sessionId, device: { platform, resourceId }, appRef: appRef ?? undefined };
     };
 }
 export function getExplorationEndHandler() {

package/dist/mcp/runtimeInstall.js

@@ -1,28 +1,62 @@
 import { spawn } from "node:child_process";
-import { cp, mkdir, rm, writeFile } from "node:fs/promises";
+import { access, cp, mkdir, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { basename, dirname, join, sep } from "node:path";
 export async function installLocalRuntime(options) {
     const runtimeRoot = options.runtimeRoot ?? join(homedir(), ".preflight", "runtime");
-    await runNpm(["run", "build"], options.projectRoot);
+    const sourceRoot = options.sourceRoot ?? options.projectRoot;
+    const targetProjectRoot = options.targetProjectRoot ?? options.projectRoot ?? process.cwd();
+    const npmRunner = options.runNpm ?? runNpm;
+    if (!sourceRoot) {
+        throw new Error("Preflight runtime source root is required.");
+    }
+    if (await exists(join(sourceRoot, "tsconfig.build.json"))) {
+        await npmRunner(["run", "build"], sourceRoot);
+    }
     await rm(runtimeRoot, { recursive: true, force: true, maxRetries: 5, retryDelay: 500 });
     await mkdir(runtimeRoot, { recursive: true });
     await mkdir(join(runtimeRoot, "node", "bin"), { recursive: true });
     await cp(process.execPath, join(runtimeRoot, "node", "bin", "node"));
-    await cp(join(options.projectRoot, "dist"), join(runtimeRoot, "dist"), { recursive: true });
-    await cp(join(options.projectRoot, "package.json"), join(runtimeRoot, "package.json"));
-    await cp(join(options.projectRoot, "package-lock.json"), join(runtimeRoot, "package-lock.json"));
-    await cp(join(options.projectRoot, "scripts"), join(runtimeRoot, "scripts"), { recursive: true }).catch(() => { });
+    await cp(join(sourceRoot, "dist"), join(runtimeRoot, "dist"), { recursive: true });
+    await cp(join(sourceRoot, "package.json"), join(runtimeRoot, "package.json"));
+    await cp(join(sourceRoot, "package-lock.json"), join(runtimeRoot, "package-lock.json")).catch(() => { });
+    await cp(join(sourceRoot, "scripts"), join(runtimeRoot, "scripts"), { recursive: true }).catch(() => { });
     await mkdir(join(runtimeRoot, "docs"), { recursive: true });
-    await cp(join(options.projectRoot, "docs", "visual-flow-ir-llm.md"), join(runtimeRoot, "docs", "visual-flow-ir-llm.md"));
-    await runNpm(["ci", "--omit=dev"], runtimeRoot);
-    await writeFile(join(runtimeRoot, "preflight-runtime.json"), `${JSON.stringify({ installedAt: new Date().toISOString(), source: options.projectRoot }, null, 2)}\n`, "utf8");
+    await cp(join(sourceRoot, "docs", "visual-flow-ir-llm.md"), join(runtimeRoot, "docs", "visual-flow-ir-llm.md"));
+    const reusedDependencies = await reuseInstalledDependencies(sourceRoot, runtimeRoot);
+    if (!reusedDependencies) {
+        await npmRunner(await exists(join(runtimeRoot, "package-lock.json")) ? ["ci", "--omit=dev"] : ["install", "--omit=dev"], runtimeRoot);
+    }
+    await writeFile(join(runtimeRoot, "preflight-runtime.json"), `${JSON.stringify({ installedAt: new Date().toISOString(), source: sourceRoot, targetProjectRoot }, null, 2)}\n`, "utf8");
     return {
         runtimeRoot,
         nodeBin: join(runtimeRoot, "node", "bin", "node"),
         mcpEntry: join(runtimeRoot, "dist", "mcp", "cli.js"),
     };
 }
+async function reuseInstalledDependencies(sourceRoot, runtimeRoot) {
+    const packageNodeModules = join(sourceRoot, "node_modules");
+    if (await exists(packageNodeModules)) {
+        await cp(packageNodeModules, join(runtimeRoot, "node_modules"), { recursive: true });
+        return true;
+    }
+    const parentNodeModules = dirname(sourceRoot);
+    const isNpxPackage = basename(parentNodeModules) === "node_modules" && parentNodeModules.includes(`${sep}_npx${sep}`);
+    if (isNpxPackage) {
+        await cp(parentNodeModules, join(runtimeRoot, "node_modules"), { recursive: true });
+        return true;
+    }
+    return false;
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function run(command, args, cwd) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, { cwd, stdio: "inherit" });

package/dist/mcp/setup.js

@@ -7,7 +7,11 @@ export async function setupLocalMcp(options) {
     const livePort = options.livePort ?? 18999;
     const shouldInstallRuntime = options.installRuntime ?? true;
     const installedRuntime = shouldInstallRuntime
-        ? await installLocalRuntime({ projectRoot: options.projectRoot, runtimeRoot: options.runtimeRoot })
+        ? await installLocalRuntime({
+            sourceRoot: options.runtimeSourceRoot ?? options.projectRoot,
+            targetProjectRoot: options.projectRoot,
+            runtimeRoot: options.runtimeRoot,
+        })
         : undefined;
     const runtimeRoot = installedRuntime?.runtimeRoot ?? options.runtimeRoot ?? process.env.AGENT_RUNTIME_ROOT?.trim();
     const isRuntime = !!runtimeRoot;

package/docs/visual-flow-ir-llm.md

@@ -0,0 +1,153 @@
+# 可视化编排 IR（供模型生成 JSON）
+
+本文档供 **对话编排 / 自动生成 `visualFlow`** 的系统提示使用：只描述 **JSON 形状、字段含义与校验约束**，不含代码生成、HTTP 接口等平台实现细节。人类可读的平台语义、codegen 对照与落库说明见 `**VISUAL_FLOW_IR.md`**；字段以 `**backend/src/contexts/visual-flow/types.ts`**、校验以 `**validate.ts`** 为准。
+
+---
+
+## 1. 根对象 `VisualFlowDocument`
+
+
+| 字段           | 必填  | 说明                                   |
+| ------------ | --- | ------------------------------------ |
+| `version`    | 是   | 固定为数字 `1`，其它值保存失败。                   |
+| `scriptVars` | 否   | 执行前由人填的变量声明数组；步骤文案里用 `{{变量名}}` 引用。   |
+| `steps`      | 是   | 顶层步骤数组，按顺序执行；**展开后总条数 ≤ 500**（含子步骤）。 |
+
+
+### 1.1 `scriptVars[]` 每项
+
+
+| 字段             | 必填  | 选填 / 备注                            |
+| -------------- | --- | ---------------------------------- |
+| `name`         | 是   | —                                  |
+| `description`  | 否   | 给人看的说明。                            |
+| `defaultValue` | 否   | 默认填值，字符串。                          |
+| `scope`        | 否   | `global`、`local` 或 `temp`；缺省按平台约定。 |
+
+
+---
+
+## 2. 步骤类型与设计原则
+
+### 核心原则：所有 UI 交互都使用 `aiAct`
+
+- `aiAct` 是**唯一**的 UI 交互步骤类型。
+- 一个 `aiAct` 覆盖**一个完整的用户意图**，由视觉模型自行规划具体的点击、长按、滑动、输入等动作。
+- 例如，"长按第一个订单，在弹出菜单中选择「删除」，如果有确认弹窗则确认删除"——这是一个完整的意图，应当用**一个** `aiAct` 表达。
+
+### 其他步骤类型
+
+除 `aiAct` 外的步骤类型分为以下几类，各自有明确的非交互用途：
+
+| 类别 | 类型 | 说明 |
+|------|------|------|
+| **应用管理** | `launch` / `closeApp` / `installApp` / `uninstallApp` | 启动、关闭、安装、卸载应用 |
+| **等待** | `sleep` | 固定延时等待（页面跳转、动画、列表更新等） |
+| **断言** | `assert` | 视觉断言，验证 UI 状态是否符合预期 |
+| **上下文** | `setAIActContext` | 设置后续 `aiAct` 的突发情况处理策略（如权限弹窗、营销弹窗） |
+| **报告** | `recordToReport` | 向测试报告写入标题和内容 |
+| **变量** | `setVar` / `assignVar` / `transformVar` | 从屏幕读取数据、赋值或转换变量 |
+| **流程控制** | `if` / `ifDeviceType` / `whileLoop` / `forLoop` | 条件判断、按设备类型分支、循环 |
+| **脚本调用** | `callScript` | 调用其他测试用例 |
+
+### 每条步骤的公共规则
+
+- 每个步骤对象 **必须有** `type`（字符串）。
+- `**launch` / `closeApp` / `uninstallApp`**：使用包名类字段（`packageName` 或 `bundleId`）表达应用目标。
+- `aiAct` / `assert` / `setAIActContext`：用 `prompt` 写 **短而可执行** 的界面描述（可见文案、区域）。
+- 突发情况处理使用 `setAIActContext`：例如 `"遇到权限弹窗请同意，营销弹窗请拒绝"`。该上下文会带给后续 act 操作，由视觉模型自行处理弹窗等临时干扰。
+- `prompt` 保持简洁明确，只写必要信息。**`assert` 的 `prompt` 只需写明判断逻辑**，已有变量用 `{{}}` 插值即可，不要重复上下文。好：`"屏幕上的登录状态文本是{{expectedStatus}}"`；差：一段描述"看当前屏幕……由于……说明……"的长句。
+- 页面跳转、启动、刷新、动画结束、列表更新等"页面稳定"场景，使用 `sleep` 固定等待（如 2000～5000ms）。
+- `assert` 放在关键校验点，通常是本次改动点或必要回归点；普通步骤执行失败会自然阻塞流程。
+- `**if` / `ifDeviceType`**：`thenSteps` 非空数组；`**elseSteps`** 为 **选填**：可整段省略、或 `[]`、或 `null`（均表示「无 else 分支」）；若写出 `elseSteps` 且为非空数组，则其中为正常子步骤。
+- `**whileLoop` / `forLoop`**：`bodySteps` **非空数组**（无选填分支数组名）。
+- **同一条「线性执行路径」上**：`setVar` 的 `name` **不得重复**（含分支内继承规则，与校验一致）。
+- `**setVar.name` / `assignVar.name` / `transformVar.name`**：支持 Unicode 字母（含中文）/数字/`_`/`$`，且首字符为非数字；须匹配 `^[$_\\p{L}][\\p{L}\\p{N}_$]*$`（`/u` 语义），长度 1～64，并避开运行时保留名（如 `agent`、`page`、`console`、`process`、`sleep` 等，详见校验）。
+- 字符串字段中引用已声明变量时，**必须**使用 `**{{变量名}}`**、`{{变量名[0]}}`、`{{变量名.1}}`、`{{变量名.length}}` 等插值形式；其中 `.length` 用于读取数组长度（非数组按 `0` 处理）。
+- 已声明变量在字符串字段中统一使用插值形式；例如已声明 `timeBefore`、`timeAfter` 时，写成 `"{{timeBefore}}和{{timeAfter}}不同"`。
+
+---
+
+## 3. 步骤类型：必填、选填与约束
+
+列 **选填**：除「—」外，写出可出现的字段名；未列出者表示不宜随意加未知键（以 `types.ts` 为准）。
+
+
+| `type`                                                           | 必填字段                                            | 选填字段                                                      | 说明与取值约束                                                                                                                                                |
+| ---------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `launch`                                                         | `packageName`                                   | —                                                         | Android 包名 / iOS bundle id / 鸿蒙 bundle name。                                                                                                           |
+| `installApp`                                                     | `appRef`                                        | —                                                         | 本地路径、`file://` 或 `http(s)` 安装包地址。                                                                                                                      |
+| `uninstallApp`                                                   | `bundleId`                                      | —                                                         | 要卸载的应用标识。                                                                                                                                              |
+| `closeApp`                                                       | `packageName`                                   | —                                                         | 关闭正在运行的应用。                                                                                                                                             |
+| `setAIActContext`                                                | `prompt`                                        | —                                                         | 设置后续 aiAct 操作的上下文，适合声明权限弹窗、营销弹窗、升级提示等突发情况处理策略。                                                                                                   |
+| `recordToReport`                                                 | `title`, `content`                              | —                                                         | 二者均为字符串，**允许空串**；有长度上限（校验）。                                                                                                                            |
+| `assert`                                                         | `prompt`                                        | —                                                         | 断言命题。                                                                                                                                                  |
+| `sleep`                                                          | `ms`                                            | —                                                         | 整数 **0～3600000**（毫秒）；页面稳定、动画结束、跳转缓冲使用本步骤。                                                                                                             |
+| `aiAct`                                                          | `prompt`                                        | —                                                         | **唯一的 UI 交互步骤类型**。描述完整的用户意图、关键约束和完成条件，让视觉模型自行规划具体操作。                                                                                                 |
+| `if`                                                             | `conditionPrompt`, `thenSteps`                  | `**elseSteps`**                                           | 条件为真执行 `thenSteps`；无 else 则省略 `elseSteps` / `[]` / `null`。                                                                                             |
+| `ifDeviceType`                                                   | `interfaceType`, `thenSteps`                    | `**elseSteps`**                                           | `interfaceType` 仅 `android`、`ios`、`harmony`；无 else 同上。                                                                                                 |
+| `whileLoop`                                                      | `conditionPrompt`, `maxIterations`, `bodySteps` | —                                                         | `maxIterations`：1～1000 整数。                                                                                                                             |
+| `forLoop`                                                        | `count`, `bodySteps`                            | —                                                         | `count`：1～500 整数。                                                                                                                                      |
+| `setVar`                                                         | `name`, `method`, `expression`                  | —                                                         | `method` 仅 `aiQuery`、`aiAsk`、`aiBoolean`、`aiNumber`、`aiString`。`aiQuery` 的 `expression` 可为自然语言或整段 JSON 抽取需求；其余 method 的 `expression` 为对应 API 的 prompt。 |
+| `assignVar`                                                      | `name`, `value`                                 | —                                                         | 字面值或带 `{{}}` 的模板；**不用**于从屏读数（读屏用 `setVar`）。                                                                                                            |
+| `transformVar`                                                   | `name`, `rule`                                  | `source`、`start`、`end`、`jsonPath`、`pattern`、`replacement` | `rule`：`onlyNumber`、`cut`、`jsonPath`、`replace`、`handleAmount`；按规则选用上述选填字段。                                                                             |
+| `callScript`                                                     | `targetTestCaseId`, `scopeId`, `varBindings`    | `**targetName`**                                          | `targetTestCaseId`：24 位 hex；`scopeId`：`sub` + 12 位小写 hex；`varBindings` 可为 `{}`；`targetName` 仅展示用。                                                      |
+
+
+步骤 `type` 使用上表枚举；生成后先调用 `validate_visual_flow`，按返回信息修正结构。
+
+---
+
+## 4. 易错校验（生成后自查）
+
+- `version !== 1` → 失败。
+- `if` / `ifDeviceType` 的 `thenSteps` 为空，或 `whileLoop` / `forLoop` 的 `bodySteps` 为空 → 失败。
+- `sleep.ms`、`whileLoop.maxIterations`、`forLoop.count` 超出上表范围 → 失败。
+- `callScript.targetTestCaseId` 非 24 位 hex，或 `scopeId` 不符合 `sub`+12hex → 失败。
+- 同一路径重复 `setVar.name` → 失败。
+- 声明过的变量在 `prompt` / `value` / `expression` / `varBindings` 等字符串字段中使用 `{{}}` 插值。
+- 页面稳定等待使用 `sleep`；关键结果检查使用 `assert`。
+- `assert` 聚焦关键校验点，通常是本次改动点或必要回归点。
+- **所有 UI 交互必须使用 `aiAct`**。
+
+---
+
+## 5. 完整示例（含 `scriptVars`、条件分支、`assert`）
+
+下列为**可直接通过结构校验**的示意：请把包名、文案改成目标应用真实情况。
+
+```json
+{
+  "version": 1,
+  "scriptVars": [
+    { "name": "phone", "description": "登录手机号", "defaultValue": "" }
+  ],
+  "steps": [
+    { "type": "launch", "packageName": "com.example.app" },
+    { "type": "setAIActContext", "prompt": "遇到权限弹窗请同意，营销弹窗请拒绝" },
+    { "type": "sleep", "ms": 3000 },
+    {
+      "type": "if",
+      "conditionPrompt": "当前是否已在登录页（能看到手机号输入框）",
+      "thenSteps": [
+        {
+          "type": "aiAct",
+          "prompt": "在手机号输入框中输入{{phone}}，然后点击「获取验证码」按钮"
+        },
+        { "type": "sleep", "ms": 3000 },
+        { "type": "assert", "prompt": "出现短信验证码输入框或倒计时提示" }
+      ],
+      "elseSteps": [
+        { "type": "aiAct", "prompt": "点击底部或顶部的「我的」或个人中心入口" }
+      ]
+    },
+    { "type": "assert", "prompt": "页面显示已登录态（头像、昵称或「退出登录」其一）" },
+    { "type": "sleep", "ms": 500 },
+    { "type": "closeApp", "packageName": "com.example.app" }
+  ]
+}
+```
+
+---
+
+**维护约定**：新增或变更步骤类型时，须同步 `**types.ts`** / `**validate.ts`** / `**VISUAL_FLOW_IR_LLM.md`** / `**VISUAL_FLOW_IR.md`**，保持模型提示与保存校验一致。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preflite",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Preflight — Local mobile AI testing via MCP. AI-assisted testing on real Android/iOS/Harmony devices.",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,6 +9,8 @@
   },
   "files": [
     "dist/",
+    "docs/visual-flow-ir-llm.md",
+    "scripts/",
     "README.md",
     "LICENSE"
   ],

package/scripts/hdc-bridge.sh

@@ -0,0 +1,4 @@
+# hdc bridge
+# Usage: eval "$(hdc-bridge.sh)" or source it
+# Should not be executed directly
+echo "hdc() { command hdc -s \"${HDC_S:-127.0.0.1:17815}\" \"\$@\"; }"

package/scripts/nvm-use-repo.sh

@@ -0,0 +1,31 @@
+# shellcheck shell=bash
+# Sourced by run-midscene-task.sh: load nvm and run `nvm use` in the repo root.
+# No side effects: failure does not exit; caller decides whether to error on insufficient Node version.
+
+_try_source_nvm() {
+  if [[ -n "${NVM_DIR:-}" && -s "${NVM_DIR}/nvm.sh" ]]; then
+    # shellcheck disable=SC1090
+    source "${NVM_DIR}/nvm.sh"
+    return 0
+  fi
+  local d
+  for d in "${HOME}/.nvm" "/usr/local/opt/nvm"; do
+    if [[ -s "${d}/nvm.sh" ]]; then
+      export NVM_DIR="${d}"
+      # shellcheck disable=SC1090
+      source "${d}/nvm.sh"
+      return 0
+    fi
+  done
+  return 1
+}
+
+_nvm_use_repo() {
+  local repo_root="${1:?repo root}"
+  _try_source_nvm || return 1
+  local dsave="${PWD}"
+  cd "${repo_root}" || return 1
+  nvm use >/dev/null 2>&1 || true
+  cd "${dsave}" || true
+  return 0
+}

package/scripts/run-midscene-task.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Midscene subprocess entry: prefer Node/tsx from runtime package; fall back to nvm + npx in dev mode.
+set -euo pipefail
+
+TASK_SCRIPT="${1:?usage: run-midscene-task.sh <path-to-task-script.ts>}"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+# shellcheck disable=SC1091
+source "${SCRIPT_DIR}/nvm-use-repo.sh"
+
+cd "${REPO_ROOT}"
+
+NODE_BIN="${PREFLIGHT_RUNTIME_NODE:-}"
+if [[ -z "${NODE_BIN}" && -x "${REPO_ROOT}/node/bin/node" ]]; then
+  NODE_BIN="${REPO_ROOT}/node/bin/node"
+fi
+if [[ -z "${NODE_BIN}" ]]; then
+  _nvm_use_repo "${REPO_ROOT}" || true
+  NODE_BIN="$(command -v node || true)"
+fi
+if [[ -z "${NODE_BIN}" || ! -x "${NODE_BIN}" ]]; then
+  echo "[run-midscene-task] Node not found. Install Node 20+ or use the runtime package's node/bin/node." >&2
+  exit 1
+fi
+
+if [[ -d "${REPO_ROOT}/node/bin" ]]; then
+  export PATH="${REPO_ROOT}/node/bin:${PATH}"
+fi
+
+major="$("${NODE_BIN}" -p "parseInt(process.versions.node,10)" 2>/dev/null || echo 0)"
+if [[ "${major}" -lt 20 ]]; then
+  echo "[run-midscene-task] Node >= 20 required (current: $("${NODE_BIN}" -v 2>/dev/null || echo unknown))." >&2
+  echo "[run-midscene-task] Install Node 20+ or set PREFLIGHT_RUNTIME_NODE or MIDSCENE_RUN_COMMAND to override." >&2
+  exit 1
+fi
+
+TSX_CLI="${REPO_ROOT}/node_modules/tsx/dist/cli.mjs"
+if [[ -f "${TSX_CLI}" ]]; then
+  exec "${NODE_BIN}" "${TSX_CLI}" "${TASK_SCRIPT}"
+fi
+
+exec npx tsx "${TASK_SCRIPT}"

package/scripts/start-ios-wda.sh

@@ -0,0 +1,328 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+UDID="${1:-}"
+WDA_PORT="${2:-}"
+
+EXIT_MISSING_ARGS=1
+EXIT_DEVICE_NOT_CONNECTED=2
+EXIT_WDA_START_FAILED=3
+EXIT_DEPENDENCY_MISSING=4
+
+if [[ -z "${UDID}" || -z "${WDA_PORT}" ]]; then
+  echo "[start-ios-wda] usage: $0 <UDID> <WDA_PORT>"
+  exit "${EXIT_MISSING_ARGS}"
+fi
+
+if ! [[ "${WDA_PORT}" =~ ^[0-9]+$ ]]; then
+  echo "[start-ios-wda] invalid WDA_PORT: ${WDA_PORT}"
+  exit "${EXIT_MISSING_ARGS}"
+fi
+
+# Local MJPEG port: matches Agent / Midscene convention, default = WDA local port + 1000 → device:9100 (WDA video stream)
+MJPEG_LOCAL_PORT=$((WDA_PORT + 1000))
+if [[ "${MJPEG_LOCAL_PORT}" -gt 65535 ]]; then
+  echo "[start-ios-wda] WDA_PORT+1000 exceeds max port: ${WDA_PORT} -> ${MJPEG_LOCAL_PORT}"
+  exit "${EXIT_MISSING_ARGS}"
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+AGENT_HOME="${AGENT_HOME:-${HOME}/.preflight}"
+
+WDA_ROOT="${WDA_PROJECT_ROOT:-${REPO_ROOT}/third_party/WebDriverAgent}"
+WDA_PROJECT="${WDA_PROJECT_PATH:-${WDA_ROOT}/WebDriverAgent.xcodeproj}"
+WDA_SCHEME="${WDA_SCHEME:-WebDriverAgentRunner}"
+WDA_DERIVED_DATA="${WDA_DERIVED_DATA:-${AGENT_HOME}/state/wda-derived-data/${UDID}}"
+
+WDA_LOG_DIR="${WDA_LOG_DIR:-${AGENT_HOME}/logs/wda}"
+WDA_LOG_FILE="${WDA_LOG_DIR}/wda-${UDID}-${WDA_PORT}.log"
+IPROXY_LOG_FILE="${WDA_LOG_DIR}/iproxy-${UDID}-${WDA_PORT}.log"
+
+WDA_STATUS_URL="http://127.0.0.1:${WDA_PORT}/status"
+
+mkdir -p "${WDA_LOG_DIR}" "${WDA_DERIVED_DATA}"
+
+# Lock file to prevent concurrent script instances (the watchdog polls every 5s,
+# but build-for-testing can take minutes). Uses PID-based stale detection.
+BUILD_LOCK_DIR="${AGENT_HOME}/state/wda-locks"
+mkdir -p "${BUILD_LOCK_DIR}"
+BUILD_LOCK="${BUILD_LOCK_DIR}/wda-start-${UDID}-${WDA_PORT}.pid"
+
+try_acquire_lock() {
+  if [[ -f "${BUILD_LOCK}" ]]; then
+    local old_pid
+    old_pid=$(cat "${BUILD_LOCK}" 2>/dev/null)
+    if [[ -n "${old_pid}" ]] && kill -0 "${old_pid}" 2>/dev/null; then
+      echo "[start-ios-wda] another instance already running (pid=${old_pid}), skipping"
+      return 1
+    fi
+    echo "[start-ios-wda] removing stale lock from pid=${old_pid}"
+    rm -f "${BUILD_LOCK}"
+  fi
+  echo "$$" > "${BUILD_LOCK}"
+  trap 'rm -f "${BUILD_LOCK}"' EXIT
+  return 0
+}
+
+if [[ ! -d "${WDA_PROJECT}" ]]; then
+  echo "[start-ios-wda] WDA project not found: ${WDA_PROJECT}"
+  echo "[start-ios-wda] run: npm run clone:wda"
+  exit 1
+fi
+
+for cmd in xcrun curl iproxy xcodebuild; do
+  if ! command -v "${cmd}" >/dev/null 2>&1; then
+    echo "[start-ios-wda] missing dependency: ${cmd}"
+    if [[ "${cmd}" == "iproxy" ]]; then
+      echo "[start-ios-wda] install it with: brew install libimobiledevice"
+    fi
+    exit "${EXIT_DEPENDENCY_MISSING}"
+  fi
+done
+
+device_is_online() {
+  # Check physical devices first (== Devices ==)
+  xcrun xctrace list devices 2>/dev/null | awk '
+    /^== Devices ==/ { in_devices=1; next }
+    /^== / { in_devices=0 }
+    in_devices { print }
+  ' | grep -F "(${UDID})" >/dev/null 2>&1 && return 0
+
+  # Then check booted simulators
+  xcrun simctl list devices booted 2>/dev/null | grep -F "(${UDID})" >/dev/null 2>&1
+}
+
+device_is_simulator() {
+  xcrun simctl list devices booted 2>/dev/null | grep -F "(${UDID})" >/dev/null 2>&1
+}
+
+wda_is_healthy() {
+  curl -fsS --max-time 2 "${WDA_STATUS_URL}" >/dev/null 2>&1
+}
+
+kill_iproxy_for_udid() {
+  pkill -f "iproxy.*-u[[:space:]]+${UDID}" >/dev/null 2>&1 || true
+  pkill -f "iproxy.*${UDID}" >/dev/null 2>&1 || true
+}
+
+kill_xcodebuild_for_udid() {
+  pkill -f "xcodebuild.*id=${UDID}" >/dev/null 2>&1 || true
+}
+
+xcodebuild_is_running_for_udid() {
+  pgrep -f "xcodebuild.*id=${UDID}" >/dev/null 2>&1
+}
+
+start_iproxy() {
+  if device_is_simulator; then
+    echo "[start-ios-wda] simulator mode, WDA binds directly to port ${WDA_PORT} (USE_PORT) — no forwarding needed"
+    return 0
+  fi
+  echo "[start-ios-wda] starting iproxy: 127.0.0.1:${WDA_PORT}->device:8100, 127.0.0.1:${MJPEG_LOCAL_PORT}->device:9100 (MJPEG)"
+  nohup iproxy -u "${UDID}" "${WDA_PORT}:8100" "${MJPEG_LOCAL_PORT}:9100" >>"${IPROXY_LOG_FILE}" 2>&1 &
+}
+
+# Modify .xctestrun plist to inject environment variables into the test process.
+# This is the only reliable way to set env vars (USE_PORT, MJPEG_SERVER_PORT)
+# for simulator test runners, because testmanagerd does NOT forward macOS env vars
+# into the simulator's iOS runtime.
+# Find the test-bundle key (top-level key excluding __xctestrun_metadata__) in xctestrun.
+# Recent Xcode uses flat <bundleName> as key instead of TestConfigurations array.
+get_xctestrun_bundle_key() {
+  local xctestrun="$1"
+  plutil -p "${xctestrun}" 2>/dev/null | grep '^  "' | grep -v '__xctestrun_metadata__' | head -1 | sed 's/^  "\(.*\)" =>.*/\1/'
+}
+
+inject_env_vars_into_xctestrun() {
+  local xctestrun="$1"
+  local port="$2"
+  local mjpeg_port="$3"
+  local bundle_key
+
+  bundle_key=$(get_xctestrun_bundle_key "${xctestrun}")
+  if [[ -z "${bundle_key}" ]]; then
+    echo "[start-ios-wda] could not determine bundle key in xctestrun"
+    return 1
+  fi
+  echo "[start-ios-wda] xctestrun bundle key: ${bundle_key}"
+
+  # Method 1: Inject USE_PORT / MJPEG_SERVER_PORT into EnvironmentVariables dict
+  # This is consumed by FBConfiguration's NSProcessInfo.processInfo.environment check.
+  local env_path="${bundle_key}.EnvironmentVariables.USE_PORT"
+  echo "[start-ios-wda] injecting USE_PORT=${port} at ${env_path}"
+  if plutil -insert "${env_path}" -string "${port}" "${xctestrun}" 2>/dev/null; then
+    echo "[start-ios-wda] injected USE_PORT"
+  else
+    # Key may already exist — replace instead
+    plutil -replace "${env_path}" -string "${port}" "${xctestrun}" 2>/dev/null && \
+      echo "[start-ios-wda] replaced USE_PORT" || \
+      echo "[start-ios-wda] WARNING: could not set USE_PORT"
+  fi
+
+  plutil -insert "${bundle_key}.EnvironmentVariables.MJPEG_SERVER_PORT" \
+    -string "${mjpeg_port}" "${xctestrun}" 2>/dev/null || \
+  plutil -replace "${bundle_key}.EnvironmentVariables.MJPEG_SERVER_PORT" \
+    -string "${mjpeg_port}" "${xctestrun}" 2>/dev/null || true
+
+  # Method 2: Inject --port into CommandLineArguments (HIGHEST priority in FBConfiguration:
+  # bindingPortRangeFromArguments reads NSProcessInfo.processInfo.arguments for "--port").
+  local cla_path="${bundle_key}.CommandLineArguments"
+  echo "[start-ios-wda] injecting --port ${port} into CommandLineArguments"
+  if plutil -replace "${cla_path}" \
+    -json "[\"--port\",\"${port}\",\"--mjpeg-server-port\",\"${mjpeg_port}\"]" \
+    "${xctestrun}" 2>/dev/null; then
+    echo "[start-ios-wda] injected --port via CommandLineArguments"
+  else
+    echo "[start-ios-wda] WARNING: could not set CommandLineArguments"
+  fi
+}
+
+start_xcodebuild() {
+  echo "[start-ios-wda] starting xcodebuild for WDA"
+
+  if device_is_simulator; then
+    echo "[start-ios-wda] simulator mode: using build-for-testing + xctestrun approach"
+    echo "[start-ios-wda] (macOS env vars do NOT propagate into simulator test processes)"
+
+    # Step 1: Build the test bundle and generate .xctestrun (blocking)
+    xcodebuild build-for-testing \
+      -project "${WDA_PROJECT}" \
+      -scheme "${WDA_SCHEME}" \
+      -destination "id=${UDID}" \
+      -derivedDataPath "${WDA_DERIVED_DATA}" \
+      >>"${WDA_LOG_FILE}" 2>&1
+
+    BUILD_RESULT=$?
+    if [[ "${BUILD_RESULT}" -ne 0 ]]; then
+      echo "[start-ios-wda] build-for-testing failed (exit=${BUILD_RESULT})"
+      echo "[start-ios-wda] check the log for details: ${WDA_LOG_FILE}"
+      return 1
+    fi
+
+    # Step 2: Find the .xctestrun file in derived data
+    XCTESTRUN=$(find "${WDA_DERIVED_DATA}" -name "*.xctestrun" -print -quit 2>/dev/null)
+    if [[ -z "${XCTESTRUN}" ]]; then
+      echo "[start-ios-wda] .xctestrun not found in ${WDA_DERIVED_DATA}"
+      echo "[start-ios-wda] falling back to env-var approach (may not work)"
+      USE_PORT="${WDA_PORT}" MJPEG_SERVER_PORT="${MJPEG_LOCAL_PORT}" \
+      nohup xcodebuild \
+        -project "${WDA_PROJECT}" \
+        -scheme "${WDA_SCHEME}" \
+        -destination "id=${UDID}" \
+        test >>"${WDA_LOG_FILE}" 2>&1 &
+    else
+      # Step 3: Inject environment variables into the xctestrun plist
+      inject_env_vars_into_xctestrun "${XCTESTRUN}" "${WDA_PORT}" "${MJPEG_LOCAL_PORT}"
+
+      echo "[start-ios-wda] modified xctestrun: ${XCTESTRUN}"
+
+      # Step 4: Run with modified xctestrun (skip rebuild, background)
+      nohup xcodebuild test-without-building \
+        -xctestrun "${XCTESTRUN}" \
+        -destination "id=${UDID}" \
+        -derivedDataPath "${WDA_DERIVED_DATA}" \
+        >>"${WDA_LOG_FILE}" 2>&1 &
+    fi
+  else
+    echo "[start-ios-wda] real-device mode: iproxy handles port forwarding, starting xcodebuild"
+    nohup xcodebuild \
+      -project "${WDA_PROJECT}" \
+      -scheme "${WDA_SCHEME}" \
+      -destination "id=${UDID}" \
+      test >>"${WDA_LOG_FILE}" 2>&1 &
+  fi
+
+  XCODEBUILD_PID=$!
+}
+
+wait_for_wda() {
+  local timeout_seconds="${1:-90}"
+
+  echo "[start-ios-wda] waiting for WDA status: ${WDA_STATUS_URL}"
+
+  for _ in $(seq 1 "${timeout_seconds}"); do
+    if ! device_is_online; then
+      echo "[start-ios-wda] device disconnected while starting: ${UDID}"
+      exit "${EXIT_DEVICE_NOT_CONNECTED}"
+    fi
+
+    if wda_is_healthy; then
+      echo "[start-ios-wda] wda ready: ${WDA_STATUS_URL}"
+      echo "[start-ios-wda] mjpeg_url=http://127.0.0.1:${MJPEG_LOCAL_PORT}/ (local -> device:9100)"
+      echo "[start-ios-wda] wda_log=${WDA_LOG_FILE}"
+      echo "[start-ios-wda] iproxy_log=${IPROXY_LOG_FILE}"
+      return 0
+    fi
+
+    sleep 1
+  done
+
+  return 1
+}
+
+echo "[start-ios-wda] checking device online: ${UDID}"
+
+if ! device_is_online; then
+  echo "[start-ios-wda] device not connected or not online: ${UDID}"
+  echo "[start-ios-wda] only devices under '== Devices ==' are considered online"
+  exit "${EXIT_DEVICE_NOT_CONNECTED}"
+fi
+
+# Acquire exclusive lock to prevent concurrent watchdog instances from racing.
+if ! try_acquire_lock; then
+  exit 0
+fi
+
+# Case 1: requested local port is already healthy.
+if wda_is_healthy; then
+  echo "[start-ios-wda] wda already healthy on requested port: ${WDA_STATUS_URL}"
+  exit 0
+fi
+
+# Case 2: status is unhealthy. Check whether xcodebuild is already running.
+if xcodebuild_is_running_for_udid; then
+  echo "[start-ios-wda] xcodebuild already running for udid=${UDID}, waiting for WDA on port ${WDA_PORT}"
+
+  if wait_for_wda 60; then
+    echo "[start-ios-wda] WDA became healthy on port ${WDA_PORT}"
+    exit 0
+  fi
+
+  # xcodebuild is running but WDA not healthy after waiting.
+  # Could be still building, or WDA is on a different port.
+  # Don't kill xcodebuild — let the next poll cycle retry.
+  echo "[start-ios-wda] xcodebuild running but WDA not healthy on ${WDA_PORT} after 60s, will retry"
+  exit 1
+fi
+
+# Case 3: no running xcodebuild — start fresh.
+echo "[start-ios-wda] no existing xcodebuild for udid, starting xcodebuild"
+if ! start_xcodebuild; then
+  echo "[start-ios-wda] start_xcodebuild failed, aborting"
+  echo "[start-ios-wda] check the log: ${WDA_LOG_FILE}"
+  tail -n 40 "${WDA_LOG_FILE}" 2>/dev/null || true
+  exit "${EXIT_WDA_START_FAILED}"
+fi
+start_iproxy
+
+if wait_for_wda 90; then
+  echo "[start-ios-wda] started udid=${UDID} wda_local=${WDA_PORT} mjpeg_local=${MJPEG_LOCAL_PORT}"
+  if [[ -n "${XCODEBUILD_PID:-}" ]]; then
+    echo "[start-ios-wda] xcodebuild_pid=${XCODEBUILD_PID}"
+  fi
+  exit 0
+fi
+
+echo "[start-ios-wda] failed to start WDA within timeout"
+echo "[start-ios-wda] status_url=${WDA_STATUS_URL}"
+echo "[start-ios-wda] wda_log=${WDA_LOG_FILE}"
+echo "[start-ios-wda] iproxy_log=${IPROXY_LOG_FILE}"
+
+echo "[start-ios-wda] last WDA logs:"
+tail -n 80 "${WDA_LOG_FILE}" 2>/dev/null || true
+
+echo "[start-ios-wda] last iproxy logs:"
+tail -n 40 "${IPROXY_LOG_FILE}" 2>/dev/null || true
+
+exit "${EXIT_WDA_START_FAILED}"

package/scripts/stop-ios-wda.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+stop_all_by_name() {
+  local process_name="$1"
+  local -a pids=()
+  local -a remaining=()
+
+  # macOS built-in bash (3.2) has no mapfile; collect pids via read loop.
+  while IFS= read -r pid; do
+    if [[ -n "${pid}" ]]; then
+      pids+=("${pid}")
+    fi
+  done < <(pgrep -x "${process_name}" || true)
+
+  if [[ "${#pids[@]}" -eq 0 ]]; then
+    echo "[stop-ios-wda] no ${process_name} process found"
+    return 0
+  fi
+
+  echo "[stop-ios-wda] stopping ${process_name} pids: ${pids[*]}"
+  kill "${pids[@]}" 2>/dev/null || true
+  sleep 1
+
+  for pid in "${pids[@]}"; do
+    if kill -0 "${pid}" >/dev/null 2>&1; then
+      remaining+=("${pid}")
+    fi
+  done
+
+  if [[ "${#remaining[@]}" -gt 0 ]]; then
+    echo "[stop-ios-wda] force killing ${process_name} pids: ${remaining[*]}"
+    kill -9 "${remaining[@]}" 2>/dev/null || true
+  fi
+
+  echo "[stop-ios-wda] ${process_name} cleaned"
+}
+
+echo "[stop-ios-wda] cleanup started"
+stop_all_by_name "iproxy"
+stop_all_by_name "xcodebuild"
+# Clean up simulator WDA Node.js TCP forwarding (pattern: connect(8100, '127.0.0.1'))
+pkill -f "node.*connect.8100.*127.0.0.1" 2>/dev/null || true
+echo "[stop-ios-wda] cleanup finished"