swipium 2.0.1 → 2.2.0

package/dist/tools/wait.js

@@ -1,44 +1,153 @@
 // qa_wait: non-shell synchronization for setup conditions, so agents don't shell out to
-// `sleep`/poll. Waits for: device_online or metro_ready (serving). Jobs are waited on with
-// qa_job_status waitMs. Returns timeout + current state + next steps.
+// `sleep`/poll. Waits for: device_online (adb), metro_ready (serving), wda_ready (WDA /status
+// ready) or simulator_booted (the session's iOS Simulator finished booting, e.g. after qa_ios boot
+// returned status:"booting").
+// Jobs are waited on with qa_job_status waitMs. Returns timeout + current state + next steps.
 import { z } from 'zod';
-import { qaOk, unknownSessionError } from '../lib/result.js';
+import { cancelledResult, qaAnnotate, qaError, qaOk, unknownSessionError } from '../lib/result.js';
+import { isAbortError, sleepOrCancel, throwIfCancelled } from '../lib/abortScope.js';
 import { resolveDevice } from '../session/attach.js';
 import { metroReadiness } from '../lib/metroState.js';
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+import { checkWda, isLoopbackWdaUrl, remoteWdaAllowedByUser, REMOTE_WDA_ENV } from '../lib/wda.js';
+import { wdaUrlForSession } from './wda.js';
+import { boundSimulatorUdid } from './ios.js';
+import { simulatorBootState } from '../lib/simctl.js';
+/** Default wait. Kept under common client tool timeouts (Codex: 60 s); the model can call again. */
+export const DEFAULT_WAIT_TIMEOUT_MS = 45_000;
+/** Effective upper bound for timeoutMs, same reasoning: one call must not outlive the client's
+ *  timeout. Larger values (older docs said 60000/180000) are accepted and CLAMPED, with a note. */
+export const MAX_WAIT_TIMEOUT_MS = 50_000;
+const POLL_INTERVAL_MS = 1500;
 export function registerWait(server, sessions) {
     server.registerTool('qa_wait', {
         title: 'Wait for a setup condition',
-        description: 'Block (bounded) until a setup condition holds instead of shelling out to sleep: for="device_online" (a device appears) or ' +
-            '"metro_ready" (Metro serving the bundle). Returns satisfied/timedOut + current state. To wait for a job, use qa_job_status waitMs.',
+        description: 'Bounded wait for a setup condition instead of shell sleep: device_online (adb), metro_ready, wda_ready (after qa_wda ' +
+            'start returned status:"starting"), or simulator_booted (the bound iOS Simulator, after qa_ios boot returned ' +
+            'status:"booting"). Returns satisfied, or timedOut:true (call again). For jobs use qa_job_status waitMs.',
         inputSchema: {
             sessionId: z.string(),
-            for: z.enum(['device_online', 'metro_ready']),
-            timeoutMs: z.number().optional().describe('default 60000 (180000 for device_online).'),
+            for: z.enum(['device_online', 'metro_ready', 'wda_ready', 'simulator_booted']),
+            timeoutMs: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe(`default ${DEFAULT_WAIT_TIMEOUT_MS}; values above ${MAX_WAIT_TIMEOUT_MS} are clamped. On timedOut, call again to keep waiting.`),
         },
     }, async ({ sessionId, for: cond, timeoutMs }) => {
         const session = sessions.get(sessionId);
         if (!session)
             return unknownSessionError(sessionId);
-        const deadline = Date.now() + (timeoutMs ?? (cond === 'device_online' ? 180000 : 60000));
-        const intervalMs = 1500;
-        while (Date.now() < deadline) {
-            if (cond === 'device_online') {
-                const dev = await resolveDevice(session);
-                if (dev.available.length > 0)
-                    return qaOk({ satisfied: true, condition: cond, availableDevices: dev.available }, `device online: ${dev.available.join(', ')}`);
-            }
-            else {
+        const requested = timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+        const effectiveMs = Math.min(requested, MAX_WAIT_TIMEOUT_MS);
+        const notes = requested > MAX_WAIT_TIMEOUT_MS
+            ? [
+                `timeoutMs ${requested} clamped to ${MAX_WAIT_TIMEOUT_MS}: one call stays under client tool timeouts (Codex: 60 s). Call qa_wait again to keep waiting.`,
+            ]
+            : [];
+        const done = (r) => qaAnnotate(r, notes);
+        const deadline = Date.now() + effectiveMs;
+        // wda_ready: the URL already used by this session (attached driver / last qa_wda start), else
+        // the configured one, which must pass the same non-loopback gate as qa_wda.
+        let wdaUrl;
+        if (cond === 'wda_ready') {
+            const resolved = wdaUrlForSession(session);
+            if (resolved.source === 'config' && !isLoopbackWdaUrl(resolved.url) && !remoteWdaAllowedByUser(resolved.url))
+                return qaError({
+                    what: `Refused to poll non-loopback WDA URL ${resolved.url} from the repository config`,
+                    changedState: false,
+                    retrySafe: false,
+                    failureCode: 'DESTRUCTIVE_REFUSED',
+                    nextSteps: [
+                        `Attach it first with qa_wda { action:"attach", webDriverAgentUrl, allowNonLoopback:true } (consent-gated), or set ${REMOTE_WDA_ENV}=<exact url> in the MCP server environment.`,
+                    ],
+                });
+            wdaUrl = resolved.url;
+        }
+        let lastWda;
+        // simulator_booted: the iOS Simulator bound to this session (qa_ios boot binds it even when
+        // it returns status:"booting").
+        let simUdid;
+        if (cond === 'simulator_booted') {
+            simUdid = boundSimulatorUdid(session);
+            if (!simUdid)
+                return qaError({
+                    what: 'No iOS Simulator bound to this session',
+                    changedState: false,
+                    retrySafe: true,
+                    failureCode: 'NO_DEVICE',
+                    nextSteps: ['Call qa_ios { action:"boot" } first; it binds the simulator even while it is still booting.'],
+                });
+        }
+        let lastSim;
+        // Cancellation (notifications/cancelled): the call's signal is scoped by the tool wrapper
+        // (abortScope), so every poll checks it and the pause between polls wakes on abort.
+        try {
+            while (Date.now() < deadline) {
+                throwIfCancelled();
+                if (cond === 'wda_ready') {
+                    lastWda = await checkWda(wdaUrl, Math.max(250, Math.min(1500, deadline - Date.now())));
+                    throwIfCancelled();
+                    if (lastWda.ready)
+                        return done(qaOk({ satisfied: true, condition: cond, webDriverAgentUrl: wdaUrl, wda: lastWda }, `WDA ready at ${wdaUrl}\nNext: qa_wda attach (if the session is not attached yet).`));
+                    await sleepOrCancel(Math.min(POLL_INTERVAL_MS, Math.max(0, deadline - Date.now())));
+                    continue;
+                }
+                if (cond === 'simulator_booted') {
+                    lastSim = await simulatorBootState(simUdid, Math.max(250, Math.min(3000, deadline - Date.now())));
+                    throwIfCancelled();
+                    if (lastSim.state === 'booted') {
+                        sessions.milestone(session, 'simulator_boot_end');
+                        return done(qaOk({ satisfied: true, condition: cond, udid: simUdid, simulator: lastSim }, `Simulator ${lastSim.name ?? simUdid} booted\nNext: qa_ios install/launch (or qa_wda start).`));
+                    }
+                    if (lastSim.state === 'failed' || lastSim.state === 'shutdown' || lastSim.state === 'unknown')
+                        return done(qaError({
+                            what: lastSim.state === 'failed'
+                                ? `Simulator ${simUdid} failed to boot: ${lastSim.error}`
+                                : lastSim.state === 'shutdown'
+                                    ? `Simulator ${simUdid} is not booting (simctl state: ${lastSim.simctlState})`
+                                    : `Simulator ${simUdid} is not listed by simctl`,
+                            changedState: false,
+                            retrySafe: true,
+                            failureCode: lastSim.state === 'failed' && /timed out/i.test(lastSim.error) ? 'SIMULATOR_BOOT_TIMEOUT' : 'SIMULATOR_BOOT_FAILED',
+                            nextSteps: ['Boot it again with qa_ios { action:"boot" }, or pick another simulator from qa_ios { action:"list" }.'],
+                        }));
+                    await sleepOrCancel(Math.min(POLL_INTERVAL_MS, Math.max(0, deadline - Date.now())));
+                    continue;
+                }
                 const dev = await resolveDevice(session);
-                if (dev.effective) {
+                throwIfCancelled();
+                if (cond === 'device_online') {
+                    if (dev.available.length > 0)
+                        return done(qaOk({ satisfied: true, condition: cond, availableDevices: dev.available }, `device online: ${dev.available.join(', ')}`));
+                }
+                else if (dev.effective) {
                     const rd = await metroReadiness(dev.effective);
                     if (rd.serving)
-                        return qaOk({ satisfied: true, condition: cond, metro: rd }, `Metro serving=${rd.serving} reverse=${rd.reverseSet} ready=${rd.ready}`);
+                        return done(qaOk({ satisfied: true, condition: cond, metro: rd }, `Metro serving=${rd.serving} reverse=${rd.reverseSet} ready=${rd.ready}`));
                 }
+                await sleepOrCancel(Math.min(POLL_INTERVAL_MS, Math.max(0, deadline - Date.now())));
             }
-            await sleep(intervalMs);
         }
-        return qaOk({ satisfied: false, timedOut: true, condition: cond }, `Timed out waiting for ${cond}. ${cond === 'device_online' ? 'Boot one with qa_prepare_target { bindOnly:true }.' : 'Start Metro with qa_metro action="start", or qa_metro diagnose.'}`);
+        catch (e) {
+            if (isAbortError(e))
+                return cancelledResult(`qa_wait ${cond} cancelled: the call was aborted before the condition held`);
+            throw e;
+        }
+        const hint = cond === 'device_online'
+            ? 'boot one with qa_prepare_target { bindOnly:true }.'
+            : cond === 'metro_ready'
+                ? 'start Metro with qa_metro action="start", or qa_metro diagnose.'
+                : cond === 'simulator_booted'
+                    ? 'check qa_ios { action:"list" } (a cold boot of a fresh runtime can take a few minutes).'
+                    : 'check qa_wda { action:"logs" } / { action:"diagnose" } (a managed WDA may have failed to launch).';
+        return done(qaOk({
+            satisfied: false,
+            timedOut: true,
+            condition: cond,
+            ...(cond === 'wda_ready' ? { webDriverAgentUrl: wdaUrl, wda: lastWda ?? null } : {}),
+            ...(cond === 'simulator_booted' ? { udid: simUdid, simulator: lastSim ?? null } : {}),
+        }, `Timed out waiting for ${cond}. Call qa_wait again to keep waiting, or ${hint}`));
     });
 }
 //# sourceMappingURL=wait.js.map

package/dist/tools/wait.js.map

@@ -1 +1 @@
-{"version":3,"file":"wait.js","sourceRoot":"","sources":["../../src/tools/wait.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wait.js","sourceRoot":"","sources":["../../src/tools/wait.ts"],"names":[],"mappings":"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"}

package/dist/tools/wda.js

@@ -2,7 +2,8 @@ import { z } from 'zod';
 import { spawn } from 'node:child_process';
 import { closeSync, existsSync, openSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { isAbsolute, join } from 'node:path';
-import { qaError, qaOk, unknownSessionError } from '../lib/result.js';
+import { cancelledResult, qaError, qaOk, unknownSessionError } from '../lib/result.js';
+import { isAbortError, runWithSignal } from '../lib/abortScope.js';
 import { consumeConsent, requireConsent } from '../consent/consent.js';
 import { sensitiveRefusal } from '../lib/sensitive.js';
 import { run } from '../lib/spawn.js';
@@ -12,6 +13,17 @@ import { recordWdaTiming, wdaRecommendations, wdaTimingSummary } from '../lib/wd
 import { WdaDriver } from '../drivers/WdaDriver.js';
 import * as sim from '../lib/simctl.js';
 import { findManagedWdaProcesses, killManagedWda, reclaimPid, registerManagedProcess, registeredWdaForSession, unregisterManagedProcess, } from '../session/processRegistry.js';
+/** qa_wda actions that run xcodebuild and are consent-gated as `wda_<name>` (CONSENT_ACTIONS in consent.ts). */
+export const WDA_XCODEBUILD_ACTIONS = ['build', 'start'];
+function isWdaXcodebuildAction(a) {
+    return WDA_XCODEBUILD_ACTIONS.includes(a);
+}
+/** How long `qa_wda start` blocks inside ONE tool call waiting for /status. One call must stay
+ *  under common client tool timeouts (Codex: 60 s), so a slower start returns status:"starting"
+ *  and the agent polls with qa_wait { for:"wda_ready" } (bounded by ios.wda.startupTimeoutMs). */
+export const WDA_START_CALL_WAIT_MS = 45_000;
+/** Kill timer for the background `qa_wda build` job (a cold WDA build-for-testing is slow). */
+export const WDA_BUILD_TIMEOUT_MS = 600_000;
 const managedProcesses = new Map();
 function pidIsAlive(pid) {
     if (!(pid > 0))
@@ -64,6 +76,19 @@ export function lastManagedWdaStart(session) {
         ...(port ? { port } : {}),
     };
 }
+/** The WDA URL to probe for this session: the attached WdaDriver's, else the URL of the latest
+ *  executed `qa_wda start` (both already passed the loopback/consent gate), else the configured
+ *  one (source 'config': the caller must apply the non-loopback gate). Exported for qa_wait. */
+export function wdaUrlForSession(session) {
+    if (session.driver instanceof WdaDriver)
+        return { url: session.driver.baseUrl, source: 'driver' };
+    const m = [...(session.mutations ?? [])]
+        .reverse()
+        .find((r) => r.tool === 'qa_wda' && r.action === 'wda_start' && r.status === 'executed' && typeof r.target?.webDriverAgentUrl === 'string');
+    if (m)
+        return { url: String(m.target.webDriverAgentUrl), source: 'wda_start' };
+    return { url: loadWdaConfig(session.root).url, source: 'config' };
+}
 const isLoopback = isLoopbackWdaUrl;
 function latestWdaArtifacts(session) {
     const logs = [...session.artifacts].reverse().filter((a) => a.kind === 'wda');
@@ -120,19 +145,20 @@ 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 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.',
+        description: 'Manage the iOS WebDriverAgent backend behind structured iOS tap/type/snapshot: attach an external WDA ' +
+            '(webDriverAgentUrl), build/start a managed one (consent-gated), stop it; status/doctor/diagnose/logs/tune inspect ' +
+            'the setup. build runs as a background job (poll qa_job_status); start waits up to 45 s, then returns status:"starting" ' +
+            '(poll qa_wait { for:"wda_ready" }).',
         inputSchema: {
             sessionId: z.string(),
             action: z.enum(['status', 'doctor', 'build', 'start', 'stop', 'attach', 'diagnose', 'logs', 'tune']),
             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).'),
+            device: z.string().optional().describe('Simulator UDID (default: 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.'),
+            scheme: z.string().optional().describe('Default WebDriverAgentRunner.'),
             allowNonLoopback: z.boolean().optional().describe('Required to use a non-loopback external WDA URL.'),
             consentId: z.string().optional(),
             approve: z.boolean().optional(),
@@ -187,7 +213,7 @@ export function registerWda(server, sessions) {
         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 discoveredAppiumProject = !explicitProjectPath && isWdaXcodebuildAction(action) ? discoverAppiumWdaProjects()[0] : undefined;
         const projectPath = explicitProjectPath ?? discoveredAppiumProject;
         const wdaProjectSource = explicitProjectPath ? 'argument' : discoveredAppiumProject ? 'appium-discovered' : null;
         const ddPath = resolvePath(derivedDataPath) ?? configured.derivedDataPath;
@@ -286,7 +312,7 @@ export function registerWda(server, sessions) {
             });
             return qaOk({ stopped: true, pid: proc.pid, logUri: proc.logUri }, `stopped managed WDA pid ${proc.pid}`);
         }
-        if (action === 'build' || action === 'start') {
+        if (isWdaXcodebuildAction(action)) {
             if (!targetUdid) {
                 return qaError({
                     what: `qa_wda ${action} requires a simulator/device UDID`,
@@ -389,60 +415,30 @@ export function registerWda(server, sessions) {
                 status: 'approved',
             });
             if (action === 'build') {
-                sessions.milestone(session, 'wda_build_start');
-                const r = await run('xcodebuild', args, { timeoutMs: 180000 });
-                sessions.milestone(session, 'wda_build_end');
-                const log = `${r.stdout}\n${r.stderr}`;
-                const logUri = sessions.saveArtifact(session, 'wda', `wda-build-${Date.now()}.log`, log, 'text/plain', `WDA build ${r.code === 0 ? 'success' : 'failed'}`);
-                sessions.addEnvChange(session, `wda build ${projectPath} ${targetUdid}`);
-                if (r.code !== 0) {
-                    const failureCode = classifyWdaBuildFailure(log);
-                    sessions.recordMutation(session, {
-                        tool: 'qa_wda',
-                        action: 'wda_build',
-                        risk: 'medium',
-                        target: { udid: targetUdid, projectPath, derivedDataPath: ddPath, scheme: scheme ?? null },
-                        consent: { required: true, consentId, approved: true },
-                        status: 'blocked',
-                        ledgerUri: logUri,
-                        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}`,
-                        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, fix the Xcode build error, then retry.'],
-                    }, { xcode, logUri, timedOut: r.timedOut });
-                }
-                sessions.recordMutation(session, {
-                    tool: 'qa_wda',
-                    action: 'wda_build',
-                    risk: 'medium',
-                    target: { udid: targetUdid, projectPath, derivedDataPath: ddPath, scheme: scheme ?? null },
-                    consent: { required: true, consentId, approved: true },
-                    status: 'executed',
-                    ledgerUri: logUri,
-                });
-                const wdaBuildProduct = managedWdaBuildProductStatus(ddPath);
-                return qaOk({
-                    built: true,
-                    logUri,
+                // xcodebuild build-for-testing can take minutes: run it as a background job so this call
+                // returns at once (one tool call stays under client timeouts). Consent was consumed above.
+                const job = sessions.createJob(session, 'wda_build');
+                const buildCtx = {
+                    projectPath,
+                    udid: targetUdid,
+                    derivedDataPath: ddPath,
+                    scheme,
+                    consentId,
+                    args,
                     xcode,
-                    command: ['xcodebuild', ...args],
+                    wdaProjectSource,
                     wdaConfig: effectiveConfig,
+                };
+                void runWithSignal(sessions.abortSignal(session, job.jobId), () => runWdaBuildJob(sessions, session, job, buildCtx));
+                return qaOk({
+                    jobId: job.jobId,
+                    status: 'running',
+                    kind: job.kind,
+                    command: ['xcodebuild', ...args],
                     wdaProjectPath: projectPath,
                     wdaProjectSource,
                     derivedDataPath: ddPath,
-                    wdaBuildProduct,
-                }, `WDA build completed (${wdaProjectSource === 'appium-discovered' ? 'auto-discovered Appium WDA ' : ''}${projectPath}) > ${logUri}`);
+                }, `Started WDA build (${wdaProjectSource === 'appium-discovered' ? 'auto-discovered Appium WDA ' : ''}${projectPath}) as job ${job.jobId}.\nNext: qa_job_status { sessionId:"${session.id}", jobId:"${job.jobId}", waitMs:45000 }, then qa_wda start.`);
             }
             const logUri = sessions.saveArtifact(session, 'wda', `wda-start-${Date.now()}.log`, '', 'text/plain', 'WDA start log');
             const rec = sessions.findArtifact(logUri);
@@ -479,9 +475,43 @@ export function registerWda(server, sessions) {
                 ledgerUri: logUri,
                 detail: 'managed WDA process started',
             });
-            const waited = await waitForWdaReady(url, configured.startupTimeoutMs);
+            // Cancelled while waiting: WDA stays started (managed + registered, so the next attach can
+            // adopt it); report CANCELLED, not a WDA startup failure.
+            // Bounded in-call wait: at most WDA_START_CALL_WAIT_MS here; the rest of the configured
+            // startupTimeoutMs is polled by the agent via qa_wait { for:"wda_ready" }.
+            const callWaitMs = Math.min(configured.startupTimeoutMs, WDA_START_CALL_WAIT_MS);
+            const waited = await waitForWdaReady(url, callWaitMs).catch((e) => {
+                if (isAbortError(e))
+                    return null;
+                throw e;
+            });
+            if (!waited)
+                return cancelledResult('qa_wda start cancelled while waiting for WDA; the managed WDA process was left running', true);
             sessions.addMilestoneDuration(session, 'wda_startup_wait_ms', waited.durationMs);
+            const remainingMs = configured.startupTimeoutMs - waited.durationMs;
+            if (!waited.ready && remainingMs > 0 && pidIsAlive(child.pid ?? -1)) {
+                return qaOk({
+                    started: true,
+                    ready: false,
+                    status: 'starting',
+                    pid: child.pid ?? null,
+                    logUri,
+                    webDriverAgentUrl: url,
+                    wdaProjectPath: projectPath,
+                    wdaProjectSource,
+                    command: ['xcodebuild', ...args],
+                    wdaConfig: effectiveConfig,
+                    wda: waited.status,
+                    startupWaitMs: waited.durationMs,
+                    startupTimeoutMs: configured.startupTimeoutMs,
+                    remainingStartupMs: remainingMs,
+                }, `started managed WDA pid ${child.pid ?? 'unknown'}; /status not ready yet after ${Math.round(waited.durationMs / 1000)} s (still starting) > ${logUri}
+` +
+                    `Next: qa_wait { sessionId:"${session.id}", for:"wda_ready" } (repeat while timedOut, up to ~${Math.ceil(remainingMs / 1000)} s more), then qa_wda attach.`);
+            }
             if (!waited.ready) {
+                const exited = remainingMs > 0; // only reached early when the xcodebuild process is gone
+                const why = `WDA not ready after ${waited.durationMs}ms${exited ? ' (the managed xcodebuild process exited)' : ''}`;
                 sessions.recordMutation(session, {
                     tool: 'qa_wda',
                     action: 'wda_start',
@@ -497,10 +527,12 @@ export function registerWda(server, sessions) {
                     consent: { required: true, consentId, approved: true },
                     status: 'blocked',
                     ledgerUri: logUri,
-                    detail: `WDA not ready after ${configured.startupTimeoutMs}ms`,
+                    detail: why,
                 });
                 return qaError({
-                    what: `Managed WDA did not become ready at ${url} within ${configured.startupTimeoutMs}ms`,
+                    what: exited
+                        ? `Managed WDA exited before becoming ready at ${url} (waited ${waited.durationMs}ms)`
+                        : `Managed WDA did not become ready at ${url} within ${configured.startupTimeoutMs}ms`,
                     changedState: true,
                     retrySafe: true,
                     failureCode: 'WDA_START_FAILED',
@@ -732,4 +764,111 @@ export function registerWda(server, sessions) {
         }
     });
 }
+/** Background body of `qa_wda build` (runs inside the job's cancellation scope). The job ends
+ *  done (built) or failed (classified build failure); a cancelled job is left cancelled. Exported
+ *  for tests. */
+export async function runWdaBuildJob(sessions, session, job, ctx) {
+    const signal = sessions.abortSignal(session, job.jobId);
+    const upd = (patch) => sessions.updateJobIfRunning(session, job, patch);
+    const target = { udid: ctx.udid, projectPath: ctx.projectPath, derivedDataPath: ctx.derivedDataPath, scheme: ctx.scheme ?? null };
+    const consent = { required: true, consentId: ctx.consentId, approved: true };
+    upd({ progress: 'xcodebuild build-for-testing' });
+    sessions.milestone(session, 'wda_build_start');
+    let r;
+    try {
+        r = await run('xcodebuild', ctx.args, { timeoutMs: WDA_BUILD_TIMEOUT_MS, signal });
+    }
+    catch (e) {
+        if (isAbortError(e, signal))
+            return; // cancelled (qa_job_cancel / shutdown): the job already says so
+        const what = `xcodebuild could not run: ${String(e.message ?? e)}`;
+        sessions.recordMutation(session, {
+            tool: 'qa_wda',
+            action: 'wda_build',
+            risk: 'medium',
+            target,
+            consent,
+            status: 'blocked',
+            detail: what,
+        });
+        upd({
+            status: 'failed',
+            error: `WDA_BUILD_FAILED: ${what}`,
+            result: { failureCode: 'WDA_BUILD_FAILED', nextSteps: ['Check the Xcode installation (qa_wda doctor), then retry qa_wda build.'] },
+            resultText: `WDA build could not start: ${what}`,
+            endedAt: Date.now(),
+        });
+        return;
+    }
+    sessions.milestone(session, 'wda_build_end');
+    if (signal?.aborted)
+        return;
+    const log = `${r.stdout}\n${r.stderr}`;
+    const logUri = sessions.saveArtifact(session, 'wda', `wda-build-${Date.now()}.log`, log, 'text/plain', `WDA build ${r.code === 0 ? 'success' : 'failed'}`);
+    sessions.addEnvChange(session, `wda build ${ctx.projectPath} ${ctx.udid}`);
+    if (r.code !== 0) {
+        const failureCode = classifyWdaBuildFailure(log);
+        sessions.recordMutation(session, {
+            tool: 'qa_wda',
+            action: 'wda_build',
+            risk: 'medium',
+            target,
+            consent,
+            status: 'blocked',
+            ledgerUri: logUri,
+            detail: `${failureCode}: exit ${r.code}`,
+        });
+        const signing = failureCode === 'WDA_SIGNING_FAILED';
+        const what = signing
+            ? `WDA signing/provisioning failed with exit ${r.code}`
+            : `WDA build failed with exit ${r.code}${r.timedOut ? ` (timed out after ${WDA_BUILD_TIMEOUT_MS} ms)` : ''}`;
+        upd({
+            status: 'failed',
+            error: `${failureCode}: ${what}`,
+            artifactUris: [logUri],
+            result: {
+                failureCode,
+                logUri,
+                timedOut: r.timedOut,
+                retrySafe: !signing,
+                nextSteps: signing
+                    ? [
+                        '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.'],
+            },
+            resultText: `${what}. Log: ${logUri}`,
+            endedAt: Date.now(),
+        });
+        return;
+    }
+    sessions.recordMutation(session, {
+        tool: 'qa_wda',
+        action: 'wda_build',
+        risk: 'medium',
+        target,
+        consent,
+        status: 'executed',
+        ledgerUri: logUri,
+    });
+    const wdaBuildProduct = managedWdaBuildProductStatus(ctx.derivedDataPath);
+    upd({
+        status: 'done',
+        progress: 'done',
+        artifactUris: [logUri],
+        result: {
+            built: true,
+            logUri,
+            xcode: ctx.xcode,
+            command: ['xcodebuild', ...ctx.args],
+            wdaConfig: ctx.wdaConfig,
+            wdaProjectPath: ctx.projectPath,
+            wdaProjectSource: ctx.wdaProjectSource,
+            derivedDataPath: ctx.derivedDataPath,
+            wdaBuildProduct,
+        },
+        resultText: `WDA build completed (${ctx.wdaProjectSource === 'appium-discovered' ? 'auto-discovered Appium WDA ' : ''}${ctx.projectPath}) > ${logUri}\nNext: qa_wda start.`,
+        endedAt: Date.now(),
+    });
+}
 //# sourceMappingURL=wda.js.map