swipium 1.4.0 → 2.0.0

package/dist/tools/wda.js

@@ -1,26 +1,70 @@
 import { z } from 'zod';
 import { spawn } from 'node:child_process';
-import { existsSync, openSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { closeSync, existsSync, openSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
-import { qaError, qaOk } from '../lib/result.js';
+import { qaError, qaOk, unknownSessionError } from '../lib/result.js';
 import { consumeConsent, requireConsent } from '../consent/consent.js';
 import { sensitiveRefusal } from '../lib/sensitive.js';
 import { run } from '../lib/spawn.js';
-import { checkWda, classifyWdaBuildFailure, classifyWdaConnectionFailure, createWdaSession, discoverWdaProjects, managedWdaBuildArgs, managedWdaStartArgs, waitForWdaReady, wdaSessionUdidMismatch, xcodeAvailable } from '../lib/wda.js';
+import { checkWda, classifyWdaBuildFailure, classifyWdaConnectionFailure, createWdaSession, discoverAppiumWdaProjects, discoverWdaProjects, managedWdaBuildArgs, managedWdaStartArgs, waitForWdaReady, wdaSessionUdidMismatch, xcodeAvailable, isLoopbackWdaUrl, remoteWdaAllowedByUser, REMOTE_WDA_ENV, } from '../lib/wda.js';
 import { loadWdaConfig, wdaSigningStatus, wdaUrlAllowedByConfig } from '../lib/wdaConfig.js';
 import { recordWdaTiming, wdaRecommendations, wdaTimingSummary } from '../lib/wdaTune.js';
 import { WdaDriver } from '../drivers/WdaDriver.js';
 import * as sim from '../lib/simctl.js';
+import { findManagedWdaProcesses, killManagedWda, reclaimPid, registerManagedProcess, registeredWdaForSession, unregisterManagedProcess, } from '../session/processRegistry.js';
 const managedProcesses = new Map();
-function isLoopback(raw) {
+function pidIsAlive(pid) {
+    if (!(pid > 0))
+        return false;
     try {
-        const u = new URL(raw);
-        return u.protocol === 'http:' && ['127.0.0.1', 'localhost', '::1'].includes(u.hostname);
+        process.kill(pid, 0);
+        return true;
     }
     catch {
         return false;
     }
 }
+/** A managed WDA this server still runs for the session (started here, or adopted at startup).
+ *  A dead in-memory entry is dropped. */
+function liveManagedWda(sessionId) {
+    const own = managedProcesses.get(sessionId);
+    if (own) {
+        if (pidIsAlive(own.pid))
+            return { pid: own.pid, adopted: false };
+        managedProcesses.delete(sessionId);
+        unregisterManagedProcess(own.pid);
+    }
+    const adopted = registeredWdaForSession(sessionId);
+    return adopted && pidIsAlive(adopted.pid) ? { pid: adopted.pid, adopted: true } : undefined;
+}
+/** The managed-WDA signature of this session's latest successful `qa_wda start` (from the
+ *  mutation ledger, which survives a server restart). Lets `qa_wda stop` find the xcodebuild
+ *  even when its process-registry entry was lost. Exported for tests. */
+export function lastManagedWdaStart(session) {
+    const m = [...(session.mutations ?? [])]
+        .reverse()
+        .find((r) => r.tool === 'qa_wda' && r.action === 'wda_start' && r.status === 'executed' && typeof r.target?.projectPath === 'string');
+    if (!m)
+        return undefined;
+    const t = m.target;
+    if (typeof t.udid !== 'string' || !t.udid)
+        return undefined;
+    let port;
+    try {
+        const u = new URL(String(t.webDriverAgentUrl ?? ''));
+        port = Number(u.port) || undefined;
+    }
+    catch {
+        port = undefined;
+    }
+    return {
+        projectPath: t.projectPath,
+        udid: t.udid,
+        ...(typeof t.derivedDataPath === 'string' && t.derivedDataPath ? { derivedDataPath: t.derivedDataPath } : {}),
+        ...(port ? { port } : {}),
+    };
+}
+const isLoopback = isLoopbackWdaUrl;
 function latestWdaArtifacts(session) {
     const logs = [...session.artifacts].reverse().filter((a) => a.kind === 'wda');
     const latestBuildLog = logs.find((a) => /build/i.test(a.label ?? a.path)) ?? null;
@@ -76,38 +120,58 @@ function managedWdaBuildProductStatus(derivedDataPath) {
 export function registerWda(server, sessions) {
     server.registerTool('qa_wda', {
         title: 'WebDriverAgent diagnostics and attach',
-        description: 'Diagnose, attach, or manage an iOS WebDriverAgent backend. External WDA: pass webDriverAgentUrl, then action:"attach". Managed WDA: pass wdaProjectPath + udid for build/start; output is captured as artifacts.',
+        description: 'Diagnose, attach, or manage an iOS WebDriverAgent backend for structured iOS tap/type/snapshot. External WDA: ' +
+            'action:"attach" with webDriverAgentUrl (default http://127.0.0.1:8100). Managed WDA: build/start (consent-gated) from ' +
+            'wdaProjectPath or an installed Appium WDA; stop ends it. status/doctor/diagnose/logs/tune inspect a setup.',
         inputSchema: {
             sessionId: z.string(),
             action: z.enum(['status', 'doctor', 'build', 'start', 'stop', 'attach', 'diagnose', 'logs', 'tune']),
-            webDriverAgentUrl: z.string().optional().describe('External WDA base URL. Defaults to http://127.0.0.1:8100. Non-loopback URLs are refused by default.'),
-            udid: z.string().optional().describe('Simulator/device UDID expected behind this WDA endpoint.'),
-            bundleId: z.string().optional().describe('App bundle id for session creation. Defaults to the session appId.'),
-            wdaProjectPath: z.string().optional().describe('Path to WebDriverAgent.xcodeproj for managed build/start. Relative paths resolve from project root.'),
-            derivedDataPath: z.string().optional().describe('Optional xcodebuild -derivedDataPath for WDA caching/reuse. Relative paths resolve from project root.'),
+            webDriverAgentUrl: z.string().optional().describe('Default http://127.0.0.1:8100; non-loopback needs allowNonLoopback + consent.'),
+            device: z.string().optional().describe('Simulator UDID behind this WDA (default: the session device).'),
+            udid: z.string().optional().describe('Deprecated alias of device.'),
+            bundleId: z.string().optional().describe('Default: the session appId.'),
+            wdaProjectPath: z.string().optional().describe('WebDriverAgent.xcodeproj (default: Appium WDA if found).'),
+            derivedDataPath: z.string().optional().describe('xcodebuild -derivedDataPath for reuse.'),
             scheme: z.string().optional().describe('WDA xcodebuild scheme. Defaults to WebDriverAgentRunner.'),
             allowNonLoopback: z.boolean().optional().describe('Required to use a non-loopback external WDA URL.'),
             consentId: z.string().optional(),
             approve: z.boolean().optional(),
         },
-    }, async ({ sessionId, action, webDriverAgentUrl, udid, bundleId, wdaProjectPath, derivedDataPath, scheme, allowNonLoopback, consentId, approve }) => {
+    }, async ({ sessionId, action, webDriverAgentUrl, device, udid: udidAlias, bundleId, wdaProjectPath, derivedDataPath, scheme, allowNonLoopback, consentId, approve, }) => {
         const session = sessions.get(sessionId);
         if (!session)
-            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
+            return unknownSessionError(sessionId);
+        // `device` is canonical (as on every other tool); `udid` is the deprecated alias.
+        if (device && udidAlias && device !== udidAlias)
+            return qaError({
+                what: `Conflicting device "${device}" and udid "${udidAlias}"; udid is a deprecated alias of device`,
+                changedState: false,
+                retrySafe: true,
+                failureCode: 'INVALID_ARGUMENT',
+                nextSteps: ['Pass only device.'],
+            });
+        const udid = device ?? udidAlias;
         const configured = loadWdaConfig(session.root);
         const url = webDriverAgentUrl ?? configured.url;
         const loopback = isLoopback(url);
-        const configAllowed = !loopback && wdaUrlAllowedByConfig(configured, url);
-        if (!loopback && !allowNonLoopback && !configAllowed) {
+        // Only the USER can pre-approve a remote WDA (env var in the MCP client config). The repo's
+        // .swipium/config.json (ios.wda.url / allowNonLoopbackUrls) arrives with the checkout, so it
+        // can never skip the per-call consent.
+        const userAllowed = !loopback && remoteWdaAllowedByUser(url);
+        const repoListed = !loopback && wdaUrlAllowedByConfig(configured, url);
+        if (!loopback && !allowNonLoopback && !userAllowed) {
             return qaError({
-                what: 'Refused non-loopback WDA URL',
+                what: `Refused non-loopback WDA URL ${url}${webDriverAgentUrl ? '' : ' (from the repository config .swipium/config.json)'}`,
                 changedState: false,
                 retrySafe: false,
                 failureCode: 'DESTRUCTIVE_REFUSED',
-                nextSteps: ['Use a localhost WDA URL, pass allowNonLoopback with explicit consent, or add this exact URL to ios.wda.allowNonLoopbackUrls for a trusted isolated automation network.'],
+                nextSteps: [
+                    `Use a localhost WDA URL, pass allowNonLoopback:true and approve the consent prompt, or (user-level, trusted isolated network only) set ${REMOTE_WDA_ENV}=<exact url> in the MCP server environment.`,
+                    ...(repoListed ? ['ios.wda.allowNonLoopbackUrls in the repository config no longer pre-approves a remote WDA.'] : []),
+                ],
             });
         }
-        if (!loopback && !configAllowed) {
+        if (!loopback && !userAllowed) {
             const gate = consumeConsent(consentId, approve, { action: 'wda_non_loopback', affects: { url } });
             if (!gate.approved) {
                 return requireConsent({
@@ -115,13 +179,21 @@ export function registerWda(server, sessions) {
                     risk: 'medium',
                     exactCommand: `connect to WebDriverAgent at ${url}`,
                     affects: { url },
-                    explain: `Use non-loopback WebDriverAgent URL ${url}? WDA is an automation server; only approve this on a trusted, isolated network.`,
+                    explain: `Use non-loopback WebDriverAgent URL ${url}${webDriverAgentUrl ? '' : ' (configured by the repository (.swipium/config.json), unreviewed)'}? WDA is an automation server that receives app screens and typed text; only approve this on a trusted, isolated network.`,
                 });
             }
         }
-        const resolvePath = (p) => p ? (isAbsolute(p) ? p : join(session.root, p)) : undefined;
-        const projectPath = resolvePath(wdaProjectPath);
+        const resolvePath = (p) => (p ? (isAbsolute(p) ? p : join(session.root, p)) : undefined);
+        const explicitProjectPath = resolvePath(wdaProjectPath);
+        // Managed build/start without wdaProjectPath: use a user-installed Appium WebDriverAgent
+        // (~/.appium/…/appium-webdriveragent, global npm), reported as wdaProjectSource.
+        const discoveredAppiumProject = !explicitProjectPath && (action === 'build' || action === 'start') ? discoverAppiumWdaProjects()[0] : undefined;
+        const projectPath = explicitProjectPath ?? discoveredAppiumProject;
+        const wdaProjectSource = explicitProjectPath ? 'argument' : discoveredAppiumProject ? 'appium-discovered' : null;
         const ddPath = resolvePath(derivedDataPath) ?? configured.derivedDataPath;
+        // What this call actually uses (args over config), echoed as `wdaConfig` so a passed
+        // derivedDataPath / webDriverAgentUrl is not misreported as the configured default.
+        const effectiveConfig = { ...configured, url, derivedDataPath: ddPath };
         const targetUdid = udid ?? session.device;
         if (udid && session.device && udid !== session.device) {
             return qaError({
@@ -148,20 +220,60 @@ export function registerWda(server, sessions) {
         if (action === 'tune') {
             const recommendations = wdaRecommendations(configured, session);
             const timings = wdaTimingSummary(session);
-            return qaOk({ webDriverAgentUrl: url, wdaConfig: configured, timings, recommendations }, recommendations.length
+            return qaOk({ webDriverAgentUrl: url, wdaConfig: effectiveConfig, timings, recommendations }, recommendations.length
                 ? `WDA tuning recommendations:\n${recommendations.map((r) => `  - ${r.setting}=${JSON.stringify(r.value)}: ${r.reason}`).join('\n')}`
                 : 'WDA tuning: no recommendations from current session evidence.');
         }
         if (action === 'stop') {
             const proc = managedProcesses.get(session.id);
-            if (!proc)
-                return qaOk({ stopped: false }, 'no managed WDA process recorded for this session');
+            if (!proc) {
+                // A WDA started by a previous server run and adopted at startup (processRegistry).
+                const adopted = registeredWdaForSession(session.id);
+                const outcome = adopted ? reclaimPid(adopted.pid, 'wda', undefined, adopted) : undefined; // fingerprint-checked
+                if (adopted)
+                    unregisterManagedProcess(adopted.pid);
+                if (adopted && outcome === 'killed') {
+                    sessions.addEnvChange(session, `wda stop pid ${adopted.pid} (adopted)`);
+                    sessions.recordMutation(session, {
+                        tool: 'qa_wda',
+                        action: 'wda_stop',
+                        risk: 'low',
+                        target: { pid: adopted.pid, adopted: true, webDriverAgentUrl: adopted.endpoint ?? null },
+                        consent: { required: false, approved: true },
+                        status: 'restored',
+                        detail: `adopted WDA ${outcome}`,
+                    });
+                    return qaOk({ stopped: true, pid: adopted.pid, adopted: true, outcome }, `stopped adopted managed WDA pid ${adopted.pid}`);
+                }
+                // Registry entry lost (or unverifiable): find the managed xcodebuild this session started
+                // by its exact signature (project + destination + derived data), never by pid alone.
+                const sig = lastManagedWdaStart(session);
+                const pids = sig ? findManagedWdaProcesses(sig) : [];
+                const killed = pids.filter((pid) => killManagedWda(pid));
+                if (!killed.length) {
+                    if (adopted)
+                        return qaOk({ stopped: false, pid: adopted.pid, adopted: true, outcome }, `adopted WDA pid ${adopted.pid} was already ${outcome}`);
+                    return qaOk({ stopped: false }, 'no managed WDA process recorded for this session');
+                }
+                sessions.addEnvChange(session, `wda stop pid ${killed.join(',')} (recovered by signature)`);
+                sessions.recordMutation(session, {
+                    tool: 'qa_wda',
+                    action: 'wda_stop',
+                    risk: 'low',
+                    target: { pids: killed, recovered: true, projectPath: sig.projectPath, udid: sig.udid },
+                    consent: { required: false, approved: true },
+                    status: 'restored',
+                    detail: 'managed WDA located by command signature (registry entry missing)',
+                });
+                return qaOk({ stopped: true, pid: killed[0], pids: killed, recovered: true }, `stopped managed WDA pid ${killed.join(', ')} (located by its xcodebuild signature; registry entry was missing)`);
+            }
             try {
                 process.kill(proc.pid, 'SIGTERM');
             }
             catch {
                 /* already gone */
             }
+            unregisterManagedProcess(proc.pid);
             managedProcesses.delete(session.id);
             sessions.addEnvChange(session, `wda stop pid ${proc.pid}`);
             sessions.recordMutation(session, {
@@ -176,7 +288,13 @@ export function registerWda(server, sessions) {
         }
         if (action === 'build' || action === 'start') {
             if (!targetUdid) {
-                return qaError({ what: `qa_wda ${action} requires a simulator/device UDID`, changedState: false, retrySafe: true, failureCode: 'NO_DEVICE', nextSteps: ['Boot/select a simulator with qa_ios boot, or pass udid explicitly.'] });
+                return qaError({
+                    what: `qa_wda ${action} requires a simulator/device UDID`,
+                    changedState: false,
+                    retrySafe: true,
+                    failureCode: 'NO_DEVICE',
+                    nextSteps: ['Boot/select a simulator with qa_ios boot, or pass device explicitly.'],
+                });
             }
             if (action === 'start' && configured.reuse) {
                 const reuseStartedAt = Date.now();
@@ -184,19 +302,66 @@ export function registerWda(server, sessions) {
                 const reuseCheckMs = Date.now() - reuseStartedAt;
                 sessions.addMilestoneDuration(session, 'wda_reuse_check_ms', reuseCheckMs);
                 if (existing.reachable && existing.ready) {
-                    return qaOk({ started: false, reused: true, ready: true, webDriverAgentUrl: url, udid: targetUdid, wda: existing, wdaConfig: configured, reuseCheckMs }, `reused existing WDA at ${url}; /status is ready\nNext: qa_wda attach.`);
+                    return qaOk({
+                        started: false,
+                        reused: true,
+                        ready: true,
+                        webDriverAgentUrl: url,
+                        udid: targetUdid,
+                        wda: existing,
+                        wdaConfig: effectiveConfig,
+                        reuseCheckMs,
+                    }, `reused existing WDA at ${url}; /status is ready\nNext: qa_wda attach.`);
                 }
             }
+            // Never start a second managed xcodebuild over a live one: the new runner would fight it
+            // for the port and the old one would be orphaned (managedProcesses would be overwritten).
+            const running = action === 'start' ? liveManagedWda(session.id) : undefined;
+            if (running) {
+                return qaError({
+                    what: `A managed WDA (pid ${running.pid}${running.adopted ? ', adopted from a previous server run' : ''}) is already running for this session`,
+                    changedState: false,
+                    retrySafe: true,
+                    failureCode: 'WDA_START_FAILED',
+                    nextSteps: ['Use it (qa_wda attach), or stop it first with qa_wda { action:"stop" } and retry start.'],
+                }, { managedPid: running.pid, adopted: running.adopted, webDriverAgentUrl: url });
+            }
             const xcode = await xcodeAvailable();
             if (!xcode.available) {
-                return qaError({ what: 'Xcode command line tools are unavailable', changedState: false, retrySafe: true, failureCode: 'BACKEND_UNSUPPORTED', nextSteps: [xcode.error ?? 'Install Xcode and select it with xcode-select.'] }, { xcode });
+                return qaError({
+                    what: 'Xcode command line tools are unavailable',
+                    changedState: false,
+                    retrySafe: true,
+                    failureCode: 'BACKEND_UNSUPPORTED',
+                    nextSteps: [xcode.error ?? 'Install Xcode and select it with xcode-select.'],
+                }, { xcode });
             }
             if (!projectPath || !existsSync(projectPath)) {
-                return qaError({ what: `qa_wda ${action} requires wdaProjectPath pointing to WebDriverAgent.xcodeproj`, changedState: false, retrySafe: true, failureCode: 'NO_ARTIFACT', nextSteps: ['Pass wdaProjectPath, for example path/to/WebDriverAgent.xcodeproj.'] }, { xcode, wdaProjectPath: projectPath ?? null });
+                return qaError({
+                    what: `qa_wda ${action} requires wdaProjectPath pointing to WebDriverAgent.xcodeproj`,
+                    changedState: false,
+                    retrySafe: true,
+                    failureCode: 'NO_ARTIFACT',
+                    nextSteps: [
+                        "Pass wdaProjectPath, for example path/to/WebDriverAgent.xcodeproj, or install Appium's WebDriverAgent (appium driver install xcuitest) so it is auto-discovered under ~/.appium.",
+                    ],
+                }, { xcode, wdaProjectPath: projectPath ?? null, wdaProjectSource });
             }
             const args = action === 'build'
-                ? managedWdaBuildArgs({ projectPath, udid: targetUdid, derivedDataPath: ddPath, scheme, developmentTeam: configured.developmentTeam })
-                : managedWdaStartArgs({ projectPath, udid: targetUdid, derivedDataPath: ddPath, scheme, developmentTeam: configured.developmentTeam });
+                ? managedWdaBuildArgs({
+                    projectPath,
+                    udid: targetUdid,
+                    derivedDataPath: ddPath,
+                    scheme,
+                    developmentTeam: configured.developmentTeam,
+                })
+                : managedWdaStartArgs({
+                    projectPath,
+                    udid: targetUdid,
+                    derivedDataPath: ddPath,
+                    scheme,
+                    developmentTeam: configured.developmentTeam,
+                });
             const gate = consumeConsent(consentId, approve, { action: `wda_${action}`, affects: { udid: targetUdid, projectPath } });
             if (!gate.approved) {
                 sessions.recordMutation(session, {
@@ -207,7 +372,13 @@ export function registerWda(server, sessions) {
                     consent: { required: true, approved: false },
                     status: 'requested',
                 });
-                return requireConsent({ action: `wda_${action}`, risk: 'medium', exactCommand: `xcodebuild ${args.join(' ')}`, affects: { udid: targetUdid, projectPath }, explain: `${action === 'build' ? 'Build' : 'Start'} WebDriverAgent with xcodebuild? This can use local signing context and run for a while.` });
+                return requireConsent({
+                    action: `wda_${action}`,
+                    risk: 'medium',
+                    exactCommand: `xcodebuild ${args.join(' ')}`,
+                    affects: { udid: targetUdid, projectPath },
+                    explain: `${action === 'build' ? 'Build' : 'Start'} WebDriverAgent with xcodebuild? This can use local signing context and run for a while.`,
+                });
             }
             sessions.recordMutation(session, {
                 tool: 'qa_wda',
@@ -237,13 +408,17 @@ export function registerWda(server, sessions) {
                         detail: `${failureCode}: exit ${r.code}`,
                     });
                     return qaError({
-                        what: failureCode === 'WDA_SIGNING_FAILED' ? `WDA signing/provisioning failed with exit ${r.code}` : `WDA build failed with exit ${r.code}`,
+                        what: failureCode === 'WDA_SIGNING_FAILED'
+                            ? `WDA signing/provisioning failed with exit ${r.code}`
+                            : `WDA build failed with exit ${r.code}`,
                         changedState: true,
                         retrySafe: failureCode !== 'WDA_SIGNING_FAILED',
                         failureCode,
                         artifactUri: logUri,
                         nextSteps: failureCode === 'WDA_SIGNING_FAILED'
-                            ? ['Open the WDA build log artifact, configure a valid development team/certificate/provisioning profile for the device, then retry.']
+                            ? [
+                                'Open the WDA build log artifact, configure a valid development team/certificate/provisioning profile for the device, then retry.',
+                            ]
                             : ['Open the WDA build log artifact, fix the Xcode build error, then retry.'],
                     }, { xcode, logUri, timedOut: r.timedOut });
                 }
@@ -256,22 +431,49 @@ export function registerWda(server, sessions) {
                     status: 'executed',
                     ledgerUri: logUri,
                 });
-                return qaOk({ built: true, logUri, xcode, command: ['xcodebuild', ...args], wdaConfig: configured }, `WDA build completed → ${logUri}`);
+                const wdaBuildProduct = managedWdaBuildProductStatus(ddPath);
+                return qaOk({
+                    built: true,
+                    logUri,
+                    xcode,
+                    command: ['xcodebuild', ...args],
+                    wdaConfig: effectiveConfig,
+                    wdaProjectPath: projectPath,
+                    wdaProjectSource,
+                    derivedDataPath: ddPath,
+                    wdaBuildProduct,
+                }, `WDA build completed (${wdaProjectSource === 'appium-discovered' ? 'auto-discovered Appium WDA ' : ''}${projectPath}) > ${logUri}`);
             }
             const logUri = sessions.saveArtifact(session, 'wda', `wda-start-${Date.now()}.log`, '', 'text/plain', 'WDA start log');
             const rec = sessions.findArtifact(logUri);
             const fd = openSync(rec.rec.path, 'a');
             sessions.milestone(session, 'wda_start_start');
-            const child = spawn('xcodebuild', args, { detached: true, stdio: ['ignore', fd, fd] });
+            let child;
+            try {
+                child = spawn('xcodebuild', args, { detached: true, stdio: ['ignore', fd, fd] });
+            }
+            finally {
+                closeSync(fd); // the child holds its own duplicate; ours would leak one fd per start
+            }
             sessions.milestone(session, 'wda_start_end');
+            child.on('error', () => undefined); // spawn failure surfaces as WDA_START_FAILED below, not a crash
             child.unref();
             managedProcesses.set(session.id, { pid: child.pid ?? -1, logUri });
+            // Reapable if this server crashes; `endpoint` lets the next server adopt it when healthy.
+            registerManagedProcess(child.pid, 'wda', session.id, { endpoint: url });
             sessions.addEnvChange(session, `wda start pid ${child.pid ?? 'unknown'} ${projectPath} ${targetUdid}`);
             sessions.recordMutation(session, {
                 tool: 'qa_wda',
                 action: 'wda_start',
                 risk: 'medium',
-                target: { udid: targetUdid, projectPath, derivedDataPath: ddPath, scheme: scheme ?? null, pid: child.pid ?? null, webDriverAgentUrl: url },
+                target: {
+                    udid: targetUdid,
+                    projectPath,
+                    derivedDataPath: ddPath,
+                    scheme: scheme ?? null,
+                    pid: child.pid ?? null,
+                    webDriverAgentUrl: url,
+                },
                 consent: { required: true, consentId, approved: true },
                 status: 'executed',
                 ledgerUri: logUri,
@@ -284,7 +486,14 @@ export function registerWda(server, sessions) {
                     tool: 'qa_wda',
                     action: 'wda_start',
                     risk: 'medium',
-                    target: { udid: targetUdid, projectPath, derivedDataPath: ddPath, scheme: scheme ?? null, pid: child.pid ?? null, webDriverAgentUrl: url },
+                    target: {
+                        udid: targetUdid,
+                        projectPath,
+                        derivedDataPath: ddPath,
+                        scheme: scheme ?? null,
+                        pid: child.pid ?? null,
+                        webDriverAgentUrl: url,
+                    },
                     consent: { required: true, consentId, approved: true },
                     status: 'blocked',
                     ledgerUri: logUri,
@@ -296,10 +505,34 @@ export function registerWda(server, sessions) {
                     retrySafe: true,
                     failureCode: 'WDA_START_FAILED',
                     artifactUri: logUri,
-                    nextSteps: ['Open the WDA start log artifact, fix the launch/signing/device issue, then retry qa_wda start. If WDA eventually becomes ready, qa_wda attach can still use this managed process.'],
-                }, { started: true, ready: false, pid: child.pid ?? null, logUri, webDriverAgentUrl: url, command: ['xcodebuild', ...args], wdaConfig: configured, wda: waited.status, startupWaitMs: waited.durationMs });
+                    nextSteps: [
+                        'Open the WDA start log artifact, fix the launch/signing/device issue, then retry qa_wda start. If WDA eventually becomes ready, qa_wda attach can still use this managed process.',
+                    ],
+                }, {
+                    started: true,
+                    ready: false,
+                    pid: child.pid ?? null,
+                    logUri,
+                    webDriverAgentUrl: url,
+                    command: ['xcodebuild', ...args],
+                    wdaConfig: effectiveConfig,
+                    wda: waited.status,
+                    startupWaitMs: waited.durationMs,
+                });
             }
-            return qaOk({ started: true, ready: true, pid: child.pid ?? null, logUri, webDriverAgentUrl: url, command: ['xcodebuild', ...args], wdaConfig: configured, wda: waited.status, startupWaitMs: waited.durationMs }, `started managed WDA pid ${child.pid ?? 'unknown'} and /status is ready → ${logUri}\nNext: qa_wda attach.`);
+            return qaOk({
+                started: true,
+                ready: true,
+                pid: child.pid ?? null,
+                logUri,
+                webDriverAgentUrl: url,
+                wdaProjectPath: projectPath,
+                wdaProjectSource,
+                command: ['xcodebuild', ...args],
+                wdaConfig: effectiveConfig,
+                wda: waited.status,
+                startupWaitMs: waited.durationMs,
+            }, `started managed WDA pid ${child.pid ?? 'unknown'} and /status is ready > ${logUri}\nNext: qa_wda attach.`);
         }
         const status = await checkWda(url);
         const xcode = await xcodeAvailable();
@@ -307,7 +540,9 @@ export function registerWda(server, sessions) {
         const appId = bundleId ?? session.appId ?? null;
         const artifactSummary = latestWdaArtifacts(session);
         const wdaProjectDiscovery = discoverWdaProjects(session.root, projectPath ? [projectPath] : []);
-        const wdaBuildProduct = (configured.mode === 'managed' || !!projectPath) ? managedWdaBuildProductStatus(ddPath) : null;
+        // Reported whenever managed WDA is in play OR a derived-data cache exists (e.g. after a
+        // qa_wda build that used an auto-discovered Appium project and no explicit path).
+        const wdaBuildProduct = configured.mode === 'managed' || !!projectPath || existsSync(ddPath) ? managedWdaBuildProductStatus(ddPath) : null;
         const simctlOk = await sim.simctlAvailable().catch(() => false);
         const simulators = simctlOk ? await sim.listSimulators().catch(() => []) : [];
         const bootedSimulators = simulators.filter((s) => s.state === 'Booted');
@@ -322,7 +557,7 @@ export function registerWda(server, sessions) {
             bundleId: appId,
             webDriverAgentUrl: url,
             wda: status,
-            wdaConfig: configured,
+            wdaConfig: effectiveConfig,
             wdaProjectDiscovery,
             signing: wdaSigningStatus(configured),
             wdaBuildProduct,
@@ -351,13 +586,19 @@ export function registerWda(server, sessions) {
                 issues.push(issue('IOS_SIMULATOR_RUNTIME_MISSING', 'xcrun simctl is available, but no iOS simulators were found', 'Install an iOS simulator runtime in Xcode, create an iPhone simulator, then retry qa_wda doctor.', 'blocker', 'SIMULATOR_RUNTIME_MISSING'));
             }
             else if (!bootedUdid && simctlOk && bootedSimulators.length === 0) {
-                issues.push(issue('NO_BOOTED_SIMULATOR', 'no booted iOS simulator was detected', 'Boot/select a simulator with qa_ios boot, or pass udid for an already-running WDA target.'));
+                issues.push(issue('NO_BOOTED_SIMULATOR', 'no booted iOS simulator was detected', 'Boot/select a simulator with qa_ios boot, or pass device for an already-running WDA target.'));
             }
             if (!bootedUdid)
-                issues.push(issue('NO_UDID', 'no simulator/device UDID is bound to this session', 'Boot/select a simulator with qa_ios boot, or pass udid explicitly.'));
-            if (wantsManaged && (!projectPath || !existsSync(projectPath))) {
+                issues.push(issue('NO_UDID', 'no simulator/device UDID is bound to this session', 'Boot/select a simulator with qa_ios boot, or pass device explicitly.'));
+            // No path given but a user-installed Appium WDA exists: build/start will auto-use it.
+            const appiumAuto = wantsManaged && !projectPath ? discoverAppiumWdaProjects()[0] : undefined;
+            if (wantsManaged && (!projectPath || !existsSync(projectPath)) && !appiumAuto) {
                 const discovered = wdaProjectDiscovery.candidates[0];
-                issues.push(issue('WDA_PROJECT_MISSING', discovered ? `managed WDA needs wdaProjectPath; discovered candidate ${discovered}` : 'managed WDA needs a WebDriverAgent.xcodeproj path; no local candidate was discovered', discovered ? `Pass wdaProjectPath: "${discovered}", or configure ios.wda for that checked-out WebDriverAgent project.` : 'Check out WebDriverAgent/Appium WDA, pass wdaProjectPath, or provide an external WDA URL.'));
+                issues.push(issue('WDA_PROJECT_MISSING', discovered
+                    ? `managed WDA needs wdaProjectPath; discovered candidate ${discovered}`
+                    : 'managed WDA needs a WebDriverAgent.xcodeproj path; no local candidate was discovered', discovered
+                    ? `Pass wdaProjectPath: "${discovered}", or configure ios.wda for that checked-out WebDriverAgent project.`
+                    : 'Check out WebDriverAgent/Appium WDA, pass wdaProjectPath, or provide an external WDA URL.'));
             }
             if (wantsManaged && projectPath && existsSync(projectPath) && wdaBuildProduct && !wdaBuildProduct.built)
                 issues.push(issue('WDA_NOT_BUILT', `no WebDriverAgentRunner .app was found under derivedDataPath ${wdaBuildProduct.checkedPath}`, 'Run qa_wda build first, or point ios.wda.derivedDataPath at a cache containing a built WebDriverAgentRunner product.'));
@@ -395,7 +636,9 @@ export function registerWda(server, sessions) {
                 changedState: false,
                 retrySafe: true,
                 failureCode: 'MULTIPLE_DEVICES',
-                nextSteps: ['Pass udid explicitly, or bind the session to a device first. This prevents attaching to a stale WDA for the wrong device.'],
+                nextSteps: [
+                    'Pass device explicitly, or bind the session to a device first. This prevents attaching to a stale WDA for the wrong device.',
+                ],
             }, base);
         }
         if (!status.reachable) {
@@ -408,7 +651,12 @@ export function registerWda(server, sessions) {
             }, base);
         }
         try {
-            const sessionOptions = { bundleId: appId ?? undefined, udid: targetUdid, capabilities: configured.capabilities, settings: configured.settings };
+            const sessionOptions = {
+                bundleId: appId ?? undefined,
+                udid: targetUdid,
+                capabilities: configured.capabilities,
+                settings: configured.settings,
+            };
             const createStarted = Date.now();
             let created;
             try {
@@ -424,7 +672,7 @@ export function registerWda(server, sessions) {
                     action: 'wda_attach',
                     risk: 'medium',
                     target: { webDriverAgentUrl: url, udid: targetUdid, bundleId: appId ?? null, reportedDevice: mismatchedUdid },
-                    consent: { required: !loopback && !configAllowed, consentId, approved: loopback || configAllowed || !!approve },
+                    consent: { required: !loopback && !userAllowed, consentId, approved: loopback || userAllowed || !!approve },
                     status: 'blocked',
                     detail: 'WDA reported a different device',
                 });
@@ -436,7 +684,11 @@ export function registerWda(server, sessions) {
                     nextSteps: ['Stop the stale WDA process or start a new WDA session for the intended UDID.'],
                 }, { ...base, capabilities: created.capabilities ?? null, wdaSessionId: created.sessionId });
             }
-            const driver = new WdaDriver(url, { ...sessionOptions, sessionId: created.sessionId, onTiming: (kind, ms) => recordWdaTiming(session, kind, ms, sessions) });
+            const driver = new WdaDriver(url, {
+                ...sessionOptions,
+                sessionId: created.sessionId,
+                onTiming: (kind, ms) => recordWdaTiming(session, kind, ms, sessions),
+            });
             session.driver = driver;
             session.device = targetUdid;
             if (appId)
@@ -447,8 +699,14 @@ export function registerWda(server, sessions) {
                 tool: 'qa_wda',
                 action: 'wda_attach',
                 risk: 'medium',
-                target: { webDriverAgentUrl: url, udid: targetUdid, bundleId: appId ?? null, wdaSessionId: created.sessionId, capabilities: created.capabilities ?? null },
-                consent: { required: !loopback && !configAllowed, consentId, approved: true },
+                target: {
+                    webDriverAgentUrl: url,
+                    udid: targetUdid,
+                    bundleId: appId ?? null,
+                    wdaSessionId: created.sessionId,
+                    capabilities: created.capabilities ?? null,
+                },
+                consent: { required: !loopback && !userAllowed, consentId, approved: true },
                 status: 'executed',
             });
             return qaOk({ ...base, sessionActive: true, wdaSessionId: created.sessionId, capabilities: created.capabilities ?? null }, `attached WDA structured iOS backend at ${url}\nNext: qa_snapshot / qa_act / qa_flow_run can use WDA-backed structured operations.`);
@@ -460,7 +718,7 @@ export function registerWda(server, sessions) {
                 action: 'wda_attach',
                 risk: 'medium',
                 target: { webDriverAgentUrl: url, udid: targetUdid, bundleId: appId ?? null },
-                consent: { required: !loopback && !configAllowed, consentId, approved: loopback || configAllowed || !!approve },
+                consent: { required: !loopback && !userAllowed, consentId, approved: loopback || userAllowed || !!approve },
                 status: 'blocked',
                 detail: String(e.message ?? e),
             });