@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/plugins/ios/remote-xpc-hid.ts

@@ -6,15 +6,16 @@ import { createInterface } from 'readline';
 import { performance } from 'perf_hooks';
 import { AssistantPluginError } from '../errors';
 
-const TOOLCHAIN_VERSION = '10.2.1';
+export const IOS_HID_TOOLCHAIN_VERSION = '11.24.0';
 const WORKER_IDLE_MS = 15 * 60_000;
 const WORKER_STARTUP_MS = 12_000;
-const MUTATION_READY_BUDGET_MS = 2_500;
 const REQUEST_TIMEOUT_MS = 12_000;
 const RSD_ENDPOINT_CACHE_TTL_MS = 30_000;
 const RSD_ENDPOINT_PERSISTED_TTL_MS = 10 * 60_000;
 const MAX_TEXT_LENGTH = 2048;
 const MAX_STDERR = 8 * 1024;
+const TOOLCHAIN_PROBE_TTL_MS = 60_000;
+const TOOLCHAIN_PROBE_TIMEOUT_MS = 5_000;
 
 export interface RemoteXpcHidInput {
   controllerHome: string;
@@ -99,6 +100,7 @@ const warmups = new Map<string, Promise<void>>();
 const workerGenerations = new Map<string, number>();
 const warmupFailures = new Map<string, WarmupFailure>();
 const endpointCache = new Map<string, EndpointCacheEntry>();
+const toolchainProbeCache = new Map<string, { checkedAt: number; installedVersion?: string; available: boolean; reason?: string }>();
 
 export function setRemoteXpcHidExecutorForTest(executor: TestExecutor | undefined): void {
   testExecutor = executor;
@@ -112,26 +114,71 @@ export function resetRemoteXpcHidForTest(): void {
   workerGenerations.clear();
   warmupFailures.clear();
   endpointCache.clear();
+  toolchainProbeCache.clear();
 }
 
-export function remoteXpcHidStatus(controllerHome: string, env: NodeJS.ProcessEnv = process.env): Record<string, unknown> {
+const TOOLCHAIN_PROBE_SCRIPT = [
+  'from importlib.metadata import version',
+  'from pymobiledevice3.remote.remote_service_discovery import RemoteServiceDiscoveryService',
+  'from pymobiledevice3.remote.core_device.pasteboard_service import PasteboardService',
+  'from pymobiledevice3.remote.core_device.hid_service import UniversalHIDServiceService, touch_session',
+  "print(version('pymobiledevice3'))",
+].join('; ');
+
+function probeHidToolchain(python: string): { installedVersion?: string; available: boolean; reason?: string } {
+  const cached = toolchainProbeCache.get(python);
+  if (cached && Date.now() - cached.checkedAt <= TOOLCHAIN_PROBE_TTL_MS) return cached;
+  const result = spawnSync(python, ['-c', TOOLCHAIN_PROBE_SCRIPT], {
+    encoding: 'utf8', timeout: TOOLCHAIN_PROBE_TIMEOUT_MS, maxBuffer: 8 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const installedVersion = typeof result.stdout === 'string' ? result.stdout.trim() : undefined;
+  const available = result.status === 0 && installedVersion === IOS_HID_TOOLCHAIN_VERSION && !result.error;
+  const reason = available ? undefined : result.error?.message ?? (result.status === 0
+    ? `Expected pymobiledevice3 ${IOS_HID_TOOLCHAIN_VERSION}, found ${installedVersion || 'unknown'}.`
+    : `pymobiledevice3 import/version probe failed (exit ${result.status ?? 'unknown'}).`);
+  const probe = { checkedAt: Date.now(), installedVersion, available, reason };
+  // A failed probe is not durable: an explicitly authorized installer may
+  // finish immediately afterward without requiring a Runtime restart.
+  if (available) toolchainProbeCache.set(python, probe);
+  else toolchainProbeCache.delete(python);
+  return probe;
+}
+
+function hidToolchainStatus(controllerHome: string, env: NodeJS.ProcessEnv, allowProbe: boolean): Record<string, unknown> {
   const python = resolvePython(controllerHome, env);
+  const cached = python ? toolchainProbeCache.get(python) : undefined;
+  const validCached = cached?.available === true && Date.now() - cached.checkedAt <= TOOLCHAIN_PROBE_TTL_MS
+    ? cached : undefined;
+  const probe = python ? (allowProbe ? probeHidToolchain(python) : validCached) : undefined;
   return {
     backend: 'remote-xpc-hid',
-    available: Boolean(python),
+    available: probe?.available === true,
     python,
-    toolchainVersion: TOOLCHAIN_VERSION,
+    toolchainVersion: IOS_HID_TOOLCHAIN_VERSION,
+    ...(probe?.installedVersion ? { installedVersion: probe.installedVersion } : {}),
+    ...(probe?.reason ? { reason: probe.reason } : {}),
     transport: 'macos-trusted-coredevice-rsd',
     runnerOwned: false,
   };
 }
 
+// Manifest reads are passive: only an explicit HID action may start Python.
+// This is a view of the same short-lived successful probe cache, not a second
+// readiness authority or a durable grant.
+export function remoteXpcHidCachedStatus(controllerHome: string, env: NodeJS.ProcessEnv = process.env): Record<string, unknown> {
+  return hidToolchainStatus(controllerHome, env, false);
+}
+
+export function remoteXpcHidStatus(controllerHome: string, env: NodeJS.ProcessEnv = process.env): Record<string, unknown> {
+  return hidToolchainStatus(controllerHome, env, true);
+}
+
 function resolvePython(controllerHome: string, env: NodeJS.ProcessEnv): string | undefined {
   const explicit = env.FORGE_IOS_HID_PYTHON?.trim();
   const candidates = [
     explicit,
-    join(controllerHome, 'toolchains', `pymobiledevice3-${TOOLCHAIN_VERSION}-py39`, 'bin', 'python'),
-    join(controllerHome, 'toolchains', `pymobiledevice3-${TOOLCHAIN_VERSION}`, 'bin', 'python'),
+    join(controllerHome, 'toolchains', `pymobiledevice3-${IOS_HID_TOOLCHAIN_VERSION}`, 'bin', 'python'),
   ].filter((value): value is string => Boolean(value));
   return candidates.find((candidate) => existsSync(candidate));
 }
@@ -143,6 +190,7 @@ import asyncio
 import json
 import sys
 import time
+from importlib.metadata import version as package_version
 
 from pymobiledevice3.remote.remote_service_discovery import RemoteServiceDiscoveryService
 from pymobiledevice3.remote.core_device.pasteboard_service import PasteboardService
@@ -222,7 +270,11 @@ async def main():
     parser = argparse.ArgumentParser()
     parser.add_argument('--host', required=True)
     parser.add_argument('--port', required=True, type=int)
+    parser.add_argument('--expected-version', required=True)
     args = parser.parse_args()
+    actual_version = package_version('pymobiledevice3')
+    if actual_version != args.expected_version:
+        raise RuntimeError(f'RemoteXPC HID pymobiledevice3 version mismatch: {actual_version} != {args.expected_version}')
     async with RemoteServiceDiscoveryService((args.host, args.port)) as rsd:
         async with touch_session(rsd) as hid:
             connected = await hid.list_connected_services()
@@ -743,11 +795,12 @@ export function stopRemoteXpcHidForDevice(deviceIdentifier: string): Record<stri
 }
 
 function startWorker(input: Pick<RemoteXpcHidInput, 'controllerHome' | 'deviceIdentifier'>, endpoint: RsdEndpoint): WorkerRecord {
-  const python = resolvePython(input.controllerHome, process.env);
+  const status = remoteXpcHidStatus(input.controllerHome);
+  const python = status.available === true && typeof status.python === 'string' ? status.python : undefined;
   if (!python) {
-    throw new AssistantPluginError('IOS_HID_TOOLCHAIN_MISSING', `The Controller-owned pymobiledevice3 ${TOOLCHAIN_VERSION} toolchain is unavailable.`, {
+    throw new AssistantPluginError('IOS_HID_TOOLCHAIN_MISSING', `The Controller-owned pymobiledevice3 ${IOS_HID_TOOLCHAIN_VERSION} toolchain is unavailable or incompatible.`, {
       retryable: false,
-      details: { expected: join(input.controllerHome, 'toolchains', `pymobiledevice3-${TOOLCHAIN_VERSION}-py39`, 'bin', 'python') },
+      details: { expected: join(input.controllerHome, 'toolchains', `pymobiledevice3-${IOS_HID_TOOLCHAIN_VERSION}`, 'bin', 'python'), reason: status.reason },
     });
   }
   const script = materializeWorker(input.controllerHome);
@@ -756,6 +809,7 @@ function startWorker(input: Pick<RemoteXpcHidInput, 'controllerHome' | 'deviceId
     '-u', script,
     '--host', endpoint.host,
     '--port', String(endpoint.port),
+    '--expected-version', IOS_HID_TOOLCHAIN_VERSION,
   ], {
     stdio: ['pipe', 'pipe', 'pipe'],
     env: {
@@ -1089,23 +1143,11 @@ async function waitForMutationWorker(
   }
   const current = workers.get(input.deviceIdentifier);
   const warmup = warmups.get(input.deviceIdentifier);
-  const readiness = current
-    ? current.ready.then(() => undefined).catch(() => undefined)
-    : warmup;
-  if (readiness) {
-    let timer: NodeJS.Timeout | undefined;
-    try {
-      await Promise.race([
-        readiness,
-        new Promise<void>((resolve) => {
-          timer = setTimeout(resolve, MUTATION_READY_BUDGET_MS);
-          timer.unref?.();
-        }),
-      ]);
-    } finally {
-      if (timer) clearTimeout(timer);
-    }
-  }
+  // Plugin actions use separate managed processes. A detached prewarm cannot
+  // survive its owning action, so the first real mutation must finish its own
+  // endpoint discovery and worker startup rather than time out and retry cold.
+  const readiness = warmup ?? current?.ready.then(() => undefined).catch(() => undefined);
+  if (readiness) await readiness;
   const waitMs = Math.round((performance.now() - startedAt) * 100) / 100;
   const worker = workers.get(input.deviceIdentifier);
   if (!worker || worker.readyState !== 'ready') {
@@ -1115,15 +1157,13 @@ async function waitForMutationWorker(
     }
     throw new AssistantPluginError(
       'IOS_HID_INPUT_NOT_READY',
-      `RemoteXPC HID is still warming after the ${MUTATION_READY_BUDGET_MS}ms mutation readiness budget. No input was sent; retry the same action after prewarm completes.`,
+      'RemoteXPC HID worker did not reach ready state in this action. No input was sent.',
       {
         retryable: true,
         details: {
           deviceIdentifier: input.deviceIdentifier,
           mutationDispatched: false,
           workerReadyWaitMs: waitMs,
-          readinessBudgetMs: MUTATION_READY_BUDGET_MS,
-          prewarmContinues: warmups.has(input.deviceIdentifier) || worker?.readyState === 'starting',
         },
       },
     );

package/src/runtime/plugins/ios-adapter.ts

@@ -33,14 +33,7 @@ import {
   iosAgentDeviceStatus,
   isIosAgentDeviceAction,
 } from './ios-agent-device';
-import {
-  executeIosPhysicalDeviceAction,
-  iosPhysicalDeviceActions,
-  iosPhysicalDeviceCapabilities,
-  iosPhysicalDeviceStatus,
-  isIosPhysicalDeviceAction,
-  resolveIosPhysicalDeviceAuthorizationContext,
-} from './ios-physical-device';
+import { iosPhysicalDeviceStatus, isIosPhysicalDeviceAction } from './ios-physical-device';
 
 const IOS_PLUGIN_ID = 'ios';
 
@@ -99,26 +92,36 @@ function health(repoRoot: string): AssistantPluginHealth {
   } as RepositoryRecord);
   const currentPlatform = iosDevelopmentPlatform();
   const platformOk = currentPlatform === 'darwin';
-  const toolingReady = platformOk && Boolean(xcode && 'ready' in xcode && xcode.ready);
+  const developmentReady = platformOk && Boolean(xcode && 'ready' in xcode && xcode.ready);
+  const physicalDevice = iosPhysicalDeviceStatus();
+  const physicalReady = platformOk && physicalDevice.coreDeviceReady;
+  const agentDevice = iosAgentDeviceStatus({ repoRoot });
+  const semanticReady = agentDevice.available === true;
+  const pluginReady = platformOk && (developmentReady || physicalReady || semanticReady);
   const warnings: string[] = [];
-  if (!platformOk) warnings.push('iOS plugin requires macOS with Xcode and Simulator.');
-  if (platformOk && !xcodeSnapshot.probed) warnings.push('Xcode/simctl readiness has not been explicitly probed in this runtime yet.');
-  else if (platformOk && !toolingReady) warnings.push('Xcode/simctl is not fully ready on this host.');
+  if (!platformOk) warnings.push('iOS capabilities require a macOS host.');
+  if (platformOk && !developmentReady) warnings.push('Xcode/Simulator development capability is not fully ready on this host.');
+  if (platformOk && !physicalReady) warnings.push('CoreDevice physical-iPhone capability is not ready on this host.');
   if (!discovery.ready) warnings.push('No .xcworkspace/.xcodeproj/Package.swift discovered in this repository yet.');
-  const status = userFacingStatusFrom(toolingReady, discovery.ready, Boolean(xcode && 'simctlAvailable' in xcode && xcode.simctlAvailable));
+  const status = userFacingStatusFrom(developmentReady, discovery.ready, Boolean(xcode && 'simctlAvailable' in xcode && xcode.simctlAvailable), physicalReady);
   return {
-    state: !platformOk ? 'disabled' : toolingReady ? 'ready' : 'degraded',
+    state: !platformOk ? 'disabled' : pluginReady ? 'ready' : 'degraded',
     checkedAt: now(),
-    ready: toolingReady,
-    probed: xcodeSnapshot.probed,
+    ready: pluginReady,
+    probed: xcodeSnapshot.probed || physicalDevice.probed || Boolean(agentDevice.available),
     errors: [],
     warnings,
     details: {
-      provider: 'local-xcode',
+      provider: 'local-ios',
       platform: currentPlatform,
       userFacingStatus: status,
       discoverable: discovery.ready,
       defaultContainer: discovery.defaultContainer,
+      capabilities: {
+        development: developmentReady,
+        physicalDevice: physicalReady,
+        semanticAgentDevice: semanticReady,
+      },
       xcode: xcode && 'ready' in xcode ? {
         ready: xcode.ready,
         xcodeSelectPath: 'xcodeSelectPath' in xcode ? xcode.xcodeSelectPath : undefined,
@@ -127,8 +130,8 @@ function health(repoRoot: string): AssistantPluginHealth {
         probed: xcodeSnapshot.probed,
         cached: xcodeSnapshot.cached,
       } : xcode,
-      agentDevice: iosAgentDeviceStatus({ repoRoot }),
-      physicalDevice: iosPhysicalDeviceStatus(),
+      agentDevice,
+      physicalDevice,
       artifactRoots: {
         repoLocal: '.forge/ios/',
         controller: 'controller-home/repositories/<repoId>/artifacts/ios/',
@@ -137,21 +140,22 @@ function health(repoRoot: string): AssistantPluginHealth {
   };
 }
 
-function userFacingStatusFrom(toolingReady: boolean, discoverable: boolean, simReady: boolean): string {
-  if (!toolingReady && !discoverable) return 'not_configured';
-  if (discoverable && toolingReady && simReady) return 'buildable';
+function userFacingStatusFrom(toolingReady: boolean, discoverable: boolean, simReady: boolean, physicalReady: boolean): string {
+  if (!toolingReady && !physicalReady && !discoverable) return 'not_configured';
+  if (toolingReady && discoverable && simReady) return 'buildable';
+  if (physicalReady && !toolingReady) return 'physical_device_ready';
   if (toolingReady && simReady) return 'simulator_ready';
   if (discoverable) return 'discoverable';
-  if (toolingReady) return 'simulator_ready';
+  if (physicalReady) return 'physical_device_ready';
   return 'not_configured';
 }
 
-function permissions(ready: boolean): AssistantPluginPermissionScope[] {
+function permissions(input: { developmentReady: boolean; physicalReady: boolean }): AssistantPluginPermissionScope[] {
   return [
-    { scope: 'ios.discover', mode: 'read', description: 'Discover Xcode projects, schemes, and simulator inventory.', granted: ready, required: true },
-    { scope: 'ios.build', mode: 'write', description: 'Build iOS app targets into bounded DerivedData.', granted: ready, required: true },
-    { scope: 'ios.simulator', mode: 'write', description: 'Boot simulators, install, launch, screenshot, and collect logs.', granted: ready, required: true },
-    { scope: 'ios.device', mode: 'write', description: 'Inspect and operate an exact paired physical iPhone through CoreDevice; optional XCTest semantics are isolated in the agent-device fallback.', granted: ready, required: false },
+    { scope: 'ios.discover', mode: 'read', description: 'Discover iOS projects and paired physical devices.', granted: input.developmentReady || input.physicalReady, required: true },
+    { scope: 'ios.build', mode: 'write', description: 'Build iOS app targets into bounded DerivedData.', granted: input.developmentReady, required: true },
+    { scope: 'ios.simulator', mode: 'write', description: 'Boot simulators, install, launch, screenshot, and collect logs.', granted: input.developmentReady, required: true },
+    { scope: 'ios.device', mode: 'write', description: 'Explicit paired-iPhone development/XCTest actions; everyday CoreDevice app interaction belongs to Computer.', granted: input.physicalReady, required: false },
   ];
 }
 
@@ -172,7 +176,6 @@ function capabilities(): AssistantPluginCapability[] {
       actions: ['smoke_review', 'build', 'xcode_test', 'launch_simulator', 'capture_screenshot'],
     },
     ...iosAgentDeviceCapabilities(),
-    ...iosPhysicalDeviceCapabilities(),
   ];
 }
 
@@ -345,7 +348,7 @@ function actions(): AssistantPluginActionDescriptor[] {
       description: 'Capture a simulator screenshot into controller artifact storage.',
       readOnly: false,
       risk: 'workspace_write',
-      confirmation: 'none',
+      confirmation: 'authorization',
       defaultTimeoutMs: 60_000,
       cancellable: true,
       idempotent: false,
@@ -395,7 +398,6 @@ function actions(): AssistantPluginActionDescriptor[] {
       },
     },
     ...iosAgentDeviceActions(),
-    ...iosPhysicalDeviceActions(),
   ];
 }
 
@@ -408,7 +410,7 @@ export function buildIosPluginManifest(previousRevision = 0, previousUpdatedAt?:
     revision: Math.max(1, previousRevision || 1),
     pluginId: IOS_PLUGIN_ID,
     provider: 'apple-local',
-    displayName: 'iOS Development Plugin',
+    displayName: 'iOS Development / Simulator / XCTest',
     pluginVersion: '1.0.0',
     authority: {
       strategy: 'derived',
@@ -419,13 +421,16 @@ export function buildIosPluginManifest(previousRevision = 0, previousUpdatedAt?:
     lifecycle: {
       state: !enabled ? 'disabled' : state.ready ? 'enabled' : 'degraded',
       reason: !enabled
-        ? 'iOS plugin is only available on macOS hosts.'
+        ? 'iOS capabilities are only available on macOS hosts.'
         : state.ready
-          ? 'Xcode and Simulator tooling are ready.'
-          : state.warnings[0] ?? 'iOS tooling is partially available.',
+          ? 'At least one iOS development or physical-device capability is ready.'
+          : state.warnings[0] ?? 'iOS capabilities are partially available.',
     },
     health: state,
-    permissions: permissions(state.ready),
+    permissions: permissions({
+      developmentReady: Boolean(state.details?.capabilities && typeof state.details.capabilities === 'object' && (state.details.capabilities as Record<string, unknown>).development === true),
+      physicalReady: Boolean(state.details?.capabilities && typeof state.details.capabilities === 'object' && (state.details.capabilities as Record<string, unknown>).physicalDevice === true),
+    }),
     capabilities: capabilities(),
     actions: actions(),
     updatedAt: previousUpdatedAt ?? now(),
@@ -434,7 +439,9 @@ export function buildIosPluginManifest(previousRevision = 0, previousUpdatedAt?:
 
 export async function executeIosPluginAction(input: AssistantPluginActionExecutionInput): Promise<Record<string, unknown>> {
   if (isIosAgentDeviceAction(input.actionId)) return executeIosAgentDeviceAction(input);
-  if (isIosPhysicalDeviceAction(input.actionId)) return executeIosPhysicalDeviceAction(input);
+  if (isIosPhysicalDeviceAction(input.actionId)) {
+    throw new AssistantPluginError('PLUGIN_ACTION_NOT_SUPPORTED', `Physical iPhone app actions are available only through computer/${input.actionId}.`, { retryable: false });
+  }
   const currentPlatform = iosDevelopmentPlatform();
   if (currentPlatform !== 'darwin' && input.actionId !== 'discover_project' && input.actionId !== 'xcode_status') {
     throw new AssistantPluginError('PLUGIN_DEPENDENCY_MISSING', 'iOS plugin actions require macOS with Xcode/Simulator.', {
@@ -590,9 +597,7 @@ export async function executeIosPluginAction(input: AssistantPluginActionExecuti
 export const iosPluginAdapter = {
   pluginId: IOS_PLUGIN_ID,
   buildManifest: buildIosPluginManifest,
-  resolveAuthorizationContext: async (input: AssistantPluginActionExecutionInput) => {
-    if (!isIosPhysicalDeviceAction(input.actionId)) return undefined;
-    return resolveIosPhysicalDeviceAuthorizationContext(input);
-  },
+  // CoreDevice actions are public only through the Computer manifest; Xcode and XCTest stay here.
+  resolveAuthorizationContext: async () => undefined,
   executeAction: executeIosPluginAction,
 };

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

@@ -8,6 +8,7 @@ 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 { ensureIosDeviceOwnership, releaseIosDeviceOwnership, withIosDeviceTransientOwnership } from './ios-device-ownership';
 import {
   interactionAutomationEngine,
   interactionMayOwnTarget,
@@ -734,6 +735,15 @@ function providerForDevice(device: AgentDeviceEntry): InteractionProvider {
   return device.kind === 'simulator' ? SIMULATOR_PROVIDER : DEVICE_PROVIDER;
 }
 
+async function runPhysicalDeviceCommand<T>(
+  input: AssistantPluginActionExecutionInput,
+  device: AgentDeviceEntry,
+  operation: () => Promise<T>,
+): Promise<T> {
+  if (device.kind !== 'device') return operation();
+  return withIosDeviceTransientOwnership(input.controllerHome, input.repoId, input.requestId, device.id, operation);
+}
+
 function selectTarget(input: AssistantPluginActionExecutionInput, selector?: string): AgentDeviceEntry {
   const inventory = devices(input);
   const normalizedSelector = selector?.trim().toLocaleLowerCase('en-US');
@@ -835,12 +845,26 @@ function requireRecord(input: AssistantPluginActionExecutionInput, allowTerminal
         status: 'closing',
         error: { code: 'AGENT_DEVICE_CLEANUP_FAILED', message: 'The expired agent-device session could not be closed; ownership remains fenced.' },
       });
+    if (record.provider === DEVICE_PROVIDER && closed) releaseIosDeviceOwnership(input.controllerHome, record.owner.repoId, interactionId, record.targetId);
     throw new AssistantPluginError(
       closed ? 'AGENT_DEVICE_SESSION_EXPIRED' : 'AGENT_DEVICE_CLEANUP_FAILED',
       closed ? 'The agent-device session expired and was closed.' : 'The expired agent-device session could not be closed; retry agent_device_close.',
       { retryable: !closed },
     );
   }
+  if (record.provider === DEVICE_PROVIDER) {
+    const ownership = ensureIosDeviceOwnership(input.controllerHome, input.repoId, interactionId, record.targetId);
+    if (!ownership.acquired) {
+      throw new AssistantPluginError('PLUGIN_RESOURCE_BUSY', 'The selected iPhone is already owned by another active Forge interaction.', {
+        retryable: true,
+        details: { interactionId, targetId: record.targetId, blocker: ownership.blocker },
+      });
+    }
+    const active = patchInteractionSession(input.repoRoot, record.provider, interactionId, {
+      expiresAt: new Date(hooks.now().getTime() + SESSION_EXPIRY_MS).toISOString(),
+    });
+    if (active) return active;
+  }
   return record;
 }
 
@@ -915,6 +939,7 @@ function reconcileExpiredSessions(input: AssistantPluginActionExecutionInput): v
         status: 'closing',
         error: { code: 'AGENT_DEVICE_CLEANUP_FAILED', message: 'The expired agent-device session could not be closed; ownership remains fenced.' },
       });
+    if (record.provider === DEVICE_PROVIDER && closed) releaseIosDeviceOwnership(input.controllerHome, record.owner.repoId, record.interactionId, record.targetId);
   }
 }
 
@@ -934,6 +959,7 @@ function failSession(input: AssistantPluginActionExecutionInput, record: Interac
       status: 'closing',
       error: { code: 'AGENT_DEVICE_CLEANUP_FAILED', message: `${normalized.message}; cleanup failed and ownership remains fenced.` },
     });
+  if (closed && record.provider === DEVICE_PROVIDER) releaseIosDeviceOwnership(input.controllerHome, record.owner.repoId, record.interactionId, record.targetId);
   if (!closed) {
     throw new AssistantPluginError('AGENT_DEVICE_CLEANUP_FAILED', 'The agent-device action failed and its session could not be closed; retry agent_device_close.', {
       retryable: true,
@@ -2258,12 +2284,12 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
       contractFingerprint: dependency.capabilityProfile.contractFingerprint,
       device: selected,
       physicalDeviceSupported: selected.kind === 'device',
-      result: bounded(await runJsonAsync(input, args, {
+      result: bounded(await runPhysicalDeviceCommand(input, selected, () => runJsonAsync(input, args, {
         signing: signingFromArgs(input.args),
         stateDir: targetRuntimeStateDir(input, selected),
         failureCode: 'AGENT_DEVICE_DOCTOR_FAILED',
         timeoutMs: 4 * 60_000,
-      })),
+      }))),
     };
   }
 
@@ -2276,14 +2302,14 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
       contractFingerprint: dependency.capabilityProfile.contractFingerprint,
       device: selected,
       physicalDeviceSupported: selected.kind === 'device',
-      result: bounded(await runJsonAsync(input, [
+      result: bounded(await runPhysicalDeviceCommand(input, selected, () => runJsonAsync(input, [
         '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,
-      })),
+      }))),
     };
   }
 
@@ -2298,6 +2324,19 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
     const conflict = listInteractionSessions(input.repoRoot, provider).find((entry) =>
       isInteractionSessionActive(entry.status) && interactionMayOwnTarget(entry, selected.aliases));
     if (conflict) {
+      if (selected.kind === 'device' && provider === DEVICE_PROVIDER && conflict.instructions === app && input.args.relaunch !== true) {
+        const ownership = ensureIosDeviceOwnership(input.controllerHome, input.repoId, conflict.interactionId, selected.id);
+        if (!ownership.acquired) {
+          throw new AssistantPluginError('PLUGIN_RESOURCE_BUSY', 'The selected iPhone is already owned by another active Forge interaction.', {
+            retryable: true,
+            details: { interactionId: conflict.interactionId, targetId: conflict.targetId, blocker: ownership.blocker },
+          });
+        }
+        const active = patchInteractionSession(input.repoRoot, provider, conflict.interactionId, {
+          expiresAt: new Date(hooks.now().getTime() + SESSION_EXPIRY_MS).toISOString(),
+        }) ?? conflict;
+        return { provider: 'agent-device', version: dependency.detectedVersion ?? IOS_AGENT_DEVICE_VERSION, contractFingerprint: dependency.capabilityProfile.contractFingerprint, interaction: active, device: selected, physicalDeviceSupported: true, reusedSession: true };
+      }
       throw new AssistantPluginError('PLUGIN_RESOURCE_BUSY', 'The selected iOS target already has an active interaction.', {
         retryable: true,
         details: {
@@ -2310,6 +2349,15 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
     }
     pruneInteractionSessions(input.repoRoot, provider, 100);
     const interactionId = `ios_agent_device_${randomUUID()}`;
+    if (selected.kind === 'device') {
+      const ownership = ensureIosDeviceOwnership(input.controllerHome, input.repoId, interactionId, selected.id);
+      if (!ownership.acquired) {
+        throw new AssistantPluginError('PLUGIN_RESOURCE_BUSY', 'The selected iPhone is already owned by another active Forge interaction.', {
+          retryable: true,
+          details: { interactionId, targetId: selected.id, blocker: ownership.blocker },
+        });
+      }
+    }
     const createdAt = timestamp();
     const record: InteractionSessionRecord = {
       schemaVersion: 1,
@@ -2348,6 +2396,7 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
         result: bounded(result),
       };
     } catch (error) {
+      if (selected.kind === 'device') releaseIosDeviceOwnership(input.controllerHome, input.repoId, interactionId, selected.id);
       return failSession(input, record, error);
     }
   }
@@ -2464,6 +2513,7 @@ export async function executeIosAgentDeviceAction(input: AssistantPluginActionEx
         try {
           const closedProvider = await closeProviderSession(input, current, args);
           const closed = patchInteractionSession(input.repoRoot, current.provider, current.interactionId, { status: 'closed' }) ?? current;
+          if (current.provider === DEVICE_PROVIDER) releaseIosDeviceOwnership(input.controllerHome, current.owner.repoId, current.interactionId, current.targetId);
           return {
             provider: 'agent-device',
             interaction: closed,

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

@@ -0,0 +1,103 @@
+import {
+  acquireControllerLock,
+  ControllerLockContentionError,
+  readControllerLock,
+  releaseControllerLock,
+  renewControllerLock,
+  type ControllerLockRecord,
+} from '../../cli/repositories/locks';
+
+const IOS_DEVICE_LOCK_PREFIX = 'ios-device:';
+const IOS_DEVICE_LOCK_TTL_MS = 2 * 60 * 60_000;
+
+export interface IosDeviceOwnershipResult {
+  acquired: boolean;
+  lock?: ControllerLockRecord;
+  blocker?: Pick<ControllerLockRecord, 'lockId' | 'owner' | 'pid' | 'acquiredAt' | 'heartbeatAt' | 'expiresAt'>;
+}
+
+function deviceResourceKey(deviceIdentifier: string): string {
+  const normalized = deviceIdentifier.trim().toUpperCase();
+  if (!normalized) throw new Error('IOS_DEVICE_IDENTIFIER_REQUIRED');
+  return `${IOS_DEVICE_LOCK_PREFIX}${normalized}`;
+}
+
+function sessionOwner(repoId: string, interactionId: string): string {
+  const repo = repoId.trim();
+  const interaction = interactionId.trim();
+  if (!repo || !interaction) throw new Error('IOS_DEVICE_OWNERSHIP_ID_REQUIRED');
+  return `ios-device-session:${repo}:${interaction}`;
+}
+
+function blocker(lock: ControllerLockRecord) {
+  return {
+    lockId: lock.lockId,
+    owner: lock.owner,
+    pid: lock.pid,
+    acquiredAt: lock.acquiredAt,
+    heartbeatAt: lock.heartbeatAt,
+    ...(lock.expiresAt ? { expiresAt: lock.expiresAt } : {}),
+  } satisfies IosDeviceOwnershipResult['blocker'];
+}
+
+// Use the hardware UDID as the single physical iPhone identity shared with XCTest.
+// CoreDevice identifier is a transport-local locator, not the agent-device device id.
+export function iosCoreDeviceOwnershipId(device: { identifier: string; udid?: string }): string {
+  const udid = device.udid?.trim();
+  if (!udid) throw new Error('IOS_DEVICE_UDID_REQUIRED');
+  return udid;
+}
+
+export function ensureIosDeviceOwnership(
+  controllerHome: string,
+  repoId: string,
+  interactionId: string,
+  deviceIdentifier: string,
+): IosDeviceOwnershipResult {
+  const key = { scope: 'global' as const, resource: deviceResourceKey(deviceIdentifier) };
+  const owner = sessionOwner(repoId, interactionId);
+  const current = readControllerLock(controllerHome, key);
+  if (current) {
+    if (current.owner !== owner) return { acquired: false, blocker: blocker(current) };
+    return { acquired: true, lock: renewControllerLock(controllerHome, key, current.lockId, IOS_DEVICE_LOCK_TTL_MS) };
+  }
+  try {
+    return { acquired: true, lock: acquireControllerLock(controllerHome, key, owner, IOS_DEVICE_LOCK_TTL_MS) };
+  } catch (error) {
+    if (!(error instanceof ControllerLockContentionError)) throw error;
+    const raced = readControllerLock(controllerHome, key);
+    if (!raced) return { acquired: false };
+    if (raced.owner !== owner) return { acquired: false, blocker: blocker(raced) };
+    return { acquired: true, lock: renewControllerLock(controllerHome, key, raced.lockId, IOS_DEVICE_LOCK_TTL_MS) };
+  }
+}
+
+export function releaseIosDeviceOwnership(
+  controllerHome: string,
+  repoId: string,
+  interactionId: string,
+  deviceIdentifier: string,
+): boolean {
+  const key = { scope: 'global' as const, resource: deviceResourceKey(deviceIdentifier) };
+  const current = readControllerLock(controllerHome, key);
+  if (!current || current.owner !== sessionOwner(repoId, interactionId)) return false;
+  releaseControllerLock(controllerHome, key, current.lockId);
+  return true;
+}
+
+export async function withIosDeviceTransientOwnership<T>(
+  controllerHome: string,
+  repoId: string,
+  requestId: string,
+  deviceIdentifier: string,
+  operation: () => T | Promise<T>,
+): Promise<T> {
+  const key = { scope: 'global' as const, resource: deviceResourceKey(deviceIdentifier) };
+  const owner = `ios-device-transient:${repoId}:${requestId}`;
+  const lock = acquireControllerLock(controllerHome, key, owner, undefined);
+  try {
+    return await operation();
+  } finally {
+    releaseControllerLock(controllerHome, key, lock.lockId);
+  }
+}