swipium 1.4.0 → 2.0.0

package/dist/explore/runner.js

@@ -1,12 +1,13 @@
 // Guided exploration runner (Phase 3.3 Milestones D/E/G). Bounded, safe-by-default screen crawl:
-// observe → signature → rank safe candidates → act → health-check → record edge, until a budget is
+// observe > signature > rank safe candidates > act > health-check > record edge, until a budget is
 // reached. Visual-only screens (poor UI tree) are verified with a screenshot + visual assertion
 // instead of blind coordinate crawling. Honest: unsafe actions are skipped with a note; an auth
-// wall with no credentials returns NeedsInput. Drives only the Driver interface — no MCP-over-MCP.
+// wall with no credentials returns NeedsInput. Drives only the Driver interface, no MCP-over-MCP.
 import { parseSnapshot } from '../snapshot/parse.js';
 import { settle } from '../snapshot/settle.js';
 import { checkHealth } from '../oracle/health.js';
 import { recordHealthFindings } from '../oracle/record.js';
+import { CancelledError, isAbortError } from '../lib/abortScope.js';
 import { ExploreGraph } from './graph.js';
 import { structuredSignature, visualSignature } from './signatures.js';
 import { actionLikeNonInteractive, rankCandidates, locatorQuality } from './candidates.js';
@@ -55,7 +56,7 @@ function valueForField(session, label, locatorValue, role, secure, gen) {
     const resolved = resolveFixtureValue(session, label, locatorValue, { role });
     if (resolved)
         return resolved;
-    // Built-in safe generator — only when generation is explicitly allowed for this environment.
+    // Built-in safe generator, only when generation is explicitly allowed for this environment.
     if (gen?.allowed) {
         const field = fieldKindFromHints(label, locatorValue, undefined, secure);
         const g = generateFieldValue(field, gen.policy);
@@ -64,7 +65,15 @@ function valueForField(session, label, locatorValue, role, secure, gen) {
             session.inputValues.set(varName, g.value);
             if (g.secret)
                 session.secrets.add(g.value);
-            session.generatedValues.push({ at: Date.now(), fixture: 'generated', field, varName, generator: g.generator, value: g.value, secret: g.secret });
+            session.generatedValues.push({
+                at: Date.now(),
+                fixture: 'generated',
+                field,
+                varName,
+                generator: g.generator,
+                value: g.value,
+                secret: g.secret,
+            });
             return { value: g.value, varName, secret: g.secret, fixture: 'generated', field, source: 'generator' };
         }
     }
@@ -75,7 +84,7 @@ function strategyToKind(strategy) {
         case 'accessibility':
             return 'accessibility_id';
         case 'id':
-            return 'resource_id'; // Android resource-id → durable id= selector (not a text match)
+            return 'resource_id'; // Android resource-id > durable id= selector (not a text match)
         case 'text':
             return 'text';
         default:
@@ -122,10 +131,13 @@ export async function runExplore(sessions, session, driver, opts, ctx = {}) {
     const maxScreens = opts.maxScreens ?? 12;
     const depth = opts.depth ?? 3;
     const stopOnAuth = opts.stopOnAuth ?? true;
-    // SWIPIUM-REQ-02: resolve the generated-data decision once. Only "allowed" when policy + the
+    // Resolve the generated-data decision once. Only "allowed" when policy + the
     // classified environment (test/staging) permit safe throwaway data; otherwise generation is off.
     const genCtx = opts.allowGeneratedData
-        ? (() => { const r = resolveFirstRunPolicy(session, { testDataPolicyPath: opts.testDataPolicyPath, allowGeneratedAccount: true }); return { allowed: r.decision.allowed, policy: r.policy }; })()
+        ? (() => {
+            const r = resolveFirstRunPolicy(session, { testDataPolicyPath: opts.testDataPolicyPath, allowGeneratedAccount: true });
+            return { allowed: r.decision.allowed, policy: r.policy };
+        })()
         : undefined;
     const startedAt = Date.now();
     const deadline = startedAt + (opts.maxDurationMs ?? 6 * 60_000);
@@ -144,7 +156,7 @@ export async function runExplore(sessions, session, driver, opts, ctx = {}) {
         promotedSuiteCandidates: 0,
         testabilityBlockers: [],
     };
-    const exploredPerScreen = new Map(); // nodeId → explored signatureKeys
+    const exploredPerScreen = new Map(); // nodeId > explored signatureKeys
     const skippedNotedScreens = new Set();
     const testabilityNotedScreens = new Set();
     const destructiveCandidates = new Map();
@@ -153,7 +165,7 @@ export async function runExplore(sessions, session, driver, opts, ctx = {}) {
     let sameScreenEdges = 0;
     let planned = false;
     const note = (n) => sessions.addNote(session, { at: Date.now(), ...n });
-    /** Observe the current screen → a graph node (structured or visual-only). */
+    /** Observe the current screen as a graph node (structured or visual-only). */
     const observe = async () => {
         const foreground = await driver.foregroundOwner().catch(() => 'unknown');
         let xml = '';
@@ -165,14 +177,24 @@ export async function runExplore(sessions, session, driver, opts, ctx = {}) {
             elements = parsed.elements;
             webviewDominance = parsed.quality.signals.webviewDominance;
         }
-        catch {
-            /* snapshot failed → treated as visual-only below */
+        catch (e) {
+            // Cancelled job: an aborted dump is not a visual-only screen, a finding or a blocker.
+            if (isAbortError(e, signal))
+                throw new CancelledError('exploration cancelled');
+            /* snapshot failed, so treated as visual-only below */
         }
+        if (signal?.aborted)
+            throw new CancelledError('exploration cancelled');
         const health = await checkHealth(driver, session.appId, xml || undefined);
+        if (health.cancelled || signal?.aborted)
+            throw new CancelledError('exploration cancelled');
         await recordHealthFindings(sessions, session, health.findings, driver, health.foreground);
         if (!health.nativeHealthy)
             summary.appErrors += 0; // native handled separately below
-        const healthSnap = { native: (health.nativeHealthy ? 'OK' : 'error'), app: health.appStatus === 'error' ? 'error' : health.appStatus === 'degraded' ? 'degraded' : 'OK' };
+        const healthSnap = {
+            native: (health.nativeHealthy ? 'OK' : 'error'),
+            app: health.appStatus === 'error' ? 'error' : health.appStatus === 'degraded' ? 'degraded' : 'OK',
+        };
         let screenshotUri;
         let png;
         // Respect the SESSION screenshot budget (not a separate fixed counter) so two observes per
@@ -187,7 +209,7 @@ export async function runExplore(sessions, session, driver, opts, ctx = {}) {
                 /* best-effort */
             }
         }
-        // Visual-only (Milestone E): no usable structured elements (canvas/map/webview/empty) → visual
+        // Visual-only (Milestone E): no usable structured elements (canvas/map/webview/empty) means visual
         // node + assertion, no blind coordinate crawl. A low automation-readiness verdict on a screen
         // that DOES expose identified elements is still structured (we can act on it).
         const visual = elements.length === 0 || webviewDominance > 0.5;
@@ -216,7 +238,20 @@ export async function runExplore(sessions, session, driver, opts, ctx = {}) {
             authState: authWall ? 'auth_required' : undefined,
             visualOnlyReason: visual ? 'no reliable UI tree (canvas/map/webview or empty snapshot)' : undefined,
             locatorQuality: visual ? undefined : locatorQuality(elements),
-            elements: candidates.map((c) => ({ ref: c.ref, candidateSignature: c.signatureKey, label: c.label, role: c.role, bounds: c.bounds, locator: c.locator, actionType: c.actionType, risk: c.risk, riskClass: c.riskClass, stepUp: c.stepUp, requiresTwoStepConfirmation: c.requiresTwoStepConfirmation, reason: c.reason })),
+            elements: candidates.map((c) => ({
+                ref: c.ref,
+                candidateSignature: c.signatureKey,
+                label: c.label,
+                role: c.role,
+                bounds: c.bounds,
+                locator: c.locator,
+                actionType: c.actionType,
+                risk: c.risk,
+                riskClass: c.riskClass,
+                stepUp: c.stepUp,
+                requiresTwoStepConfirmation: c.requiresTwoStepConfirmation,
+                reason: c.reason,
+            })),
         });
         if (isNew)
             summary.screensVisited++;
@@ -226,14 +261,22 @@ export async function runExplore(sessions, session, driver, opts, ctx = {}) {
             summary.appErrors++;
         // Visual-only screens get a recorded visual assertion as their oracle (Milestone E).
         if (visual && isNew) {
-            note({ workflow: 'guided_exploration', outcome: 'pass', category: undefined, reason: `visual-only screen "${foreground}" — verified by screenshot`, verifiedVisually: true, method: 'visual', artifactUris: screenshotUri ? [screenshotUri] : undefined });
+            note({
+                workflow: 'guided_exploration',
+                outcome: 'pass',
+                category: undefined,
+                reason: `visual-only screen "${foreground}", verified by screenshot`,
+                verifiedVisually: true,
+                method: 'visual',
+                artifactUris: screenshotUri ? [screenshotUri] : undefined,
+            });
         }
         return { node, isNew, candidates, visual, authWall, actionLikeSkipped };
     };
     const allowedCandidate = (candidate, node) => {
         if (candidate.risk !== 'destructive')
             return allowedUnder(candidate.risk, safeMode);
-        // Controlled account-cycle exception (REQ-07): logout — and only logout — is an expected step
+        // Controlled account-cycle exception: logout (and only logout) is an expected step
         // on a disposable generated account inside the mobile-audit account-cycle workflow.
         if (opts.accountCycle?.enabled &&
             allowsControlledLogout({ label: candidate.label, id: candidate.locator?.value, role: candidate.locator?.strategy }, { accountCycle: true, disposableAccount: opts.accountCycle.disposableAccount })) {
@@ -272,155 +315,264 @@ export async function runExplore(sessions, session, driver, opts, ctx = {}) {
     };
     // ---- main loop ----
     let stoppedReason = 'exploration complete';
-    while (true) {
-        if (signal?.aborted) {
-            stoppedReason = 'cancelled';
-            break;
-        }
-        if (summary.actionsTried >= maxActions) {
-            stoppedReason = `action budget reached (${maxActions})`;
-            break;
-        }
-        if (graph.nodeCount() >= maxScreens) {
-            stoppedReason = `screen budget reached (${maxScreens})`;
-            break;
-        }
-        if (Date.now() >= deadline) {
-            stoppedReason = 'time budget reached';
-            break;
-        }
-        const budgetStop = sessions.budgetStop(session);
-        if (budgetStop) {
-            stoppedReason = `session budget: ${budgetStop}`;
-            break;
-        }
-        const obs = await observe();
-        progress(`exploring: ${summary.screensVisited} screens, ${summary.actionsTried} actions${obs.visual ? ', visual-only' : ''}`);
-        if (!planned && (opts.strategy === 'task_planner' || opts.strategy === 'hybrid')) {
-            planned = true;
-            const screenText = obs.candidates.map((c) => `${c.label ?? ''} ${c.locator?.value ?? ''}`).join(' ');
-            const domain = inferAppDomain({ packageId: session.appId, goal: opts.goal, screenText, fixtures: session.fixtures.map((f) => f.name) });
-            const tasks = proposeTasks({ packageId: session.appId, goal: opts.goal, screenText, fixtures: session.fixtures.map((f) => f.name), candidates: obs.candidates });
-            graph.setTasks(tasks);
-            graph.setHypotheses([`domain:${domain.domain}`, ...tasks.map((t) => `${t.feature}:${t.title}`)]);
-            graph.setBlockedPreconditions([...new Set(tasks.flatMap((t) => t.preconditions))]);
-        }
-        // App error → record + stop this path (do not hide bugs; do not keep crawling a broken screen).
-        if (obs.node.health.app === 'error') {
-            note({ workflow: 'guided_exploration', outcome: 'fail', category: 'app_bug', reason: `app-layer error on "${obs.node.title}"`, artifactUris: obs.node.screenshotUri ? [obs.node.screenshotUri] : undefined });
-            summary.blockers++;
-            if (lastNodeId)
-                graph.addEdge({ from: lastNodeId, to: obs.node.id, action: { type: 'tap', targetDescription: 'prev action' }, outcome: 'app_error', evidenceUris: obs.node.screenshotUri ? [obs.node.screenshotUri] : [] });
-            stoppedReason = 'app-layer error encountered';
-            break;
-        }
-        if (obs.node.health.native === 'error') {
-            summary.blockers++;
-            stoppedReason = 'native error encountered';
-            break;
-        }
-        // Auth wall with no credentials.
-        if (obs.authWall && !hasCredentials(session)) {
-            note({ workflow: 'guided_exploration', outcome: 'blocked', category: 'missing_test_data', reason: 'login required, no credentials available', missingPrecondition: 'test account credentials', recommendedSetup: 'Provide TEST_EMAIL/TEST_PASSWORD (qa_continue_from_blocker) or accept pre-login coverage.' });
-            summary.blockers++;
-            if (stopOnAuth) {
-                const suitePromotion = finalizeGraph(graph, summary, sameScreenEdges, destructiveCandidates, ['auth wall blocked exploration']);
-                return { graph, summary, needsInput: NeedsInput.credentials('Exploration hit a login screen.'), state: 'needs_input', stoppedReason: 'auth required (credentials missing)', suitePromotion, destructiveCandidates: [...destructiveCandidates.values()] };
+    // A cancelled job unwinds via CancelledError (thrown by observe). It's never recorded as a finding,
+    // blocker or visual-only screen; the partial graph is still finalized below.
+    try {
+        while (true) {
+            if (signal?.aborted) {
+                stoppedReason = 'cancelled';
+                break;
             }
-            // stopOnAuth:false → record blocked and stop crawling further (only public screens were reachable).
-            stoppedReason = 'auth required — recorded blocked, no credentials to proceed';
-            break;
-        }
-        const explored = exploredPerScreen.get(obs.node.id) ?? new Set();
-        exploredPerScreen.set(obs.node.id, explored);
-        // Visual-only screens: no safe structured target → step back to keep the graph connected.
-        const pick = obs.candidates.find((c) => !explored.has(c.signatureKey) && allowedCandidate(c, obs.node));
-        const blockedCandidates = obs.candidates.filter((c) => !allowedCandidate(c, obs.node));
-        if (blockedCandidates.length && !skippedNotedScreens.has(obs.node.id)) {
-            skippedNotedScreens.add(obs.node.id);
-            const ex = blockedCandidates[0];
-            note({ workflow: 'guided_exploration', outcome: 'skipped', category: ex.risk === 'destructive' ? 'destructive_refused' : 'other', reason: `Skipped ${ex.risk} action "${ex.label ?? ex.locator?.value}": ${ex.reason}`, recommendedSetup: ex.risk === 'destructive' ? 'Run dry_run_destructive to list candidate-bound approvals, then approve one exact candidate with disposable test state.' : 'Add accessibilityLabel/testID so the action can be judged + automated.' });
-            summary.unsafeActionsSkipped += blockedCandidates.length;
-        }
-        if (!pick) {
-            if (obs.actionLikeSkipped.length && !testabilityNotedScreens.has(obs.node.id)) {
-                testabilityNotedScreens.add(obs.node.id);
-                for (const s of obs.actionLikeSkipped.slice(0, 8)) {
-                    summary.testabilityBlockers.push({
-                        screen: obs.node.title ?? 'unknown',
-                        visibleText: s.visibleText,
-                        role: s.role,
-                        bounds: s.bounds,
-                        clickable: s.clickable,
-                        recommendation: `"${s.visibleText}" looks tappable but the UI tree marks it non-interactive. Add accessibilityRole="button" and a stable testID or accessibility identifier.`,
-                        manualCandidate: { x: Math.round(s.bounds.x + s.bounds.w / 2), y: Math.round(s.bounds.y + s.bounds.h / 2) },
+            if (summary.actionsTried >= maxActions) {
+                stoppedReason = `action budget reached (${maxActions})`;
+                break;
+            }
+            if (graph.nodeCount() >= maxScreens) {
+                stoppedReason = `screen budget reached (${maxScreens})`;
+                break;
+            }
+            if (Date.now() >= deadline) {
+                stoppedReason = 'time budget reached';
+                break;
+            }
+            const budgetStop = sessions.budgetStop(session);
+            if (budgetStop) {
+                stoppedReason = `session budget: ${budgetStop}`;
+                break;
+            }
+            const obs = await observe();
+            progress(`exploring: ${summary.screensVisited} screens, ${summary.actionsTried} actions${obs.visual ? ', visual-only' : ''}`);
+            if (!planned && (opts.strategy === 'task_planner' || opts.strategy === 'hybrid')) {
+                planned = true;
+                const screenText = obs.candidates.map((c) => `${c.label ?? ''} ${c.locator?.value ?? ''}`).join(' ');
+                const domain = inferAppDomain({
+                    packageId: session.appId,
+                    goal: opts.goal,
+                    screenText,
+                    fixtures: session.fixtures.map((f) => f.name),
+                });
+                const tasks = proposeTasks({
+                    packageId: session.appId,
+                    goal: opts.goal,
+                    screenText,
+                    fixtures: session.fixtures.map((f) => f.name),
+                    candidates: obs.candidates,
+                });
+                graph.setTasks(tasks);
+                graph.setHypotheses([`domain:${domain.domain}`, ...tasks.map((t) => `${t.feature}:${t.title}`)]);
+                graph.setBlockedPreconditions([...new Set(tasks.flatMap((t) => t.preconditions))]);
+            }
+            // App error: record + stop this path (do not hide bugs; do not keep crawling a broken screen).
+            if (obs.node.health.app === 'error') {
+                note({
+                    workflow: 'guided_exploration',
+                    outcome: 'fail',
+                    category: 'app_bug',
+                    reason: `app-layer error on "${obs.node.title}"`,
+                    artifactUris: obs.node.screenshotUri ? [obs.node.screenshotUri] : undefined,
+                });
+                summary.blockers++;
+                if (lastNodeId)
+                    graph.addEdge({
+                        from: lastNodeId,
+                        to: obs.node.id,
+                        action: { type: 'tap', targetDescription: 'prev action' },
+                        outcome: 'app_error',
+                        evidenceUris: obs.node.screenshotUri ? [obs.node.screenshotUri] : [],
                     });
-                }
+                stoppedReason = 'app-layer error encountered';
+                break;
+            }
+            if (obs.node.health.native === 'error') {
+                summary.blockers++;
+                stoppedReason = 'native error encountered';
+                break;
+            }
+            // Auth wall with no credentials.
+            if (obs.authWall && !hasCredentials(session)) {
                 note({
                     workflow: 'guided_exploration',
                     outcome: 'blocked',
-                    category: 'mcp_limitation',
-                    reason: `No safe actionable elements on "${obs.node.title}". ${obs.actionLikeSkipped.length} visible action-like text element(s) are not clickable in the UI tree.`,
-                    missingPrecondition: 'tappable controls with accessibilityRole and testID',
-                    recommendedSetup: `Add accessibilityRole="button" and a stable testID to primary buttons such as "${obs.actionLikeSkipped[0].visibleText}".`,
+                    category: 'missing_test_data',
+                    reason: 'login required, no credentials available',
+                    missingPrecondition: 'test account credentials',
+                    recommendedSetup: 'Provide SWIPIUM_TEST_EMAIL/SWIPIUM_TEST_PASSWORD (qa_continue_from_blocker) or accept pre-login coverage.',
                 });
+                summary.blockers++;
+                if (stopOnAuth) {
+                    const suitePromotion = finalizeGraph(graph, summary, sameScreenEdges, destructiveCandidates, ['auth wall blocked exploration']);
+                    return {
+                        graph,
+                        summary,
+                        needsInput: NeedsInput.credentials('Exploration hit a login screen.'),
+                        state: 'needs_input',
+                        stoppedReason: 'auth required (credentials missing)',
+                        suitePromotion,
+                        destructiveCandidates: [...destructiveCandidates.values()],
+                    };
+                }
+                // stopOnAuth:false: record blocked and stop crawling further (only public screens were reachable).
+                stoppedReason = 'auth required: recorded blocked, no credentials to proceed';
+                break;
             }
-            // Nothing safe+new here. Go back to keep exploring; if we're at the root with nothing, stop.
-            if (lastNodeId && obs.node.id !== graph.rootId && depth > 1) {
-                await driver.pressKey('back').catch(() => { });
-                graph.addEdge({ from: obs.node.id, action: { type: 'back', targetDescription: 'back' }, outcome: 'changed_screen', evidenceUris: [] });
-                await settle(driver, { timeoutMs: 4000 }).catch(() => { });
-                lastNodeId = obs.node.id;
-                continue;
+            const explored = exploredPerScreen.get(obs.node.id) ?? new Set();
+            exploredPerScreen.set(obs.node.id, explored);
+            // Visual-only screens: no safe structured target, so step back to keep the graph connected.
+            const pick = obs.candidates.find((c) => !explored.has(c.signatureKey) && allowedCandidate(c, obs.node));
+            const blockedCandidates = obs.candidates.filter((c) => !allowedCandidate(c, obs.node));
+            if (blockedCandidates.length && !skippedNotedScreens.has(obs.node.id)) {
+                skippedNotedScreens.add(obs.node.id);
+                const ex = blockedCandidates[0];
+                note({
+                    workflow: 'guided_exploration',
+                    outcome: 'skipped',
+                    category: ex.risk === 'destructive' ? 'destructive_refused' : 'other',
+                    reason: `Skipped ${ex.risk} action "${ex.label ?? ex.locator?.value}": ${ex.reason}`,
+                    recommendedSetup: ex.risk === 'destructive'
+                        ? 'Run dry_run_destructive to list candidate-bound approvals, then approve one exact candidate with disposable test state.'
+                        : 'Add accessibilityLabel/testID so the action can be judged + automated.',
+                });
+                summary.unsafeActionsSkipped += blockedCandidates.length;
             }
-            stoppedReason = 'no further safe, unexplored actions';
-            break;
-        }
-        // ---- act on the chosen candidate ----
-        explored.add(pick.signatureKey);
-        const cx = (pick.bounds?.x ?? 0) + (pick.bounds?.w ?? 0) / 2;
-        const cy = (pick.bounds?.y ?? 0) + (pick.bounds?.h ?? 0) / 2;
-        const fromId = obs.node.id;
-        // Text entry only with a value source (P1 fix): never type blindly. If none, skip honestly.
-        if (pick.actionType === 'type') {
-            const v = valueForField(session, pick.label, pick.locator?.value, pick.role, pick.secure, genCtx);
-            if (!v) {
-                note({ workflow: 'guided_exploration', outcome: 'skipped', category: 'missing_test_data', reason: `text field "${pick.label ?? pick.locator?.value}" needs a value to exercise`, missingPrecondition: 'a fixture value or credential for this field', recommendedSetup: 'Provide credentials (qa_continue_from_blocker) or a fixture { name, value }.' });
-                summary.blockers++;
+            if (!pick) {
+                if (obs.actionLikeSkipped.length && !testabilityNotedScreens.has(obs.node.id)) {
+                    testabilityNotedScreens.add(obs.node.id);
+                    for (const s of obs.actionLikeSkipped.slice(0, 8)) {
+                        summary.testabilityBlockers.push({
+                            screen: obs.node.title ?? 'unknown',
+                            visibleText: s.visibleText,
+                            role: s.role,
+                            bounds: s.bounds,
+                            clickable: s.clickable,
+                            recommendation: `"${s.visibleText}" looks tappable but the UI tree marks it non-interactive. Add accessibilityRole="button" and a stable testID or accessibility identifier.`,
+                            manualCandidate: { x: Math.round(s.bounds.x + s.bounds.w / 2), y: Math.round(s.bounds.y + s.bounds.h / 2) },
+                        });
+                    }
+                    note({
+                        workflow: 'guided_exploration',
+                        outcome: 'blocked',
+                        category: 'mcp_limitation',
+                        reason: `No safe actionable elements on "${obs.node.title}". ${obs.actionLikeSkipped.length} visible action-like text element(s) are not clickable in the UI tree.`,
+                        missingPrecondition: 'tappable controls with accessibilityRole and testID',
+                        recommendedSetup: `Add accessibilityRole="button" and a stable testID to primary buttons such as "${obs.actionLikeSkipped[0].visibleText}".`,
+                    });
+                }
+                // Nothing safe+new here. Go back to keep exploring; if we're at the root with nothing, stop.
+                if (lastNodeId && obs.node.id !== graph.rootId && depth > 1) {
+                    await driver.pressKey('back').catch(() => { });
+                    graph.addEdge({
+                        from: obs.node.id,
+                        action: { type: 'back', targetDescription: 'back' },
+                        outcome: 'changed_screen',
+                        evidenceUris: [],
+                    });
+                    await settle(driver, { timeoutMs: 4000 }).catch(() => { });
+                    lastNodeId = obs.node.id;
+                    continue;
+                }
+                stoppedReason = 'no further safe, unexplored actions';
+                break;
+            }
+            // ---- act on the chosen candidate ----
+            explored.add(pick.signatureKey);
+            const cx = (pick.bounds?.x ?? 0) + (pick.bounds?.w ?? 0) / 2;
+            const cy = (pick.bounds?.y ?? 0) + (pick.bounds?.h ?? 0) / 2;
+            const fromId = obs.node.id;
+            // Text entry only with a value source (P1 fix): never type blindly. If none, skip honestly.
+            if (pick.actionType === 'type') {
+                const v = valueForField(session, pick.label, pick.locator?.value, pick.role, pick.secure, genCtx);
+                if (!v) {
+                    note({
+                        workflow: 'guided_exploration',
+                        outcome: 'skipped',
+                        category: 'missing_test_data',
+                        reason: `text field "${pick.label ?? pick.locator?.value}" needs a value to exercise`,
+                        missingPrecondition: 'a fixture value or credential for this field',
+                        recommendedSetup: 'Provide credentials (qa_continue_from_blocker) or a fixture { name, value }.',
+                    });
+                    summary.blockers++;
+                    continue;
+                }
+                try {
+                    await driver.tapXY(Math.round(cx), Math.round(cy)); // focus the field
+                    await driver.inputText(v.value);
+                }
+                catch {
+                    graph.addEdge({
+                        from: fromId,
+                        action: { type: 'type', targetDescription: pick.label ?? 'field' },
+                        outcome: 'blocked',
+                        evidenceUris: [],
+                    });
+                    continue;
+                }
+                summary.actionsTried++;
+                sessions.bump(session, 'actions');
+                if (v.secret)
+                    session.secrets.add(v.value);
+                if (v.source === 'generator') {
+                    const rec = session.generatedValues.find((g) => g.varName === v.varName && g.fixture === v.fixture && g.field === v.field);
+                    if (rec && !rec.artifactUri) {
+                        rec.artifactUri = sessions.saveArtifact(session, 'generated_data', `generated-${v.varName.toLowerCase()}-${Date.now()}.json`, JSON.stringify({
+                            schema: 'swipium.generated_value.v1',
+                            fixture: rec.fixture,
+                            field: rec.field,
+                            varName: rec.varName,
+                            generator: rec.generator,
+                            value: rec.secret ? '<redacted>' : rec.value,
+                            secret: rec.secret,
+                        }, null, 2), 'application/json', `generated fixture value ${rec.fixture}.${rec.field}`);
+                        sessions.persist(session);
+                    }
+                }
+                if (pick.locator && pick.locator.strategy !== 'coordinate') {
+                    sessions.addRecordedAction(session, {
+                        at: Date.now(),
+                        action: 'type',
+                        selector: pick.locator.value,
+                        selectorKind: strategyToKind(pick.locator.strategy),
+                        text: `\${${v.varName}}`,
+                        secret: v.secret,
+                        exportability: v.secret ? 'needs-human-data' : 'semantic',
+                        screen: obs.node.title,
+                        provenance: provenanceForCandidate(obs.node, pick),
+                    });
+                }
+                await settle(driver, { timeoutMs: 5000 }).catch(() => { });
+                const afterType = await observe();
+                graph.addEdge({
+                    from: fromId,
+                    to: afterType.node.id,
+                    action: { type: 'type', targetDescription: pick.label ?? 'field' },
+                    outcome: afterType.node.id === fromId ? 'same_screen' : 'changed_screen',
+                    evidenceUris: [],
+                });
+                lastNodeId = afterType.node.id;
                 continue;
             }
             try {
-                await driver.tapXY(Math.round(cx), Math.round(cy)); // focus the field
-                await driver.inputText(v.value);
+                await driver.tapXY(Math.round(cx), Math.round(cy));
             }
             catch {
-                graph.addEdge({ from: fromId, action: { type: 'type', targetDescription: pick.label ?? 'field' }, outcome: 'blocked', evidenceUris: [] });
-                continue;
-            }
-            summary.actionsTried++;
-            sessions.bump(session, 'actions');
-            if (v.secret)
-                session.secrets.add(v.value);
-            if (v.source === 'generator') {
-                const rec = session.generatedValues.find((g) => g.varName === v.varName && g.fixture === v.fixture && g.field === v.field);
-                if (rec && !rec.artifactUri) {
-                    rec.artifactUri = sessions.saveArtifact(session, 'generated_data', `generated-${v.varName.toLowerCase()}-${Date.now()}.json`, JSON.stringify({ schema: 'swipium.generated_value.v1', fixture: rec.fixture, field: rec.field, varName: rec.varName, generator: rec.generator, value: rec.secret ? '<redacted>' : rec.value, secret: rec.secret }, null, 2), 'application/json', `generated fixture value ${rec.fixture}.${rec.field}`);
-                    sessions.persist(session);
+                if (pick.risk === 'destructive') {
+                    sessions.recordMutation(session, {
+                        tool: 'qa_explore',
+                        action: 'destructive_ui_candidate',
+                        risk: 'high',
+                        target: destructiveMutationTarget(session, obs.node, pick, opts.destructiveApproval),
+                        consent: { required: true, consentId: opts.destructiveApproval?.consentId, approved: true },
+                        status: 'blocked',
+                        detail: 'Approved destructive exploration candidate could not be tapped.',
+                    });
                 }
+                graph.addEdge({
+                    from: fromId,
+                    action: { type: 'tap', targetDescription: pick.label ?? pick.locator?.value ?? 'control' },
+                    outcome: 'blocked',
+                    evidenceUris: [],
+                });
+                continue;
             }
-            if (pick.locator && pick.locator.strategy !== 'coordinate') {
-                sessions.addRecordedAction(session, { at: Date.now(), action: 'type', selector: pick.locator.value, selectorKind: strategyToKind(pick.locator.strategy), text: `\${${v.varName}}`, secret: v.secret, exportability: v.secret ? 'needs-human-data' : 'semantic', screen: obs.node.title, provenance: provenanceForCandidate(obs.node, pick) });
-            }
-            await settle(driver, { timeoutMs: 5000 }).catch(() => { });
-            const afterType = await observe();
-            graph.addEdge({ from: fromId, to: afterType.node.id, action: { type: 'type', targetDescription: pick.label ?? 'field' }, outcome: afterType.node.id === fromId ? 'same_screen' : 'changed_screen', evidenceUris: [] });
-            lastNodeId = afterType.node.id;
-            continue;
-        }
-        try {
-            await driver.tapXY(Math.round(cx), Math.round(cy));
-        }
-        catch {
             if (pick.risk === 'destructive') {
                 sessions.recordMutation(session, {
                     tool: 'qa_explore',
@@ -428,52 +580,73 @@ export async function runExplore(sessions, session, driver, opts, ctx = {}) {
                     risk: 'high',
                     target: destructiveMutationTarget(session, obs.node, pick, opts.destructiveApproval),
                     consent: { required: true, consentId: opts.destructiveApproval?.consentId, approved: true },
-                    status: 'blocked',
-                    detail: 'Approved destructive exploration candidate could not be tapped.',
+                    status: 'executed',
+                    detail: 'Approved destructive exploration candidate tapped.',
                 });
             }
-            graph.addEdge({ from: fromId, action: { type: 'tap', targetDescription: pick.label ?? pick.locator?.value ?? 'control' }, outcome: 'blocked', evidenceUris: [] });
-            continue;
-        }
-        if (pick.risk === 'destructive') {
-            sessions.recordMutation(session, {
-                tool: 'qa_explore',
-                action: 'destructive_ui_candidate',
-                risk: 'high',
-                target: destructiveMutationTarget(session, obs.node, pick, opts.destructiveApproval),
-                consent: { required: true, consentId: opts.destructiveApproval?.consentId, approved: true },
-                status: 'executed',
-                detail: 'Approved destructive exploration candidate tapped.',
+            summary.actionsTried++;
+            sessions.bump(session, 'actions');
+            // Record durable taps so qa_generate target:"suite" can promote the path (§9.3).
+            if (pick.locator && pick.locator.strategy !== 'coordinate') {
+                sessions.addRecordedAction(session, {
+                    at: Date.now(),
+                    action: 'tap',
+                    selector: pick.locator.value,
+                    selectorKind: strategyToKind(pick.locator.strategy),
+                    exportability: 'semantic',
+                    screen: obs.node.title,
+                    provenance: provenanceForCandidate(obs.node, pick),
+                });
+            }
+            await settle(driver, { timeoutMs: 5000 }).catch(() => { });
+            // ---- observe outcome to classify the transition ----
+            const after = await observe();
+            const outcome = after.node.id === fromId ? 'same_screen' : 'changed_screen';
+            if (outcome === 'changed_screen') {
+                summary.workflowsFound++;
+                consecutiveNoChange = 0;
+            }
+            else {
+                consecutiveNoChange++;
+            }
+            if (outcome === 'same_screen')
+                sameScreenEdges++;
+            graph.addEdge({
+                from: fromId,
+                to: after.node.id,
+                action: {
+                    type: 'tap',
+                    targetDescription: pick.label ?? pick.locator?.value ?? 'control',
+                    locator: pick.locator,
+                },
+                outcome,
+                evidenceUris: after.node.screenshotUri ? [after.node.screenshotUri] : [],
+                riskDecision: pick.riskClass ?? pick.risk,
+                preActionState: obs.node.signature,
+                postActionState: after.node.signature,
+                oracle: outcome === 'changed_screen' ? 'screen_signature_changed' : 'screen_signature_same',
             });
+            lastNodeId = after.node.id;
+            if (consecutiveNoChange >= 3) {
+                stoppedReason = 'repeated no-change actions';
+                break;
+            }
         }
-        summary.actionsTried++;
-        sessions.bump(session, 'actions');
-        // Record durable taps so qa_suite_generate can promote the path (§9.3).
-        if (pick.locator && pick.locator.strategy !== 'coordinate') {
-            sessions.addRecordedAction(session, { at: Date.now(), action: 'tap', selector: pick.locator.value, selectorKind: strategyToKind(pick.locator.strategy), exportability: 'semantic', screen: obs.node.title, provenance: provenanceForCandidate(obs.node, pick) });
-        }
-        await settle(driver, { timeoutMs: 5000 }).catch(() => { });
-        // ---- observe outcome to classify the transition ----
-        const after = await observe();
-        const outcome = after.node.id === fromId ? 'same_screen' : 'changed_screen';
-        if (outcome === 'changed_screen') {
-            summary.workflowsFound++;
-            consecutiveNoChange = 0;
-        }
-        else {
-            consecutiveNoChange++;
-        }
-        if (outcome === 'same_screen')
-            sameScreenEdges++;
-        graph.addEdge({ from: fromId, to: after.node.id, action: { type: 'tap', targetDescription: pick.label ?? pick.locator?.value ?? 'control', locator: pick.locator }, outcome, evidenceUris: after.node.screenshotUri ? [after.node.screenshotUri] : [], riskDecision: pick.riskClass ?? pick.risk, preActionState: obs.node.signature, postActionState: after.node.signature, oracle: outcome === 'changed_screen' ? 'screen_signature_changed' : 'screen_signature_same' });
-        lastNodeId = after.node.id;
-        if (consecutiveNoChange >= 3) {
-            stoppedReason = 'repeated no-change actions';
-            break;
-        }
+    }
+    catch (e) {
+        if (!(e instanceof CancelledError) && !(signal?.aborted && isAbortError(e, signal)))
+            throw e;
+        stoppedReason = 'cancelled';
     }
     const suitePromotion = finalizeGraph(graph, summary, sameScreenEdges, destructiveCandidates, []);
-    return { graph, summary, state: summary.appErrors > 0 || summary.blockers > 0 ? 'blocked' : 'completed', stoppedReason, suitePromotion, destructiveCandidates: [...destructiveCandidates.values()] };
+    return {
+        graph,
+        summary,
+        state: summary.appErrors > 0 || summary.blockers > 0 ? 'blocked' : 'completed',
+        stoppedReason,
+        suitePromotion,
+        destructiveCandidates: [...destructiveCandidates.values()],
+    };
 }
 function finalizeGraph(graph, summary, sameScreenEdges, destructiveCandidates, reasons) {
     const nodes = graph.allNodes();