swipium 1.3.0 → 1.5.0

package/dist/tools/flow.js

@@ -1,11 +1,13 @@
 // qa_flow_check + qa_flow_run (PHASE3-PLAN §3.4) — 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 { qaOk, qaError, qaStop, qaAnnotate } from '../lib/result.js';
 import { parseFlow } from '../flows/schema.js';
 import { lintFlowObjectWithOptions } from '../flows/lint.js';
 import { runFlow } from '../flows/run.js';
@@ -50,16 +52,19 @@ function loadFlowSource(root, flow, flowYaml) {
     return { error: `Flow not found. Looked for: ${candidates.join(', ') || '(no project root)'}` };
 }
 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);
@@ -92,7 +97,8 @@ function flowMutationAffects(flow, session, source, repeat, externalProviders =
 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'))
         return 'medium';
     return 'low';
 }
@@ -108,28 +114,44 @@ function ocrSteps(flow) {
 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: '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. Related: qa_flow_check is the STATIC LINT of the YAML; qa_flow_run mode:"plan" is the read-only EXECUTION PREVIEW (which backends can run it, step-by-step support); qa_flow_run mode:"run" executes.',
         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).'),
-            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('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.'),
         },
     }, async ({ sessionId, flow, flowYaml, platform, ci }) => {
         const root = sessionId ? sessions.get(sessionId)?.root : undefined;
         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 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'})`, 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,
+                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 — 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.');
         if (src.yamlText.includes('${'))
@@ -151,14 +173,21 @@ export function registerFlow(server, sessions) {
             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 +200,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 +211,65 @@ 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')) {
+                if (s.kind === 'tapImage' || s.kind === 'assertImage') {
                     const p = isAbsolute(s.template) ? s.template : join(root, s.template);
                     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 Swipium flow against the prepared app and report the result — or, with mode:"plan", preview the execution WITHOUT touching a device. mode:"run" (default) 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 flow mode structured|visual|auto. Fail-fast, NO auto-retry of mutating steps; on failure returns the exact failing step + screenshot + typed failureCode + health. mode:"plan" (read-only) compiles the flow into a deterministic backend-specific automation plan: per backend, can it run, each step classified native | supported_with_fallback | visual_only | unsupported with the missing capability, and an agent-repeatable ready | candidate | blocked message. Provide `flow` (name/path) or `flowYaml`, plus `variables` for any ${VAR}. Related: qa_flow_check is the STATIC LINT of the YAML; mode:"plan" here is the read-only execution preview.',
         inputSchema: {
-            sessionId: z.string().optional(),
+            mode: z
+                .enum(['plan', 'run'])
+                .optional()
+                .describe("run (default): execute the flow on the session's prepared device. plan: READ-ONLY execution preview — no device is touched; compiles the flow against backend capabilities (Android direct, iOS raw simulator, iOS WDA, Appium UiAutomator2/XCUITest) and reports what would run, what falls back, and what is blocked."),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('REQUIRED for mode:"run" (needs a prepared device). Optional for mode:"plan" — it resolves flow names against the session\'s project root and marks the attached backend.'),
             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).'),
+            variables: z
+                .record(z.string())
+                .optional()
+                .describe('(mode:"run" only) Values for ${VAR} placeholders (merged over process.env). Credential-looking names are auto-redacted.'),
+            repeat: z
+                .number()
+                .int()
+                .min(1)
+                .max(10)
+                .optional()
+                .describe('(mode:"run" only) 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('(mode:"run" only) Consent token returned when the flow contains mutating steps or external visual-provider steps such as OCR.'),
+            approve: z
+                .boolean()
+                .optional()
+                .describe('(mode:"run" only) Set true with consentId to execute after reviewing the exact flow hash, mutation list, and external provider command if present.'),
+            backend: z
+                .enum(['android-direct', 'ios-raw-simulator', 'ios-wda', 'appium-uiautomator2', 'appium-xcuitest'])
+                .optional()
+                .describe('(mode:"plan" only) Plan only for this backend. Omit to plan across all five (the pre-run "can this run on Android and iOS?" answer).'),
             appium: z
                 .object({
                 automationName: z.string().optional(),
@@ -203,113 +277,152 @@ 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('(mode:"plan" only) Appium session hints that refine the Appium backend capability picture (driver family, WebView contexts).'),
         },
-    }, 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, 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 = session?.root;
+            const src = loadFlowSource(root, flow, flowYaml);
+            if (src.error)
+                return qaAnnotate(qaError({
+                    what: src.error,
+                    changedState: false,
+                    retrySafe: true,
+                    nextSteps: ['Pass an existing flow name/path or inline flowYaml.'],
+                }), 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,
+                    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);
+        // ---- mode:"run" — execute on the prepared device. ----
+        const runIgnored = [backend !== undefined && 'backend', appium !== undefined && 'appium'].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;
         const { driver } = session ? await getDriver(session) : { driver: 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.'] });
+            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(qaError({
+                what: src.error,
+                changedState: false,
+                retrySafe: true,
+                nextSteps: ['Pass an existing flow name/path or inline flowYaml.'],
+            }), 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,
+                nextSteps: ['Fix the flow and re-run.'],
+            }, { errors }), notes);
         }
         // Backend/mode gate (NEXT-PLAN: 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 +438,24 @@ 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);
         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,7 +472,7 @@ 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}`,
@@ -361,7 +480,7 @@ export function registerFlow(server, sessions) {
                     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.`,
-                });
+                }), notes);
             }
             mutationConsent = { required: true, consentId, approved: true, payloadHash };
             sessions.recordMutation(session, {
@@ -383,15 +502,31 @@ export function registerFlow(server, sessions) {
                 results.push(await runFlow(sessions, session, driver, parsed, { variables, 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 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');
+        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}`);
+        return qaAnnotate(qaOk({ ...result }, `${head}\n${stepLines}`), notes);
     });
 }
 //# sourceMappingURL=flow.js.map