@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/plugins/ios-agent-device.ts

@@ -1,11 +1,12 @@
 import { randomUUID } from 'crypto';
 import { existsSync, mkdirSync, realpathSync } from 'fs';
-import { isAbsolute, join } from 'path';
+import { delimiter, dirname, isAbsolute, join } from 'path';
 import { spawnSync } from 'child_process';
 import { performance } from 'perf_hooks';
 import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import { runBoundedProcess } from '../execution/thin-harness/async-process';
 import { readJsonFile, writeJsonAtomic } from '../shared/json-files';
+import { resolveTrustedNodeExecutable } from '../shared/trusted-node-executable';
 import { AssistantPluginError, toAssistantPluginError } from './errors';
 import {
   interactionAutomationEngine,
@@ -169,16 +170,35 @@ export function resetIosAgentDeviceRuntimeHooksForTest(): void {
   interactionCommandTails.clear();
 }
 
-function executable(): string {
-  return process.env.FORGE_AGENT_DEVICE_EXECUTABLE?.trim() || 'agent-device';
+function configuredExecutable(): string | undefined {
+  return process.env.FORGE_AGENT_DEVICE_EXECUTABLE?.trim() || undefined;
 }
 
-function resolvedExecutable(): string {
-  const configured = executable();
+function repoLocalExecutable(repoRoot?: string): string | undefined {
+  if (!repoRoot) return undefined;
+  const candidates = [
+    join(repoRoot, 'node_modules', '.bin', 'agent-device'),
+    join(repoRoot, 'node_modules', 'agent-device', 'bin', 'agent-device.mjs'),
+  ];
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue;
+    try { return realpathSync(candidate); } catch { return candidate; }
+  }
+  return undefined;
+}
+
+function executable(repoRoot?: string): string {
+  const configured = configuredExecutable();
+  if (configured) return configured;
+  return repoLocalExecutable(repoRoot) ?? 'agent-device';
+}
+
+function resolvedExecutable(repoRoot?: string): string {
+  const configured = executable(repoRoot);
   if (isAbsolute(configured)) {
     try { return realpathSync(configured); } catch { return configured; }
   }
-  for (const directory of (process.env.PATH ?? '').split(':').filter(Boolean)) {
+  for (const directory of (process.env.PATH ?? '').split(delimiter).filter(Boolean)) {
     const candidate = join(directory, configured);
     if (!existsSync(candidate)) continue;
     try { return realpathSync(candidate); } catch { return candidate; }
@@ -186,6 +206,13 @@ function resolvedExecutable(): string {
   return configured;
 }
 
+function withTrustedNodePath(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const node = resolveTrustedNodeExecutable(env).executable;
+  if (!node) return env;
+  const path = [dirname(node), env.PATH].filter((value): value is string => Boolean(value)).join(delimiter);
+  return { ...env, PATH: path };
+}
+
 function timestamp(): string {
   return hooks.now().toISOString();
 }
@@ -194,28 +221,29 @@ function sanitize(value: string): string {
   return value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'ios-agent-device';
 }
 
-function statusProbeCacheKey(): string {
+function statusProbeCacheKey(repoRoot?: string): string {
   return [
     hooks.platform(),
-    executable(),
-    resolvedExecutable(),
+    repoRoot ?? '',
+    executable(repoRoot),
+    resolvedExecutable(repoRoot),
     configuredAgentDeviceBackendMode(),
     process.versions.node,
     process.env.PATH ?? '',
   ].join('|');
 }
 
-function probeStatus() {
+function probeStatus(repoRoot?: string) {
   const backendMode = configuredAgentDeviceBackendMode();
-  const typedClient = typedAgentDeviceIdentity();
+  const typedClient = typedAgentDeviceIdentity({ repoRoot });
   if (hooks.platform() !== 'darwin') {
     return {
       available: false,
       expectedVersion: IOS_AGENT_DEVICE_VERSION,
       supportedVersionPolicy: '>=0.19.3 <0.21.0 with reviewed command contract',
       detectedVersion: undefined,
-      executable: executable(),
-      resolvedExecutable: resolvedExecutable(),
+      executable: executable(repoRoot),
+      resolvedExecutable: resolvedExecutable(repoRoot),
       platform: hooks.platform(),
       capabilityProfile: detectAgentDeviceCapabilities('', {}),
       backendMode,
@@ -223,14 +251,15 @@ function probeStatus() {
       reason: 'agent-device iOS support requires macOS.',
     };
   }
-  const result = hooks.runCommand(executable(), ['--version'], { timeoutMs: 3_000 });
+  const runtimeEnv = withTrustedNodePath({ ...process.env });
+  const result = hooks.runCommand(executable(repoRoot), ['--version'], { cwd: repoRoot, env: runtimeEnv, timeoutMs: 3_000 });
   const detectedVersion = result.ok ? result.stdout.trim() : undefined;
   const help: AgentDeviceHelpContract = {};
   if (result.ok && detectedVersion) {
-    const rootHelp = hooks.runCommand(executable(), ['help'], { timeoutMs: 3_000 });
+    const rootHelp = hooks.runCommand(executable(repoRoot), ['help'], { cwd: repoRoot, env: runtimeEnv, timeoutMs: 3_000 });
     if (rootHelp.ok) help.root = rootHelp.stdout || rootHelp.stderr;
     for (const topic of ['snapshot', 'press', 'fill', 'batch', 'keyboard'] as const) {
-      const topicResult = hooks.runCommand(executable(), ['help', topic], { timeoutMs: 3_000 });
+      const topicResult = hooks.runCommand(executable(repoRoot), ['help', topic], { cwd: repoRoot, env: runtimeEnv, timeoutMs: 3_000 });
       if (topicResult.ok) help[topic] = topicResult.stdout || topicResult.stderr;
     }
   }
@@ -251,8 +280,8 @@ function probeStatus() {
     expectedVersion: IOS_AGENT_DEVICE_VERSION,
     supportedVersionPolicy: '>=0.19.3 <0.21.0 with reviewed command contract',
     detectedVersion,
-    executable: executable(),
-    resolvedExecutable: resolvedExecutable(),
+    executable: executable(repoRoot),
+    resolvedExecutable: resolvedExecutable(repoRoot),
     platform: hooks.platform(),
     capabilityProfile,
     backendMode,
@@ -267,20 +296,105 @@ function probeStatus() {
   };
 }
 
-export function iosAgentDeviceStatus(options: { forceRefresh?: boolean } = {}) {
+function unprobedAgentDeviceStatus(repoRoot?: string): ReturnType<typeof probeStatus> {
+  const backendMode = configuredAgentDeviceBackendMode();
+  const typedClient = typedAgentDeviceIdentity({ repoRoot });
+  return {
+    available: false,
+    expectedVersion: IOS_AGENT_DEVICE_VERSION,
+    supportedVersionPolicy: '>=0.19.3 <0.21.0 with reviewed command contract',
+    detectedVersion: undefined,
+    executable: executable(repoRoot),
+    resolvedExecutable: resolvedExecutable(repoRoot),
+    platform: hooks.platform(),
+    capabilityProfile: detectAgentDeviceCapabilities('', {}),
+    backendMode,
+    typedClient: { ...typedClient, cliVersion: undefined, cliVersionCompatible: false },
+    reason: 'agent-device readiness has not been probed by an explicit asynchronous action in this runtime yet.',
+  };
+}
+
+export function iosAgentDeviceStatus(options: { forceRefresh?: boolean; repoRoot?: string } = {}) {
   const nowMs = hooks.now().getTime();
-  const cacheKey = statusProbeCacheKey();
+  const cacheKey = statusProbeCacheKey(options.repoRoot);
   if (!options.forceRefresh
     && statusCache
     && statusCache.cacheKey === cacheKey
     && statusCache.expiresAt > nowMs) return statusCache.value;
-  const value = probeStatus();
+  if (hooks.platform() !== 'darwin') return probeStatus(options.repoRoot);
+  return unprobedAgentDeviceStatus(options.repoRoot);
+}
+
+async function probeStatusAsync(input: Pick<AssistantPluginActionExecutionInput, 'repoRoot' | 'signal'>): Promise<ReturnType<typeof probeStatus>> {
+  const repoRoot = input.repoRoot;
+  const backendMode = configuredAgentDeviceBackendMode();
+  const typedClient = typedAgentDeviceIdentity({ repoRoot });
+  if (hooks.platform() !== 'darwin') return probeStatus(repoRoot);
+  const runtimeEnv = withTrustedNodePath({ ...process.env });
+  const result = await hooks.runCommandAsync(executable(repoRoot), ['--version'], {
+    cwd: repoRoot,
+    env: runtimeEnv,
+    timeoutMs: 3_000,
+    signal: input.signal,
+  });
+  const detectedVersion = result.ok ? result.stdout.trim() : undefined;
+  const help: AgentDeviceHelpContract = {};
+  if (result.ok && detectedVersion) {
+    const rootHelp = await hooks.runCommandAsync(executable(repoRoot), ['help'], {
+      cwd: repoRoot, env: runtimeEnv, timeoutMs: 3_000, signal: input.signal,
+    });
+    if (rootHelp.ok) help.root = rootHelp.stdout || rootHelp.stderr;
+    for (const topic of ['snapshot', 'press', 'fill', 'batch', 'keyboard'] as const) {
+      const topicResult = await hooks.runCommandAsync(executable(repoRoot), ['help', topic], {
+        cwd: repoRoot, env: runtimeEnv, timeoutMs: 3_000, signal: input.signal,
+      });
+      if (topicResult.ok) help[topic] = topicResult.stdout || topicResult.stderr;
+    }
+  }
+  const capabilityProfile = detectAgentDeviceCapabilities(detectedVersion ?? '', help);
+  const typedClientWithCompatibility = {
+    ...typedClient,
+    cliVersion: detectedVersion,
+    cliVersionCompatible: agentDeviceProviderVersionsMatch(typedClient.version, detectedVersion),
+  };
+  const available = result.ok
+    && capabilityProfile.versionSupported
+    && Boolean(capabilityProfile.snapshot.interactiveFlag)
+    && capabilityProfile.press.supported
+    && capabilityProfile.fill.supported
+    && capabilityProfile.batch.supported;
+  return {
+    available,
+    expectedVersion: IOS_AGENT_DEVICE_VERSION,
+    supportedVersionPolicy: '>=0.19.3 <0.21.0 with reviewed command contract',
+    detectedVersion,
+    executable: executable(repoRoot),
+    resolvedExecutable: resolvedExecutable(repoRoot),
+    platform: hooks.platform(),
+    capabilityProfile,
+    backendMode,
+    typedClient: typedClientWithCompatibility,
+    reason: !result.ok
+      ? (result.stderr || result.stdout || 'agent-device is not installed.')
+      : !capabilityProfile.versionSupported
+        ? `Unsupported agent-device version ${detectedVersion || 'unknown'}; expected the reviewed >=0.19.3 <0.21.0 contract.`
+        : !available
+          ? 'The installed agent-device command contract is missing required snapshot, press, fill, or batch capabilities.'
+          : undefined,
+  };
+}
+
+async function iosAgentDeviceActionStatus(input: AssistantPluginActionExecutionInput): Promise<ReturnType<typeof probeStatus>> {
+  const nowMs = hooks.now().getTime();
+  const cacheKey = statusProbeCacheKey(input.repoRoot);
+  if (statusCache && statusCache.cacheKey === cacheKey && statusCache.expiresAt > nowMs) return statusCache.value;
+  const value = await probeStatusAsync(input);
   statusCache = { cacheKey, expiresAt: nowMs + STATUS_TTL_MS, value };
   return value;
 }
 
-function requireDependency(): ReturnType<typeof probeStatus> {
-  const status = iosAgentDeviceStatus();
+function requireDependency(repoRoot?: string): ReturnType<typeof probeStatus> {
+  const status = iosAgentDeviceStatus({ repoRoot });
   if (!status.available) {
     throw new AssistantPluginError('PLUGIN_DEPENDENCY_MISSING', status.reason ?? 'A compatible agent-device provider is unavailable.', {
       retryable: false,
@@ -290,8 +404,19 @@ function requireDependency(): ReturnType<typeof probeStatus> {
   return status;
 }
 
-function capabilityProfile(): AgentDeviceCapabilityProfile {
-  return requireDependency().capabilityProfile;
+async function requireDependencyAsync(input: AssistantPluginActionExecutionInput): Promise<ReturnType<typeof probeStatus>> {
+  const status = await iosAgentDeviceActionStatus(input);
+  if (!status.available) {
+    throw new AssistantPluginError('PLUGIN_DEPENDENCY_MISSING', status.reason ?? 'A compatible agent-device provider is unavailable.', {
+      retryable: false,
+      details: status,
+    });
+  }
+  return status;
+}
+
+function capabilityProfile(repoRoot?: string): AgentDeviceCapabilityProfile {
+  return requireDependency(repoRoot).capabilityProfile;
 }
 
 function controllerRoot(input: AssistantPluginActionExecutionInput): string {
@@ -308,6 +433,37 @@ function stateDir(input: AssistantPluginActionExecutionInput, interactionId: str
   return path;
 }
 
+function physicalDeviceRuntimeRoot(input: AssistantPluginActionExecutionInput, targetId: string): string {
+  const path = join(
+    controllerRoot(input),
+    'interactions',
+    'ios-agent-device',
+    'device-runtime',
+    sanitize(targetId),
+  );
+  mkdirSync(path, { recursive: true });
+  return path;
+}
+
+function physicalDeviceRuntimeStateDir(input: AssistantPluginActionExecutionInput, targetId: string): string {
+  const path = join(physicalDeviceRuntimeRoot(input, targetId), 'state');
+  mkdirSync(path, { recursive: true });
+  return path;
+}
+
+function runtimeStateDir(input: AssistantPluginActionExecutionInput, record: InteractionSessionRecord): string {
+  // A real iPhone must not get a fresh daemon/Runner cache for every logical
+  // interaction. One stable per-device runtime owns provider metadata and any
+  // explicitly prepared semantic Runner. Simulator sessions remain isolated.
+  return record.provider === DEVICE_PROVIDER
+    ? physicalDeviceRuntimeStateDir(input, record.targetId)
+    : stateDir(input, record.interactionId);
+}
+
+function targetRuntimeStateDir(input: AssistantPluginActionExecutionInput, target: AgentDeviceEntry): string | undefined {
+  return target.kind === 'device' ? physicalDeviceRuntimeStateDir(input, target.id) : undefined;
+}
+
 function signingConfigPath(input: AssistantPluginActionExecutionInput, interactionId: string): string {
   return join(interactionRoot(input, interactionId), 'signing.json');
 }
@@ -344,27 +500,31 @@ function artifactDir(input: AssistantPluginActionExecutionInput, interactionId:
 
 function sessionEnv(input: AssistantPluginActionExecutionInput, record: InteractionSessionRecord): NodeJS.ProcessEnv {
   const config = readSigningConfig(input, record.interactionId);
-  return {
+  return withTrustedNodePath({
     ...process.env,
     ...signingEnv(config),
-    AGENT_DEVICE_STATE_DIR: stateDir(input, record.interactionId),
+    AGENT_DEVICE_STATE_DIR: runtimeStateDir(input, record),
     AGENT_DEVICE_SESSION: record.sessionId,
     AGENT_DEVICE_PLATFORM: 'ios',
     AGENT_DEVICE_SESSION_LOCK: 'reject',
-    // Keep the per-interaction daemon and a healthy XCTest runner warm between
-    // commands. The previous five-second/zero-retention policy forced repeated
-    // cold starts during ordinary multi-step device workflows.
+    // Keep the daemon and an explicitly prepared Runner warm. Physical devices
+    // share one stable runtime state directory across logical interactions;
+    // Simulator interactions remain isolated.
     AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS:
       process.env.FORGE_AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS?.trim() || DEFAULT_AGENT_DEVICE_IDLE_MS,
     AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS:
       process.env.FORGE_AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS?.trim() || DEFAULT_AGENT_DEVICE_IDLE_MS,
-  };
+  });
 }
 
-function probeEnv(input: AssistantPluginActionExecutionInput, config?: AgentDeviceSigningConfig): NodeJS.ProcessEnv {
-  const path = join(controllerRoot(input), 'interactions', 'ios-agent-device', 'probe-state');
+function probeEnv(
+  input: AssistantPluginActionExecutionInput,
+  config?: AgentDeviceSigningConfig,
+  requestedStateDir?: string,
+): NodeJS.ProcessEnv {
+  const path = requestedStateDir ?? join(controllerRoot(input), 'interactions', 'ios-agent-device', 'probe-state');
   mkdirSync(path, { recursive: true });
-  return {
+  return withTrustedNodePath({
     ...process.env,
     ...signingEnv(config),
     AGENT_DEVICE_STATE_DIR: path,
@@ -373,7 +533,7 @@ function probeEnv(input: AssistantPluginActionExecutionInput, config?: AgentDevi
       process.env.FORGE_AGENT_DEVICE_DAEMON_IDLE_TIMEOUT_MS?.trim() || DEFAULT_AGENT_DEVICE_IDLE_MS,
     AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS:
       process.env.FORGE_AGENT_DEVICE_IOS_RUNNER_IDLE_STOP_MS?.trim() || DEFAULT_AGENT_DEVICE_IDLE_MS,
-  };
+  });
 }
 
 function bounded(value: unknown): unknown {
@@ -488,14 +648,15 @@ function runJson(
   options: {
     record?: InteractionSessionRecord;
     signing?: AgentDeviceSigningConfig;
+    stateDir?: string;
     timeoutMs?: number;
     failureCode: string;
   },
 ): Record<string, unknown> {
-  const result = hooks.runCommand(executable(), args, {
+  const result = hooks.runCommand(executable(input.repoRoot), args, {
     cwd: input.repoRoot,
     timeoutMs: effectiveCommandTimeout(input, options.timeoutMs),
-    env: options.record ? sessionEnv(input, options.record) : probeEnv(input, options.signing),
+    env: options.record ? sessionEnv(input, options.record) : probeEnv(input, options.signing, options.stateDir),
     signal: input.signal,
   });
   return parseJsonResult(result, options.failureCode);
@@ -507,14 +668,15 @@ async function runJsonAsync(
   options: {
     record?: InteractionSessionRecord;
     signing?: AgentDeviceSigningConfig;
+    stateDir?: string;
     timeoutMs?: number;
     failureCode: string;
   },
 ): Promise<Record<string, unknown>> {
-  const result = await hooks.runCommandAsync(executable(), args, {
+  const result = await hooks.runCommandAsync(executable(input.repoRoot), args, {
     cwd: input.repoRoot,
     timeoutMs: effectiveCommandTimeout(input, options.timeoutMs),
-    env: options.record ? sessionEnv(input, options.record) : probeEnv(input, options.signing),
+    env: options.record ? sessionEnv(input, options.record) : probeEnv(input, options.signing, options.stateDir),
     signal: input.signal,
   });
   return parseJsonResult(result, options.failureCode);
@@ -696,7 +858,7 @@ function providerSessionAlreadyAbsent(result: CommandResult): boolean {
 }
 
 function bestEffortClose(input: AssistantPluginActionExecutionInput, record: InteractionSessionRecord): boolean {
-  const result = hooks.runCommand(executable(), ['close', '--session', record.sessionId, '--platform', 'ios', '--json'], {
+  const result = hooks.runCommand(executable(input.repoRoot), ['close', '--session', record.sessionId, '--platform', 'ios', '--json'], {
     cwd: input.repoRoot,
     timeoutMs: 30_000,
     env: sessionEnv(input, record),
@@ -716,7 +878,7 @@ async function closeProviderSession(
   record: InteractionSessionRecord,
   args: string[],
 ): Promise<{ result: Record<string, unknown>; providerAlreadyAbsent: boolean }> {
-  const commandResult = await hooks.runCommandAsync(executable(), [
+  const commandResult = await hooks.runCommandAsync(executable(input.repoRoot), [
     ...args,
     '--session', record.sessionId,
     '--platform', 'ios',
@@ -985,8 +1147,8 @@ async function executeSessionSnapshotBackend(
   let fallbackTypedVersion: string | undefined;
   let fallbackCliVersion: string | undefined;
   if (mode !== 'cli') {
-    const dependency = requireDependency();
-    const typed = new TypedAgentDeviceReadProvider();
+    const dependency = requireDependency(input.repoRoot);
+    const typed = new TypedAgentDeviceReadProvider(typedAgentDeviceIdentity({ repoRoot: input.repoRoot }));
     const versionsMatch = agentDeviceProviderVersionsMatch(
       typed.identity.version,
       dependency.detectedVersion,
@@ -1013,9 +1175,8 @@ async function executeSessionSnapshotBackend(
     } else if (typed.identity.available || mode === 'typed') {
       try {
         return await typed.snapshot({
-          stateDir: stateDir(input, record.interactionId),
+          stateDir: runtimeStateDir(input, record),
           session: record.sessionId,
-          device: record.targetId,
           platform: 'ios',
           requestId: input.requestId,
           cwd: input.repoRoot,
@@ -1052,7 +1213,7 @@ async function executeSessionSnapshotBackend(
     }
   }
 
-  const args = compileSnapshotCommand(capabilityProfile(), request);
+  const args = compileSnapshotCommand(capabilityProfile(input.repoRoot), request);
   const result = await runJsonAsync(
     input,
     [...args, '--session', record.sessionId, '--platform', 'ios', '--json'],
@@ -1378,7 +1539,7 @@ async function runSessionBatch(
   let result: unknown = await runSessionCommand(
     input,
     record,
-    compileBatchCommand(capabilityProfile(), prepared.nativeSteps, MAX_BATCH_STEPS, { includeCost: true }),
+    compileBatchCommand(capabilityProfile(input.repoRoot), prepared.nativeSteps, MAX_BATCH_STEPS, { includeCost: true }),
     'AGENT_DEVICE_BATCH_FAILED',
     timeoutMs,
   );
@@ -1395,7 +1556,7 @@ async function runSessionBatchAttempt(
   let result: unknown = await runSessionCommandAttempt(
     input,
     record,
-    compileBatchCommand(capabilityProfile(), prepared.nativeSteps, MAX_BATCH_STEPS, { includeCost: true }),
+    compileBatchCommand(capabilityProfile(input.repoRoot), prepared.nativeSteps, MAX_BATCH_STEPS, { includeCost: true }),
     'AGENT_DEVICE_BATCH_FAILED',
     timeoutMs,
   );
@@ -1817,7 +1978,7 @@ async function executeJdSearch(input: AssistantPluginActionExecutionInput): Prom
       // The current batch schema supports only status/dismiss, so Return stays
       // a separate provider command, but only when the negotiated contract
       // explicitly advertises it.
-      if (!capabilityProfile().keyboard.returnSupported) {
+      if (!capabilityProfile(input.repoRoot).keyboard.returnSupported) {
         return failWorkflowSession(input, record, new AssistantPluginError(
           'PLUGIN_ACTION_NOT_SUPPORTED',
           'The detected agent-device contract does not support keyboard Return.',
@@ -1921,7 +2082,7 @@ export function iosAgentDeviceCapabilities(): AssistantPluginCapability[] {
     {
       capabilityId: 'ios-agent-device-physical',
       title: 'agent-device physical iPhone',
-      description: 'Optional signed, capability-negotiated agent-device XCTest sessions for one exact connected physical iPhone.',
+      description: 'Opt-in XCTest accessibility fallback for one exact physical iPhone. CoreDevice/RemoteXPC is the default physical-device path. Do not use agent-device for ordinary profile/form editing, Unicode text entry, screenshots, or known-coordinate interaction; use the physical-device provider and its batch fast path instead. Prepare XCTest only when semantic AX inspection is genuinely required.',
       scopes: ['ios.discover', 'ios.device'],
       actions,
     },
@@ -1935,7 +2096,7 @@ export function iosAgentDeviceActions(): AssistantPluginActionDescriptor[] {
     { resource: 'repo-state' as const, mode: 'write' as const },
   ];
   const interactionProperty = { interaction_id: { type: 'string' } };
-  return [
+  const actions: AssistantPluginActionDescriptor[] = [
     {
       actionId: 'agent_device_status', title: 'agent-device status',
       description: 'Resolve the exact executable and verify a reviewed agent-device command contract.',
@@ -1950,8 +2111,8 @@ export function iosAgentDeviceActions(): AssistantPluginActionDescriptor[] {
       argumentsSchema: { type: 'object', properties: { app: { type: 'string' }, device: { type: 'string' }, team_id: { type: 'string' }, runner_bundle_id: { type: 'string' }, developer_dir: { type: 'string' } }, additionalProperties: false },
     },
     {
-      actionId: 'agent_device_prepare', title: 'Prepare signed iOS Runner',
-      description: 'Build, sign, install and health-check the agent-device XCTest Runner for one exact iOS target.',
+      actionId: 'agent_device_prepare', title: 'Prepare semantic XCTest fallback',
+      description: 'Explicitly build, sign, install and health-check the agent-device XCTest Runner. This is a heavy semantic fallback, not the normal physical-iPhone form-edit path. Physical-device preparation uses one stable per-device runtime so repeated semantic interactions can reuse it.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 10 * 60_000, cancellable: true, idempotent: false,
       scopes: ['ios.discover', 'ios.simulator', 'ios.device'], resourceClaims: write,
       argumentsSchema: {
@@ -1961,7 +2122,7 @@ export function iosAgentDeviceActions(): AssistantPluginActionDescriptor[] {
     },
     {
       actionId: 'agent_device_open', title: 'Open agent-device iOS session',
-      description: 'Open an app on one exact connected physical iPhone or already-booted iOS Simulator.',
+      description: 'Open an agent-device semantic session on one exact physical iPhone or booted Simulator. On physical iPhone this may start/reconnect an XCTest Runner; prefer physical_device_open plus physical_device_batch for ordinary app navigation and profile/form edits.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 4 * 60_000, cancellable: true, idempotent: false,
       scopes: ['ios.simulator', 'ios.device'], resourceClaims: write,
       argumentsSchema: {
@@ -1971,7 +2132,7 @@ export function iosAgentDeviceActions(): AssistantPluginActionDescriptor[] {
     },
     {
       actionId: 'agent_device_batch', title: 'Run fast typed iOS action batch',
-      description: `Run up to ${MAX_BATCH_STEPS} allowlisted session steps in one agent-device process and one daemon request. Mutating steps always settle before the next step.`,
+      description: `Run up to ${MAX_BATCH_STEPS} semantic AX steps in one agent-device process and one daemon request. Mutating steps settle before the next step. On a physical iPhone, use this only when accessibility semantics are required; known-coordinate/form workflows should use physical_device_batch to avoid XCTest lifecycle cost.`,
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 2 * 60_000, cancellable: true, idempotent: false,
       scopes: ['ios.simulator', 'ios.device'], resourceClaims: write,
       argumentsSchema: {
@@ -2023,7 +2184,7 @@ export function iosAgentDeviceActions(): AssistantPluginActionDescriptor[] {
     },
     {
       actionId: 'agent_device_press', title: 'Press agent-device target',
-      description: 'Press one ref, selector, or explicit coordinate pair and return a settled bounded diff.',
+      description: 'Press one ref, selector, or explicit coordinate pair. Semantic targets return a settled bounded diff; explicit coordinates bypass accessibility settle for heavy-screen recovery.',
       readOnly: false, risk: 'workspace_write', confirmation: 'authorization', defaultTimeoutMs: 60_000, cancellable: true, idempotent: false,
       scopes: ['ios.simulator', 'ios.device'], resourceClaims: write,
       argumentsSchema: { type: 'object', properties: { ...interactionProperty, target: { type: 'string' }, x: { type: 'number' }, y: { type: 'number' } }, required: ['interaction_id'], additionalProperties: false },
@@ -2064,13 +2225,16 @@ export function iosAgentDeviceActions(): AssistantPluginActionDescriptor[] {
       argumentsSchema: { type: 'object', properties: { ...interactionProperty, shutdown_simulator: { type: 'boolean' } }, required: ['interaction_id'], additionalProperties: false },
     },
   ];
+  return actions.map((action) => action.readOnly
+    ? action
+    : { ...action, executionMode: 'lightweight_process' });
 }
 
 export async function executeIosAgentDeviceAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>> {
   if (input.deadlineAtMs === undefined && typeof input.timeoutMs === 'number' && Number.isFinite(input.timeoutMs)) {
     input = { ...input, deadlineAtMs: Date.now() + Math.max(1, Math.trunc(input.timeoutMs)) };
   }
-  if (input.actionId === 'agent_device_status') return { provider: 'agent-device', ...iosAgentDeviceStatus() };
+  if (input.actionId === 'agent_device_status') return { provider: 'agent-device', ...await iosAgentDeviceActionStatus(input) };
   if (input.actionId === 'agent_device_close') {
     const interactionId = requireString(input.args.interaction_id, 'interaction_id');
     const existing = readAgentDeviceInteraction(input.repoRoot, interactionId);
@@ -2078,7 +2242,7 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
       return { provider: 'agent-device', interaction: existing, alreadyClosed: true };
     }
   }
-  const dependency = requireDependency();
+  const dependency = await requireDependencyAsync(input);
 
   if (input.actionId === 'agent_device_jd_search') return executeJdSearch(input);
 
@@ -2096,6 +2260,7 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
       physicalDeviceSupported: selected.kind === 'device',
       result: bounded(await runJsonAsync(input, args, {
         signing: signingFromArgs(input.args),
+        stateDir: targetRuntimeStateDir(input, selected),
         failureCode: 'AGENT_DEVICE_DOCTOR_FAILED',
         timeoutMs: 4 * 60_000,
       })),
@@ -2115,6 +2280,7 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
         'prepare', 'ios-runner', '--platform', 'ios', '--device', selected.name, '--timeout', '600000', '--json',
       ], {
         signing,
+        stateDir: targetRuntimeStateDir(input, selected),
         failureCode: 'AGENT_DEVICE_PREPARE_FAILED',
         timeoutMs: 10 * 60_000,
       })),
@@ -2223,11 +2389,15 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
       if (record.provider === DEVICE_PROVIDER && target && SENSITIVE_SEMANTICS.test(target)) {
         throw new AssistantPluginError('IOS_DEVICE_SENSITIVE_ACTION_BLOCKED', 'Press targets involving credentials, verification, biometrics, checkout, purchase or payment require human interaction.', { retryable: false });
       }
-      const args = appendSettleFlag(
-        capabilityProfile(),
-        ['press', ...(target ? [target] : [String(input.args.x), String(input.args.y)])],
-        'press',
-      );
+      const baseArgs = ['press', ...(target ? [target] : [String(input.args.x), String(input.args.y)])];
+      // Explicit coordinate presses are the bounded fallback for screens whose
+      // accessibility tree is too heavy or animated to snapshot reliably.
+      // Settling forces an AX snapshot after the mutation, defeating that
+      // fallback and can recycle/wedge the XCTest runner. Keep semantic target
+      // presses settled, but let explicit points complete without AX capture.
+      const args = target
+        ? appendSettleFlag(capabilityProfile(input.repoRoot), baseArgs, 'press')
+        : baseArgs;
       return { provider: 'agent-device', interaction: record, result: bounded(await runSessionCommand(input, record, args, 'AGENT_DEVICE_PRESS_FAILED')) };
     }
     case 'agent_device_fill': {
@@ -2237,7 +2407,7 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
       if (record.provider === DEVICE_PROVIDER && (SENSITIVE_SEMANTICS.test(target) || SENSITIVE_SEMANTICS.test(text))) {
         throw new AssistantPluginError('IOS_DEVICE_SENSITIVE_ACTION_BLOCKED', 'Sensitive text and credential, verification, checkout, purchase or payment targets require human interaction.', { retryable: false });
       }
-      const profile = capabilityProfile();
+      const profile = capabilityProfile(input.repoRoot);
       const args = appendSettleFlag(profile, ['fill', target, text]);
       if (typeof input.args.delay_ms === 'number') {
         if (!profile.fill.delayFlag) {