swipium 1.4.0 → 2.0.0

package/dist/tools/flow.js

@@ -1,15 +1,20 @@
-// qa_flow_check + qa_flow_run (PHASE3-PLAN §3.4) — turn exploration into repeatable QA.
+// qa_flow_check + qa_flow_run: turn exploration into repeatable QA.
 // Flows live as .swipium/flows/*.yaml. check = parse + static validation (no device).
-// run = the orchestrator (src/flows/run.ts), reporting the exact failing step + evidence.
+// run (mode:"run", default) = the orchestrator (src/flows/run.ts), reporting the exact failing
+// step + evidence. run (mode:"plan", 1.5.0 consolidation) = read-only execution preview:
+// compile the flow against backend capabilities without touching a device.
 import { z } from 'zod';
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, isAbsolute } from 'node:path';
-import { qaOk, qaError, qaStop } from '../lib/result.js';
-import { parseFlow } from '../flows/schema.js';
+import { qaOk, qaError, qaStop, qaAnnotate, unknownSessionError } from '../lib/result.js';
+import { FLOW_ENV_PREFIX, isMutatingFlowStep, lookupFlowVar, parseFlow, SECRET_VAR_NAME, } from '../flows/schema.js';
+import { seedExactCommand } from '../flows/seedExec.js';
+import { withinRootOrNull } from '../flows/paths.js';
+import { makeRedactor } from '../lib/redact.js';
 import { lintFlowObjectWithOptions } from '../flows/lint.js';
 import { runFlow } from '../flows/run.js';
-import { getDriver } from '../session/attach.js';
+import { blockedDeviceResult, getDriver } from '../session/attach.js';
 import { loadPolicy } from '../report/policy.js';
 import { classifyFlakeResults } from '../report/flake.js';
 import { validateCiMutationPolicy, validateCiVariables } from '../ci/preflight.js';
@@ -21,14 +26,15 @@ import { resolveMaskProvider, resolveVisualProvider } from '../visual/provider.j
 import { backendCapabilities, backendForDriverKind } from '../automation/capabilities.js';
 import { compileAutomationPlan } from '../automation/plan.js';
 import { buildReadiness } from '../automation/report.js';
+import { resolveProjectRoot } from '../context/projectRoot.js';
 const ALL_BACKENDS = ['android-direct', 'ios-raw-simulator', 'ios-wda', 'appium-uiautomator2', 'appium-xcuitest'];
 const STATUS_ICON = { ready: '✅', candidate: '🟡', blocked: '⛔' };
 /** Resolve a flow's YAML from explicit text, an absolute/relative path, or a name under .swipium/flows. */
-function loadFlowSource(root, flow, flowYaml) {
+export function loadFlowSource(root, flow, flowYaml) {
     if (flowYaml && flowYaml.trim())
         return { yamlText: flowYaml, source: 'inline' };
     if (!flow)
-        return { error: 'Provide a flow name, a path, or flowYaml.' };
+        return { error: 'Provide a flow name, a path, or flowYaml.', errorCode: 'INVALID_ARGUMENT' };
     const candidates = [];
     if (isAbsolute(flow))
         candidates.push(flow);
@@ -43,23 +49,52 @@ function loadFlowSource(root, flow, flowYaml) {
                 return { yamlText: readFileSync(p, 'utf8'), source: p };
             }
             catch (e) {
-                return { error: `Could not read ${p}: ${String(e)}` };
+                return { error: `Could not read ${p}: ${String(e)}`, errorCode: 'INVALID_FLOW' };
             }
         }
     }
-    return { error: `Flow not found. Looked for: ${candidates.join(', ') || '(no project root)'}` };
+    return {
+        error: `Flow not found. Looked for: ${candidates.join(', ') || '(no project root; pass projectRoot or set SWIPIUM_PROJECT_ROOT)'}`,
+        errorCode: 'FLOW_NOT_FOUND',
+    };
+}
+/**
+ * The project root a flow tool reads from: explicit projectRoot arg > the session's root >
+ * resolveProjectRoot (MCP roots > SWIPIUM_PROJECT_ROOT/CLAUDE_PROJECT_DIR > cwd marker), like
+ * every other root-aware tool. Undefined only when nothing resolves (inline flowYaml still works).
+ */
+async function flowRoot(server, sessionRoot, projectRoot) {
+    if (!projectRoot && sessionRoot)
+        return sessionRoot;
+    const resolved = await resolveProjectRoot(server, projectRoot);
+    return resolved.root ?? sessionRoot;
+}
+function flowSourceError(src) {
+    return qaError({
+        what: src.error ?? 'Flow could not be loaded',
+        changedState: false,
+        retrySafe: true,
+        failureCode: src.errorCode ?? 'FLOW_NOT_FOUND',
+        nextSteps: [
+            src.errorCode === 'INVALID_ARGUMENT'
+                ? 'Pass flow="<name>" (under .swipium/flows), a .yaml path, or inline flowYaml.'
+                : 'Pass an existing flow name/path or inline flowYaml; pass projectRoot (or set SWIPIUM_PROJECT_ROOT) if the flow lives in another project.',
+        ],
+    });
 }
-const MUTATING_FLOW_STEPS = new Set(['networkOffline', 'networkOnline', 'seed', 'restartApp']);
-const EXTERNAL_PROVIDER_FLOW_STEPS = new Set(['tapOcrText', 'assertOcrText']);
 function stable(value) {
     if (Array.isArray(value))
         return value.map(stable);
     if (value && typeof value === 'object')
-        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, stable(v)]));
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([k, v]) => [k, stable(v)]));
     return value;
 }
 function fullHash(value) {
-    return createHash('sha256').update(JSON.stringify(stable(value))).digest('hex');
+    return createHash('sha256')
+        .update(JSON.stringify(stable(value)))
+        .digest('hex');
 }
 function hash(value) {
     return fullHash(value).slice(0, 16);
@@ -67,15 +102,41 @@ function hash(value) {
 function allFlowSteps(flow) {
     return [...flow.setup, ...flow.steps, ...flow.teardown];
 }
-function flowMutationAffects(flow, session, source, repeat, externalProviders = []) {
+/** Where a seed's command came from, stated in consent: fixtures are loaded from the repo's
+ *  .swipium/fixtures.json (or qa_start_session fixtures). Swipium never reviewed them. */
+const SEED_ORIGIN = 'declared fixture (.swipium/fixtures.json or qa_start_session fixtures), repo-supplied, UNREVIEWED';
+/** `${VAR}` URL preview for consent: the URL as it will be opened, with credential-like variable
+ *  values and registered session secrets masked, plus where each variable is read from. */
+function openUrlPreview(url, vars, secrets) {
+    const variables = [];
+    const resolved = url.replace(/\$\{([^}]+)\}/g, (_, name) => {
+        const v = lookupFlowVar(name, vars);
+        variables.push({ name, source: v == null ? 'missing' : vars[name] != null ? 'variables' : 'env' });
+        if (v == null)
+            return `\${${name}}`;
+        return SECRET_VAR_NAME.test(name) ? `«${name}»` : v;
+    });
+    return { url, resolvedUrl: makeRedactor(secrets)(resolved) ?? resolved, variables };
+}
+function flowMutationAffects(flow, session, source, repeat, externalProviders = [], vars = {}) {
     const mutations = allFlowSteps(flow)
         .map((step, index) => {
-        if (!MUTATING_FLOW_STEPS.has(step.kind))
+        if (!isMutatingFlowStep(step))
             return null;
         if (step.kind === 'seed') {
-            const seedType = session.fixtures.find((f) => f.name === step.fixture)?.seed?.type ?? 'unknown';
-            return { step: index + 1, kind: step.kind, fixture: step.fixture, seedType };
+            const seed = session.fixtures.find((f) => f.name === step.fixture)?.seed;
+            return {
+                step: index + 1,
+                kind: step.kind,
+                fixture: step.fixture,
+                seedType: seed?.type ?? 'unknown',
+                // The EXACT argv / URL the seed will run. Consent must show what executes.
+                command: seed ? seedExactCommand(seed) : null,
+                origin: SEED_ORIGIN,
+            };
         }
+        if (step.kind === 'openUrl')
+            return { step: index + 1, kind: step.kind, ...openUrlPreview(step.url, vars, session.secrets ?? []) };
         return { step: index + 1, kind: step.kind };
     })
         .filter((x) => !!x);
@@ -89,10 +150,21 @@ function flowMutationAffects(flow, session, source, repeat, externalProviders =
         externalProviders,
     };
 }
+/** One line per mutating step for the consent's exactCommand (seeds show their argv/URL). */
+function mutationCommandLines(affects) {
+    return affects.mutations.map((m) => {
+        if (m.kind === 'seed' && 'fixture' in m)
+            return `${m.step}:seed ${m.fixture} [${m.seedType}] > ${m.command ?? '(no seed spec, step will fail)'}  (repo-supplied, unreviewed)`;
+        if (m.kind === 'openUrl' && 'resolvedUrl' in m)
+            return `${m.step}:openUrl ${m.resolvedUrl}  (variables: ${m.variables.map((v) => `${v.name}←${v.source}`).join(', ')})`;
+        return `${m.step}:${m.kind}`;
+    });
+}
 function flowMutationRisk(affects) {
     if (affects.mutations.some((m) => m.kind === 'seed' && m.seedType === 'script'))
         return 'high';
-    if (affects.externalProviders.length || affects.mutations.some((m) => m.kind === 'networkOffline' || m.kind === 'networkOnline' || m.kind === 'seed'))
+    if (affects.externalProviders.length ||
+        affects.mutations.some((m) => m.kind === 'networkOffline' || m.kind === 'networkOnline' || m.kind === 'seed' || m.kind === 'openUrl'))
         return 'medium';
     return 'low';
 }
@@ -105,35 +177,58 @@ function ocrSteps(flow) {
     });
     return out;
 }
+const LOCATOR_FAILURES = new Set(['ELEMENT_NOT_FOUND', 'AMBIGUOUS_SELECTOR', 'STALE_REF', 'INVALID_SELECTOR', 'ASSERTION_FAILED']);
+/** nextSteps for a failed qa_flow_run: point at qa_flow_repair for the failing step. */
+export function failedFlowNextSteps(name, flowArg, failedAtStep, failureCode) {
+    const out = [];
+    // A missing variable is not locator drift: qa_flow_repair cannot fix it (and a cancelled run is
+    // not a failure to repair).
+    if (failedAtStep != null && failureCode !== 'MISSING_FIXTURE' && failureCode !== 'CANCELLED') {
+        const target = flowArg ? `flow:"${flowArg}"` : 'flowYaml:<same YAML>';
+        out.push(`${failureCode && !LOCATOR_FAILURES.has(failureCode) ? 'If this is locator drift (renamed/moved control), ' : ''}call qa_flow_repair { ${target}, failedStep:${failedAtStep} } for a reviewable locator fix (review before apply).`);
+    }
+    if (failureCode === 'MISSING_FIXTURE')
+        out.push(`Pass missing values via qa_flow_run { variables } (flows read process.env only for ${FLOW_ENV_PREFIX}* names).`);
+    out.push(`If the app itself is wrong, record it with qa_note { workflow:"${name}", outcome:"fail" } with the step evidence.`);
+    return out;
+}
 export function registerFlow(server, sessions) {
     server.registerTool('qa_flow_check', {
         title: 'Check a flow',
-        description: 'Parse and statically validate a Swipium flow (a .swipium/flows/*.yaml authored as name + steps) WITHOUT running it. Reports syntax/schema errors with the offending step, plus warnings (e.g. selector resolvability is only known at run time). Provide `flow` (a name under .swipium/flows, or a path) or `flowYaml` (inline). A sessionId lets it resolve names against that session\'s project root.',
+        description: 'Statically validate a flow (.swipium/flows/*.yaml: name + steps) without running it: syntax/schema errors with the offending ' +
+            'step, plus warnings. Pass flow (name or path) or flowYaml. For an execution preview per backend use qa_flow_run mode:"plan".',
         inputSchema: {
             sessionId: z.string().optional(),
+            projectRoot: z.string().optional().describe('Absolute app root (default: session root > MCP roots > env > cwd).'),
             flow: z.string().optional().describe('Flow name under .swipium/flows, or a path to a .yaml file.'),
             flowYaml: z.string().optional().describe('Inline flow YAML (instead of a file).'),
-            platform: z.enum(['android', 'ios', 'cross-platform']).optional().describe('Optional authoring target for platform-aware warnings.'),
-            ci: z.boolean().optional().describe('When true, add CI preflight warnings such as missing variables and mutating steps not allowed by policy.'),
+            platform: z.enum(['android', 'ios', 'cross-platform']).optional().describe('Authoring target for platform-aware warnings.'),
+            ci: z.boolean().optional().describe('Add CI preflight warnings (missing variables, mutating steps policy forbids).'),
         },
-    }, async ({ sessionId, flow, flowYaml, platform, ci }) => {
-        const root = sessionId ? sessions.get(sessionId)?.root : undefined;
+    }, async ({ sessionId, projectRoot, flow, flowYaml, platform, ci }) => {
+        const root = await flowRoot(server, sessionId ? sessions.get(sessionId)?.root : undefined, projectRoot);
         const src = loadFlowSource(root, flow, flowYaml);
         if (src.error)
-            return qaError({ what: src.error, changedState: false, retrySafe: true, nextSteps: ['Pass an existing flow name/path or inline flowYaml.'] });
+            return flowSourceError(src);
         const { flow: parsed, errors } = parseFlow(src.yamlText);
         if (errors.length || !parsed) {
-            return qaError({ what: `Flow is invalid (${errors.length} error${errors.length === 1 ? '' : 's'})`, changedState: false, retrySafe: true, nextSteps: ['Fix the listed errors and re-check.'] }, { source: src.source, errors });
+            return qaError({
+                what: `Flow is invalid (${errors.length} error${errors.length === 1 ? '' : 's'})`,
+                changedState: false,
+                retrySafe: true,
+                failureCode: 'INVALID_FLOW',
+                nextSteps: ['Fix the listed errors and re-check.'],
+            }, { source: src.source, errors });
         }
         const allSteps = [...parsed.setup, ...parsed.steps, ...parsed.teardown];
         const STRUCTURED_KINDS = new Set(['tap', 'assertVisible', 'assertNotVisible', 'scrollTo', 'waitForVisible', 'inputText']);
         const warnings = [];
         if (!parsed.appId)
-            warnings.push('No appId — a prepareTarget step will rely on the session\'s prepared appId.');
+            warnings.push("No appId, so a prepareTarget step will rely on the session's prepared appId.");
         if (allSteps.some((s) => s.kind === 'tap' && s.selector.startsWith('@')))
-            warnings.push('Uses @ref selectors — refs are run-time only; prefer text/id selectors for durable flows.');
+            warnings.push('Uses @ref selectors. Refs are run-time only; prefer text/id selectors for durable flows.');
         if (src.yamlText.includes('${'))
-            warnings.push('Uses ${VARIABLES} — provide them via qa_flow_run { variables } or the environment.');
+            warnings.push(`Uses \${VARIABLES}. Provide them via qa_flow_run { variables }, stored session inputs, or ${FLOW_ENV_PREFIX}* environment variables (other env names are never read).`);
         const flowOcrSteps = ocrSteps(parsed);
         if (flowOcrSteps.length) {
             warnings.push(`Uses OCR visual-provider steps (${flowOcrSteps.map((s) => `${s.step}:${s.kind}`).join(', ')}); qa_flow_run will require provider consent and a configured ocrCommand.`);
@@ -145,20 +240,27 @@ export function registerFlow(server, sessions) {
         const inferredPlatform = platform ?? (driverKind === 'simulator' || driverKind === 'wda' ? 'ios' : driverKind === 'direct' ? 'android' : undefined);
         const usesStructured = allSteps.some((s) => STRUCTURED_KINDS.has(s.kind));
         if (driverKind === 'simulator' && parsed.mode === 'structured') {
-            warnings.push('mode:structured on the iOS simulator backend — tap/assertVisible/inputText need a UI tree (unavailable). Use mode: visual with image/visual steps.');
+            warnings.push('mode:structured on the iOS simulator backend. tap/assertVisible/inputText need a UI tree (unavailable). Use mode: visual with image/visual steps.');
         }
         if (parsed.mode === 'visual' && usesStructured) {
-            warnings.push('mode:visual but the flow uses structured steps (tap/assertVisible/…) — those need a UI tree and will fail on a visual-only screen.');
+            warnings.push('mode:visual but the flow uses structured steps (tap/assertVisible/…). Those need a UI tree and will fail on a visual-only screen.');
         }
         for (const s of allSteps) {
-            const text = s.kind === 'tap' ? s.selector : s.kind === 'inputText' ? s.into ?? s.value : 'query' in s && typeof s.query === 'string' ? s.query : '';
+            const text = s.kind === 'tap'
+                ? s.selector
+                : s.kind === 'inputText'
+                    ? (s.into ?? s.value)
+                    : 'query' in s && typeof s.query === 'string'
+                        ? s.query
+                        : '';
             if (!text)
                 continue;
             if (inferredPlatform === 'ios' && /resource-id=|uiautomator|android\./i.test(text))
                 warnings.push(`Android-specific locator in iOS flow: "${text}". Prefer accessibilityIdentifier/name/label on iOS.`);
             if (inferredPlatform === 'android' && /class chain|predicate string|XCUIElementType|accessibility id=/i.test(text))
                 warnings.push(`iOS-specific locator in Android flow: "${text}". Prefer resource-id/content-desc/text on Android.`);
-            if (inferredPlatform === 'cross-platform' && /(resource-id=|uiautomator|android\.|accessibility id=|class chain|predicate string|XCUIElementType|xpath=|^\/\/)/i.test(text)) {
+            if (inferredPlatform === 'cross-platform' &&
+                /(resource-id=|uiautomator|android\.|accessibility id=|class chain|predicate string|XCUIElementType|xpath=|^\/\/)/i.test(text)) {
                 warnings.push(`Platform-specific or brittle locator in cross-platform flow: "${text}". Prefer shared text/testID/accessibility labels.`);
             }
         }
@@ -171,7 +273,10 @@ export function registerFlow(server, sessions) {
             for (const v of missingVars)
                 warnings.push(`CI variable: ${v.variable} is required by ${v.flow} step ${v.step} but is not set in the environment.`);
         }
-        const lintFindings = lintFlowObjectWithOptions(src.source ?? 'inline', parsed, { platform, policy: ci ? (root ? loadPolicy(root) : null) : undefined });
+        const lintFindings = lintFlowObjectWithOptions(src.source ?? 'inline', parsed, {
+            platform,
+            policy: ci ? (root ? loadPolicy(root) : null) : undefined,
+        });
         for (const f of lintFindings) {
             const prefix = f.severity === 'error' ? 'Lint error' : 'Lint warning';
             warnings.push(`${prefix} ${f.code}${f.step ? ` step ${f.step}` : ''}: ${f.message}`);
@@ -179,23 +284,57 @@ export function registerFlow(server, sessions) {
         // Image-template steps: verify the referenced files exist (best-effort, when a root is known).
         if (root) {
             for (const s of allSteps) {
-                if ((s.kind === 'tapImage' || s.kind === 'assertImage')) {
-                    const p = isAbsolute(s.template) ? s.template : join(root, s.template);
-                    if (!existsSync(p))
+                if (s.kind === 'tapImage' || s.kind === 'assertImage') {
+                    const p = withinRootOrNull(root, s.template);
+                    if (!p)
+                        warnings.push(`image template outside the project root: ${s.template}; qa_flow_run will refuse it.`);
+                    else if (!existsSync(p))
                         warnings.push(`image template not found: ${s.template} (resolve relative to the project root).`);
                 }
             }
         }
-        return qaOk({ valid: true, source: src.source, name: parsed.name, appId: parsed.appId ?? null, mode: parsed.mode, budgetProfile: parsed.budgetProfile ?? null, stepCount: parsed.steps.length, setupCount: parsed.setup.length, teardownCount: parsed.teardown.length, fixtures: parsed.fixtures, warnings, lintFindings }, `✅ flow "${parsed.name}" is valid — ${parsed.steps.length} steps (mode=${parsed.mode}${parsed.setup.length ? `, ${parsed.setup.length} setup` : ''}${parsed.teardown.length ? `, ${parsed.teardown.length} teardown` : ''})${warnings.length ? `\nwarnings:\n - ${warnings.join('\n - ')}` : ''}`);
+        return qaOk({
+            valid: true,
+            source: src.source,
+            name: parsed.name,
+            appId: parsed.appId ?? null,
+            mode: parsed.mode,
+            budgetProfile: parsed.budgetProfile ?? null,
+            stepCount: parsed.steps.length,
+            setupCount: parsed.setup.length,
+            teardownCount: parsed.teardown.length,
+            fixtures: parsed.fixtures,
+            warnings,
+            lintFindings,
+        }, `✅ flow "${parsed.name}" is valid: ${parsed.steps.length} steps (mode=${parsed.mode}${parsed.setup.length ? `, ${parsed.setup.length} setup` : ''}${parsed.teardown.length ? `, ${parsed.teardown.length} teardown` : ''})${warnings.length ? `\nwarnings:\n - ${warnings.join('\n - ')}` : ''}`);
     });
-    server.registerTool('qa_flow_plan', {
-        title: 'Plan a flow for a backend',
-        description: 'Compile a Swipium flow into a deterministic, backend-specific automation plan WITHOUT touching a device (Automation Kernel V2). For each backend it answers: can this flow run, which exact selectors/gestures/waits will it use, and what to fix if it cannot. Each step is classified native | supported_with_fallback | visual_only | unsupported, with the exact missing capability and a concrete next step named for anything blocked. Returns structured data plus a natural-language message a coding agent can repeat to the user (ready | candidate | blocked). Provide `flow` (name/path) or `flowYaml`. Without `backend`, it plans across Android DirectDriver, iOS raw simulator, iOS WDA, Appium UiAutomator2, and Appium XCUITest; with a sessionId it also reports the attached backend.',
+    server.registerTool('qa_flow_run', {
+        title: 'Run a flow (or preview its execution plan)',
+        description: 'Run a flow on the prepared app (mode:"run", default) or preview it without a device (mode:"plan"). run executes steps ' +
+            'server-side with setup/teardown, fail-fast, no auto-retry of mutating steps (consent-gated, like OCR steps); a failure ' +
+            'returns the step, screenshot, failureCode, and health. plan reports, per backend (Android, iOS simulator, iOS WDA, ' +
+            'Appium), whether each step is native / fallback / visual_only / unsupported. Pass flow (name/path) or flowYaml, plus ' +
+            'variables for ${VAR}. Steps: docs/tools.md#flow-steps.',
         inputSchema: {
-            sessionId: z.string().optional(),
-            flow: z.string().optional().describe('Flow name under .swipium/flows, or a path to a .yaml file.'),
-            flowYaml: z.string().optional().describe('Inline flow YAML (instead of a file).'),
-            backend: z.enum(['android-direct', 'ios-raw-simulator', 'ios-wda', 'appium-uiautomator2', 'appium-xcuitest']).optional().describe('Plan only for this backend. Omit to plan across all five (the pre-run "can this run on Android and iOS?" answer).'),
+            mode: z.enum(['plan', 'run']).optional(),
+            sessionId: z.string().optional().describe('Required for run; plan: resolves names + marks the attached backend.'),
+            projectRoot: z
+                .string()
+                .optional()
+                .describe('plan: absolute app root for flow names (default: session root > MCP roots > env > cwd).'),
+            flow: z.string().optional().describe('Flow name under .swipium/flows, or a .yaml path.'),
+            flowYaml: z.string().optional().describe('Inline flow YAML.'),
+            variables: z
+                .record(z.string())
+                .optional()
+                .describe('run: ${VAR} values (win over stored session inputs, then SWIPIUM_* env only); credential-like names redacted.'),
+            repeat: z.number().int().min(1).max(10).optional().describe('run: repeat N times for flake classification (default 1).'),
+            consentId: z.string().optional().describe('run: consent for mutating / OCR steps.'),
+            approve: z.boolean().optional(),
+            backend: z
+                .enum(['android-direct', 'ios-raw-simulator', 'ios-wda', 'appium-uiautomator2', 'appium-xcuitest'])
+                .optional()
+                .describe('plan: only this backend (default all five).'),
             appium: z
                 .object({
                 automationName: z.string().optional(),
@@ -203,113 +342,153 @@ export function registerFlow(server, sessions) {
                 webviewContextsAvailable: z.boolean().optional(),
             })
                 .optional()
-                .describe('Appium session hints that refine the Appium backend capability picture (driver family, WebView contexts).'),
+                .describe('plan: Appium session hints.'),
         },
-    }, async ({ sessionId, flow, flowYaml, backend, appium }) => {
-        const session = sessionId ? sessions.get(sessionId) : undefined;
-        const root = session?.root;
-        const src = loadFlowSource(root, flow, flowYaml);
-        if (src.error)
-            return qaError({ what: src.error, changedState: false, retrySafe: true, nextSteps: ['Pass an existing flow name/path or inline flowYaml.'] });
-        const { flow: parsed, errors } = parseFlow(src.yamlText);
-        if (errors.length || !parsed) {
-            return qaError({ what: `Flow is invalid (${errors.length} error${errors.length === 1 ? '' : 's'}) — run qa_flow_check`, changedState: false, retrySafe: true, nextSteps: ['Fix the listed errors and re-plan.'] }, { source: src.source, errors });
+    }, async ({ mode, sessionId, projectRoot, flow, flowYaml, variables, repeat, consentId, approve, backend, appium }) => {
+        const effectiveMode = mode ?? 'run';
+        const notes = [];
+        // ---- mode:"plan": read-only execution preview (merged twin, 1.5.0). ----
+        if (effectiveMode === 'plan') {
+            const ignored = [
+                variables !== undefined && 'variables',
+                repeat !== undefined && 'repeat',
+                consentId !== undefined && 'consentId',
+                approve !== undefined && 'approve',
+            ].filter((x) => !!x);
+            if (ignored.length)
+                notes.push(`ignored parameter(s) not applicable to mode:"plan": ${ignored.join(', ')}; re-run with mode:"run" to execute`);
+            const session = sessionId ? sessions.get(sessionId) : undefined;
+            const root = await flowRoot(server, session?.root, projectRoot);
+            const src = loadFlowSource(root, flow, flowYaml);
+            if (src.error)
+                return qaAnnotate(flowSourceError(src), notes);
+            const { flow: parsed, errors } = parseFlow(src.yamlText);
+            if (errors.length || !parsed) {
+                return qaAnnotate(qaError({
+                    what: `Flow is invalid (${errors.length} error${errors.length === 1 ? '' : 's'}), run qa_flow_check`,
+                    changedState: false,
+                    retrySafe: true,
+                    failureCode: 'INVALID_FLOW',
+                    nextSteps: ['Fix the listed errors and re-plan.'],
+                }, { source: src.source, errors }), notes);
+            }
+            const appiumHints = appium ? { ...appium } : undefined;
+            const attachedBackend = session?.driver?.kind ? backendForDriverKind(session.driver.kind, appiumHints) : undefined;
+            // Which backends to plan for: an explicit one, else all concrete backends (so the answer covers
+            // Android + iOS even with no device attached: the pre-run "can this run?" product question).
+            const targets = backend ? [backend] : [...ALL_BACKENDS];
+            if (attachedBackend && attachedBackend !== 'unknown' && !targets.includes(attachedBackend))
+                targets.unshift(attachedBackend);
+            const plans = targets.map((b) => {
+                const caps = backendCapabilities(b, appiumHints);
+                const plan = compileAutomationPlan(parsed, caps);
+                const readiness = buildReadiness(plan);
+                return {
+                    backend: b,
+                    attached: b === attachedBackend,
+                    status: readiness.status,
+                    headline: readiness.headline,
+                    executable: plan.executable,
+                    supportedSteps: readiness.supportedSteps,
+                    unsupportedSteps: readiness.unsupportedSteps,
+                    fallbackUsed: readiness.fallbackUsed,
+                    agentMessage: readiness.agentMessage,
+                    developerMessage: readiness.developerMessage,
+                    blockers: readiness.blockers,
+                    warnings: readiness.warnings,
+                    steps: plan.steps.map((s) => ({
+                        index: s.index,
+                        kind: s.action.kind,
+                        target: s.action.note,
+                        support: s.support,
+                        reason: s.reason,
+                        requiredCapability: s.requiredCapability,
+                    })),
+                };
+            });
+            const summaryLines = plans.map((p) => {
+                const head = `${STATUS_ICON[p.status] ?? '•'} ${p.backend}${p.attached ? ' (attached)' : ''}: ${p.status}, ${p.supportedSteps} supported, ${p.unsupportedSteps} unsupported`;
+                return `${head}\n   ${p.agentMessage}`;
+            });
+            const summary = `flow "${parsed.name}": automation plan across ${plans.length} backend(s) (mode:"plan", read-only, nothing executed):\n${summaryLines.join('\n')}`;
+            return qaAnnotate(qaOk({ flow: parsed.name, appId: parsed.appId ?? null, mode: parsed.mode, source: src.source, plans }, summary), notes);
         }
-        const appiumHints = appium ? { ...appium } : undefined;
-        const attachedBackend = session?.driver?.kind ? backendForDriverKind(session.driver.kind, appiumHints) : undefined;
-        // Which backends to plan for: an explicit one, else all concrete backends (so the answer covers
-        // Android + iOS even with no device attached — the pre-run "can this run?" product question).
-        const targets = backend ? [backend] : [...ALL_BACKENDS];
-        if (attachedBackend && attachedBackend !== 'unknown' && !targets.includes(attachedBackend))
-            targets.unshift(attachedBackend);
-        const plans = targets.map((b) => {
-            const caps = backendCapabilities(b, appiumHints);
-            const plan = compileAutomationPlan(parsed, caps);
-            const readiness = buildReadiness(plan);
-            return {
-                backend: b,
-                attached: b === attachedBackend,
-                status: readiness.status,
-                headline: readiness.headline,
-                executable: plan.executable,
-                supportedSteps: readiness.supportedSteps,
-                unsupportedSteps: readiness.unsupportedSteps,
-                fallbackUsed: readiness.fallbackUsed,
-                agentMessage: readiness.agentMessage,
-                developerMessage: readiness.developerMessage,
-                blockers: readiness.blockers,
-                warnings: readiness.warnings,
-                steps: plan.steps.map((s) => ({ index: s.index, kind: s.action.kind, target: s.action.note, support: s.support, reason: s.reason, requiredCapability: s.requiredCapability })),
-            };
-        });
-        const summaryLines = plans.map((p) => {
-            const head = `${STATUS_ICON[p.status] ?? '•'} ${p.backend}${p.attached ? ' (attached)' : ''}: ${p.status} — ${p.supportedSteps} supported, ${p.unsupportedSteps} unsupported`;
-            return `${head}\n   ${p.agentMessage}`;
-        });
-        const summary = `flow "${parsed.name}" — automation plan across ${plans.length} backend(s):\n${summaryLines.join('\n')}`;
-        return qaOk({ flow: parsed.name, appId: parsed.appId ?? null, mode: parsed.mode, source: src.source, plans }, summary);
-    });
-    server.registerTool('qa_flow_run', {
-        title: 'Run a flow',
-        description: 'Run a Swipium flow against the prepared app and report the result. Drives steps server-side: tap/tapAt/tapImage, inputText (incl. { into, text } to focus a named field), assertVisible/assertNotVisible/assertImage/assertVisual/assertDiff, swipe (device-relative { direction, area, distance }), scrollTo, press, openUrl, wait/waitForIdle/waitForVisible, clearOverlay, networkOffline/Online, restartApp, seed, note, screenshot — with optional setup/teardown (teardown always runs) and mode structured|visual|auto. Fail-fast, NO auto-retry of mutating steps; on failure returns the exact failing step + screenshot + typed failureCode + health. Provide `flow` (name/path) or `flowYaml`, plus `variables` for any ${VAR}.',
-        inputSchema: {
-            sessionId: z.string(),
-            flow: z.string().optional(),
-            flowYaml: z.string().optional(),
-            variables: z.record(z.string()).optional().describe('Values for ${VAR} placeholders (merged over process.env). Credential-looking names are auto-redacted.'),
-            repeat: z.number().int().min(1).max(10).optional().describe('Run the flow N times for flake detection (default 1). Reports pass-rate + a deterministic-pass | deterministic-fail | flaky classification.'),
-            consentId: z.string().optional().describe('Consent token returned when the flow contains mutating steps or external visual-provider steps such as OCR.'),
-            approve: z.boolean().optional().describe('Set true with consentId to execute after reviewing the exact flow hash, mutation list, and external provider command if present.'),
-        },
-    }, async ({ sessionId, flow, flowYaml, variables, repeat, consentId, approve }) => {
-        const session = sessions.get(sessionId);
-        const { driver } = session ? await getDriver(session) : { driver: undefined };
+        // ---- mode:"run": execute on the prepared device. ----
+        const runIgnored = [
+            backend !== undefined && 'backend',
+            appium !== undefined && 'appium',
+            projectRoot !== undefined && 'projectRoot',
+        ].filter((x) => !!x);
+        if (runIgnored.length)
+            notes.push(`ignored parameter(s) not applicable to mode:"run": ${runIgnored.join(', ')}; they refine the mode:"plan" preview`);
+        const session = sessionId ? sessions.get(sessionId) : undefined;
+        if (sessionId && !session)
+            return qaAnnotate(unknownSessionError(sessionId), notes);
+        const { driver, blocked } = session ? await getDriver(session) : { driver: undefined, blocked: undefined };
         if (!session || !driver) {
-            return qaError({ what: 'No device attached to this session', changedState: false, retrySafe: true, nextSteps: ['Call qa_prepare_target / qa_ios boot first, then qa_flow_run.'] });
+            const refused = blockedDeviceResult(blocked);
+            if (refused)
+                return qaAnnotate(refused, notes);
+            return qaAnnotate(qaError({
+                what: sessionId
+                    ? 'No device attached to this session'
+                    : 'qa_flow_run mode:"run" needs a sessionId with a prepared device (mode:"plan" works without one)',
+                changedState: false,
+                retrySafe: true,
+                nextSteps: ['Call qa_prepare_target / qa_ios boot first, then qa_flow_run.'],
+            }), notes);
         }
         const src = loadFlowSource(session.root, flow, flowYaml);
         if (src.error)
-            return qaError({ what: src.error, changedState: false, retrySafe: true, nextSteps: ['Pass an existing flow name/path or inline flowYaml.'] });
+            return qaAnnotate(flowSourceError(src), notes);
         const { flow: parsed, errors } = parseFlow(src.yamlText);
         if (errors.length || !parsed) {
-            return qaError({ what: `Flow is invalid — run qa_flow_check first`, changedState: false, retrySafe: true, nextSteps: ['Fix the flow and re-run.'] }, { errors });
+            return qaAnnotate(qaError({
+                what: `Flow is invalid. Run qa_flow_check first`,
+                changedState: false,
+                retrySafe: true,
+                failureCode: 'INVALID_FLOW',
+                nextSteps: ['Fix the flow and re-run.'],
+            }, { errors }), notes);
         }
-        // Backend/mode gate (NEXT-PLAN: catch unsupported combos before running). A structured-mode
+        // Backend/mode gate (catch unsupported combos before running). A structured-mode
         // flow needs a UI tree, which the iOS simulator and a visual-fallback session don't have.
         if (parsed.mode === 'structured' && (driver.kind === 'simulator' || session.mode === 'visual-fallback')) {
-            return qaError({
+            return qaAnnotate(qaError({
                 what: `This flow is mode:structured but ${driver.kind === 'simulator' ? 'the iOS simulator backend has no UI tree' : 'the session is in visual-fallback'}`,
                 changedState: false,
                 retrySafe: false,
                 failureCode: 'BACKEND_UNSUPPORTED',
-                nextSteps: ['Author the flow with `mode: visual` (or auto) and use image/visual steps (tapImage/assertImage/assertDiff/assertVisual).'],
-            });
+                nextSteps: [
+                    'Author the flow with `mode: visual` (or auto) and use image/visual steps (tapImage/assertImage/assertDiff/assertVisual).',
+                ],
+            }), notes);
         }
         const budget = sessions.budgetStop(session);
         if (budget)
-            return qaStop(budget, { counters: session.counters });
+            return qaAnnotate(qaStop(budget, { counters: session.counters }), notes);
         const runs = repeat ?? 1;
         const externalProviderSteps = ocrSteps(parsed);
         const externalProviders = [];
         if (externalProviderSteps.length) {
             if (session.sensitive) {
-                return qaError({
+                return qaAnnotate(qaError({
                     what: 'Sensitive mode refuses OCR flow steps because they would pass screenshots to an external provider',
                     changedState: false,
                     retrySafe: false,
                     failureCode: 'UNSAFE_ACTION_REFUSED',
                     nextSteps: ['Disable sensitive mode only for a safe, masked QA screen, or remove tapOcrText/assertOcrText from the flow.'],
-                });
+                }), notes);
             }
             const command = configuredOcrCommand(session.root);
             if (!command) {
-                return qaError({
+                return qaAnnotate(qaError({
                     what: 'Flow uses OCR text steps, but OCR is not configured',
                     changedState: false,
                     retrySafe: true,
                     failureCode: 'VISUAL_ONLY_SCREEN',
                     nextSteps: ['Configure ocrCommand in .swipium/config.json or remove tapOcrText/assertOcrText from the flow.'],
-                });
+                }), notes);
             }
             try {
                 const preview = resolveVisualProvider(command, { image: '<screenshot>' }, 30000);
@@ -325,18 +504,31 @@ export function registerFlow(server, sessions) {
                 });
             }
             catch (e) {
-                return qaError({
+                return qaAnnotate(qaError({
                     what: e instanceof GitScopeForbiddenError ? e.message : `Invalid OCR command template: ${String(e)}`,
                     changedState: false,
                     retrySafe: !(e instanceof GitScopeForbiddenError),
                     failureCode: e instanceof GitScopeForbiddenError ? 'GIT_SCOPE_FORBIDDEN' : 'INVALID_FLOW',
-                    nextSteps: e instanceof GitScopeForbiddenError ? ['Run Git yourself outside Swipium; configure ocrCommand to use a non-Git executable.'] : ['Use an argv array in .swipium/config.json, e.g. ["node","ocr.js","{image}"].'],
-                });
+                    nextSteps: e instanceof GitScopeForbiddenError
+                        ? ['Run Git yourself outside Swipium; configure ocrCommand to use a non-Git executable.']
+                        : ['Use an argv array in .swipium/config.json, e.g. ["node","ocr.js","{image}"].'],
+                }), notes);
             }
         }
-        const affects = flowMutationAffects(parsed, session, src.source, runs, externalProviders);
+        // Stored session inputs (qa_agent needs_input / first-run credentials) fill ${VAR}s so a
+        // generated flow replays without the agent re-sending raw secrets; explicit args win.
+        const sessionInputs = sessions.inputVariables(session);
+        const runVariables = { ...sessionInputs, ...(variables ?? {}) };
+        const usedSessionInputs = Object.keys(sessionInputs).filter((k) => variables?.[k] == null);
+        if (usedSessionInputs.length)
+            notes.push(`using stored session input(s): ${usedSessionInputs.join(', ')} (values not shown)`);
+        const affects = flowMutationAffects(parsed, session, src.source, runs, externalProviders, runVariables);
         const mutationRisk = flowMutationRisk(affects);
-        let mutationConsent = { required: false, approved: true, payloadHash: affects.flowHash };
+        let mutationConsent = {
+            required: false,
+            approved: true,
+            payloadHash: affects.flowHash,
+        };
         const privileged = affects.mutations.length > 0 || affects.externalProviders.length > 0;
         if (privileged) {
             const payloadHash = fullHash(affects);
@@ -353,15 +545,21 @@ export function registerFlow(server, sessions) {
                 const externalCommand = affects.externalProviders.length
                     ? `; external provider: ${displayArgv(affects.externalProviders[0].argv ?? [])}`
                     : '';
-                return requireConsent({
+                return qaAnnotate(requireConsent({
                     action: 'flow_mutation_run',
                     risk: mutationRisk,
-                    exactCommand: `qa_flow_run ${parsed.name} (${[...affects.mutations.map((m) => `${m.step}:${m.kind}`), ...externalProviderSteps.map((s) => `${s.step}:${s.kind}`)].join(', ')})${externalCommand}`,
+                    exactCommand: `qa_flow_run ${parsed.name} (${[...affects.mutations.map((m) => `${m.step}:${m.kind}`), ...externalProviderSteps.map((s) => `${s.step}:${s.kind}`)].join(', ')})${externalCommand}${mutationCommandLines(affects).length ? `\n${mutationCommandLines(affects).join('\n')}` : ''}`,
                     affects,
-                    explain: affects.externalProviders.length
+                    explain: (affects.externalProviders.length
                         ? `Run flow "${parsed.name}" with external visual provider steps? OCR steps pass ${runs * externalProviderSteps.length} screenshot(s) to the configured provider and any mutating steps can change app/device/test state.`
-                        : `Run mutating flow "${parsed.name}"? Mutating steps can change app/device/test state and will be recorded in the mutation ledger.`,
-                });
+                        : `Run mutating flow "${parsed.name}"? Mutating steps can change app/device/test state and will be recorded in the mutation ledger.`) +
+                        (affects.mutations.some((m) => m.kind === 'seed')
+                            ? " Seed steps run the exact command/URL shown, taken from the repo's fixture declarations. These are repo-supplied and UNREVIEWED by Swipium; approve only if you trust them."
+                            : '') +
+                        (affects.mutations.some((m) => m.kind === 'openUrl')
+                            ? ' openUrl steps interpolate variables into a URL that leaves the test harness, so check the destination.'
+                            : ''),
+                }), notes);
             }
             mutationConsent = { required: true, consentId, approved: true, payloadHash };
             sessions.recordMutation(session, {
@@ -380,18 +578,35 @@ export function registerFlow(server, sessions) {
                 const b = sessions.budgetStop(session);
                 if (b)
                     break;
-                results.push(await runFlow(sessions, session, driver, parsed, { variables, mutationConsent }));
+                results.push(await runFlow(sessions, session, driver, parsed, { variables: runVariables, mutationConsent }));
             }
             const flake = classifyFlakeResults(results, runs);
-            return qaOk({ flow: parsed.name, runs: results.length, passes: flake.passed, fails: flake.failed, passRate: flake.passRate, classification: flake.classification, triage: flake.triage, results: results.map((r) => ({ passed: r.passed, failedAtStep: r.failedAtStep, reason: r.reason, failureCode: r.failureCode })) }, `flow "${parsed.name}" × ${results.length}: ${flake.passed} passed, ${flake.failed} failed → ${flake.classification === 'flaky' ? '⚠ FLAKY' : flake.classification === 'deterministic-pass' ? '✅ deterministic-pass' : '❌ deterministic-fail'} (${flake.passRate}% pass-rate); triage=${flake.triage.likelyCause}`);
+            return qaAnnotate(qaOk({
+                flow: parsed.name,
+                runs: results.length,
+                passes: flake.passed,
+                fails: flake.failed,
+                passRate: flake.passRate,
+                classification: flake.classification,
+                triage: flake.triage,
+                results: results.map((r) => ({
+                    passed: r.passed,
+                    failedAtStep: r.failedAtStep,
+                    reason: r.reason,
+                    failureCode: r.failureCode,
+                })),
+            }, `flow "${parsed.name}" × ${results.length}: ${flake.passed} passed, ${flake.failed} failed > ${flake.classification === 'flaky' ? '⚠ FLAKY' : flake.classification === 'deterministic-pass' ? '✅ deterministic-pass' : '❌ deterministic-fail'} (${flake.passRate}% pass-rate); triage=${flake.triage.likelyCause}`), notes);
         }
-        const result = await runFlow(sessions, session, driver, parsed, { variables, mutationConsent });
+        const result = await runFlow(sessions, session, driver, parsed, { variables: runVariables, mutationConsent });
         const head = `flow "${result.name}" ${result.passed ? '✅ PASSED' : `❌ FAILED at step ${result.failedAtStep} (${result.reason})`} ` +
-            `— ${result.steps.filter((s) => s.ok).length}/${result.steps.length} steps in ${result.durationSec}s` +
+            `: ${result.steps.filter((s) => s.ok).length}/${result.steps.length} steps in ${Math.round(result.durationMs / 100) / 10}s` +
             (result.appHealth ? `\nhealth: native=${result.nativeHealth} app=${result.appHealth}` : '');
-        const stepLines = result.steps.map((s) => `${s.ok ? '✓' : '✗'} ${s.index}. ${s.summary}${s.detail ? ` — ${s.detail}` : ''}${s.screenshotUri ? `\n   evidence: ${s.screenshotUri}` : ''}`).join('\n');
-        // A failed flow is a structured result, not a protocol error — the agent should record it.
-        return qaOk({ ...result }, `${head}\n${stepLines}`);
+        const stepLines = result.steps
+            .map((s) => `${s.ok ? '✓' : '✗'} ${s.index}. ${s.summary}${s.detail ? `: ${s.detail}` : ''}${s.screenshotUri ? `\n   evidence: ${s.screenshotUri}` : ''}`)
+            .join('\n');
+        // A failed flow is a structured result, not a protocol error. The agent should record it.
+        const nextSteps = result.passed ? undefined : failedFlowNextSteps(parsed.name, flow, result.failedAtStep, result.failureCode);
+        return qaAnnotate(qaOk({ ...result, ...(nextSteps ? { nextSteps } : {}) }, `${head}\n${stepLines}${nextSteps ? `\nnext:\n - ${nextSteps.join('\n - ')}` : ''}`), notes);
     });
 }
 //# sourceMappingURL=flow.js.map