swipium 1.4.0 → 2.0.0

package/dist/flows/run.js

@@ -1,78 +1,83 @@
-// Flow runner v2 (NEXT-PLAN: Flow System V2). Drives a parsed Flow step-by-step using core
+// Flow runner v2 (Flow System V2). Drives a parsed Flow step-by-step using core
 // primitives + the driver directly, WITHOUT re-entering through the model. Fail-fast, never
-// auto-retries (DESIGN §6). v2 adds: setup/teardown phases (teardown always runs), selector-bound
+// auto-retries. v2 adds: setup/teardown phases (teardown always runs), selector-bound
 // inputText, visual steps (image match / diff / visual evidence), device-relative gestures,
 // overlay/network/lifecycle/seed/note steps, and typed per-step failure codes. On failure it
 // captures a screenshot + health so the result stands alone.
 import { readFileSync, existsSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { join } from 'node:path';
 import { createHash } from 'node:crypto';
 import { parseSnapshot, signature } from '../snapshot/parse.js';
 import { settle } from '../snapshot/settle.js';
 import { checkHealth } from '../oracle/health.js';
 import { recordHealthFindings } from '../oracle/record.js';
+import { isAbortError } from '../lib/abortScope.js';
 import { boundsBucket, resolveTarget, resourceIdMatches } from '../core/target.js';
 import { imageDiff, findTemplate } from '../lib/image.js';
 import { captureCoordinateSpace, toDevicePoint } from '../lib/coordSpace.js';
 import { executeSeed } from './seedExec.js';
-import { resolveVars } from './schema.js';
+import { withinRootOrNull } from './paths.js';
+import { lookupFlowVar, missingVarMessage, resolveVars, SECRET_VAR_NAME, } from './schema.js';
+// Shared with qa_act: flow replay keeps the default inset 0 so recorded flows
+// reproduce their historical vectors byte-for-byte.
+import { swipeVector } from '../lib/gestures.js';
 import { configuredOcrCommand, findOcrRegion, runOcr } from '../visual/ocr.js';
 import { makeRedactor } from '../lib/redact.js';
-const FALLBACK_SWIPE = {
-    up: [540, 1500, 540, 600],
-    down: [540, 600, 540, 1500],
-    left: [800, 1100, 200, 1100],
-    right: [200, 1100, 800, 1100],
-};
-const AREA_ANCHOR = { center: [0.5, 0.5], top: [0.5, 0.3], bottom: [0.5, 0.7], left: [0.3, 0.5], right: [0.7, 0.5] };
-const SECRET_VAR_NAME = /pass|secret|token|otp|pin|cvv|key/i;
-/** Device-relative swipe vector (fractions of the screen), falling back to fixed coords if no size. */
-function swipeVector(size, dir, area = 'center', distance = 0.6) {
-    if (!size)
-        return FALLBACK_SWIPE[dir];
-    const [ax, ay] = AREA_ANCHOR[area];
-    const cx = size.width * ax;
-    const cy = size.height * ay;
-    const vd = (size.height * distance) / 2;
-    const hd = (size.width * distance) / 2;
-    const clampX = (x) => Math.max(1, Math.min(size.width - 1, Math.round(x)));
-    const clampY = (y) => Math.max(1, Math.min(size.height - 1, Math.round(y)));
-    const v = {
-        up: [cx, cy + vd, cx, cy - vd],
-        down: [cx, cy - vd, cx, cy + vd],
-        left: [cx + hd, cy, cx - hd, cy],
-        right: [cx - hd, cy, cx + hd, cy],
-    }[dir];
-    return [clampX(v[0]), clampY(v[1]), clampX(v[2]), clampY(v[3])];
-}
+import { classifyForeground, detectTreeOverlays } from '../snapshot/overlays.js';
 function describe(step) {
     switch (step.kind) {
-        case 'tap': return `tap ${step.selector}`;
-        case 'tapAt': return `tapAt ${step.x},${step.y}`;
-        case 'tapImage': return `tapImage ${step.template}`;
-        case 'tapOcrText': return `tapOcrText ${JSON.stringify(step.query)}`;
-        case 'inputText': return `inputText${step.into ? ` into "${step.into}"` : ''} ${step.secret ? '«secret»' : JSON.stringify(step.value)}`;
-        case 'assertVisible': return `assertVisible ${JSON.stringify(step.query)}`;
-        case 'assertNotVisible': return `assertNotVisible ${JSON.stringify(step.query)}`;
-        case 'assertImage': return `assertImage ${step.template}`;
-        case 'assertOcrText': return `assertOcrText ${JSON.stringify(step.query)}`;
-        case 'assertVisual': return `assertVisual ${JSON.stringify(step.description)}`;
-        case 'assertDiff': return `assertDiff ${step.baseline}`;
-        case 'swipe': return `swipe ${step.direction}${step.area ? `@${step.area}` : ''}`;
-        case 'scrollTo': return `scrollTo ${JSON.stringify(step.query)}`;
-        case 'press': return `press ${step.key}`;
-        case 'openUrl': return `openUrl ${step.url}`;
-        case 'wait': return step.ms != null ? `wait ${step.ms}ms` : `wait for ${JSON.stringify(step.query)}`;
-        case 'waitForIdle': return 'waitForIdle';
-        case 'waitForVisible': return `waitForVisible ${JSON.stringify(step.query)}`;
-        case 'clearOverlay': return 'clearOverlay';
-        case 'networkOffline': return 'networkOffline';
-        case 'networkOnline': return 'networkOnline';
-        case 'restartApp': return 'restartApp';
-        case 'seed': return `seed ${step.fixture}`;
-        case 'note': return `note(${step.outcome}) ${JSON.stringify(step.reason)}`;
-        case 'screenshot': return 'screenshot';
-        case 'prepareTarget': return 'prepareTarget';
+        case 'tap':
+            return `tap ${step.selector}`;
+        case 'tapAt':
+            return `tapAt ${step.x},${step.y}`;
+        case 'tapImage':
+            return `tapImage ${step.template}`;
+        case 'tapOcrText':
+            return `tapOcrText ${JSON.stringify(step.query)}`;
+        case 'inputText':
+            return `inputText${step.into ? ` into "${step.into}"` : ''} ${step.secret ? '«secret»' : JSON.stringify(step.value)}`;
+        case 'assertVisible':
+            return `assertVisible ${JSON.stringify(step.query)}`;
+        case 'assertNotVisible':
+            return `assertNotVisible ${JSON.stringify(step.query)}`;
+        case 'assertImage':
+            return `assertImage ${step.template}`;
+        case 'assertOcrText':
+            return `assertOcrText ${JSON.stringify(step.query)}`;
+        case 'assertVisual':
+            return `assertVisual ${JSON.stringify(step.description)}`;
+        case 'assertDiff':
+            return `assertDiff ${step.baseline}`;
+        case 'swipe':
+            return `swipe ${step.direction}${step.area ? `@${step.area}` : ''}`;
+        case 'scrollTo':
+            return `scrollTo ${JSON.stringify(step.query)}`;
+        case 'press':
+            return `press ${step.key}`;
+        case 'openUrl':
+            return `openUrl ${step.url}`;
+        case 'wait':
+            return step.ms != null ? `wait ${step.ms}ms` : `wait for ${JSON.stringify(step.query)}`;
+        case 'waitForIdle':
+            return 'waitForIdle';
+        case 'waitForVisible':
+            return `waitForVisible ${JSON.stringify(step.query)}`;
+        case 'clearOverlay':
+            return 'clearOverlay';
+        case 'networkOffline':
+            return 'networkOffline';
+        case 'networkOnline':
+            return 'networkOnline';
+        case 'restartApp':
+            return 'restartApp';
+        case 'seed':
+            return `seed ${step.fixture}`;
+        case 'note':
+            return `note(${step.outcome}) ${JSON.stringify(step.reason)}`;
+        case 'screenshot':
+            return 'screenshot';
+        case 'prepareTarget':
+            return 'prepareTarget';
     }
 }
 async function snapshot(session, d) {
@@ -95,14 +100,16 @@ function resourceIdSelector(selector) {
 }
 function provenanceForStep(flow, stepIndex, kind) {
     const oneBased = stepIndex + 1;
-    return (flow.provenance ?? []).find((entry) => (entry.generatedStepIndex === oneBased &&
-        (!entry.generatedKind || entry.generatedKind === kind || (kind === 'wait' && entry.generatedKind === 'waitForVisible'))));
+    return (flow.provenance ?? []).find((entry) => entry.generatedStepIndex === oneBased &&
+        (!entry.generatedKind || entry.generatedKind === kind || (kind === 'wait' && entry.generatedKind === 'waitForVisible')));
 }
 function targetHintsFromProvenance(provenance) {
     if (!provenance)
         return {};
     return {
-        packageName: provenance.resourceId?.includes(':id/') ? provenance.resourceId.slice(0, provenance.resourceId.indexOf(':id/')) : undefined,
+        packageName: provenance.resourceId?.includes(':id/')
+            ? provenance.resourceId.slice(0, provenance.resourceId.indexOf(':id/'))
+            : undefined,
         className: provenance.className ?? provenance.elementRole,
         textHint: provenance.text ?? provenance.accessibilityLabel,
         boundsHint: provenance.boundsBucket,
@@ -178,17 +185,57 @@ async function resourceIdVisibility(session, d, id, provenance) {
     const matches = parsed.allNodes.filter((node) => resourceIdMatches(undefined, node.id, id));
     const screenMismatch = provenance?.originalScreenSignature && flowScreenSignature(parsed) !== provenance.originalScreenSignature;
     if (!matches.length)
-        return { visible: false, detail: `resource-id "${id}" not visible${screenMismatch ? ' (recorded screen signature differs from current screen)' : ''}` };
+        return {
+            visible: false,
+            detail: `resource-id "${id}" not visible${screenMismatch ? ' (recorded screen signature differs from current screen)' : ''}`,
+        };
     const narrowed = matches.length > 1 ? narrowRawResourceMatches(matches, provenance) : matches;
     if (narrowed.length > 1) {
         const labels = narrowed.map((node, index) => `${index + 1}:${node.cls}:${node.text || node.desc || node.id || 'unlabeled'}`).join(', ');
-        return { visible: true, ambiguous: true, detail: `AMBIGUOUS_SELECTOR: resource-id ${id} matched ${narrowed.length} visible nodes (${labels}); add text/class/bounds hints or a unique testID${screenMismatch ? ' (recorded screen signature differs from current screen)' : ''}.` };
+        return {
+            visible: true,
+            ambiguous: true,
+            detail: `AMBIGUOUS_SELECTOR: resource-id ${id} matched ${narrowed.length} visible nodes (${labels}); add text/class/bounds hints or a unique testID${screenMismatch ? ' (recorded screen signature differs from current screen)' : ''}.`,
+        };
     }
     const node = narrowed[0];
     return { visible: node.enabled !== false && node.bounds[2] > node.bounds[0] && node.bounds[3] > node.bounds[1] };
 }
+/** In-tree modal surfaces that BACK dismisses (Android dialogs / bottom sheets / popups, iOS
+ * alerts and action sheets, system permission dialogs rendered in-tree). */
+const MODAL_CLASS_RE = /BottomSheet|AlertDialog|DialogTitle|PopupWindow|XCUIElementTypeAlert|XCUIElementTypeSheet/;
+const MODAL_ID_RE = /design_bottom_sheet|bottom_sheet|touch_outside|android:id\/(?:alertTitle|button1|button2|parentPanel|select_dialog_listview)|permissioncontroller:id\/|packageinstaller:id\/permission|:id\/(?:modal|dialog)[_a-z]*/i;
+/** Classify what (if anything) the clearOverlay flow step may safely dismiss with BACK.
+ * Snackbars / banners are NOT BACK-dismissible (BACK would navigate the app instead). */
+export function detectBackDismissibleOverlay(nodes, screen, appId, foregroundOwner) {
+    const fg = classifyForeground(appId, foregroundOwner);
+    if (fg && (fg.type === 'permission_dialog' || fg.type === 'account_picker'))
+        return fg.type;
+    const tree = detectTreeOverlays(nodes, screen).find((o) => o.type === 'native_dialog' || o.type === 'rn_logbox' || o.type === 'rn_redbox');
+    if (tree)
+        return tree.type;
+    const modal = nodes.find((n) => MODAL_CLASS_RE.test(n.cls) || MODAL_ID_RE.test(n.id));
+    if (modal)
+        return /permission/i.test(modal.id) ? 'permission_dialog' : /sheet/i.test(`${modal.cls} ${modal.id}`) ? 'bottom_sheet' : 'modal';
+    return undefined;
+}
 export function classifyFlowDriverError(error, fallback = 'UNKNOWN') {
+    // Cancelled work (the call/job was aborted) is CANCELLED, never WDA_UNREACHABLE / SNAPSHOT_FAILED
+    // because the aborted request's message says "aborted" or "dump failed".
+    if (isAbortError(error))
+        return 'CANCELLED';
     const msg = String(error?.message ?? error);
+    // A crashing OCR/mask provider (tapOcrText/assertOcrText) is typed, not UNKNOWN.
+    if (error?.code === 'OCR_PROVIDER_FAILED')
+        return 'OCR_PROVIDER_FAILED';
+    // Driver-side argument validation (e.g. a malformed app id from assertAndroidAppId) carries
+    // code INVALID_ARGUMENT and/or an `INVALID_ARGUMENT:` message prefix. That's a caller error, not UNKNOWN.
+    if (error?.code === 'INVALID_ARGUMENT' || /^(?:Error:\s*)?INVALID_ARGUMENT\b/.test(msg))
+        return 'INVALID_ARGUMENT';
+    // Drivers self-classify undeliverable text (DirectDriver/WdaDriver prefix the code), so match
+    // first so the free-form detail after the prefix can't hit a broader pattern below.
+    if (/TEXT_INPUT_UNSUPPORTED/.test(msg))
+        return 'TEXT_INPUT_UNSUPPORTED';
     if (/not hittable|not hit.?point|not visible.*hittable|is not enabled|element.*obscured|other element.*would receive/i.test(msg))
         return 'ELEMENT_NOT_HITTABLE';
     if (/stale element|stale.*reference|element.*no longer|invalid element/i.test(msg))
@@ -231,22 +278,34 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
     const steps = [];
     const appId = flow.appId ?? session.appId;
     const timeoutMs = 8000;
-    // Ensure session.driver is the driver we're running with — core helpers (resolveTarget) read it.
+    // Ensure session.driver is the driver we're running with. Core helpers (resolveTarget) read it.
     session.driver = d;
-    const screenSize = await d.screenSize().catch(() => null);
+    // Re-read per gesture: a rotation mid-flow swaps the axes (the WDA driver caches per
+    // orientation, so this is cheap there). Keeps the first read as the fallback.
+    const initialScreenSize = await d.screenSize().catch(() => null);
+    const currentScreenSize = async () => (await d.screenSize().catch(() => null)) ?? initialScreenSize;
     const mutationConsent = opts.mutationConsent ?? { required: false, approved: true };
     const resolveFlowText = (value) => {
         const resolved = resolveVars(value, vars);
         for (const m of value.matchAll(/\$\{([^}]+)\}/g)) {
             const name = m[1];
-            const v = vars[name] ?? process.env[name];
-            if (v != null && SECRET_VAR_NAME.test(name))
+            const v = lookupFlowVar(name, vars);
+            if (v != null && v !== '' && SECRET_VAR_NAME.test(name))
                 session.secrets.add(v);
         }
         return resolved;
     };
-    const unresolved = (missing) => ({ ok: false, detail: `unresolved variable(s): ${missing.join(', ')}`, failureCode: 'MISSING_FIXTURE' });
+    const unresolved = (missing) => ({
+        ok: false,
+        detail: missingVarMessage(missing),
+        failureCode: 'MISSING_FIXTURE',
+    });
     const shown = (value) => makeRedactor(session.secrets)(value) ?? value;
+    const outsideRoot = (p) => ({
+        ok: false,
+        detail: `path "${p}" resolves outside the project root. Image templates and baselines must live under the project root`,
+        failureCode: 'UNSAFE_ACTION_REFUSED',
+    });
     const recordFlowMutation = (action, risk, target, status, detail) => {
         sessions.recordMutation(session, {
             tool: 'qa_flow_run',
@@ -263,8 +322,8 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
     let reason;
     let failureCode;
     const tapImageHit = async (template, minScore) => {
-        const tplPath = isAbsolute(template) ? template : join(session.root, template);
-        if (!existsSync(tplPath))
+        const tplPath = withinRootOrNull(session.root, template);
+        if (!tplPath || !existsSync(tplPath))
             return null;
         const png = await d.screenshot();
         const m = findTemplate(png, readFileSync(tplPath), minScore ?? 0.85);
@@ -315,7 +374,11 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                     return { ok: true };
                 }
                 if (native && native.using !== 'accessibility id' && native.using !== 'name') {
-                    return { ok: false, detail: `${native.using} selectors require backend-native selector support`, failureCode: 'BACKEND_UNSUPPORTED' };
+                    return {
+                        ok: false,
+                        detail: `${native.using} selectors require backend-native selector support`,
+                        failureCode: 'BACKEND_UNSUPPORTED',
+                    };
                 }
                 const t = await resolveTarget(session, targetForTapSelector(selector, provenance));
                 if ('error' in t)
@@ -331,6 +394,8 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                 await settle(d, { timeoutMs });
                 return { ok: true };
             case 'tapImage': {
+                if (!withinRootOrNull(session.root, step.template))
+                    return outsideRoot(step.template);
                 const pt = await tapImageHit(step.template, step.minScore);
                 if (!pt)
                     return { ok: false, detail: `image "${step.template}" not found on screen`, failureCode: 'ELEMENT_NOT_FOUND' };
@@ -345,7 +410,11 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                     return unresolved(resolved.missing);
                 const query = resolved.out;
                 if (session.sensitive)
-                    return { ok: false, detail: 'Sensitive mode refuses OCR visual text search because it would pass a screenshot to an external provider', failureCode: 'UNSAFE_ACTION_REFUSED' };
+                    return {
+                        ok: false,
+                        detail: 'Sensitive mode refuses OCR visual text search because it would pass a screenshot to an external provider',
+                        failureCode: 'UNSAFE_ACTION_REFUSED',
+                    };
                 const command = configuredOcrCommand(session.root);
                 if (!command)
                     return { ok: false, detail: 'OCR command is not configured', failureCode: 'VISUAL_ONLY_SCREEN' };
@@ -360,9 +429,17 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
             case 'inputText': {
                 const { out, missing } = resolveFlowText(step.value);
                 if (missing.length)
-                    return { ok: false, detail: `unresolved variable(s): ${missing.join(', ')}`, failureCode: 'MISSING_FIXTURE' };
+                    return unresolved(missing);
+                // Register a secret BEFORE typing so a failing driver call's error is scrubbed too (H2).
+                if (step.secret && out)
+                    session.secrets.add(out);
+                // eslint-disable-next-line no-control-regex -- intentional: detect non-ASCII (outside \x00-\x7F) before adb text input
                 if (d.kind === 'direct' && /[^\x00-\x7F]/.test(out)) {
-                    return { ok: false, detail: 'Android DirectDriver text entry is ASCII-safe only for generated replay values', failureCode: 'TEXT_INPUT_UNSUPPORTED' };
+                    return {
+                        ok: false,
+                        detail: 'Android DirectDriver text entry is ASCII-safe only for generated replay values',
+                        failureCode: 'TEXT_INPUT_UNSUPPORTED',
+                    };
                 }
                 if (step.into) {
                     const into = resolveFlowText(step.into);
@@ -384,12 +461,20 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                         return { ok: true };
                     }
                     if (native && native.using !== 'accessibility id' && native.using !== 'name') {
-                        return { ok: false, detail: `${native.using} selectors require backend-native selector support`, failureCode: 'BACKEND_UNSUPPORTED' };
+                        return {
+                            ok: false,
+                            detail: `${native.using} selectors require backend-native selector support`,
+                            failureCode: 'BACKEND_UNSUPPORTED',
+                        };
                     }
                     // selector-bound: focus the named field first (no reliance on existing focus)
                     const t = await resolveTarget(session, targetForTapSelector(into.out, provenance));
                     if ('error' in t)
-                        return { ok: false, detail: `field "${shown(into.out)}": ${t.error}`, failureCode: classifyFlowDriverError(t.error, 'ELEMENT_NOT_FOUND') };
+                        return {
+                            ok: false,
+                            detail: `field "${shown(into.out)}": ${t.error}`,
+                            failureCode: classifyFlowDriverError(t.error, 'ELEMENT_NOT_FOUND'),
+                        };
                     await d.tapXY(t.x, t.y);
                     await new Promise((r) => setTimeout(r, 600));
                     await d.clearFocusedText(t.textLen);
@@ -418,7 +503,9 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                     const visibleById = await resourceIdVisibility(session, d, id, provenance);
                     if (visibleById.ambiguous)
                         return { ok: false, detail: visibleById.detail, failureCode: 'AMBIGUOUS_SELECTOR' };
-                    return visibleById.visible ? { ok: true } : { ok: false, detail: visibleById.detail ?? `"${shown(query)}" not visible`, failureCode: 'ASSERTION_FAILED' };
+                    return visibleById.visible
+                        ? { ok: true }
+                        : { ok: false, detail: visibleById.detail ?? `"${shown(query)}" not visible`, failureCode: 'ASSERTION_FAILED' };
                 }
                 const ok = visible(await snapshot(session, d), fallbackVisibleQuery(query));
                 return ok ? { ok } : { ok, detail: `"${shown(query)}" not visible`, failureCode: 'ASSERTION_FAILED' };
@@ -431,7 +518,9 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                 try {
                     const native = await nativeVisible(d, query);
                     if (native != null)
-                        return !native ? { ok: true } : { ok: false, detail: `"${shown(query)}" unexpectedly visible`, failureCode: 'ASSERTION_FAILED' };
+                        return !native
+                            ? { ok: true }
+                            : { ok: false, detail: `"${shown(query)}" unexpectedly visible`, failureCode: 'ASSERTION_FAILED' };
                 }
                 catch (e) {
                     return { ok: false, detail: String(e.message ?? e), failureCode: 'BACKEND_UNSUPPORTED' };
@@ -441,17 +530,23 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                     const visibleById = await resourceIdVisibility(session, d, id, provenance);
                     if (visibleById.ambiguous)
                         return { ok: false, detail: visibleById.detail, failureCode: 'AMBIGUOUS_SELECTOR' };
-                    return !visibleById.visible ? { ok: true } : { ok: false, detail: `"${shown(query)}" unexpectedly visible`, failureCode: 'ASSERTION_FAILED' };
+                    return !visibleById.visible
+                        ? { ok: true }
+                        : { ok: false, detail: `"${shown(query)}" unexpectedly visible`, failureCode: 'ASSERTION_FAILED' };
                 }
                 const ok = !visible(await snapshot(session, d), fallbackVisibleQuery(query));
                 return ok ? { ok } : { ok, detail: `"${shown(query)}" unexpectedly visible`, failureCode: 'ASSERTION_FAILED' };
             }
             case 'assertImage': {
-                const tplPath = isAbsolute(step.template) ? step.template : join(session.root, step.template);
+                const tplPath = withinRootOrNull(session.root, step.template);
+                if (!tplPath)
+                    return outsideRoot(step.template);
                 if (!existsSync(tplPath))
                     return { ok: false, detail: `template not found: ${tplPath}`, failureCode: 'ASSERTION_FAILED' };
                 const m = findTemplate(await d.screenshot(), readFileSync(tplPath), step.minScore ?? 0.85);
-                return m.found ? { ok: true } : { ok: false, detail: `image "${step.template}" not visible (best score ${m.score})`, failureCode: 'ASSERTION_FAILED' };
+                return m.found
+                    ? { ok: true }
+                    : { ok: false, detail: `image "${step.template}" not visible (best score ${m.score})`, failureCode: 'ASSERTION_FAILED' };
             }
             case 'assertOcrText': {
                 const resolved = resolveFlowText(step.query);
@@ -459,7 +554,11 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                     return unresolved(resolved.missing);
                 const query = resolved.out;
                 if (session.sensitive)
-                    return { ok: false, detail: 'Sensitive mode refuses OCR visual text assertion because it would pass a screenshot to an external provider', failureCode: 'UNSAFE_ACTION_REFUSED' };
+                    return {
+                        ok: false,
+                        detail: 'Sensitive mode refuses OCR visual text assertion because it would pass a screenshot to an external provider',
+                        failureCode: 'UNSAFE_ACTION_REFUSED',
+                    };
                 const command = configuredOcrCommand(session.root);
                 if (!command)
                     return { ok: false, detail: 'OCR command is not configured', failureCode: 'VISUAL_ONLY_SCREEN' };
@@ -468,22 +567,51 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
             }
             case 'assertVisual': {
                 // human-readable visual checkpoint: capture evidence + record a visual note; passes.
+                // Sensitive mode never persists screenshots, so record an honest skipped checkpoint instead.
+                if (session.sensitive) {
+                    sessions.addNote(session, {
+                        at: Date.now(),
+                        workflow: `${flow.name}:visual`,
+                        outcome: 'skipped',
+                        reason: `${step.description}: not captured, sensitive mode disables screenshots`,
+                        method: 'visual',
+                    });
+                    return { ok: true, detail: 'sensitive mode: visual checkpoint screenshot not captured' };
+                }
                 const png = await d.screenshot();
                 const uri = sessions.saveArtifact(session, 'screenshot', `flow-visual-${Date.now()}.png`, png, 'image/png', `visual checkpoint: ${step.description}`);
                 sessions.bump(session, 'screenshots');
-                sessions.addNote(session, { at: Date.now(), workflow: `${flow.name}:visual`, outcome: 'pass', reason: step.description, method: 'visual', verifiedVisually: true, artifactUris: [uri] });
+                sessions.addNote(session, {
+                    at: Date.now(),
+                    workflow: `${flow.name}:visual`,
+                    outcome: 'pass',
+                    reason: step.description,
+                    method: 'visual',
+                    verifiedVisually: true,
+                    artifactUris: [uri],
+                });
                 return { ok: true };
             }
             case 'assertDiff': {
-                const basePath = join(session.root, '.swipium', 'baselines', `${step.baseline}.png`);
+                const basePath = withinRootOrNull(join(session.root, '.swipium', 'baselines'), `${step.baseline}.png`);
+                if (!basePath)
+                    return outsideRoot(step.baseline);
                 if (!existsSync(basePath))
                     return { ok: false, detail: `no baseline "${step.baseline}" (create a visual baseline first)`, failureCode: 'MISSING_FIXTURE' };
                 const res = imageDiff(readFileSync(basePath), await d.screenshot());
                 const tol = step.threshold ?? 0.02;
-                return res.comparable && res.ratio <= tol ? { ok: true } : { ok: false, detail: res.comparable ? `${(res.ratio * 100).toFixed(2)}% changed > ${(tol * 100).toFixed(1)}%` : `not comparable: ${res.reason}`, failureCode: 'ASSERTION_FAILED' };
+                return res.comparable && res.ratio <= tol
+                    ? { ok: true }
+                    : {
+                        ok: false,
+                        detail: res.comparable
+                            ? `${(res.ratio * 100).toFixed(2)}% changed > ${(tol * 100).toFixed(1)}%`
+                            : `not comparable: ${res.reason}`,
+                        failureCode: 'ASSERTION_FAILED',
+                    };
             }
             case 'swipe': {
-                const v = swipeVector(screenSize, step.direction, step.area, step.distance);
+                const v = swipeVector(await currentScreenSize(), step.direction, step.area, step.distance);
                 await d.swipe(v[0], v[1], v[2], v[3], 300);
                 sessions.bump(session, 'actions');
                 await settle(d, { timeoutMs });
@@ -494,6 +622,7 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                 if (resolved.missing.length)
                     return unresolved(resolved.missing);
                 const query = resolved.out;
+                const screenSize = await currentScreenSize();
                 for (let n = 0; n < 8; n++) {
                     try {
                         const native = await nativeVisible(d, query);
@@ -534,7 +663,7 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
             case 'openUrl': {
                 const { out, missing } = resolveFlowText(step.url);
                 if (missing.length)
-                    return { ok: false, detail: `unresolved variable(s): ${missing.join(', ')}`, failureCode: 'MISSING_FIXTURE' };
+                    return unresolved(missing);
                 await d.openUrl(out);
                 await settle(d, { timeoutMs });
                 return { ok: true };
@@ -553,7 +682,7 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                 if (resolved.missing.length)
                     return unresolved(resolved.missing);
                 const query = resolved.out;
-                const deadline = Date.now() + (step.kind === 'waitForVisible' ? step.timeoutMs ?? timeoutMs : timeoutMs);
+                const deadline = Date.now() + (step.kind === 'waitForVisible' ? (step.timeoutMs ?? timeoutMs) : timeoutMs);
                 const waitStarted = Date.now();
                 while (Date.now() < deadline) {
                     try {
@@ -602,13 +731,62 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                 return { ok: true };
             }
             case 'clearOverlay': {
-                // best-effort: hide the keyboard / dismiss a dialog with BACK (a flow cleanup, always ok)
-                if (await d.imeShown().catch(() => false))
-                    await d.pressKey('back');
-                else
-                    await d.pressKey('back');
+                // Best-effort cleanup (always ok), but BACK only when something is there to dismiss:
+                // with nothing open, BACK navigates away / exits the app (H7).
+                if (await d.imeShown().catch(() => false)) {
+                    if (d.hideKeyboard)
+                        await d.hideKeyboard().catch(() => false);
+                    else
+                        await d.pressKey('back');
+                    await settle(d, { timeoutMs });
+                    return { ok: true, detail: 'keyboard hidden' };
+                }
+                const parsed = await snapshot(session, d).catch(() => null);
+                const fg = await d.foregroundOwner().catch(() => 'unknown');
+                const dismissible = detectBackDismissibleOverlay(parsed?.allNodes ?? [], parsed?.screen, session.appId, fg);
+                if (!dismissible) {
+                    return {
+                        ok: true,
+                        nothingCleared: true,
+                        detail: 'nothing to clear (no keyboard, dialog, sheet or permission prompt detected), BACK not pressed',
+                    };
+                }
+                // iOS has no BACK for alerts/sheets: WDA "back" taps the nav bar / edge-swipes, which
+                // navigates the app instead of dismissing the alert. Use the native alert API, and never
+                // claim success when it is unavailable or the overlay is still there.
+                if (d.kind === 'wda' || d.kind === 'simulator') {
+                    if (!d.dismissAlert) {
+                        return {
+                            ok: true,
+                            nothingCleared: false,
+                            detail: `${dismissible} detected but NOT dismissed. This iOS backend has no native alert API (BACK is not used on iOS); dismiss it with an explicit tap step`,
+                        };
+                    }
+                    try {
+                        await d.dismissAlert();
+                    }
+                    catch (e) {
+                        return {
+                            ok: true,
+                            nothingCleared: false,
+                            detail: `${dismissible} detected but NOT dismissed: native alert dismiss failed: ${String(e?.message ?? e)}`,
+                        };
+                    }
+                    await settle(d, { timeoutMs });
+                    const after = await snapshot(session, d).catch(() => null);
+                    const fgAfter = await d.foregroundOwner().catch(() => 'unknown');
+                    const still = after ? detectBackDismissibleOverlay(after.allNodes, after.screen, session.appId, fgAfter) : undefined;
+                    if (still)
+                        return {
+                            ok: true,
+                            nothingCleared: false,
+                            detail: `${dismissible} still present after native alert dismiss. Dismiss it with an explicit tap step`,
+                        };
+                    return { ok: true, detail: `dismissed ${dismissible} with the native alert API` };
+                }
+                await d.pressKey('back');
                 await settle(d, { timeoutMs });
-                return { ok: true };
+                return { ok: true, detail: `dismissed ${dismissible} with BACK` };
             }
             case 'networkOffline':
             case 'networkOnline': {
@@ -637,7 +815,15 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                 const r = await executeSeed(sessions, session, d, step.fixture, fixture.seed);
                 const risk = fixture.seed.type === 'script' ? 'high' : fixture.seed.type === 'api' ? 'medium' : 'low';
                 if (!r.ok) {
-                    sessions.addNote(session, { at: Date.now(), workflow: `seed:${step.fixture}`, outcome: 'blocked', category: 'missing_test_data', reason: `seed failed: ${r.detail}`, requiredState: fixture.requiredState, recommendedSetup: fixture.recommendedSetup });
+                    sessions.addNote(session, {
+                        at: Date.now(),
+                        workflow: `seed:${step.fixture}`,
+                        outcome: 'blocked',
+                        category: 'missing_test_data',
+                        reason: `seed failed: ${r.detail}`,
+                        requiredState: fixture.requiredState,
+                        recommendedSetup: fixture.recommendedSetup,
+                    });
                     recordFlowMutation('flow_seed_state', risk, { stepKind: step.kind, fixture: step.fixture, seedType: fixture.seed.type }, 'blocked', r.detail);
                     return { ok: false, detail: `seed "${step.fixture}" failed: ${r.detail}`, failureCode: 'SEED_FAILED' };
                 }
@@ -648,6 +834,8 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
                 sessions.addNote(session, { at: Date.now(), workflow: `${flow.name}:note`, outcome: step.outcome, reason: step.reason });
                 return { ok: true };
             case 'screenshot': {
+                if (session.sensitive)
+                    return { ok: true, detail: 'sensitive mode: screenshot not captured' };
                 const png = await d.screenshot();
                 sessions.saveArtifact(session, 'screenshot', `flow-shot-${Date.now()}.png`, png, 'image/png', step.reason ?? 'flow screenshot');
                 sessions.bump(session, 'screenshots');
@@ -670,7 +858,7 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
             reason,
             failureCode,
             steps,
-            durationSec: Math.round(elapsedMs / 100) / 10,
+            durationMs: Math.round(elapsedMs),
             counters: session.counters,
         };
     };
@@ -682,7 +870,7 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
             const summary = describe(step);
             const budget = sessions.budgetStop(session);
             if (budget && phase !== 'teardown') {
-                steps.push({ index, phase, kind: step.kind, summary, ok: false, durationSec: 0, detail: budget });
+                steps.push({ index, phase, kind: step.kind, summary, ok: false, durationMs: 0, detail: budget });
                 passed = false;
                 failedAtStep = index;
                 reason = `budget: ${budget}`;
@@ -696,24 +884,45 @@ export async function runFlow(sessions, session, d, flow, opts = {}) {
             catch (e) {
                 outcome = { ok: false, detail: String(e), failureCode: classifyFlowDriverError(e) };
             }
-            const rec = { index, phase, kind: step.kind, summary, ok: outcome.ok, durationSec: Math.round((Date.now() - stepStarted) / 100) / 10, detail: outcome.detail, failureCode: outcome.failureCode };
+            // H2: step detail can carry driver errors (argv/stderr), so scrub session secrets, which
+            // include every value typed into a secret step/variable before it ran.
+            if (outcome.detail)
+                outcome = { ...outcome, detail: shown(outcome.detail) };
+            const rec = {
+                index,
+                phase,
+                kind: step.kind,
+                summary: shown(summary),
+                ok: outcome.ok,
+                durationMs: Math.round(Date.now() - stepStarted),
+                detail: outcome.detail,
+                failureCode: outcome.failureCode,
+                ...(outcome.nothingCleared !== undefined ? { nothingCleared: outcome.nothingCleared } : {}),
+            };
             steps.push(rec);
             if (!outcome.ok && failFast) {
                 passed = false;
                 failedAtStep = index;
                 reason = outcome.detail ?? 'step failed';
                 failureCode = outcome.failureCode;
+                // Sensitive mode never persists screenshots, including failure evidence.
+                if (session.sensitive) {
+                    rec.detail = `${rec.detail ?? 'step failed'} (sensitive mode: failure screenshot not captured)`;
+                    return index;
+                }
                 try {
                     const png = await d.screenshot();
                     rec.screenshotUri = sessions.saveArtifact(session, 'screenshot', `flow-fail-${index}-${Date.now()}.png`, png, 'image/png', `flow ${flow.name} failed at step ${index}: ${summary}`);
                 }
-                catch { /* best-effort */ }
+                catch {
+                    /* best-effort */
+                }
                 return index;
             }
         }
         return -1;
     };
-    // setup → main → teardown (teardown ALWAYS runs, even after a failure).
+    // setup > main > teardown (teardown ALWAYS runs, even after a failure).
     let nextBase = 0;
     const setupFail = await runPhase(flow.setup, 'setup', nextBase, true);
     nextBase += flow.setup.length;