swipium 1.0.0

package/dist/tools/note.js

@@ -0,0 +1,69 @@
+// qa_note — record a structured test outcome (Phase 2.2). Lets the agent state explicitly
+// that a workflow passed / failed / was blocked / skipped / not-applicable, with the reason,
+// missing precondition, required state, and recommended setup. This is how a report
+// distinguishes a real app bug from "no saved flight existed to delete" — so missing test
+// data and intentional skips stop being mislabeled as failures.
+import { z } from 'zod';
+import { qaOk, qaError } from '../lib/result.js';
+const OUTCOMES = ['pass', 'fail', 'blocked', 'skipped', 'not_applicable'];
+const CATEGORIES = ['app_bug', 'mcp_limitation', 'missing_test_data', 'intentionally_skipped', 'destructive_refused', 'other'];
+export function registerNote(server, sessions) {
+    server.registerTool('qa_note', {
+        title: 'Record a test outcome',
+        description: 'Record a STRUCTURED test outcome for one workflow so the report is honest about what was and was not verified. Use outcome="blocked" with a missingPrecondition (e.g. "no saved flight exists") instead of reporting a false failure; "not_applicable" when the workflow does not apply; "skipped" when intentionally not run. Set category to classify (app_bug | mcp_limitation | missing_test_data | intentionally_skipped | destructive_refused | other). Attach artifactUris (screenshots/dumps) as evidence.',
+        inputSchema: {
+            sessionId: z.string(),
+            workflow: z.string().describe('the workflow/test this outcome is about, e.g. "Delete saved flight"'),
+            outcome: z.enum(OUTCOMES).describe('WHAT happened (independent of category).'),
+            category: z.enum(CATEGORIES).optional().describe('WHY / classification — an INDEPENDENT axis from outcome (e.g. a not_applicable outcome may be category=intentionally_skipped). The report cross-tabs the two; they are not folded together.'),
+            reason: z.string().optional(),
+            missingPrecondition: z.string().optional().describe('what state was required but absent, e.g. "no saved flight exists"'),
+            requiredState: z.string().optional().describe('the state the test needs, e.g. "at least one saved flight"'),
+            recommendedSetup: z.string().optional().describe('how to satisfy the precondition next time'),
+            artifactUris: z.array(z.string()).optional(),
+            verifiedVisually: z.boolean().optional().describe('pass was confirmed from a screenshot (animated/map/canvas screen with no structured tree) — counts as a real pass, not a weak one. Attach the screenshot in artifactUris.'),
+        },
+    }, async ({ sessionId, workflow, outcome, category, reason, missingPrecondition, requiredState, recommendedSetup, artifactUris, verifiedVisually }) => {
+        const session = sessions.get(sessionId);
+        if (!session) {
+            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
+        }
+        // A visual-only pass should carry its evidence so the report isn't taking it on faith.
+        if (verifiedVisually && outcome === 'pass' && !(artifactUris && artifactUris.length)) {
+            return qaError({
+                what: 'A visually-verified pass needs a screenshot in artifactUris as evidence.',
+                changedState: false,
+                retrySafe: true,
+                nextSteps: ['Call qa_screenshot (with a reason), then re-call qa_note with its URI in artifactUris.'],
+            });
+        }
+        // A "blocked" outcome with no explanation is exactly the unhelpful case this tool exists
+        // to prevent — nudge for the precondition.
+        if (outcome === 'blocked' && !missingPrecondition && !reason) {
+            return qaError({
+                what: 'A "blocked" outcome needs a missingPrecondition or reason so the report is actionable.',
+                changedState: false,
+                retrySafe: true,
+                nextSteps: ['Re-call qa_note with missingPrecondition (e.g. "no saved flight exists") and/or reason.'],
+            });
+        }
+        // If a declared fixture matches this workflow/precondition, borrow its recommendedSetup
+        // so a blocked outcome carries the setup guidance the agent already declared (P1.4).
+        const fx = session.fixtures.find((f) => f.name.toLowerCase() === workflow.toLowerCase() || (missingPrecondition && f.name.toLowerCase() === missingPrecondition.toLowerCase()));
+        sessions.addNote(session, {
+            at: Date.now(),
+            workflow,
+            outcome: outcome,
+            category: category,
+            reason,
+            missingPrecondition: missingPrecondition ?? fx?.requiredState,
+            requiredState: requiredState ?? fx?.requiredState,
+            recommendedSetup: recommendedSetup ?? fx?.recommendedSetup,
+            artifactUris,
+            verifiedVisually,
+        });
+        const tally = session.notes.reduce((a, n) => ((a[n.outcome] = (a[n.outcome] ?? 0) + 1), a), {});
+        return qaOk({ recorded: { workflow, outcome, category }, tally }, `noted: "${workflow}" → ${outcome}${category ? ` (${category})` : ''}${missingPrecondition ? ` — missing: ${missingPrecondition}` : ''}\ntally: ${Object.entries(tally).map(([k, v]) => `${k}=${v}`).join(' ')}`);
+    });
+}
+//# sourceMappingURL=note.js.map

package/dist/tools/note.js.map

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

package/dist/tools/plan.js

@@ -0,0 +1,49 @@
+// qa_plan (PHASE3-PLAN §3.2) — propose a safe test plan instead of making the agent guess.
+// Synthesizes detectContext() + the session's declared fixtures / observed auth / prepared
+// appId into READY / BLOCKED / UNSAFE workflows. Pure planning logic lives in src/plan/plan.ts.
+import { z } from 'zod';
+import { qaOk, qaError } from '../lib/result.js';
+import { detectContext } from '../context/detect.js';
+import { buildPlan } from '../plan/plan.js';
+import { listFlowFiles } from '../flows/discover.js';
+export function registerPlan(server, sessions) {
+    server.registerTool('qa_plan', {
+        title: 'Plan what to test',
+        description: 'Propose a safe test plan for the current session instead of guessing. Returns READY workflows (with budget profile + satisfied preconditions), BLOCKED workflows (with a category — missing_device/missing_artifact/missing_test_data/missing_toolchain — required state, and how to unblock), and UNSAFE workflows (with a reason, e.g. bundle_cache_loss for fresh_start on a debug RN/Expo build). Call this first to decide what to run. Reads detected context + declared fixtures + observed auth; does not touch the device.',
+        inputSchema: {
+            sessionId: z.string().describe('A session from qa_start_session (its fixtures/auth/root inform the plan).'),
+        },
+    }, async ({ sessionId }) => {
+        const session = sessions.get(sessionId);
+        if (!session) {
+            return qaError({
+                what: 'No such session',
+                changedState: false,
+                retrySafe: true,
+                nextSteps: ['Call qa_start_session first, then qa_plan with its sessionId.'],
+            });
+        }
+        const ctx = await detectContext(session.root);
+        const plan = buildPlan({
+            framework: ctx.framework,
+            hasDevice: ctx.devices.androidOnline.length > 0 || ctx.devices.avds.length > 0,
+            hasApk: ctx.artifacts.apks.length > 0 || ctx.artifacts.ipas.length > 0 || ctx.artifacts.appBundles.length > 0,
+            appPrepared: !!session.appId,
+            fixtures: session.fixtures,
+            auth: session.auth,
+            blockers: ctx.blockers,
+            flows: listFlowFiles(session.root).map((f) => f.name),
+        });
+        const line = (s) => ` - ${s}`;
+        const summary = `Plan for session ${session.id} (framework=${ctx.framework})\n` +
+            `READY (${plan.ready.length}):\n` +
+            (plan.ready.map((w) => line(`${w.workflow} [${w.budgetProfile}]${w.requires.length ? ` needs ${w.requires.join(', ')}` : ''}`)).join('\n') || ' (none)') +
+            `\nBLOCKED (${plan.blocked.length}):\n` +
+            (plan.blocked.map((w) => line(`${w.workflow}: ${w.category} — ${w.requiredState} → ${w.recommendedSetup}`)).join('\n') || ' (none)') +
+            `\nUNSAFE (${plan.unsafe.length}):\n` +
+            (plan.unsafe.map((w) => line(`${w.workflow}: ${w.reason} — ${w.detail}`)).join('\n') || ' (none)') +
+            (plan.notes.length ? `\nnotes:\n` + plan.notes.map(line).join('\n') : '');
+        return qaOk({ ...plan, framework: ctx.framework }, summary);
+    });
+}
+//# sourceMappingURL=plan.js.map

package/dist/tools/plan.js.map

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

package/dist/tools/prepareIosTarget.js

@@ -0,0 +1,99 @@
+// qa_prepare_ios_target (hardening P0.3) — one high-level iOS prepare: boot simulator → install
+// .app → launch bundle → verify → report WDA/visual mode. The cross-platform counterpart to
+// qa_prepare_target's Android path, so qa_test_this can complete iOS first-runs end-to-end.
+import { z } from 'zod';
+import { isAbsolute, join } from 'node:path';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { qaOk, qaError } from '../lib/result.js';
+import { qaFail } from '../oracle/failures.js';
+import { requireConsent, consumeConsent } from '../consent/consent.js';
+import { prepareIos } from '../services/prepareIos.js';
+/** A .app is a directory — hash a stable signature (Info.plist) for consent binding. */
+function appSignature(appPath) {
+    try {
+        const plist = join(appPath, 'Info.plist');
+        if (existsSync(plist))
+            return createHash('sha256').update(readFileSync(plist)).digest('hex').slice(0, 16);
+        return createHash('sha256').update(`${appPath}:${statSync(appPath).mtimeMs}`).digest('hex').slice(0, 16);
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function externalToRoot(session, appPath) {
+    const abs = isAbsolute(appPath) ? appPath : join(session.root, appPath);
+    return !abs.startsWith(session.root);
+}
+export function registerPrepareIosTarget(server, sessions) {
+    server.registerTool('qa_prepare_ios_target', {
+        title: 'Prepare an iOS simulator target',
+        description: 'High-level iOS simulator prepare: pick + boot a simulator, install a simulator .app (consent-gated), launch its bundle id, verify foreground, and report whether structured automation (WDA) is available or it is honestly visual-only. Refuses a .ipa on the simulator (real-device only). attachWda: auto (use WDA if reachable, else visual) | required (fail if no WDA) | skip (visual-only). Returns typed blockers (IPA_NEEDS_REAL_DEVICE, IOS_SIMULATOR_APP_MISSING, SIMULATOR_BOOT_FAILED, WDA_UNREACHABLE).',
+        inputSchema: {
+            sessionId: z.string(),
+            app: z.string().optional().describe('Simulator .app path (absolute or project-relative).'),
+            bundleId: z.string().optional(),
+            simulator: z.string().optional().describe('Simulator udid or name substring.'),
+            launch: z.boolean().optional(),
+            attachWda: z.enum(['auto', 'required', 'skip']).optional(),
+            consentId: z.string().optional(),
+            approve: z.boolean().optional(),
+        },
+    }, async ({ sessionId, app, bundleId, simulator, launch, attachWda, 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.'] });
+        // Installing app code is privileged → consent (mirrors qa_ios install).
+        let mutationConsent;
+        let installAffects;
+        if (app) {
+            const abs = isAbsolute(app) ? app : join(session.root, app);
+            const sig = appSignature(abs);
+            const affects = { appPath: abs, sig, external: externalToRoot(session, app) };
+            installAffects = affects;
+            const gate = consumeConsent(consentId, approve, { action: 'install_app', affects });
+            if (!gate.approved) {
+                sessions.recordMutation(session, {
+                    tool: 'qa_prepare_ios_target',
+                    action: 'install_app',
+                    risk: affects.external ? 'medium' : 'low',
+                    target: affects,
+                    consent: { required: true, approved: false, payloadHash: sig },
+                    status: 'requested',
+                });
+                return requireConsent({
+                    action: 'install_app', risk: affects.external ? 'medium' : 'low',
+                    exactCommand: `xcrun simctl install <booted> ${abs}`,
+                    affects,
+                    explain: `Boot a simulator and install ${abs}${affects.external ? ' (outside the project root)' : ''}? It runs third-party app code.`,
+                });
+            }
+            mutationConsent = { required: true, consentId, approved: true, payloadHash: sig };
+            sessions.recordMutation(session, {
+                tool: 'qa_prepare_ios_target',
+                action: 'install_app',
+                risk: affects.external ? 'medium' : 'low',
+                target: affects,
+                consent: mutationConsent,
+                status: 'approved',
+            });
+        }
+        const res = await prepareIos(sessions, session, { app, bundleId, simulator, launch, attachWda, mutationConsent }, { onProgress: () => { } });
+        if (!res.ok) {
+            if (installAffects) {
+                sessions.recordMutation(session, {
+                    tool: 'qa_prepare_ios_target',
+                    action: 'install_app',
+                    risk: installAffects.external ? 'medium' : 'low',
+                    target: installAffects,
+                    consent: mutationConsent,
+                    status: 'blocked',
+                    detail: res.error ?? res.failureCode ?? 'prepare failed',
+                });
+            }
+            return qaFail(res.failureCode ?? 'APP_LAUNCH_FAILED', { what: res.error ?? 'iOS prepare failed', extra: { udid: res.udid ?? null, name: res.name ?? null } });
+        }
+        return qaOk({ udid: res.udid, name: res.name, bundleId: res.bundleId ?? null, installed: res.installed, launched: res.launched, mode: res.mode, wda: res.wda ?? null }, res.resultText ?? 'iOS target prepared.');
+    });
+}
+//# sourceMappingURL=prepareIosTarget.js.map

package/dist/tools/prepareIosTarget.js.map

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

package/dist/tools/prepareTarget.js

@@ -0,0 +1,257 @@
+// qa_prepare_target — get the app running on a device.
+//
+// Fast path (device online + app installed + !force): run synchronously, return the result.
+// Long-op path (needs emulator boot or an install): create a JOB, run async, return a
+// `jobId` immediately (poll with qa_job_status) — so client tool-call timeouts don't hit
+// the slow paths (review #2). Interactive consent (boot, external-APK) is resolved
+// synchronously BEFORE the job is kicked off.
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import { sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { qaOk, qaError } from '../lib/result.js';
+import { requireConsent, consumeConsent } from '../consent/consent.js';
+import { listAvds, resolveApk, apkPackageId, } from '../lib/android.js';
+import { DirectDriver } from '../drivers/DirectDriver.js';
+import { detectFramework } from '../context/detect.js';
+import { metroReadiness, reverseSet } from '../lib/metroState.js';
+import { resolveDevice, bindDevice } from '../session/attach.js';
+import { prepareAndroid } from '../services/prepareAndroid.js';
+/** RN/Expo debug builds load JS from Metro; launching before Metro is SERVING → RedBox. */
+function needsMetro(root) {
+    const fw = detectFramework(root);
+    return fw === 'expo' || fw === 'bare-react-native';
+}
+function isAndroidEmulatorSerial(serial) {
+    return /^emulator-\d+/.test(serial);
+}
+export function registerPrepareTarget(server, sessions) {
+    server.registerTool('qa_prepare_target', {
+        title: 'Prepare a target device + app',
+        description: 'Orchestrate device→Metro→install→launch in the correct order, with a SINGLE combined consent for any privileged steps (boot, external-APK). Resolves/boots a device (binds the single online one automatically; asks if >1), sets adb reverse for RN/Expo, gates launch on Metro SERVING, installs the APK if needed, launches, verifies. Long ops return a jobId. Flags: bindOnly (bind/boot + reverse, no install/launch — use to break a setup deadlock); allowLaunchWithoutMetro (risky override); headless.',
+        inputSchema: {
+            sessionId: z.string(),
+            apk: z.string().optional(),
+            appId: z.string().optional(),
+            avd: z.string().optional(),
+            device: z.string().optional().describe('Target serial; required when >1 device is online.'),
+            force: z.boolean().optional(),
+            headless: z.boolean().optional().describe('If Swipium boots an AVD: headless (default true) or visible window (false).'),
+            bindOnly: z.boolean().optional().describe('Bind/boot the device + set adb reverse, but do NOT install or launch. Safe way to break a device/Metro setup deadlock.'),
+            allowLaunchWithoutMetro: z.boolean().optional().describe('Risky: launch a debug RN/Expo build even if Metro is not serving (may RedBox).'),
+            consentId: z.string().optional(),
+            approve: z.boolean().optional(),
+        },
+    }, async ({ sessionId, apk, appId, avd, device, force, headless, bindOnly, allowLaunchWithoutMetro, 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.'] });
+        }
+        const rnDebug = needsMetro(session.root);
+        // ---- appId (+apk if needed for detection) — not needed for bindOnly ----
+        let resolvedAppId = appId;
+        let apkPath = apk;
+        if (!bindOnly && !resolvedAppId) {
+            const r = resolveApk(session.root, apk);
+            if (!r.apk)
+                return qaError({ what: r.error ?? 'No APK to detect appId', changedState: false, retrySafe: true, nextSteps: ['Pass appId= or apk=, or drop a build under apps/android/, or use bindOnly:true to just bind a device.'] });
+            apkPath = r.apk;
+            resolvedAppId = (await apkPackageId(apkPath)) ?? undefined;
+            if (!resolvedAppId)
+                return qaError({ what: 'Could not determine applicationId from the APK', changedState: false, retrySafe: true, nextSteps: ['Pass appId explicitly.'] });
+        }
+        // ---- device resolution (centralized; binds single online, asks on >1) ----
+        const res = await resolveDevice(session, device);
+        if (device && !res.effective) {
+            return qaError({ what: `Device "${device}" is not online`, changedState: false, retrySafe: true, nextSteps: [`Online: ${res.available.join(', ') || '(none)'}`] });
+        }
+        if (res.effective && !isAndroidEmulatorSerial(res.effective)) {
+            return qaError({
+                what: `Android target "${res.effective}" appears to be a real device. Swipium 1.0.0 supports Android Emulator only.`,
+                changedState: false,
+                retrySafe: true,
+                failureCode: 'BACKEND_UNSUPPORTED',
+                nextSteps: ['Start or create an Android Emulator, then retry with its emulator serial.'],
+            });
+        }
+        if (res.needSelection) {
+            return qaError({ what: 'Multiple devices online — choose one', changedState: false, retrySafe: true, nextSteps: [`Re-call with device="<serial>". Online: ${res.available.join(', ')}`] });
+        }
+        const needBoot = !res.effective;
+        // ---- external-APK detection (needs the file hash for the plan consent) ----
+        let externalApk;
+        if (!bindOnly && apkPath && !apkPath.startsWith(session.root + sep)) {
+            externalApk = { path: apkPath, sha256: createHash('sha256').update(readFileSync(apkPath)).digest('hex') };
+        }
+        // ---- COMBINED plan consent (Phase 2.1): all privileged steps approved at once,
+        //      so boot + external-APK don't ping-pong across calls. ----
+        const hl = headless ?? true;
+        const avds = needBoot ? await listAvds() : [];
+        const bootTarget = avd ?? avds[0];
+        if (needBoot && avds.length === 0) {
+            return qaError({ what: 'No device online and no AVD to boot', changedState: false, retrySafe: true, nextSteps: ['Create an AVD (see qa_doctor), or start a device, then retry.'] });
+        }
+        const plan = [
+            needBoot ? `boot_emulator(${bootTarget}${hl ? ',headless' : ',windowed'})` : null,
+            rnDebug ? 'set_metro_reverse' : null,
+            externalApk ? `install_external_apk(${externalApk.sha256.slice(0, 12)}…)` : (!bindOnly ? 'install_if_needed' : null),
+            bindOnly ? 'bind_only' : 'launch_app',
+        ].filter(Boolean);
+        const privileged = needBoot || !!externalApk;
+        const planAffects = { plan, boot: needBoot ? { avd: bootTarget, headless: hl } : null, externalApkSha256: externalApk?.sha256 ?? null };
+        let mutationConsent;
+        let preparePlanMutation;
+        if (privileged) {
+            const gate = consumeConsent(consentId, approve, { action: 'prepare_plan', affects: planAffects });
+            if (!gate.approved) {
+                sessions.recordMutation(session, {
+                    tool: 'qa_prepare_target',
+                    action: 'prepare_plan',
+                    risk: externalApk ? 'medium' : 'low',
+                    target: planAffects,
+                    consent: { required: true, approved: false, payloadHash: externalApk?.sha256 },
+                    status: 'requested',
+                });
+                const lines = [
+                    needBoot ? `• boot emulator "${bootTarget}" (${hl ? 'headless' : 'visible'}): emulator -avd ${bootTarget}${hl ? ' -no-window' : ''}` : '',
+                    externalApk ? `• install EXTERNAL apk (outside project root), sha256 ${externalApk.sha256.slice(0, 16)}…: adb install -r -g ${externalApk.path}` : '',
+                ].filter(Boolean).join('\n');
+                return requireConsent({
+                    action: 'prepare_plan',
+                    risk: externalApk ? 'medium' : 'low',
+                    exactCommand: lines,
+                    affects: planAffects,
+                    explain: `This prepare needs ${privileged ? 'these privileged steps' : 'no consent'} (approved together so they don't re-prompt):\n${lines}\nPlan: ${plan.join(' → ')}`,
+                });
+            }
+            mutationConsent = { required: true, consentId, approved: true, payloadHash: externalApk?.sha256 };
+            preparePlanMutation = { affects: planAffects, risk: externalApk ? 'medium' : 'low', consentId };
+            sessions.recordMutation(session, {
+                tool: 'qa_prepare_target',
+                action: 'prepare_plan',
+                risk: preparePlanMutation.risk,
+                target: planAffects,
+                consent: mutationConsent,
+                status: 'approved',
+            });
+            if (externalApk)
+                sessions.addEnvChange(session, `consented external-APK install (sha256 ${externalApk.sha256.slice(0, 12)}…)`);
+        }
+        // ---- FAST PATHS (synchronous) when no long op (no boot, no install) ----
+        if (!needBoot && res.effective) {
+            const serial = res.effective;
+            const driver = bindDevice(session, serial); // bind now (also fixes device:null across tools)
+            await driver.disableAnimations().catch(() => { });
+            // Set reverse for RN/Expo (cheap, non-destructive) so the bundle path is wired.
+            if (rnDebug && !(await reverseSet(serial))) {
+                try {
+                    await driver.adbReverseMetro();
+                    sessions.addEnvChange(session, 'set adb reverse tcp:8081');
+                }
+                catch { /* best-effort */ }
+            }
+            if (bindOnly) {
+                const rd = await metroReadiness(serial);
+                sessions.persist(session);
+                return qaOk({ device: serial, bound: true, metro: rd }, `Bound ${serial}.${rnDebug ? ` Metro: serving=${rd.serving} reverse=${rd.reverseSet} ready=${rd.ready}.` : ''} (bindOnly — no install/launch)`);
+            }
+            const installed = await driver.isInstalled(resolvedAppId);
+            if (installed && !force) {
+                // Launch gate (Phase 2.1, P1.5): refuse only if Metro is NOT SERVING. A missing
+                // reverse is not fatal — emulators reach the host via 10.0.2.2 — so serving is the
+                // real signal. allowLaunchWithoutMetro overrides.
+                if (rnDebug && !allowLaunchWithoutMetro) {
+                    const rd = await metroReadiness(serial);
+                    if (!rd.serving) {
+                        return qaError({
+                            what: `Debug RN/Expo build; Metro is not SERVING the bundle yet (listening=${rd.listening} reverse=${rd.reverseSet} serving=${rd.serving}). Launching now risks the "Unable to load script" RedBox.`,
+                            changedState: false,
+                            retrySafe: true,
+                            nextSteps: [
+                                'Start Metro/dev server manually, wait for serving=true, then re-run qa_prepare_target.',
+                                'If this is a release build with an embedded bundle, OR you accept the risk, pass allowLaunchWithoutMetro:true.',
+                            ],
+                        });
+                    }
+                }
+                if (rnDebug && allowLaunchWithoutMetro)
+                    sessions.addEnvChange(session, 'OVERRIDE allowLaunchWithoutMetro — launched without confirmed Metro readiness');
+                sessions.milestone(session, 'app_launch_start');
+                await driver.launchApp(resolvedAppId);
+                await new Promise((r) => setTimeout(r, 2500));
+                const foreground = await driver.foregroundOwner();
+                sessions.milestone(session, 'app_launch_end');
+                session.appId = resolvedAppId;
+                sessions.persist(session);
+                const launchedOk = foreground.startsWith(resolvedAppId);
+                sessions.recordMutation(session, {
+                    tool: 'qa_prepare_target',
+                    action: 'launch_app',
+                    risk: 'low',
+                    target: { device: serial, appId: resolvedAppId, foreground },
+                    consent: { required: false, approved: true },
+                    status: 'executed',
+                });
+                if (preparePlanMutation) {
+                    sessions.recordMutation(session, {
+                        tool: 'qa_prepare_target',
+                        action: 'prepare_plan',
+                        risk: preparePlanMutation.risk,
+                        target: preparePlanMutation.affects,
+                        consent: mutationConsent,
+                        status: 'executed',
+                    });
+                }
+                return qaOk({ device: serial, appId: resolvedAppId, installed: 'already-present', foreground, launchedOk, launchedWithoutMetro: !!(rnDebug && allowLaunchWithoutMetro) || undefined }, `${launchedOk ? '✅' : '⚠️'} ${resolvedAppId} on ${serial} (already present); foreground=${foreground}.`);
+            }
+            // install needed → JOB
+            return startJob(sessions, session, driver, { needBoot: false, serial, resolvedAppId: resolvedAppId, apkPath, apk, force, rnDebug, allowLaunchWithoutMetro: !!allowLaunchWithoutMetro, mutationConsent, preparePlanMutation });
+        }
+        // ---- BOOT path → JOB (consent already granted via the plan) ----
+        const driver = new DirectDriver();
+        return startJob(sessions, session, driver, { needBoot: true, bootTarget, resolvedAppId: resolvedAppId, apkPath, apk, force, headless: hl, rnDebug, allowLaunchWithoutMetro: !!allowLaunchWithoutMetro, bindOnly: !!bindOnly, mutationConsent, preparePlanMutation });
+    });
+}
+function startJob(sessions, session, driver, a) {
+    const job = sessions.createJob(session, a.needBoot ? 'boot+install' : 'install');
+    void runHeavy(sessions, session, driver, job, a);
+    return qaOk({ jobId: job.jobId, status: 'running', kind: job.kind }, `Started ${job.kind} as job ${job.jobId}. Poll with qa_job_status { sessionId:"${session.id}", jobId:"${job.jobId}" }.`);
+}
+async function runHeavy(sessions, session, driver, job, a) {
+    const signal = sessions.abortSignal(session, job.jobId);
+    driver.setSignal(signal); // cancel kills in-flight adb children (install/dump/etc.)
+    const upd = (patch) => {
+        sessions.updateJobIfRunning(session, job, patch);
+    };
+    // Delegate to the shared service so qa_test_this execute mode runs the identical path.
+    const res = await prepareAndroid(sessions, session, driver, a, { signal, onProgress: (p) => upd({ progress: p }) });
+    if (res.aborted)
+        return; // cancelJob already set the terminal status; do not overwrite
+    if (!res.ok) {
+        if (a.preparePlanMutation) {
+            sessions.recordMutation(session, {
+                tool: 'qa_prepare_target',
+                action: 'prepare_plan',
+                risk: a.preparePlanMutation.risk,
+                target: a.preparePlanMutation.affects,
+                consent: a.mutationConsent,
+                status: 'blocked',
+                detail: res.error ?? res.failureCode ?? 'prepare failed',
+            });
+        }
+        upd({ status: 'failed', error: res.error ?? 'prepare failed', endedAt: Date.now() });
+        return;
+    }
+    if (a.preparePlanMutation) {
+        sessions.recordMutation(session, {
+            tool: 'qa_prepare_target',
+            action: 'prepare_plan',
+            risk: a.preparePlanMutation.risk,
+            target: a.preparePlanMutation.affects,
+            consent: a.mutationConsent,
+            status: 'executed',
+        });
+    }
+    upd({ status: 'done', progress: 'done', result: res.result, resultText: res.resultText, endedAt: Date.now() });
+}
+//# sourceMappingURL=prepareTarget.js.map

package/dist/tools/prepareTarget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepareTarget.js","sourceRoot":"","sources":["../../src/tools/prepareTarget.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,4FAA4F;AAC5F,sFAAsF;AACtF,yFAAyF;AACzF,mFAAmF;AACnF,8CAA8C;AAE9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAY,YAAY,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EACO,QAAQ,EAA6B,UAAU,EAAE,YAAY,GAE1E,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAc,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAG/D,2FAA2F;AAC3F,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,EAAE,KAAK,MAAM,IAAI,EAAE,KAAK,mBAAmB,CAAC;AACrD,CAAC;AAED,SAAS,uBAAuB,CAAC,MAAc;IAC7C,OAAO,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAAiB,EAAE,QAAsB;IAC7E,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;QACE,KAAK,EAAE,+BAA+B;QACtC,WAAW,EACT,kfAAkf;QACpf,WAAW,EAAE;YACX,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;YACrB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC1B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC5B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC1B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mDAAmD,CAAC;YAC3F,KAAK,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;YAC7B,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,6EAA6E,CAAC;YACxH,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,wHAAwH,CAAC;YACnK,uBAAuB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gFAAgF,CAAC;YAC1I,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAChC,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;SAChC;KACF,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,uBAAuB,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,EAAE;QACvH,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,sBAAsB,SAAS,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,8BAA8B,CAAC,EAAE,CAAC,CAAC;QAClJ,CAAC;QACD,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAEzC,2EAA2E;QAC3E,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,IAAI,OAAO,GAAuB,GAAG,CAAC;QACtC,IAAI,CAAC,QAAQ,IAAI,CAAC,aAAa,EAAE,CAAC;YAChC,MAAM,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACxC,IAAI,CAAC,CAAC,CAAC,GAAG;gBAAE,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,IAAI,wBAAwB,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,uGAAuG,CAAC,EAAE,CAAC,CAAC;YACtO,OAAO,GAAG,CAAC,CAAC,GAAG,CAAC;YAChB,aAAa,GAAG,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,SAAS,CAAC;YAC3D,IAAI,CAAC,aAAa;gBAAE,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,gDAAgD,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC;QAC9K,CAAC;QAED,6EAA6E;QAC7E,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACjD,IAAI,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC;YAC7B,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,MAAM,iBAAiB,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,WAAW,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;QACrK,CAAC;QACD,IAAI,GAAG,CAAC,SAAS,IAAI,CAAC,uBAAuB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7D,OAAO,OAAO,CAAC;gBACb,IAAI,EAAE,mBAAmB,GAAG,CAAC,SAAS,8EAA8E;gBACpH,YAAY,EAAE,KAAK;gBACnB,SAAS,EAAE,IAAI;gBACf,WAAW,EAAE,qBAAqB;gBAClC,SAAS,EAAE,CAAC,2EAA2E,CAAC;aACzF,CAAC,CAAC;QACL,CAAC;QACD,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;YACtB,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,sCAAsC,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,2CAA2C,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7L,CAAC;QACD,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC;QAEhC,8EAA8E;QAC9E,IAAI,WAAyD,CAAC;QAC9D,IAAI,CAAC,QAAQ,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;YACpE,WAAW,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5G,CAAC;QAED,iFAAiF;QACjF,iEAAiE;QACjE,MAAM,EAAE,GAAG,QAAQ,IAAI,IAAI,CAAC;QAC5B,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,MAAM,UAAU,GAAG,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC;QAClC,IAAI,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,qCAAqC,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,+DAA+D,CAAC,EAAE,CAAC,CAAC;QACtL,CAAC;QACD,MAAM,IAAI,GAAG;YACX,QAAQ,CAAC,CAAC,CAAC,iBAAiB,UAAU,GAAG,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,IAAI;YACjF,OAAO,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI;YACpC,WAAW,CAAC,CAAC,CAAC,wBAAwB,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC;YACpH,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY;SACtC,CAAC,MAAM,CAAC,OAAO,CAAa,CAAC;QAC9B,MAAM,UAAU,GAAG,QAAQ,IAAI,CAAC,CAAC,WAAW,CAAC;QAC7C,MAAM,WAAW,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,IAAI,IAAI,EAAE,CAAC;QACxI,IAAI,eAA6C,CAAC;QAClD,IAAI,mBAAqD,CAAC;QAC1D,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;YAClG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACnB,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE;oBAC/B,IAAI,EAAE,mBAAmB;oBACzB,MAAM,EAAE,cAAc;oBACtB,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK;oBACpC,MAAM,EAAE,WAAW;oBACnB,OAAO,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE;oBAC9E,MAAM,EAAE,WAAW;iBACpB,CAAC,CAAC;gBACH,MAAM,KAAK,GAAG;oBACZ,QAAQ,CAAC,CAAC,CAAC,oBAAoB,UAAU,MAAM,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,oBAAoB,UAAU,GAAG,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE;oBACzI,WAAW,CAAC,CAAC,CAAC,yDAAyD,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,wBAAwB,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE;iBACtJ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC7B,OAAO,cAAc,CAAC;oBACpB,MAAM,EAAE,cAAc;oBACtB,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK;oBACpC,YAAY,EAAE,KAAK;oBACnB,OAAO,EAAE,WAAW;oBACpB,OAAO,EAAE,sBAAsB,UAAU,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,YAAY,kDAAkD,KAAK,WAAW,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;iBACxK,CAAC,CAAC;YACL,CAAC;YACD,eAAe,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;YAClG,mBAAmB,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC;YAChG,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE;gBAC/B,IAAI,EAAE,mBAAmB;gBACzB,MAAM,EAAE,cAAc;gBACtB,IAAI,EAAE,mBAAmB,CAAC,IAAI;gBAC9B,MAAM,EAAE,WAAW;gBACnB,OAAO,EAAE,eAAe;gBACxB,MAAM,EAAE,UAAU;aACnB,CAAC,CAAC;YACH,IAAI,WAAW;gBAAE,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE,0CAA0C,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QACjI,CAAC;QAED,2EAA2E;QAC3E,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,SAAS,CAAC;YAC7B,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,iDAAiD;YAC7F,MAAM,MAAM,CAAC,iBAAiB,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACjD,gFAAgF;YAChF,IAAI,OAAO,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;gBAC3C,IAAI,CAAC;oBAAC,MAAM,MAAM,CAAC,eAAe,EAAE,CAAC;oBAAC,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE,0BAA0B,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,iBAAiB,CAAC,CAAC;YACjI,CAAC;YACD,IAAI,QAAQ,EAAE,CAAC;gBACb,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;gBACxC,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC1B,OAAO,IAAI,CACT,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,EAC1C,SAAS,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,mBAAmB,EAAE,CAAC,OAAO,YAAY,EAAE,CAAC,UAAU,UAAU,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,iCAAiC,CAC/I,CAAC;YACJ,CAAC;YACD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,aAAc,CAAC,CAAC;YAC3D,IAAI,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC;gBACxB,gFAAgF;gBAChF,mFAAmF;gBACnF,kDAAkD;gBAClD,IAAI,OAAO,IAAI,CAAC,uBAAuB,EAAE,CAAC;oBACxC,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;oBACxC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC;wBAChB,OAAO,OAAO,CAAC;4BACb,IAAI,EAAE,uEAAuE,EAAE,CAAC,SAAS,YAAY,EAAE,CAAC,UAAU,YAAY,EAAE,CAAC,OAAO,4DAA4D;4BACpM,YAAY,EAAE,KAAK;4BACnB,SAAS,EAAE,IAAI;4BACf,SAAS,EAAE;gCACT,wFAAwF;gCACxF,gHAAgH;6BACjH;yBACF,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;gBACD,IAAI,OAAO,IAAI,uBAAuB;oBAAE,QAAQ,CAAC,YAAY,CAAC,OAAO,EAAE,+EAA+E,CAAC,CAAC;gBACxJ,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;gBAChD,MAAM,MAAM,CAAC,SAAS,CAAC,aAAc,CAAC,CAAC;gBACvC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;gBAC9C,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,eAAe,EAAE,CAAC;gBAClD,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;gBAC9C,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC;gBAC9B,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC1B,MAAM,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC,aAAc,CAAC,CAAC;gBACzD,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE;oBAC/B,IAAI,EAAE,mBAAmB;oBACzB,MAAM,EAAE,YAAY;oBACpB,IAAI,EAAE,KAAK;oBACX,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE;oBAC5D,OAAO,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE;oBAC5C,MAAM,EAAE,UAAU;iBACnB,CAAC,CAAC;gBACH,IAAI,mBAAmB,EAAE,CAAC;oBACxB,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE;wBAC/B,IAAI,EAAE,mBAAmB;wBACzB,MAAM,EAAE,cAAc;wBACtB,IAAI,EAAE,mBAAmB,CAAC,IAAI;wBAC9B,MAAM,EAAE,mBAAmB,CAAC,OAAO;wBACnC,OAAO,EAAE,eAAe;wBACxB,MAAM,EAAE,UAAU;qBACnB,CAAC,CAAC;gBACL,CAAC;gBACD,OAAO,IAAI,CACT,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,iBAAiB,EAAE,UAAU,EAAE,UAAU,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,uBAAuB,CAAC,IAAI,SAAS,EAAE,EACzK,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,aAAa,OAAO,MAAM,kCAAkC,UAAU,GAAG,CACxG,CAAC;YACJ,CAAC;YACD,uBAAuB;YACvB,OAAO,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,aAAc,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC,uBAAuB,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC,CAAC;QACjO,CAAC;QAED,mEAAmE;QACnE,MAAM,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAClC,OAAO,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,EAAE,aAAa,EAAE,aAAc,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC,CAAC,uBAAuB,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC,CAAC;IACxQ,CAAC,CACF,CAAC;AACJ,CAAC;AAkBD,SAAS,QAAQ,CAAC,QAAsB,EAAE,OAAgB,EAAE,MAAoB,EAAE,CAAY;IAC5F,MAAM,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACjF,KAAK,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACjD,OAAO,IAAI,CACT,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EACvD,WAAW,GAAG,CAAC,IAAI,WAAW,GAAG,CAAC,KAAK,0CAA0C,OAAO,CAAC,EAAE,aAAa,GAAG,CAAC,KAAK,MAAM,CACxH,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,QAAsB,EAAE,OAAgB,EAAE,MAAoB,EAAE,GAAc,EAAE,CAAY;IAClH,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IACxD,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,0DAA0D;IACpF,MAAM,GAAG,GAAG,CAAC,KAAyB,EAAQ,EAAE;QAC9C,QAAQ,CAAC,kBAAkB,CAAC,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC,CAAC;IACF,uFAAuF;IACvF,MAAM,GAAG,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACpH,IAAI,GAAG,CAAC,OAAO;QAAE,OAAO,CAAC,8DAA8D;IACvF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,IAAI,CAAC,CAAC,mBAAmB,EAAE,CAAC;YAC1B,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE;gBAC/B,IAAI,EAAE,mBAAmB;gBACzB,MAAM,EAAE,cAAc;gBACtB,IAAI,EAAE,CAAC,CAAC,mBAAmB,CAAC,IAAI;gBAChC,MAAM,EAAE,CAAC,CAAC,mBAAmB,CAAC,OAAO;gBACrC,OAAO,EAAE,CAAC,CAAC,eAAe;gBAC1B,MAAM,EAAE,SAAS;gBACjB,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,WAAW,IAAI,gBAAgB;aACzD,CAAC,CAAC;QACL,CAAC;QACD,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACrF,OAAO;IACT,CAAC;IACD,IAAI,CAAC,CAAC,mBAAmB,EAAE,CAAC;QAC1B,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE;YAC/B,IAAI,EAAE,mBAAmB;YACzB,MAAM,EAAE,cAAc;YACtB,IAAI,EAAE,CAAC,CAAC,mBAAmB,CAAC,IAAI;YAChC,MAAM,EAAE,CAAC,CAAC,mBAAmB,CAAC,OAAO;YACrC,OAAO,EAAE,CAAC,CAAC,eAAe;YAC1B,MAAM,EAAE,UAAU;SACnB,CAAC,CAAC;IACL,CAAC;IACD,GAAG,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;AACjH,CAAC"}

package/dist/tools/report.js

@@ -0,0 +1,42 @@
+// qa_report — thin wrapper around the report service (Phase 3.2 Milestone B). All assembly lives in
+// src/services/report.ts so qa_test_this execute produces the identical report artifact in every
+// terminal state. This tool resolves the session, runs the service, and surfaces its result.
+import { z } from 'zod';
+import { qaOk, qaError } from '../lib/result.js';
+import { generateSessionReport } from '../services/report.js';
+export function registerReport(server, sessions) {
+    server.registerTool('qa_report', {
+        title: 'Build a session report',
+        description: 'Assemble a report for the session: an executive summary (release risk ship/caution/block + the single next action), native/app health, structured outcomes by workflow, findings, artifact links, env mutations + restoration, workarounds + provided inputs. Returns a summary + resource URIs (not the whole bundle); saves the full report as an artifact. Pass `format` to also export: markdown (issue-ready), json, junit (CI), playwright (dashboard JSON), or flow — returns the export artifact URI. qa_test_this execute generates this report automatically at the end of a run.',
+        inputSchema: {
+            sessionId: z.string(),
+            format: z.enum(['summary', 'markdown', 'json', 'junit', 'flow', 'playwright']).optional().describe('Also emit this export as an artifact (default summary only). markdown = issue-ready; junit = CI; playwright = Playwright-style dashboard JSON; flow = a replayable flow drafted from the actions recorded this run.'),
+            baseline: z.string().optional().describe('Optional baseline report.json path. When provided, qa_report adds comparison and PR-summary links.'),
+            trendRoot: z.string().optional().describe('Optional project root containing .swipium/runs or legacy .swipium/ci history. When provided, qa_report adds trend/flake context.'),
+        },
+    }, async ({ sessionId, format, baseline, trendRoot }) => {
+        const session = sessions.get(sessionId);
+        if (!session) {
+            return qaError({ what: `Unknown sessionId ${sessionId}`, changedState: false, retrySafe: true, nextSteps: ['Call qa_start_session first.'] });
+        }
+        // format:"flow" with no recorded actions is a user error (kept from the original tool).
+        if (format === 'flow' && !session.recordedActions.length) {
+            return qaError({ what: 'No actions were recorded this run, so there is no flow to export', changedState: false, retrySafe: true, nextSteps: ['Drive the app with qa_act first, then qa_report { format: "flow" } — or use qa_flow_generate.'] });
+        }
+        const r = await generateSessionReport(sessions, session, {
+            format,
+            baseline,
+            trendRoot,
+        });
+        return qaOk({
+            ...r.report,
+            reportUri: r.reportUri,
+            manifestUri: r.manifestUri,
+            manifest: r.manifest,
+            dumpUri: r.dumpUri,
+            ...(r.reportLinks ? { reportLinks: r.reportLinks } : {}),
+            ...(r.exportUri ? { exportUri: r.exportUri, exportFormat: r.exportFormat } : {}),
+        }, r.summaryText);
+    });
+}
+//# sourceMappingURL=report.js.map

package/dist/tools/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../src/tools/report.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,iGAAiG;AACjG,6FAA6F;AAE7F,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAG9D,MAAM,UAAU,cAAc,CAAC,MAAiB,EAAE,QAAsB;IACtE,MAAM,CAAC,YAAY,CACjB,WAAW,EACX;QACE,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EACT,6jBAA6jB;QAC/jB,WAAW,EAAE;YACX,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;YACrB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qNAAqN,CAAC;YACzT,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,oGAAoG,CAAC;YAC9I,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kIAAkI,CAAC;SAC9K;KACF,EACD,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE;QACnD,MAAM,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACxC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,qBAAqB,SAAS,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,8BAA8B,CAAC,EAAE,CAAC,CAAC;QAChJ,CAAC;QAED,wFAAwF;QACxF,IAAI,MAAM,KAAK,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC;YACzD,OAAO,OAAO,CAAC,EAAE,IAAI,EAAE,kEAAkE,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,+FAA+F,CAAC,EAAE,CAAC,CAAC;QACnP,CAAC;QAED,MAAM,CAAC,GAAG,MAAM,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE;YACvD,MAAM;YACN,QAAQ;YACR,SAAS;SACV,CAAC,CAAC;QACH,OAAO,IAAI,CACT;YACE,GAAG,CAAC,CAAC,MAAM;YACX,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACxD,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACjF,EACD,CAAC,CAAC,WAAW,CACd,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/screenRecord.js

@@ -0,0 +1,24 @@
+// Screen-recording lifecycle helpers retained so shutdown/report paths stay idempotent.
+import { run } from '../lib/spawn.js';
+const active = new Map();
+/** Is a recording active for this session? Used by qa_report. */
+export function activeRecording(sessionId) {
+    const r = active.get(sessionId);
+    return r ? { backend: r.backend, seconds: Math.round((Date.now() - r.startedAt) / 1000) } : undefined;
+}
+/** Best-effort: stop every active recorder so the server does not leave a device recording. */
+export async function stopAllRecordings() {
+    for (const [, rec] of active) {
+        try {
+            if (rec.backend === 'direct') {
+                await run('adb', ['-s', rec.serial, 'shell', 'pkill', '-INT', 'screenrecord'], { timeoutMs: 5000 }).catch(() => { });
+            }
+            rec.child.kill('SIGINT');
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    active.clear();
+}
+//# sourceMappingURL=screenRecord.js.map

package/dist/tools/screenRecord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenRecord.js","sourceRoot":"","sources":["../../src/tools/screenRecord.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAGxF,OAAO,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAC;AAStC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAqB,CAAC;AAE5C,iEAAiE;AACjE,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACxG,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,KAAK,MAAM,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;gBAC7B,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACtH,CAAC;YACD,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,iBAAiB;QACnB,CAAC;IACH,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC"}