android-midscene-automation 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # 更新记录
+## v0.2.3
+- 修复长时间执行 ADB 操作、延时或 AI 识别后，Appium 因默认 60 秒命令空闲超时销毁会话，导致后续 Home 键、点击等节点报“invalid session id”的问题；托管服务关闭会话空闲计时，外部服务通过心跳保活并保留 60 秒空闲回收，避免创建请求取消或清理失败后遗留永久会话。
+- 为启动 App、清理数据、坐标点击与滑动补齐 ADB 超时和取消控制；终止前台检查后不再继续启动 App，异常结束仍清理会话。
+- 修复远程回放固定 10 分钟超时后丢失结果的问题：任务随代理心跳续期，离线任务支持恢复连接后终止与补交历史记录，结果上报失败自动重试且不会重复执行脚本。
+- 修复远程设备无法手动终止回放的问题，通过独立心跳传递取消信号，兼容任务派发前取消，并阻止同一设备重复提交回放。
+
 ## v0.2.2
-- 更新 Vben 风格的浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
+- 更新浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
 - 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
 - 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
 - Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。

package/README.md

@@ -1358,8 +1358,14 @@ Linux: ~/.local/share/android-midscene-automation
 
 # 项目更新记录
 
+## v0.2.3
+- 修复长时间执行 ADB 操作、延时或 AI 识别后，Appium 因默认 60 秒命令空闲超时销毁会话，导致后续 Home 键、点击等节点报“invalid session id”的问题；托管服务关闭会话空闲计时，外部服务通过心跳保活并保留 60 秒空闲回收，避免创建请求取消或清理失败后遗留永久会话。
+- 为启动 App、清理数据、坐标点击与滑动补齐 ADB 超时和取消控制；终止前台检查后不再继续启动 App，异常结束仍清理会话。
+- 修复远程回放固定 10 分钟超时后丢失结果的问题：任务随代理心跳续期，离线任务支持恢复连接后终止与补交历史记录，结果上报失败自动重试且不会重复执行脚本。
+- 修复远程设备无法手动终止回放的问题，通过独立心跳传递取消信号，兼容任务派发前取消，并阻止同一设备重复提交回放。
+
 ## v0.2.2
-- 更新 Vben 风格的浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
+- 更新浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
 - 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
 - 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
 - Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "android-midscene-automation",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oooooooko/android-midscene-automation.git"

package/remote-agent/index.ts

@@ -6,7 +6,9 @@ import type { RemoteAgentDevice, RemoteCommand } from '../server/remote-agents/p
 import { replayAppiumScript } from '../server/appium-recorder/appium-runner';
 import type { AppiumRecordedScriptRecord } from '../server/appium-recorder/repository';
 
-const VERSION = '0.1.0';
+const VERSION = '0.2.3';
+const replays = new Map<string, AbortController>();
+let lastHeartbeatAt = Date.now();
 
 function argValue(name: string, fallback = '') {
   const index = process.argv.indexOf(`--${name}`);
@@ -25,7 +27,7 @@ if (!server) {
 
 function execText(command: string, args: string[] = []) {
   return new Promise<string>((resolve, reject) => {
-    execFile(command, args, { maxBuffer: 20 * 1024 * 1024 }, (error, stdout, stderr) => {
+    execFile(command, args, { maxBuffer: 20 * 1024 * 1024, timeout: 10000 }, (error, stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -37,7 +39,7 @@ function execText(command: string, args: string[] = []) {
 
 function execBuffer(command: string, args: string[] = []) {
   return new Promise<Buffer>((resolve, reject) => {
-    execFile(command, args, { encoding: 'buffer', maxBuffer: 20 * 1024 * 1024 }, (error, stdout, stderr) => {
+    execFile(command, args, { encoding: 'buffer', maxBuffer: 20 * 1024 * 1024, timeout: 10000 }, (error, stdout, stderr) => {
       if (error) {
         reject(new Error(Buffer.isBuffer(stderr) ? stderr.toString() : stderr || error.message));
         return;
@@ -50,10 +52,11 @@ function execBuffer(command: string, args: string[] = []) {
 async function postJson<T>(url: string, body: unknown) {
   const response = await fetch(url, {
     method: 'POST',
+    signal: AbortSignal.timeout(10000),
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify(body),
   });
-  const payload = await response.json().catch(() => ({})) as T & { message?: string };
+  const payload = await response.json() as T & { message?: string };
   if (!response.ok) throw new Error(payload.message || `HTTP ${response.status}`);
   return payload;
 }
@@ -94,7 +97,7 @@ async function getCurrentActivity(deviceId: string) {
   return resumedLine?.match(/\s([\w.$]+\/[\w.$]+)\s/)?.[1] || '';
 }
 
-async function handleCommand(command: RemoteCommand) {
+async function handleCommand(command: RemoteCommand, signal?: AbortSignal) {
   const payload = command.payload || {};
   if (command.type === 'screenshot') {
     const image = await execBuffer('adb', ['-s', command.deviceId, 'exec-out', 'screencap', '-p']);
@@ -135,8 +138,10 @@ async function handleCommand(command: RemoteCommand) {
   if (command.type === 'replay') {
     const script = payload.script as AppiumRecordedScriptRecord | undefined;
     if (!script) throw new Error('远程回放缺少脚本内容');
-    return await replayAppiumScript(script, command.deviceId, undefined, undefined, {
+    return await replayAppiumScript(script, command.deviceId, undefined, signal, {
       screenshotReport: payload.screenshotReport === true,
+      reportSummaryEnabled: typeof payload.reportSummaryEnabled === 'boolean' ? payload.reportSummaryEnabled : undefined,
+      reportSummaryPrompt: typeof payload.reportSummaryPrompt === 'string' ? payload.reportSummaryPrompt : undefined,
       parameters: payload.parameters as import('../src/appium-recorder/variables').TestVariable[] | undefined,
       globalVariables: payload.globalVariables as import('../src/appium-recorder/variables').TestVariable[] | undefined,
       linkedScripts: payload.linkedScripts as AppiumRecordedScriptRecord[] | undefined,
@@ -150,48 +155,71 @@ async function heartbeat() {
     console.warn(`扫描设备失败：${error instanceof Error ? error.message : String(error)}`);
     return [];
   });
-  await postJson(`${server}/api/remote-agents/heartbeat`, {
+  const control = await postJson<{ cancelledCommandIds?: string[] }>(`${server}/api/remote-agents/heartbeat`, {
     agentId,
     agentName,
     version: VERSION,
     token,
     devices,
   });
+  lastHeartbeatAt = Date.now();
+  for (const id of control.cancelledCommandIds || []) replays.get(id)?.abort();
   console.log(`已上报 ${devices.length} 台设备到 ${server}`);
 }
 
 async function reportResult(command: RemoteCommand, ok: boolean, data?: unknown, error?: string) {
-  await postJson(`${server}/api/remote-agents/result`, {
-    agentId,
-    token,
-    commandId: command.id,
-    ok,
-    data,
-    error,
-  });
+  // 上报失败只重试结果，绝不重新执行已经操作过设备的脚本。
+  for (;;) {
+    try {
+      await postJson(`${server}/api/remote-agents/result`, { agentId, token, commandId: command.id, ok, data, error });
+      return;
+    } catch (error) {
+      if (command.type !== 'replay') throw error;
+      console.warn(`结果上报失败，正在重试：${error instanceof Error ? error.message : String(error)}`);
+      await new Promise(resolve => setTimeout(resolve, 3000));
+    }
+  }
 }
 
 async function pollOnce() {
   const url = new URL(`${server}/api/remote-agents/poll`);
   url.searchParams.set('agentId', agentId);
   if (token) url.searchParams.set('token', token);
-  const response = await fetch(url);
+  const response = await fetch(url, { signal: AbortSignal.timeout(10000) });
   const payload = await response.json().catch(() => ({})) as { command?: RemoteCommand | null; message?: string };
   if (!response.ok) throw new Error(payload.message || `HTTP ${response.status}`);
   if (!payload.command) return;
-  try {
-    const result = await handleCommand(payload.command);
-    await reportResult(payload.command, true, result);
-  } catch (error) {
-    await reportResult(payload.command, false, undefined, error instanceof Error ? error.message : String(error));
+  const command = payload.command;
+  const controller = command.type === 'replay' ? new AbortController() : undefined;
+  if (controller) {
+    replays.set(command.id, controller);
+    if (command.cancelled) controller.abort();
   }
+  try {
+    let result: unknown;
+    try {
+      result = await handleCommand(command, controller?.signal);
+    } catch (error) {
+      await reportResult(command, false, undefined, error instanceof Error ? error.message : String(error));
+      return;
+    }
+    await reportResult(command, true, result);
+  } finally { replays.delete(command.id); }
 }
 
 async function main() {
   console.log(`Remote Agent 启动：${agentId}`);
   console.log(`中央服务：${server}`);
   await heartbeat();
-  setInterval(() => void heartbeat().catch((error) => console.warn(`心跳失败：${error.message}`)), 3000);
+  let heartbeatTask: Promise<void> | undefined;
+  setInterval(() => {
+    if (Date.now() - lastHeartbeatAt >= 45000) {
+      for (const controller of replays.values()) controller.abort();
+    }
+    if (!heartbeatTask) heartbeatTask = heartbeat()
+      .catch(error => console.warn(`心跳失败：${error.message}`))
+      .finally(() => { heartbeatTask = undefined; });
+  }, 3000);
   for (;;) {
     await pollOnce().catch((error) => console.warn(`轮询失败：${error.message}`));
     await new Promise((resolve) => setTimeout(resolve, 300));

package/server/appium-recorder/appium-runner.ts

@@ -139,8 +139,9 @@ function normalizeTextForContains(value: string) {
 }
 
 function adbTap(deviceId: string, x: number, y: number) {
+  throwIfReplayStopped();
   return new Promise<void>((resolve, reject) => {
-    execFile(getAdbCommand(), ['-s', deviceId, 'shell', 'input', 'tap', String(Math.round(x)), String(Math.round(y))], (error, _stdout, stderr) => {
+    execFile(getAdbCommand(), ['-s', deviceId, 'shell', 'input', 'tap', String(Math.round(x)), String(Math.round(y))], { timeout: 10000, signal: replayContext.getStore()?.signal }, (error, _stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -150,7 +151,8 @@ function adbTap(deviceId: string, x: number, y: number) {
   });
 }
 
-export function launchAppOnDevice(deviceId: string, packageName: string) {
+export function launchAppOnDevice(deviceId: string, packageName: string, signal = replayContext.getStore()?.signal) {
+  signal?.throwIfAborted();
   if (!packageName) return Promise.reject(new Error('启动 APP 缺少包名'));
   return new Promise<void>((resolve, reject) => {
     execFile(getAdbCommand(), [
@@ -163,7 +165,7 @@ export function launchAppOnDevice(deviceId: string, packageName: string) {
       '-c',
       'android.intent.category.LAUNCHER',
       '1',
-    ], { maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+    ], { maxBuffer: 4 * 1024 * 1024, timeout: 30000, signal }, (error, stdout, stderr) => {
       const output = `${stdout || ''}\n${stderr || ''}`.trim();
       if (error || /no activities found|monkey aborted/i.test(output)) {
         reject(new Error(output || error?.message || `ADB 启动 ${packageName} 失败`));
@@ -174,7 +176,8 @@ export function launchAppOnDevice(deviceId: string, packageName: string) {
   });
 }
 
-export function clearAppDataOnDevice(deviceId: string, packageName: string) {
+export function clearAppDataOnDevice(deviceId: string, packageName: string, signal = replayContext.getStore()?.signal) {
+  signal?.throwIfAborted();
   if (!packageName) return Promise.reject(new Error('清理 App 缓存缺少包名'));
   return new Promise<void>((resolve, reject) => {
     execFile(getAdbCommand(), [
@@ -184,7 +187,7 @@ export function clearAppDataOnDevice(deviceId: string, packageName: string) {
       'pm',
       'clear',
       packageName,
-    ], { maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+    ], { maxBuffer: 4 * 1024 * 1024, timeout: 30000, signal }, (error, stdout, stderr) => {
       const output = `${stdout || ''}\n${stderr || ''}`.trim();
       if (error || !/^success$/im.test(output)) {
         reject(new Error(output || error?.message || `ADB 清理 ${packageName} 失败`));
@@ -196,6 +199,7 @@ export function clearAppDataOnDevice(deviceId: string, packageName: string) {
 }
 
 function adbSwipe(deviceId: string, step: Required<AppiumRecordedStepRecord>['swipe']) {
+  throwIfReplayStopped();
   return new Promise<void>((resolve, reject) => {
     execFile(getAdbCommand(), [
       '-s',
@@ -208,7 +212,7 @@ function adbSwipe(deviceId: string, step: Required<AppiumRecordedStepRecord>['sw
       String(Math.round(step.endX)),
       String(Math.round(step.endY)),
       String(Math.round(step.duration)),
-    ], (error, _stdout, stderr) => {
+    ], { timeout: Math.max(10000, step.duration + 5000), signal: replayContext.getStore()?.signal }, (error, _stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -294,7 +298,8 @@ async function appiumRequest<T>(
   try {
     const result = await timedAppiumFetch(requestUrl, {
       ...init,
-      signal: options?.ignoreAbort ? undefined : context?.signal || init?.signal,
+      signal: options?.ignoreAbort ? undefined : (context?.signal && init?.signal
+        ? AbortSignal.any([context.signal, init.signal]) : context?.signal || init?.signal),
       headers: {
         'Content-Type': 'application/json',
         ...(init?.headers || {}),
@@ -415,6 +420,8 @@ async function createSession(deviceId: string) {
           'appium:udid': deviceId,
           'appium:autoLaunch': false,
           'appium:noReset': true,
+          // 托管进程由 finally 释放；外部服务保留回收期限，避免创建请求取消后遗留永久会话。
+          'appium:newCommandTimeout': usesManagedAppiumServer() ? 0 : 60,
           'appium:skipDeviceInitialization': true,
           'appium:ignoreHiddenApiPolicyError': true,
         },
@@ -803,7 +810,7 @@ async function runStep(
 
   if (step.type === 'launchApp') {
     const packageName = step.value || '';
-    if (await isAppInForeground(deviceId, packageName).catch(() => false)) {
+    if (await isAppInForeground(deviceId, packageName).catch(error => { throwIfReplayStopped(error); return false; })) {
       return `APP 已在前台，跳过启动 ${packageName}`;
     }
     await launchAppOnDevice(deviceId, packageName);
@@ -1566,6 +1573,7 @@ export async function replayAppiumScript(
     );
     let sessionId = '';
     let sessionCreationStarted = false;
+    let stopHeartbeat: (() => Promise<void>) | undefined;
     let success = false;
     let stopped = false;
     let recording: Awaited<ReturnType<typeof startReplayVideo>> | undefined;
@@ -1594,6 +1602,18 @@ export async function replayAppiumScript(
         await resetUiAutomator2(targetDeviceId);
         sessionId = await createSession(targetDeviceId);
       }
+      if (!managedAppium) {
+        const heartbeatAbort = new AbortController();
+        let heartbeatTask: Promise<unknown> | undefined;
+        const timer = setInterval(() => {
+          if (heartbeatTask || signal?.aborted) return;
+          heartbeatTask = appiumRequest(`/session/${sessionId}/timeouts`, { signal: heartbeatAbort.signal }, { timeoutMs: 5000 })
+            .catch(error => { if (!heartbeatAbort.signal.aborted && !signal?.aborted) lines.push(`Appium 保活失败：${errorDetail(error)}`); })
+            .finally(() => { heartbeatTask = undefined; });
+        }, 15000);
+        timer.unref();
+        stopHeartbeat = async () => { clearInterval(timer); heartbeatAbort.abort(); await heartbeatTask; };
+      }
       lines.push(`Appium session 已创建：${sessionId}`);
       if (runOptions.recordVideo) {
         if (scope.privacy.enabled) throw new Error('本次运行包含敏感变量，为避免泄露已禁止录屏，请关闭录制回放视频');
@@ -1660,6 +1680,7 @@ export async function replayAppiumScript(
           lines.push('[录屏提示] 本次录像未能完整保存。请检查报告目录的写入权限、磁盘空间及设备连接；录像保存失败不等同于流程节点失败，请以节点执行日志为准。');
         }
       }
+      await stopHeartbeat?.();
       let managedAppiumStopped = false;
       if (signal?.aborted && managedAppium) {
         await managedAppium.stop();
@@ -1669,7 +1690,7 @@ export async function replayAppiumScript(
           `/session/${sessionId}`,
           { method: 'DELETE' },
           { ignoreAbort: true, timeoutMs: 2000 },
-        ).catch(() => undefined);
+        ).catch(error => { lines.push(`Appium 会话清理失败：${errorDetail(error)}${managedAppium ? '' : '；外部服务将在命令空闲 60 秒后回收会话'}`); });
       }
       if (managedAppium) {
         if (!managedAppiumStopped) await managedAppium.stop();

package/server/appium-recorder/managed-cleanup.test.ts

@@ -8,12 +8,14 @@ import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-test('owned device instrumentation is cleaned after success, abort and failed session creation; external servers are untouched', async () => {
+test('replay survives command idle periods and cleans sessions after success, abort and creation failure', async () => {
   const root = await mkdtemp(join(tmpdir(), 'managed-cleanup-'));
   const env = { ...process.env };
   const original = { execFile: childProcess.execFile, spawn: childProcess.spawn, fetch: globalThis.fetch };
   const calls: string[][] = [];
   let mode = 'success', stopped = false;
+  let elapsedMs = 0, lastCommandMs = 0, commandTimeoutMs = 60_000;
+  let keyCommands = 0, deletedSessions = 0;
   let controller = new AbortController();
   try {
     const sdk = join(root, 'sdk');
@@ -44,8 +46,20 @@ test('owned device instrumentation is cleaned after success, abort and failed se
       const path = new URL(String(input)).pathname;
       if (path === '/session' && init?.method === 'POST') {
         if (mode === 'creation-failure') return Response.json({ value: { error: 'session not created', message: 'creation failed' } }, { status: 500 });
+        const capabilities = JSON.parse(String(init.body)).capabilities.alwaysMatch;
+        commandTimeoutMs = (capabilities['appium:newCommandTimeout'] ?? 60) * 1000;
+        lastCommandMs = elapsedMs;
         return Response.json({ value: { sessionId: 'test-session' } });
       }
+      if (path.endsWith('/press_keycode')) {
+        keyCommands++;
+        // Model Appium's idle expiry without waiting a real minute or touching a device.
+        if (commandTimeoutMs && elapsedMs - lastCommandMs > commandTimeoutMs) {
+          return Response.json({ value: { error: 'invalid session id', message: 'New Command Timeout expired' } }, { status: 404 });
+        }
+        lastCommandMs = elapsedMs;
+      }
+      if (path === '/session/test-session' && init?.method === 'DELETE') deletedSessions++;
       return Response.json({ value: {} });
     };
     const { replayAppiumScript } = await import('./appium-runner');
@@ -53,19 +67,35 @@ test('owned device instrumentation is cleaned after success, abort and failed se
       id: 'cleanup', name: 'cleanup', deviceId: 'test-device', appPackage: '', appActivity: '', createdAt: '', updatedAt: '',
       steps: [{ id: 'log', type: 'log' as const, label: 'log', value: 'ok' }],
     };
-    for (mode of ['success', 'abort', 'creation-failure', 'cleanup-failure', 'external']) {
+    for (mode of ['success', 'long-idle', 'abort', 'creation-failure', 'cleanup-failure', 'external', 'external-abort']) {
       calls.length = 0;
+      elapsedMs = lastCommandMs = keyCommands = deletedSessions = 0;
       controller = new AbortController();
-      if (mode === 'external') process.env.APPIUM_SERVER_URL = 'http://external.invalid';
-      const result = await replayAppiumScript(script, 'test-device', line => {
-        if (mode === 'abort' && line.includes('Appium session 已创建')) controller.abort();
+      const external = mode.startsWith('external');
+      const aborted = mode.endsWith('abort');
+      const longIdle = mode.endsWith('long-idle');
+      if (external) process.env.APPIUM_SERVER_URL = 'http://external.invalid';
+      else delete process.env.APPIUM_SERVER_URL;
+      const replayScript = longIdle ? { ...script, steps: [
+        ...script.steps,
+        { id: 'home', type: 'key' as const, label: 'Home', keyCode: 3 },
+      ] } : script;
+      const result = await replayAppiumScript(replayScript, 'test-device', line => {
+        // ADB operations and model inference do not reset Appium's command timer.
+        if (longIdle && line.includes('[节点 1] 完成')) elapsedMs += 120_000;
+        if (aborted && line.includes('Appium session 已创建')) controller.abort();
       }, controller.signal);
-      assert.equal(calls.length, mode === 'external' ? 0 : 2);
-      if (mode !== 'external') {
+      assert.equal(calls.length, external ? 0 : 2);
+      assert.equal(deletedSessions, mode === 'creation-failure' || (aborted && !external) ? 0 : 1, 'release the replay session even when idle expiry is disabled');
+      if (!external) {
         assert.deepEqual(calls.map(args => args.slice(0, 5)), Array(2).fill(['-s', 'test-device', 'shell', 'am', 'force-stop']));
         assert.deepEqual(calls.map(args => args.at(-1)).sort(), ['io.appium.uiautomator2.server', 'io.appium.uiautomator2.server.test']);
       }
-      if (mode === 'abort') assert.equal(result.stopped, true);
+      if (longIdle) {
+        assert.equal(keyCommands, 1, 'execute Home after the long interval without Appium commands');
+        assert.equal(result.success, true, result.output);
+      }
+      if (aborted) assert.equal(result.stopped, true);
       if (mode === 'creation-failure') assert.equal(result.success, false);
       if (mode === 'cleanup-failure') assert.match(result.output, /UiAutomator2 清理失败/);
     }

package/server/appium-recorder/replay-lifecycle.test.ts

@@ -0,0 +1,123 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import childProcess from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createServer } from 'node:http';
+import type { AppiumRecordedScriptRecord, AppiumRecordedStepRecord } from './repository';
+
+test('ADB cancellation and deadlines cover actions; external sessions survive idle work and expire after creation cancellation', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'replay-lifecycle-'));
+  const env = { ...process.env };
+  const original = { execFile: childProcess.execFile, fetch: globalThis.fetch, setInterval: globalThis.setInterval };
+  let controller = new AbortController();
+  let mode = '', deletes = 0, launchedAfterAbort = false;
+  let requestCount = 0;
+  try {
+    const sdk = join(root, 'sdk');
+    await mkdir(join(sdk, 'platform-tools'), { recursive: true });
+    await writeFile(join(sdk, 'platform-tools', 'adb'), '');
+    Object.assign(process.env, { ANDROID_MIDSCENE_DATA_ROOT: root, ANDROID_HOME: sdk, ANDROID_SDK_ROOT: sdk, APPIUM_SERVER_URL: 'http://external.invalid' });
+    childProcess.execFile = ((_cmd, args: string[], options, callback) => {
+      requestCount++;
+      if (mode === 'foreground-abort' && args.includes('activities')) {
+        queueMicrotask(() => { controller.abort(); callback(new Error('aborted'), '', ''); });
+      } else if (args.includes('monkey') || args.includes('clear') || args.includes('input')) {
+        launchedAfterAbort ||= controller.signal.aborted;
+        assert.ok(options.timeout > 0, 'every device action has a deadline');
+        assert.equal(options.signal, controller.signal);
+        if (mode === 'timeout') {
+          queueMicrotask(() => callback(new Error('ADB command timed out'), '', ''));
+        } else {
+          options.signal.addEventListener('abort', () => callback(new Error('aborted'), '', ''), { once: true });
+          queueMicrotask(() => controller.abort());
+        }
+      } else queueMicrotask(() => callback(null, '', ''));
+      return {};
+    }) as typeof childProcess.execFile;
+    syncBuiltinESMExports();
+    globalThis.fetch = async (input, init) => {
+      if (init?.method === 'DELETE') deletes++;
+      return Response.json({ value: new URL(String(input)).pathname === '/session' ? { sessionId: 'test-session' } : {} });
+    };
+    const { replayAppiumScript, launchAppOnDevice, clearAppDataOnDevice } = await import('./appium-runner');
+    const script: AppiumRecordedScriptRecord = { id: 'audit', name: 'audit', deviceId: 'fake-device', appPackage: '', appActivity: '', createdAt: '', updatedAt: '', steps: [] };
+    const run = (steps: AppiumRecordedStepRecord[]) => replayAppiumScript({ ...script, steps }, 'fake-device', undefined, controller.signal, { screenshotReport: false, reportSummaryEnabled: false });
+    const actions: AppiumRecordedStepRecord[] = [
+      { id: 'launch', type: 'launchApp', label: 'launch', value: 'example.test' },
+      { id: 'clear', type: 'clearAppData', label: 'clear', value: 'example.test' },
+      { id: 'tap', type: 'coordinateTap', label: 'tap', fallback: { strategy: 'bounds', centerX: 10, centerY: 10 } },
+      { id: 'swipe', type: 'swipe', label: 'swipe', swipe: { startX: 10, startY: 10, endX: 50, endY: 50, duration: 100 } },
+    ];
+    for (const action of actions) {
+      mode = 'abort'; controller = new AbortController(); deletes = 0;
+      assert.equal((await run([action])).stopped, true, action.type);
+      assert.equal(deletes, 1, 'abort releases the known external session');
+    }
+    mode = 'foreground-abort'; controller = new AbortController(); launchedAfterAbort = false;
+    assert.equal((await run([actions[0]!])).stopped, true);
+    assert.equal(launchedAfterAbort, false, 'foreground cancellation must not launch monkey');
+    const count = requestCount;
+    assert.throws(() => launchAppOnDevice('fake', 'example.test', controller.signal));
+    assert.throws(() => clearAppDataOnDevice('fake', 'example.test', controller.signal));
+    assert.equal(requestCount, count, 'already-cancelled actions never spawn');
+    mode = 'timeout'; controller = new AbortController(); deletes = 0;
+    const failed = await run([actions[0]!]);
+    assert.equal(failed.success, false); assert.match(failed.output, /timed out/); assert.equal(deletes, 1);
+
+    // A local HTTP server models the idle lease at accelerated time, without a real device.
+    globalThis.fetch = original.fetch;
+    globalThis.setInterval = ((fn, ms, ...args) => original.setInterval(fn, ms === 15000 ? 15 : ms, ...args)) as typeof setInterval;
+    let active = false, timeoutSeconds = 0, heartbeats = 0, homeKeys = 0, deleted = 0;
+    let expiry: ReturnType<typeof setTimeout> | undefined;
+    let createdResolve: () => void = () => {};
+    const renew = () => { clearTimeout(expiry); expiry = setTimeout(() => { active = false; }, timeoutSeconds * 3); };
+    const server = createServer(async (req, res) => {
+      res.setHeader('Content-Type', 'application/json');
+      if (req.url === '/session' && req.method === 'POST') {
+        let body = ''; for await (const chunk of req) body += chunk;
+        timeoutSeconds = JSON.parse(body).capabilities.alwaysMatch['appium:newCommandTimeout'];
+        if (mode === 'creation-abort') { controller.abort(); await new Promise(resolve => setTimeout(resolve, 20)); }
+        active = true; renew(); createdResolve();
+        res.end(JSON.stringify({ value: { sessionId: 'delayed-session' } }));
+      } else if (req.method === 'DELETE') {
+        deleted++; active = false; clearTimeout(expiry); res.end('{"value":null}');
+      } else if (!active) {
+        res.statusCode = 404; res.end('{"value":{"error":"invalid session id"}}');
+      } else {
+        renew();
+        if (req.url?.endsWith('/timeouts')) heartbeats++;
+        if (req.url?.endsWith('/press_keycode')) homeKeys++;
+        res.end('{"value":{}}');
+      }
+    });
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+    process.env.APPIUM_SERVER_URL = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+    try {
+      mode = 'long-idle'; controller = new AbortController();
+      const result = await run([{ id: 'wait', type: 'delay', label: 'idle', timeoutMs: 450 }, { id: 'home', type: 'key', label: 'Home', keyCode: 3 }]);
+      assert.equal(result.success, true, result.output);
+      assert.equal(timeoutSeconds, 60); assert.ok(heartbeats > 3); assert.equal(homeKeys, 1); assert.equal(deleted, 1);
+      const heartbeatCount = heartbeats;
+      await new Promise(resolve => setTimeout(resolve, 40));
+      assert.equal(heartbeats, heartbeatCount, 'heartbeat stops after cleanup');
+      mode = 'creation-abort'; controller = new AbortController();
+      const created = new Promise<void>(resolve => { createdResolve = resolve; });
+      assert.equal((await run([actions[0]!])).stopped, true);
+      await created;
+      assert.equal(active, true, 'server can create a session after the client cancelled');
+      await new Promise(resolve => setTimeout(resolve, 220));
+      assert.equal(active, false, 'unclaimed external session has a finite idle lease');
+    } finally {
+      clearTimeout(expiry); server.closeAllConnections(); await new Promise<void>(resolve => server.close(() => resolve()));
+    }
+  } finally {
+    childProcess.execFile = original.execFile; globalThis.fetch = original.fetch; globalThis.setInterval = original.setInterval; syncBuiltinESMExports();
+    for (const key of ['ANDROID_MIDSCENE_DATA_ROOT', 'ANDROID_HOME', 'ANDROID_SDK_ROOT', 'APPIUM_SERVER_URL']) {
+      if (env[key] === undefined) delete process.env[key]; else process.env[key] = env[key];
+    }
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/server/appium-recorder/routes.ts

@@ -24,7 +24,7 @@ import {
   type AppiumRecordedStepRecord,
 } from './repository';
 import { clearAppDataOnDevice, launchAppOnDevice, replayAppiumScript } from './appium-runner';
-import { isRemoteDeviceId, sendRemoteCommand } from '../remote-agents/registry';
+import { isRemoteDeviceId, sendRemoteCommand, stopRemoteReplay } from '../remote-agents/registry';
 import { getAdbCommand } from '../android-sdk';
 import { createAppiumScriptExport } from './script-export';
 import { resolveReportSummary } from '../../src/appium-recorder/report-summary';
@@ -47,7 +47,7 @@ function sendStreamEvent(res: ServerResponse, payload: unknown) {
 
 function execFileText(command: string, args: string[] = []) {
   return new Promise<string>((resolve, reject) => {
-    execFile(command, args, { maxBuffer: 20 * 1024 * 1024 }, (error, stdout, stderr) => {
+    execFile(command, args, { maxBuffer: 20 * 1024 * 1024, timeout: 10000 }, (error, stdout, stderr) => {
       if (error) {
         reject(new Error(stderr || error.message));
         return;
@@ -376,6 +376,10 @@ export async function handleAppiumRecorderRequest(
       const parsed = await readBody<{ deviceId?: string }>(req);
       const deviceId = parsed.deviceId || selectedDeviceId;
       assertDeviceAllowed(deviceId);
+      if (isRemoteDeviceId(deviceId)) {
+        sendJson(res, { success: true, stopped: stopRemoteReplay(deviceId) });
+        return true;
+      }
       const controller = replayAbortControllers.get(deviceId);
       controller?.abort();
       sendJson(res, { success: true, stopped: Boolean(controller) });
@@ -434,10 +438,6 @@ export async function handleAppiumRecorderRequest(
           globalVariables: getPresetVariables(),
           linkedScripts: linkedScriptSnapshot(script),
         }) as Awaited<ReturnType<typeof replayAppiumScript>>;
-        if (result.history) {
-          try { saveRunHistory({ ...result.history, scriptId: script.id, deviceId }); }
-          catch { result.output += '\n历史记录保存失败'; }
-        }
         const { history: _history, ...response } = result;
         if (streamOutput) {
           result.output?.split(/\r?\n/).forEach((line) => sendStreamEvent(res, { type: 'log', line }));

package/server/remote-agents/protocol.ts

@@ -20,6 +20,7 @@ export type RemoteCommand = {
   type: RemoteCommandType;
   deviceId: string;
   payload?: Record<string, unknown>;
+  cancelled?: boolean;
 };
 
 export type RemoteCommandResult = {

package/server/remote-agents/registry.test.ts

@@ -0,0 +1,65 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { registerRemoteAgent, makeRemoteDeviceId, sendRemoteCommand, pollRemoteCommand, completeRemoteCommand, stopRemoteReplay } from './registry';
+
+test('replay heartbeat renews beyond ten minutes, cancellation survives dispatch, late results save once', async () => {
+  const originalSetTimeout = globalThis.setTimeout;
+  const originalClearTimeout = globalThis.clearTimeout;
+  const originalNow = Date.now;
+  const token = process.env.REMOTE_AGENT_TOKEN;
+  let now = originalNow();
+  const timers = new Set<{ at: number; callback: () => void; refresh: () => void }>();
+  const advance = (ms: number) => {
+    now += ms;
+    for (const timer of [...timers]) if (timer.at <= now) { timers.delete(timer); timer.callback(); }
+  };
+  try {
+    Date.now = () => now;
+    globalThis.setTimeout = ((callback: () => void, ms: number) => {
+      const timer = { at: now + ms, callback, refresh: () => { timer.at = now + ms; } };
+      timers.add(timer); return timer;
+    }) as unknown as typeof setTimeout;
+    globalThis.clearTimeout = ((timer: any) => { timers.delete(timer); }) as typeof clearTimeout;
+    const agentId = 'test-lease-agent';
+    const heartbeat = () => registerRemoteAgent({ agentId, token, devices: [{ id: 'device', status: 'device' }] });
+    const device = makeRemoteDeviceId(agentId, 'device');
+    heartbeat();
+    const result = sendRemoteCommand(device, 'replay', { script: { id: 'script' } });
+    let completed = false;
+    void result.then(() => { completed = true; });
+    const command = pollRemoteCommand({ agentId, token })!;
+    assert.throws(() => sendRemoteCommand(device, 'replay'), /已有回放任务/);
+    for (let i = 0; i < 70; i++) { advance(10000); heartbeat(); }
+    assert.equal(completed, false, 'healthy replay remains pending after 11 minutes');
+    assert.equal(stopRemoteReplay(device), true);
+    assert.deepEqual(heartbeat().cancelledCommandIds, [command.id]);
+    assert.throws(() => completeRemoteCommand({ agentId: 'other', token, commandId: command.id, ok: true }), /不属于/);
+    let saves = 0;
+    const stopped = { stopped: true, history: { status: 'stopped' } };
+    completeRemoteCommand({ agentId, token, commandId: command.id, ok: true, data: stopped }, () => { saves++; });
+    assert.deepEqual(await result, stopped);
+    completeRemoteCommand({ agentId, token, commandId: command.id, ok: true, data: stopped }, () => { saves++; });
+    assert.equal(saves, 1, 'result retry must not duplicate history');
+    assert.equal(stopRemoteReplay(device), false);
+
+    const queuedResult = sendRemoteCommand(device, 'replay');
+    assert.equal(stopRemoteReplay(device), true);
+    const queued = pollRemoteCommand({ agentId, token })!;
+    assert.equal(queued.cancelled, true, 'cancel before poll survives delivery');
+    completeRemoteCommand({ agentId, token, commandId: queued.id, ok: true }); await queuedResult;
+
+    const lateResult = sendRemoteCommand(device, 'replay', { script: { id: 'late-script' } });
+    const rejected = assert.rejects(lateResult, /心跳超时/);
+    const late = pollRemoteCommand({ agentId, token })!;
+    advance(45001); await rejected;
+    assert.deepEqual(heartbeat().cancelledCommandIds, [late.id], 'reconnecting agent stops expired replay');
+    const input = { agentId, token, commandId: late.id, ok: true, data: { history: {} } };
+    assert.throws(() => completeRemoteCommand(input, () => { throw new Error('disk busy'); }), /disk busy/);
+    completeRemoteCommand(input, command => { assert.equal((command.payload?.script as { id: string }).id, 'late-script'); saves++; });
+    completeRemoteCommand(input, () => { saves++; });
+    assert.equal(saves, 2, 'late result is saved once even after a temporary persistence failure');
+    assert.deepEqual(heartbeat().cancelledCommandIds, []);
+  } finally {
+    globalThis.setTimeout = originalSetTimeout; globalThis.clearTimeout = originalClearTimeout; Date.now = originalNow;
+  }
+});

package/server/remote-agents/registry.ts

@@ -3,7 +3,9 @@ import type { RemoteAgentDevice, RemoteAndroidDevice, RemoteCommand, RemoteComma
 const REMOTE_DEVICE_PREFIX = 'remote:';
 const AGENT_TTL_MS = 15_000;
 const COMMAND_TIMEOUT_MS = 15_000;
-const REPLAY_COMMAND_TIMEOUT_MS = 10 * 60_000;
+// 回放由代理心跳续期，运行时长不受固定十分钟限制。
+const REPLAY_COMMAND_TIMEOUT_MS = 45_000;
+const LATE_RESULT_TTL_MS = 24 * 60 * 60_000;
 
 type RegisteredAgent = {
   id: string;
@@ -14,6 +16,9 @@ type RegisteredAgent = {
 };
 
 type PendingCommand = RemoteCommand & {
+  agentId: string;
+  delivered: boolean;
+  cancelRequested: boolean;
   resolve: (result: unknown) => void;
   reject: (error: Error) => void;
   timer: ReturnType<typeof setTimeout>;
@@ -22,6 +27,24 @@ type PendingCommand = RemoteCommand & {
 const agents = new Map<string, RegisteredAgent>();
 const queues = new Map<string, RemoteCommand[]>();
 const pending = new Map<string, PendingCommand>();
+// ponytail: 当前进程保留离线回放身份 24 小时；跨服务重启补交需要持久化任务表。
+const lateReplays = new Map<string, { command: RemoteCommand; agentId: string; expiresAt: number }>();
+function pruneLateReplays() {
+  for (const [id, receipt] of lateReplays) if (receipt.expiresAt <= Date.now()) lateReplays.delete(id);
+}
+
+export function stopRemoteReplay(deviceId: string) {
+  const target = parseRemoteDeviceId(deviceId);
+  if (!target) return false;
+  let stopped = false;
+  for (const command of pending.values()) {
+    if (command.type === 'replay' && command.agentId === target.agentId && command.deviceId === target.deviceSerial) {
+      command.cancelRequested = true;
+      stopped = true;
+    }
+  }
+  return stopped;
+}
 
 function validateToken(token?: string) {
   const expected = process.env.REMOTE_AGENT_TOKEN || '';
@@ -70,6 +93,17 @@ export function registerRemoteAgent(input: {
     devices: input.devices || [],
     lastSeenAt: Date.now(),
   });
+  pruneLateReplays();
+  const cancelledCommandIds: string[] = [];
+  for (const command of pending.values()) {
+    if (command.agentId !== agentId || command.type !== 'replay') continue;
+    command.timer.refresh();
+    if (command.cancelRequested) cancelledCommandIds.push(command.id);
+  }
+  for (const receipt of lateReplays.values()) {
+    if (receipt.agentId === agentId) cancelledCommandIds.push(receipt.command.id);
+  }
+  return { cancelledCommandIds };
 }
 
 export function listRemoteAndroidDevices(): RemoteAndroidDevice[] {
@@ -88,15 +122,27 @@ export function listRemoteAndroidDevices(): RemoteAndroidDevice[] {
 export function pollRemoteCommand(input: { agentId: string; token?: string }) {
   validateToken(input.token);
   const queue = queues.get(input.agentId) || [];
-  return queue.shift() || null;
+  const command = queue.shift();
+  if (!command) return null;
+  const task = pending.get(command.id);
+  if (!task) return null;
+  task.delivered = true;
+  return { ...command, cancelled: task.cancelRequested };
 }
 
 export function completeRemoteCommand(input: {
   agentId: string;
   token?: string;
-} & RemoteCommandResult) {
+} & RemoteCommandResult, saveResult?: (command: RemoteCommand) => void) {
   validateToken(input.token);
+  pruneLateReplays();
   const command = pending.get(input.commandId);
+  const late = lateReplays.get(input.commandId);
+  if (!command && !late) return;
+  if ((command?.agentId ?? late?.agentId) !== input.agentId) throw new Error('远程命令不属于当前代理');
+  // 先落库再确认；保存失败时保留任务身份，让代理重试上报。
+  if (input.ok) saveResult?.(command ?? late!.command);
+  lateReplays.delete(input.commandId);
   if (!command) return;
   pending.delete(input.commandId);
   clearTimeout(command.timer);
@@ -112,6 +158,10 @@ export function sendRemoteCommand(deviceId: string, type: RemoteCommandType, pay
   if (!parsed) throw new Error('远程设备 ID 无效');
   const agent = agents.get(parsed.agentId);
   if (!agent || !isOnline(agent)) throw new Error('远程设备代理已离线');
+  if (type === 'replay' && [...pending.values()].some(command =>
+    command.type === 'replay' && command.agentId === parsed.agentId && command.deviceId === parsed.deviceSerial)) {
+    throw new Error('该设备已有回放任务正在执行');
+  }
   const commandId = `remote_cmd_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
   const command: RemoteCommand = {
     id: commandId,
@@ -123,12 +173,17 @@ export function sendRemoteCommand(deviceId: string, type: RemoteCommandType, pay
   return new Promise<unknown>((resolve, reject) => {
     const timeoutMs = type === 'replay' ? REPLAY_COMMAND_TIMEOUT_MS : COMMAND_TIMEOUT_MS;
     const timer = setTimeout(() => {
+      const task = pending.get(commandId);
       pending.delete(commandId);
+      if (type === 'replay' && task?.delivered) {
+        pruneLateReplays();
+        lateReplays.set(commandId, { command, agentId: parsed.agentId, expiresAt: Date.now() + LATE_RESULT_TTL_MS });
+      }
       const queue = queues.get(parsed.agentId) || [];
       queues.set(parsed.agentId, queue.filter((item) => item.id !== commandId));
-      reject(new Error('远程设备命令超时'));
+      reject(new Error(type === 'replay' ? '远程代理心跳超时，恢复连接后将终止任务并补交结果' : '远程设备命令超时'));
     }, timeoutMs);
-    pending.set(commandId, { ...command, resolve, reject, timer });
+    pending.set(commandId, { ...command, agentId: parsed.agentId, delivered: false, cancelRequested: false, resolve, reject, timer });
     const queue = queues.get(parsed.agentId) || [];
     queue.push(command);
     queues.set(parsed.agentId, queue);

package/server/remote-agents/replay-integration.test.ts

@@ -0,0 +1,79 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+test('real agent receives stop during replay and retries result delivery without replaying', { skip: process.platform === 'win32', timeout: 25000 }, async () => {
+  const root = await mkdtemp(join(tmpdir(), 'remote-replay-'));
+  const env = { ...process.env };
+  process.env.ANDROID_MIDSCENE_DATA_ROOT = join(root, 'central');
+  process.env.REMOTE_AGENT_TOKEN = 'test-only-token';
+  const { handleRemoteAgentRequest } = await import('./routes');
+  const { handleAppiumRecorderRequest } = await import('../appium-recorder/routes');
+  const { listRemoteAndroidDevices } = await import('./registry');
+  const { saveAppiumRecordedScript } = await import('../appium-recorder/repository');
+  const { listRunHistory } = await import('../appium-recorder/run-history');
+  let sessions = 0, deletes = 0, keys = 0, resultAttempts = 0;
+  const server = createServer(async (req, res) => {
+    if (req.url === '/session') {
+      sessions++; res.setHeader('Content-Type', 'application/json'); res.end('{"value":{"sessionId":"test-session"}}'); return;
+    }
+    if (req.url?.startsWith('/session/')) {
+      if (req.method === 'DELETE') deletes++;
+      if (req.url.endsWith('/press_keycode')) keys++;
+      res.setHeader('Content-Type', 'application/json'); res.end('{"value":{}}'); return;
+    }
+    if (req.url === '/api/remote-agents/result' && ++resultAttempts === 1) {
+      req.resume(); res.statusCode = 503; res.end('{"message":"temporary failure"}'); return;
+    }
+    if (await handleRemoteAgentRequest(req, res)) return;
+    if (await handleAppiumRecorderRequest(req, res, '')) return;
+    res.statusCode = 404; res.end();
+  });
+  let agent: ReturnType<typeof spawn> | undefined;
+  const waitFor = async (check: () => boolean) => {
+    const until = Date.now() + 12000;
+    while (!check()) { assert.ok(Date.now() < until, 'agent action completed within deadline'); await new Promise(resolve => setTimeout(resolve, 25)); }
+  };
+  try {
+    const sdk = join(root, 'sdk'), bin = join(sdk, 'platform-tools');
+    await mkdir(bin, { recursive: true });
+    await writeFile(join(bin, 'adb'), '#!/usr/bin/env node\nif(process.argv.includes("devices")) console.log("List of devices attached\\nfake-device device model:Test");\n', { mode: 0o755 });
+    await new Promise<void>(resolve => server.listen(0, '127.0.0.1', resolve));
+    const base = `http://127.0.0.1:${(server.address() as { port: number }).port}`;
+    const script = saveAppiumRecordedScript({ name: 'remote-test', appPackage: 'example.test', steps: [
+      { id: 'wait', type: 'delay', label: 'wait', timeoutMs: 60000 },
+      { id: 'home', type: 'key', label: 'Home', keyCode: 3 },
+    ] });
+    agent = spawn(process.execPath, ['--import', 'tsx', resolve('remote-agent/index.ts'), '--server', base, '--agent-id', 'integration-agent'], {
+      env: { ...process.env, ANDROID_MIDSCENE_DATA_ROOT: join(root, 'agent'), ANDROID_HOME: sdk, ANDROID_SDK_ROOT: sdk, APPIUM_SERVER_URL: base, PATH: `${bin}:${process.env.PATH}` },
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    let stderr = ''; agent.stderr?.on('data', chunk => { stderr += chunk; });
+    await waitFor(() => listRemoteAndroidDevices().length > 0);
+    const deviceId = listRemoteAndroidDevices()[0]!.id;
+    const post = (path: string, data: unknown) => fetch(base + path, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data), signal: AbortSignal.timeout(18000) });
+    const running = post(`/api/appium-recorder/scripts/${script.id}/replay`, { deviceId, reportSummaryEnabled: false }).then(response => response.json() as Promise<{ stopped: boolean }>);
+    await waitFor(() => sessions === 1);
+    const stop = await (await post('/api/appium-recorder/replay/stop', { deviceId })).json() as { stopped: boolean };
+    assert.equal(stop.stopped, true);
+    const result = await running;
+    assert.equal(result.stopped, true, stderr);
+    assert.equal(sessions, 1, 'retrying the result never replays device actions');
+    assert.equal(deletes, 1); assert.equal(keys, 0, 'Home must not run after cancellation');
+    assert.equal(resultAttempts, 2, 'temporary result failure is retried');
+    const history = listRunHistory(script.id);
+    assert.equal(history.length, 1); assert.equal(history[0]?.status, 'stopped'); assert.equal(history[0]?.deviceId, deviceId);
+  } finally {
+    if (agent && agent.exitCode === null) {
+      const exited = new Promise<void>(resolve => agent!.once('exit', () => resolve()));
+      agent.kill('SIGKILL'); await exited;
+    }
+    server.closeAllConnections(); await new Promise<void>(resolve => server.close(() => resolve()));
+    for (const key of ['ANDROID_MIDSCENE_DATA_ROOT', 'REMOTE_AGENT_TOKEN']) { if (env[key] === undefined) delete process.env[key]; else process.env[key] = env[key]; }
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/server/remote-agents/routes.ts

@@ -1,6 +1,8 @@
+import { saveRunHistory } from '../appium-recorder/run-history';
+import type { RunDetail } from '../../src/appium-recorder/run-history';
 import { readBody, requestErrorStatus } from '../request-body';
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { completeRemoteCommand, listRemoteAndroidDevices, pollRemoteCommand, registerRemoteAgent } from './registry';
+import { completeRemoteCommand, makeRemoteDeviceId, listRemoteAndroidDevices, pollRemoteCommand, registerRemoteAgent } from './registry';
 import type { RemoteAgentDevice } from './protocol';
 
 function sendJson(res: ServerResponse, payload: unknown, statusCode = 200) {
@@ -29,14 +31,14 @@ export async function handleRemoteAgentRequest(req: IncomingMessage, res: Server
         token?: string;
         devices?: RemoteAgentDevice[];
       }>(req);
-      registerRemoteAgent({
+      const control = registerRemoteAgent({
         agentId: parsed.agentId || '',
         agentName: parsed.agentName,
         version: parsed.version,
         token: parsed.token,
         devices: parsed.devices || [],
       });
-      sendJson(res, { success: true });
+      sendJson(res, { success: true, ...control });
       return true;
     }
 
@@ -65,6 +67,11 @@ export async function handleRemoteAgentRequest(req: IncomingMessage, res: Server
         ok: parsed.ok === true,
         data: parsed.data,
         error: parsed.error,
+      }, command => {
+        const result = parsed.data as { history?: RunDetail } | undefined;
+        if (command.type !== 'replay' || !result?.history) return;
+        const script = command.payload?.script as { id: string };
+        saveRunHistory({ ...result.history, scriptId: script.id, deviceId: makeRemoteDeviceId(parsed.agentId!, command.deviceId) });
       });
       sendJson(res, { success: true });
       return true;