@moretea-labs/forge 1.8.1 → 1.8.2

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(),
   ];
 }
 
@@ -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);
+  }
+}