@moretea-labs/forge 1.5.1 → 1.7.0

package/src/runtime/safe-tooling/ios-development.ts

@@ -1,4 +1,5 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'fs';
 import { basename, dirname, join, relative, resolve, sep } from 'path';
 import { spawnSync } from 'child_process';
 import type { RepositoryRecord } from '../../cli/repositories/types';
@@ -19,32 +20,40 @@ export interface IosDevelopmentHooks {
 }
 
 let hooks: IosDevelopmentHooks = {};
+let artifactSequence = 0;
 
 /** Host Xcode/simctl probes are expensive (spawnSync). Cache them for hot MCP reads. */
 const XCODE_STATUS_TTL_MS = 60_000;
 const XCODE_STATUS_DEGRADED_TTL_MS = 10_000;
 const PROJECT_DISCOVER_TTL_MS = 30_000;
+const SCHEME_LIST_TTL_MS = 30_000;
 let xcodeStatusCache:
   | { expiresAt: number; value: ReturnType<typeof probeIosXcodeStatus> }
   | undefined;
 const projectDiscoverCache = new Map<string, { expiresAt: number; value: ReturnType<typeof probeIosProjectDiscover> }>();
+const schemeListCache = new Map<string, { expiresAt: number; value: ReturnType<typeof probeIosSchemesList> }>();
 
 export function setIosDevelopmentHooksForTest(next: IosDevelopmentHooks): void {
   hooks = next;
+  artifactSequence = 0;
   xcodeStatusCache = undefined;
   projectDiscoverCache.clear();
+  schemeListCache.clear();
 }
 
 export function resetIosDevelopmentHooksForTest(): void {
   hooks = {};
+  artifactSequence = 0;
   xcodeStatusCache = undefined;
   projectDiscoverCache.clear();
+  schemeListCache.clear();
 }
 
 /** Test helper: drop cached Xcode probe results without clearing hooks. */
 export function clearIosXcodeStatusCacheForTest(): void {
   xcodeStatusCache = undefined;
   projectDiscoverCache.clear();
+  schemeListCache.clear();
 }
 
 export function iosDevelopmentPlatform(): NodeJS.Platform {
@@ -113,7 +122,7 @@ function safeRepoRelativePath(repoRoot: string, value: string | undefined): stri
 
 function safeArtifactDir(
   repository: RepositoryRecord,
-  leaf: 'screenshots' | 'logs' | 'build-reports' | 'DerivedData',
+  leaf: 'screenshots' | 'logs' | 'build-reports' | 'test-results' | 'DerivedData',
   overrideRoot?: string,
 ): string {
   const root = overrideRoot
@@ -135,10 +144,24 @@ function timestamp(): string {
   return now().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
 }
 
+function artifactStamp(): string {
+  artifactSequence = (artifactSequence + 1) % Number.MAX_SAFE_INTEGER;
+  return `${timestamp()}-${process.pid}-${artifactSequence}`;
+}
+
 function sanitize(value: string): string {
   return value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'ios';
 }
 
+function stableBuildDerivedDataPath(
+  repository: RepositoryRecord,
+  input: { workspace?: string; project?: string; scheme: string; configuration: string; destination: string },
+): string {
+  const identity = JSON.stringify([input.workspace ?? '', input.project ?? '', input.scheme, input.configuration, input.destination]);
+  const digest = createHash('sha256').update(identity).digest('hex').slice(0, 16);
+  return join(safeArtifactDir(repository, 'DerivedData'), `build-${sanitize(input.scheme)}-${digest}`);
+}
+
 function boundedText(value: string, maxBytes = 20_000): { content: string; truncated: boolean } {
   const buffer = Buffer.from(value, 'utf-8');
   if (buffer.byteLength <= maxBytes) return { content: value, truncated: false };
@@ -172,6 +195,28 @@ function probeIosXcodeStatus() {
   };
 }
 
+export function iosXcodeStatusSnapshot() {
+  const unsupported = assertDarwin();
+  if (unsupported) return { status: unsupported, probed: true, cached: false };
+  const currentMs = currentTimeMs();
+  if (xcodeStatusCache && xcodeStatusCache.expiresAt > currentMs) {
+    return { status: xcodeStatusCache.value, probed: true, cached: true };
+  }
+  return {
+    status: {
+      ready: false,
+      platform: platform(),
+      simctlAvailable: false,
+      problems: [{
+        code: 'XCODE_STATUS_NOT_PROBED',
+        message: 'Xcode readiness has not been probed asynchronously or explicitly in this runtime yet.',
+      }],
+    },
+    probed: false,
+    cached: false,
+  };
+}
+
 export function iosXcodeStatus(options: { forceRefresh?: boolean } = {}) {
   const currentMs = currentTimeMs();
   if (!options.forceRefresh && xcodeStatusCache && xcodeStatusCache.expiresAt > currentMs) {
@@ -205,15 +250,16 @@ export function iosSimulatorsList(input: { runtime?: string; name?: string } = {
   return { ready: true, devices };
 }
 
-function findFiles(root: string, suffix: string, maxDepth = 3): string[] {
+function findFiles(root: string, suffix: string, maxDepth = 6): string[] {
   const results: string[] = [];
+  const skippedDirectories = new Set(['node_modules', '.git', '.forge', '.ai', 'DerivedData', 'Pods', '.build', 'build', 'dist', '.cache', 'Carthage']);
   function visit(dir: string, depth: number) {
     if (depth > maxDepth || results.length > 50) return;
     let entries;
     try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
     for (const entry of entries) {
       const entryName = String(entry.name);
-      if (entryName === 'node_modules' || entryName === '.git' || entryName === '.forge' || entryName === '.ai') continue;
+      if (skippedDirectories.has(entryName)) continue;
       const path = join(dir, entryName);
       if (entry.isDirectory() && entryName.endsWith(suffix)) results.push(path);
       else if (entry.isDirectory()) visit(path, depth + 1);
@@ -253,12 +299,11 @@ export function iosProjectDiscover(repository: RepositoryRecord, options: { forc
   return value;
 }
 
-export function iosSchemesList(repository: RepositoryRecord, input: { workspace?: string; project?: string } = {}) {
+function probeIosSchemesList(repository: RepositoryRecord, input: { workspace?: string; project?: string } = {}) {
   const unsupported = assertDarwin();
   if (unsupported) return unsupported;
-  const discovered = iosProjectDiscover(repository);
-  const workspace = safeRepoRelativePath(repository.canonicalRoot, input.workspace ?? discovered.workspace);
-  const project = safeRepoRelativePath(repository.canonicalRoot, input.project ?? discovered.project);
+  const workspace = safeRepoRelativePath(repository.canonicalRoot, input.workspace);
+  const project = safeRepoRelativePath(repository.canonicalRoot, input.project);
   const args = workspace
     ? ['-list', '-json', '-workspace', workspace]
     : project
@@ -274,6 +319,21 @@ export function iosSchemesList(repository: RepositoryRecord, input: { workspace?
   }
 }
 
+export function iosSchemesList(repository: RepositoryRecord, input: { workspace?: string; project?: string } = {}) {
+  const unsupported = assertDarwin();
+  if (unsupported) return unsupported;
+  const discovered = iosProjectDiscover(repository);
+  const workspace = safeRepoRelativePath(repository.canonicalRoot, input.workspace ?? discovered.workspace);
+  const project = safeRepoRelativePath(repository.canonicalRoot, input.project ?? discovered.project);
+  const cacheKey = JSON.stringify([resolve(repository.canonicalRoot), workspace ?? '', project ?? '']);
+  const currentMs = currentTimeMs();
+  const cached = schemeListCache.get(cacheKey);
+  if (cached && cached.expiresAt > currentMs) return cached.value;
+  const value = probeIosSchemesList(repository, { workspace, project });
+  if (value.ready) schemeListCache.set(cacheKey, { expiresAt: currentMs + SCHEME_LIST_TTL_MS, value });
+  return value;
+}
+
 export function iosSimulatorBoot(input: { udid: string; openSimulator?: boolean; timeoutMs?: number }) {
   const unsupported = assertDarwin();
   if (unsupported) return unsupported;
@@ -281,15 +341,23 @@ export function iosSimulatorBoot(input: { udid: string; openSimulator?: boolean;
   if (!udid) throw new Error('IOS_SIMULATOR_UDID_REQUIRED');
   const timeoutMs = input.timeoutMs ?? 60_000;
   const boot = runCommand('xcrun', ['simctl', 'boot', udid], { timeoutMs });
-  const alreadyBooted = /Unable to boot|current state: Booted|already booted/i.test(boot.stderr + boot.stdout);
+  const alreadyBooted = /current state:\s*Booted|already booted/i.test(boot.stderr + boot.stdout);
   if (!boot.ok && !alreadyBooted) {
-    return { ready: false, booted: false, error: { code: 'SIMULATOR_BOOT_FAILED', message: boot.stderr || boot.stdout }, command: boot.command };
+    return {
+      ready: false,
+      booted: false,
+      udid,
+      alreadyBooted: false,
+      error: { code: 'SIMULATOR_BOOT_FAILED', message: boot.stderr || boot.stdout },
+      command: boot.command,
+    };
   }
   const readiness = runCommand('xcrun', ['simctl', 'bootstatus', udid, '-b'], { timeoutMs });
   if (!readiness.ok) {
     return {
       ready: false,
-      booted: true,
+      booted: false,
+      bootRequested: boot.ok || alreadyBooted,
       udid,
       alreadyBooted,
       ownership: alreadyBooted ? 'reused' : 'started_by_work',
@@ -316,7 +384,7 @@ export function iosSimulatorShutdown(input: { udid: string; timeoutMs?: number }
   const udid = String(input.udid ?? '').trim();
   if (!udid) throw new Error('IOS_SIMULATOR_UDID_REQUIRED');
   const result = runCommand('xcrun', ['simctl', 'shutdown', udid], { timeoutMs: input.timeoutMs ?? 60_000 });
-  const alreadyShutdown = /current state: Shutdown|already shutdown|Unable to shutdown/i.test(result.stderr + result.stdout);
+  const alreadyShutdown = /current state:\s*Shutdown|already shutdown/i.test(result.stderr + result.stdout);
   return {
     ready: result.ok || alreadyShutdown,
     shutdown: result.ok || alreadyShutdown,
@@ -327,7 +395,20 @@ export function iosSimulatorShutdown(input: { udid: string; timeoutMs?: number }
   };
 }
 
-export function iosAppBuild(repository: RepositoryRecord, input: { scheme?: string; udid?: string; workspace?: string; project?: string; configuration?: string; timeoutMs?: number; simulatorName?: string }) {
+export function iosAppBuild(repository: RepositoryRecord, input: {
+  scheme?: string;
+  udid?: string;
+  workspace?: string;
+  project?: string;
+  configuration?: string;
+  timeoutMs?: number;
+  simulatorName?: string;
+  destinationPlatform?: 'ios_simulator' | 'ios';
+  provisioning?: {
+    allowUpdates: boolean;
+    authentication?: { privateKeyPath: string; keyId: string; issuerId: string };
+  };
+}) {
   const unsupported = assertDarwin();
   if (unsupported) return unsupported;
   const listed = iosSchemesList(repository, { workspace: input.workspace, project: input.project });
@@ -337,34 +418,136 @@ export function iosAppBuild(repository: RepositoryRecord, input: { scheme?: stri
   if (!scheme) throw new Error('IOS_SCHEME_REQUIRED: provide scheme or share at least one Xcode scheme');
   const workspace = safeRepoRelativePath(repository.canonicalRoot, input.workspace ?? listedReady.workspace);
   const project = safeRepoRelativePath(repository.canonicalRoot, input.project ?? listedReady.project);
-  const derivedDataRoot = safeArtifactDir(repository, 'DerivedData');
-  const derivedDataPath = join(derivedDataRoot, `${timestamp()}-${sanitize(scheme)}`);
+  const configuration = input.configuration ?? 'Debug';
+  const destinationPlatform = input.destinationPlatform ?? 'ios_simulator';
+  const udid = String(input.udid ?? '').trim();
+  if (destinationPlatform === 'ios' && !udid) throw new Error('IOS_PHYSICAL_DEVICE_UDID_REQUIRED');
+  const destination = destinationPlatform === 'ios'
+    ? `platform=iOS,id=${udid}`
+    : udid
+      ? `platform=iOS Simulator,id=${udid}`
+      : `platform=iOS Simulator,name=${input.simulatorName ?? 'iPhone 16 Pro'}`;
+  const derivedDataPath = stableBuildDerivedDataPath(repository, { workspace, project, scheme, configuration, destination });
+  const derivedDataReused = existsSync(derivedDataPath);
   mkdirSync(derivedDataPath, { recursive: true });
+  const priorBuiltApps = derivedDataReused ? findBuiltApps(repository, derivedDataPath) : [];
   const args = ['build'];
   if (workspace) args.push('-workspace', workspace);
   else if (project) args.push('-project', project);
-  args.push('-scheme', scheme, '-configuration', input.configuration ?? 'Debug');
-  if (input.udid) args.push('-destination', `platform=iOS Simulator,id=${String(input.udid).trim()}`);
-  else args.push('-destination', 'platform=iOS Simulator,name=' + (input.simulatorName ?? 'iPhone 16 Pro'));
+  args.push('-scheme', scheme, '-configuration', configuration, '-destination', destination);
   args.push('-derivedDataPath', derivedDataPath);
+  const authentication = input.provisioning?.authentication;
+  if (input.provisioning?.allowUpdates) args.push('-allowProvisioningUpdates');
+  if (authentication) {
+    args.push(
+      '-authenticationKeyPath', authentication.privateKeyPath,
+      '-authenticationKeyID', authentication.keyId,
+      '-authenticationKeyIssuerID', authentication.issuerId,
+    );
+  }
   const result = runCommand('xcodebuild', args, { cwd: repository.canonicalRoot, timeoutMs: input.timeoutMs ?? 10 * 60_000 });
+  const sensitiveValues = authentication
+    ? [authentication.privateKeyPath, authentication.keyId, authentication.issuerId]
+    : [];
+  const redactSensitiveText = (value: string): string => sensitiveValues.reduce(
+    (current, secret) => secret ? current.split(secret).join('[REDACTED]') : current,
+    value,
+  );
+  const redactBoundedText = (value: string) => {
+    const bounded = boundedText(value);
+    return { ...bounded, content: redactSensitiveText(bounded.content) };
+  };
+  const sensitiveFlags = new Set(['-authenticationKeyPath', '-authenticationKeyID', '-authenticationKeyIssuerID']);
+  const safeCommand = result.command.map((entry, index, command) => (
+    index > 0 && sensitiveFlags.has(command[index - 1] ?? '') ? '[REDACTED]' : entry
+  ));
+  const safeStdout = redactBoundedText(result.stdout);
+  const safeStderr = redactBoundedText(result.stderr);
   const builtApps = findBuiltApps(repository, derivedDataPath);
-  const selected = selectBuiltAppProduct(scheme, builtApps);
+  const priorSet = new Set(priorBuiltApps);
+  const newBuiltApps = builtApps.filter((candidate) => !priorSet.has(candidate));
+  const selected = selectBuiltAppProduct(scheme, newBuiltApps.length > 0 ? newBuiltApps : builtApps);
   const productError = result.ok ? selected.error : undefined;
   return {
     ready: result.ok && Boolean(selected.appPath),
     ok: result.ok && Boolean(selected.appPath),
     scheme,
-    configuration: input.configuration ?? 'Debug',
+    configuration,
+    destination,
     derivedDataPath: relative(repository.canonicalRoot, derivedDataPath),
+    derivedDataReused,
     appPath: selected.appPath,
     builtApps,
-    command: result.command,
-    stdout: boundedText(result.stdout),
-    stderr: boundedText(result.stderr),
+    newBuiltApps,
+    command: safeCommand,
+    stdout: safeStdout,
+    stderr: safeStderr,
     error: result.ok
       ? productError
-      : { code: 'IOS_BUILD_FAILED', message: (result.stderr || result.stdout).slice(0, 2000) },
+      : { code: 'IOS_BUILD_FAILED', message: redactSensitiveText(result.stderr || result.stdout).slice(0, 2000) },
+  };
+}
+
+export function iosXcodeTest(repository: RepositoryRecord, input: {
+  scheme?: string;
+  udid?: string;
+  simulatorName?: string;
+  workspace?: string;
+  project?: string;
+  configuration?: string;
+  onlyTesting?: string[];
+  parallelTesting?: boolean;
+  maxParallelTestingWorkers?: number;
+  timeoutMs?: number;
+}) {
+  const unsupported = assertDarwin();
+  if (unsupported) return unsupported;
+  const listed = iosSchemesList(repository, { workspace: input.workspace, project: input.project });
+  if (!listed.ready) return listed;
+  const listedReady = listed as { ready: true; workspace?: string; project?: string; schemes: string[] };
+  const scheme = String(input.scheme ?? listedReady.schemes?.[0] ?? '').trim();
+  if (!scheme) throw new Error('IOS_SCHEME_REQUIRED: provide scheme or share at least one Xcode scheme');
+  const workspace = safeRepoRelativePath(repository.canonicalRoot, input.workspace ?? listedReady.workspace);
+  const project = safeRepoRelativePath(repository.canonicalRoot, input.project ?? listedReady.project);
+  const derivedDataPath = join(safeArtifactDir(repository, 'DerivedData'), `tests-${sanitize(scheme)}`);
+  const resultBundlePath = join(safeArtifactDir(repository, 'test-results'), `${timestamp()}-${sanitize(scheme)}.xcresult`);
+  mkdirSync(derivedDataPath, { recursive: true });
+  const args = ['test'];
+  if (workspace) args.push('-workspace', workspace);
+  else if (project) args.push('-project', project);
+  args.push('-scheme', scheme, '-configuration', input.configuration ?? 'Debug');
+  if (input.udid) args.push('-destination', `platform=iOS Simulator,id=${String(input.udid).trim()}`);
+  else args.push('-destination', 'platform=iOS Simulator,name=' + (input.simulatorName ?? 'iPhone 16 Pro'));
+  const parallelTesting = input.parallelTesting === true;
+  const maxParallelTestingWorkers = parallelTesting
+    ? Math.max(1, Math.min(8, Math.trunc(input.maxParallelTestingWorkers ?? 2)))
+    : 1;
+  args.push(
+    '-parallel-testing-enabled', parallelTesting ? 'YES' : 'NO',
+    '-maximum-parallel-testing-workers', String(maxParallelTestingWorkers),
+  );
+  for (const selector of (input.onlyTesting ?? []).slice(0, 50)) {
+    const normalized = String(selector).trim();
+    if (normalized) args.push(`-only-testing:${normalized}`);
+  }
+  args.push('-derivedDataPath', derivedDataPath, '-resultBundlePath', resultBundlePath);
+  const result = runCommand('xcodebuild', args, { cwd: repository.canonicalRoot, timeoutMs: input.timeoutMs ?? 15 * 60_000 });
+  return {
+    ready: result.ok,
+    ok: result.ok,
+    scheme,
+    configuration: input.configuration ?? 'Debug',
+    onlyTesting: (input.onlyTesting ?? []).map((entry) => String(entry).trim()).filter(Boolean).slice(0, 50),
+    parallelTesting,
+    maxParallelTestingWorkers,
+    derivedDataPath: artifactRelativePath(repository, derivedDataPath),
+    resultBundlePath: artifactRelativePath(repository, resultBundlePath),
+    command: result.command,
+    stdout: boundedText(result.stdout, 64 * 1024),
+    stderr: boundedText(result.stderr, 32 * 1024),
+    error: result.ok
+      ? undefined
+      : { code: 'IOS_TEST_FAILED', message: (result.stderr || result.stdout).slice(0, 4000) },
   };
 }
 
@@ -398,7 +581,7 @@ function selectBuiltAppProduct(scheme: string, builtApps: string[]): {
     return !/(?:tests?|uitests?|xctrunner|runner|testhost)\.app$/i.test(name);
   });
   if (productionCandidates.length === 0) {
-    return { error: { code: 'IOS_BUILD_PRODUCT_MISSING', message: 'Build succeeded but no application product was found in this build-specific DerivedData directory.' } };
+    return { error: { code: 'IOS_BUILD_PRODUCT_MISSING', message: 'Build succeeded but no application product was found in this DerivedData cache bucket.' } };
   }
   const normalizedScheme = normalizedProductName(scheme);
   const exact = productionCandidates.filter((candidate) => normalizedProductName(basename(candidate)) === normalizedScheme);
@@ -413,46 +596,96 @@ function selectBuiltAppProduct(scheme: string, builtApps: string[]): {
   };
 }
 
-function readBuiltAppBundleId(repository: RepositoryRecord, appPath: string): string | undefined {
-  const appRoot = assertRepoBoundedAppPath(repository, appPath);
+function readBuiltAppPlistValue(repository: RepositoryRecord, appPath: string, key: string, artifactRoot?: string): string | undefined {
+  const appRoot = assertBoundedAppPath(repository, appPath, artifactRoot);
   const plist = join(appRoot, 'Info.plist');
   if (!existsSync(plist)) return undefined;
-  const plutil = runCommand('plutil', ['-extract', 'CFBundleIdentifier', 'raw', '-o', '-', plist]);
+  const plutil = runCommand('plutil', ['-extract', key, 'raw', '-o', '-', plist]);
   return plutil.ok && plutil.stdout.trim() ? plutil.stdout.trim() : undefined;
 }
 
+function readBuiltAppBundleId(repository: RepositoryRecord, appPath: string, artifactRoot?: string): string | undefined {
+  return readBuiltAppPlistValue(repository, appPath, 'CFBundleIdentifier', artifactRoot);
+}
+
+function readBuiltAppExecutable(repository: RepositoryRecord, appPath: string, artifactRoot?: string): string | undefined {
+  return readBuiltAppPlistValue(repository, appPath, 'CFBundleExecutable', artifactRoot);
+}
+
+function compareSimulatorCandidates(
+  left: { runtime: string; name: string; state: string; udid: string },
+  right: { runtime: string; name: string; state: string; udid: string },
+): number {
+  const leftBooted = left.state === 'Booted' ? 1 : 0;
+  const rightBooted = right.state === 'Booted' ? 1 : 0;
+  if (leftBooted !== rightBooted) return rightBooted - leftBooted;
+  const runtimeOrder = right.runtime.localeCompare(left.runtime, undefined, { numeric: true, sensitivity: 'base' });
+  if (runtimeOrder !== 0) return runtimeOrder;
+  return left.name.localeCompare(right.name, undefined, { numeric: true, sensitivity: 'base' });
+}
+
 function chooseSimulatorUdid(input: { udid?: string; simulatorName?: string }): string {
   const requested = String(input.udid ?? '').trim();
   if (requested) return requested;
-  const preferred = iosSimulatorsList({ name: input.simulatorName ?? 'iPhone 16 Pro' });
-  if (preferred.ready) {
-    const preferredReady = preferred as { ready: true; devices: Array<{ udid: string }> };
-    if (preferredReady.devices[0]?.udid) return preferredReady.devices[0].udid;
-  }
-  const fallback = iosSimulatorsList();
-  if (fallback.ready) {
-    const fallbackReady = fallback as { ready: true; devices: Array<{ udid: string }> };
-    if (fallbackReady.devices[0]?.udid) return fallbackReady.devices[0].udid;
+  const inventory = iosSimulatorsList();
+  if (!inventory.ready) throw new Error('IOS_SIMULATOR_UNAVAILABLE: simulator inventory could not be read');
+  const devices = (inventory as { ready: true; devices: Array<{ runtime: string; name: string; state: string; udid: string }> }).devices
+    .filter((device) => /SimRuntime\.iOS-/i.test(device.runtime));
+  const requestedName = String(input.simulatorName ?? '').trim();
+  const matches = requestedName
+    ? devices.filter((device) => device.name.includes(requestedName)).sort(compareSimulatorCandidates)
+    : [];
+  if (matches[0]?.udid) return matches[0].udid;
+  if (!requestedName) {
+    const booted = devices.filter((device) => device.state === 'Booted').sort(compareSimulatorCandidates);
+    if (booted[0]?.udid) return booted[0].udid;
+    const preferred = devices.filter((device) => device.name.includes('iPhone 16 Pro')).sort(compareSimulatorCandidates);
+    if (preferred[0]?.udid) return preferred[0].udid;
   }
+  const fallback = [...devices].sort(compareSimulatorCandidates);
+  if (fallback[0]?.udid) return fallback[0].udid;
   throw new Error('IOS_SIMULATOR_UNAVAILABLE: no available simulator was found');
 }
 
-function assertRepoBoundedAppPath(repository: RepositoryRecord, appPath: string): string {
-  const resolved = resolve(repository.canonicalRoot, appPath);
-  const allowedRoot = resolve(repository.canonicalRoot, '.forge', 'ios', 'DerivedData');
-  const rel = relative(allowedRoot, resolved);
-  if (rel === '' || rel === '..' || rel.startsWith(`..${sep}`)) throw new Error('IOS_APP_PATH_NOT_BOUNDED: app_path must be under .forge/ios/DerivedData');
+function pathIsWithin(root: string, target: string): boolean {
+  const canonicalRoot = existsSync(root) ? realpathSync(root) : resolve(root);
+  const canonicalTarget = existsSync(target) ? realpathSync(target) : resolve(target);
+  const rel = relative(canonicalRoot, canonicalTarget);
+  return Boolean(rel) && rel !== '..' && !rel.startsWith(`..${sep}`);
+}
+
+function assertBoundedAppPath(repository: RepositoryRecord, appPath: string, artifactRoot?: string): string {
+  const controllerPrefix = 'controller-artifacts/ios/';
+  const resolved = artifactRoot && appPath.startsWith(controllerPrefix)
+    ? resolve(artifactRoot, appPath.slice(controllerPrefix.length))
+    : resolve(repository.canonicalRoot, appPath);
   if (!resolved.endsWith('.app')) throw new Error('IOS_APP_PATH_INVALID: app_path must end with .app');
+  const derivedDataRoot = resolve(repository.canonicalRoot, '.forge', 'ios', 'DerivedData');
+  const controllerArtifactRoot = artifactRoot ? resolve(artifactRoot) : undefined;
+  if (!pathIsWithin(derivedDataRoot, resolved) && !(controllerArtifactRoot && pathIsWithin(controllerArtifactRoot, resolved))) {
+    throw new Error(
+      controllerArtifactRoot
+        ? 'IOS_APP_PATH_NOT_BOUNDED: app_path must be under .forge/ios/DerivedData or the Controller iOS artifact root'
+        : 'IOS_APP_PATH_NOT_BOUNDED: app_path must be under .forge/ios/DerivedData',
+    );
+  }
   return resolved;
 }
 
-export function iosAppInstall(repository: RepositoryRecord, input: { udid: string; appPath: string }) {
+export function iosAppInstall(repository: RepositoryRecord, input: { udid: string; appPath: string; artifactRoot?: string }) {
   const unsupported = assertDarwin();
   if (unsupported) return unsupported;
   const udid = String(input.udid ?? '').trim();
-  const appPath = assertRepoBoundedAppPath(repository, String(input.appPath ?? ''));
+  const appPath = assertBoundedAppPath(repository, String(input.appPath ?? ''), input.artifactRoot);
   const result = runCommand('xcrun', ['simctl', 'install', udid, appPath], { timeoutMs: 120_000 });
-  return { ready: result.ok, installed: result.ok, udid, appPath: relative(repository.canonicalRoot, appPath), error: result.ok ? undefined : { code: 'IOS_INSTALL_FAILED', message: result.stderr || result.stdout } };
+  return {
+    ready: result.ok,
+    installed: result.ok,
+    udid,
+    appPath: artifactRelativePath(repository, appPath, input.artifactRoot),
+    absolutePath: appPath,
+    error: result.ok ? undefined : { code: 'IOS_INSTALL_FAILED', message: result.stderr || result.stdout },
+  };
 }
 
 export function iosAppLaunch(input: { udid: string; bundleId: string; arguments?: string[]; waitMs?: number }) {
@@ -465,14 +698,32 @@ export function iosAppLaunch(input: { udid: string; bundleId: string; arguments?
   const result = runCommand('xcrun', ['simctl', 'launch', udid, bundleId, ...launchArgs], { timeoutMs: 60_000 });
   const waitMs = Math.max(0, Math.min(Math.trunc(input.waitMs ?? 1_500), 15_000));
   if (result.ok) sleep(waitMs);
+  const pidMatch = result.ok ? result.stdout.match(/:\s*(\d+)\s*$/m) : undefined;
+  const pid = pidMatch?.[1] ? Number(pidMatch[1]) : undefined;
+  const processCheck = result.ok && Number.isFinite(pid)
+    ? runCommand('xcrun', ['simctl', 'spawn', udid, 'launchctl', 'procinfo', String(pid)], { timeoutMs: 10_000 })
+    : undefined;
+  const processCheckText = processCheck ? `${processCheck.stdout}\n${processCheck.stderr}` : '';
+  const alive = processCheck
+    ? processCheck.ok && !/No such process|could not resolve path/i.test(processCheckText)
+    : undefined;
+  const ready = result.ok && alive !== false;
   return {
-    ready: result.ok,
+    ready,
     launched: result.ok,
+    alive,
+    pid,
     udid,
     bundleId,
     waitMs,
     stdout: result.stdout.trim(),
-    error: result.ok ? undefined : { code: 'IOS_LAUNCH_FAILED', message: result.stderr || result.stdout },
+    command: result.command,
+    processCheckCommand: processCheck?.command,
+    error: !result.ok
+      ? { code: 'IOS_LAUNCH_FAILED', message: result.stderr || result.stdout }
+      : alive === false
+        ? { code: 'IOS_LAUNCH_PROCESS_EXITED', message: processCheck?.stderr || processCheck?.stdout || `Process ${pid} exited during post-launch verification.` }
+        : undefined,
   };
 }
 
@@ -482,7 +733,7 @@ export function iosSimulatorScreenshot(repository: RepositoryRecord, input: { ud
   const udid = String(input.udid ?? '').trim();
   if (!udid) throw new Error('IOS_SIMULATOR_UDID_REQUIRED');
   const dir = safeArtifactDir(repository, 'screenshots', input.artifactRoot);
-  const file = join(dir, `${timestamp()}-${sanitize(input.label ?? udid)}.png`);
+  const file = join(dir, `${artifactStamp()}-${sanitize(input.label ?? udid)}.png`);
   const result = runCommand('xcrun', ['simctl', 'io', udid, 'screenshot', file], { timeoutMs: 60_000 });
   return {
     ready: result.ok,
@@ -514,23 +765,27 @@ export function iosSimulatorLogTail(repository: RepositoryRecord, input: { udid:
         ['show', '--style', 'compact', '--last', last, '--predicate', predicate],
         { timeoutMs: 30_000 },
       );
-  const result = hostResult?.ok ? hostResult : simulatorResult;
-  const text = boundedText(result.stdout || result.stderr, input.maxBytes ?? 20_000);
+  const diagnosticResult = simulatorResult.ok ? simulatorResult : hostResult?.ok ? hostResult : simulatorResult;
+  const text = boundedText(diagnosticResult.stdout || diagnosticResult.stderr, input.maxBytes ?? 20_000);
   const dir = safeArtifactDir(repository, 'logs', input.artifactRoot);
-  const file = join(dir, `${timestamp()}-${sanitize(input.process ?? udid)}.log`);
+  const file = join(dir, `${artifactStamp()}-${sanitize(input.process ?? udid)}.log`);
   writeFileSync(file, text.content, 'utf-8');
   return {
-    ready: result.ok,
+    ready: simulatorResult.ok,
     path: artifactRelativePath(repository, file, input.artifactRoot),
     absolutePath: file,
     content: text.content,
     truncated: text.truncated,
-    command: result.command,
+    command: simulatorResult.command,
     attempts: [simulatorResult.command, ...(hostResult ? [hostResult.command] : [])],
-    source: hostResult?.ok ? 'host_unified_log_fallback' : 'simulator_unified_log',
-    error: result.ok ? undefined : {
+    source: simulatorResult.ok ? 'simulator_unified_log' : hostResult?.ok ? 'host_unified_log_diagnostic_fallback' : 'simulator_unified_log',
+    targetProcess: input.process,
+    error: simulatorResult.ok ? undefined : {
       code: 'IOS_LOG_TAIL_FAILED',
-      message: [simulatorResult.stderr || simulatorResult.stdout, hostResult?.stderr || hostResult?.stdout]
+      message: [
+        simulatorResult.stderr || simulatorResult.stdout,
+        hostResult?.ok ? 'Host unified log fallback was captured for diagnostics only.' : hostResult?.stderr || hostResult?.stdout,
+      ]
         .filter(Boolean)
         .join('\n--- fallback ---\n'),
     },
@@ -860,7 +1115,7 @@ export function iosSmokeReview(repository: RepositoryRecord, input: IosSmokeRevi
   }));
 
   // 5. install
-  const install = iosAppInstall(repository, { udid, appPath });
+  const install = iosAppInstall(repository, { udid, appPath, artifactRoot: input.artifactRoot });
   if (!install.ready) {
     overallStatus = 'failed';
     blockedStage = 'install';
@@ -883,7 +1138,7 @@ export function iosSmokeReview(repository: RepositoryRecord, input: IosSmokeRevi
   }));
 
   // 6. launch
-  const bundleId = String(input.bundleId ?? readBuiltAppBundleId(repository, appPath) ?? '').trim();
+  const bundleId = String(input.bundleId ?? readBuiltAppBundleId(repository, appPath, input.artifactRoot) ?? '').trim();
   if (!bundleId) {
     overallStatus = 'failed';
     blockedStage = 'launch';
@@ -901,6 +1156,7 @@ export function iosSmokeReview(repository: RepositoryRecord, input: IosSmokeRevi
       simulatorOwnership, cleanupPolicy, simulatorCleanup,
     };
   }
+  const appExecutable = readBuiltAppExecutable(repository, appPath, input.artifactRoot);
   const launch = iosAppLaunch({ udid, bundleId, waitMs: input.launchWaitMs });
   if (!launch.ready) {
     overallStatus = 'failed';
@@ -946,8 +1202,7 @@ export function iosSmokeReview(repository: RepositoryRecord, input: IosSmokeRevi
       'Ensure the simulator is booted and simctl io screenshot works for the selected udid.',
       { command: screenshot.command, evidence: screenshot as unknown as Record<string, unknown> },
     ));
-    failRemaining(7, 'Skipped because screenshot failed.');
-    // still attempt logs for diagnosis
+    // Continue to logs for diagnosis; do not add a skipped logs stage before the real attempt.
   } else {
     stages.push(stagePassed('screenshot', `Captured screenshot ${screenshot.screenshot}.`, {
       command: screenshot.command,
@@ -959,7 +1214,7 @@ export function iosSmokeReview(repository: RepositoryRecord, input: IosSmokeRevi
   // 8. logs
   const logs = iosSimulatorLogTail(repository, {
     udid,
-    process: selectedScheme,
+    process: appExecutable,
     maxBytes: 12_000,
     artifactRoot: input.artifactRoot,
   }) as {
@@ -969,6 +1224,8 @@ export function iosSmokeReview(repository: RepositoryRecord, input: IosSmokeRevi
     truncated?: boolean;
     command?: string[];
     error?: { message?: string };
+    source?: string;
+    targetProcess?: string;
   };
   if (Array.isArray(logs.command)) commands.push(logs.command);
   if (logs.path) artifacts.push(logs.path);
@@ -981,12 +1238,12 @@ export function iosSmokeReview(repository: RepositoryRecord, input: IosSmokeRevi
       'logs',
       logs.error?.message ?? 'Log collection failed',
       'Simulator may still be booting; retry log_tail after a few seconds.',
-      { command: logs.command, evidence: { path: logs.path, truncated: logs.truncated }, artifacts: logs.path ? [logs.path] : undefined },
+      { command: logs.command, evidence: { path: logs.path, truncated: logs.truncated, process: appExecutable, source: logs.source }, artifacts: logs.path ? [logs.path] : undefined },
     ));
   } else {
     stages.push(stagePassed('logs', `Collected logs at ${logs.path}.`, {
       command: logs.command,
-      evidence: { path: logs.path, truncated: logs.truncated, preview: logs.content?.slice(0, 500) },
+      evidence: { path: logs.path, truncated: logs.truncated, process: appExecutable, source: logs.source, preview: logs.content?.slice(0, 500) },
       artifacts: logs.path ? [logs.path] : undefined,
     }));
   }
@@ -1005,6 +1262,7 @@ export function iosSmokeReview(repository: RepositoryRecord, input: IosSmokeRevi
     schemes: schemesList,
     scheme: selectedScheme,
     bundleId,
+    appExecutable,
     udid,
     build: buildResult,
     boot,