flowstride 1.0.21 → 1.0.22

package/NATIVE_BROWSER.md

@@ -1,5 +1,7 @@
 # Native browser workflows
 
+For API/UI composition, email OTP, iframe examples, audio-to-text, tables, variables and manual testing, start with [Core Flowstride workflows](NATIVE_WORKFLOWS.md).
+
 OS and Cloud support these commands directly in `.flow` files. Existing commands, plugins and saved sessions continue to work. Use `flow.<area>.<action>` followed by a JSON object. Unknown actions and options fail explicitly.
 
 Keep both engine installations current when using these features. If an installed Cloud engine lacks the required capability protocol, the public runner warns and uses OS fallback for the run. Existing commands can still use an older compatible Cloud engine; Cloud-only services require a compatible Cloud installation.
@@ -72,6 +74,8 @@ Chromium remains the default. Browser installation must match the installed Flow
 
 Validated settings include viewport/screen, device scale, touch/mobile emulation, locale/timezone, color/contrast/motion, JavaScript, HTTPS handling, CSP bypass, permissions/geolocation, offline mode, headers, HTTP credentials, proxy, downloads, strict selectors, storage state and project-local client certificate paths. Use `browserOptions` for the default profile and `options` in `flow.browser.create` for a separate profile. Secrets belong in environment variables or private local files.
 
+Set `BASE_URL` directly in a project `.env` file when you want a common application URL. String values in native `.flow` command payloads support environment templates. The JSON configuration loader does not generally expand `{{env.NAME}}` throughout arbitrary `browserOptions`; use supported native profile options for command-time credential interpolation.
+
 Runtime commands include `flow.browser.offline` with `value`, `flow.browser.permissions` with `permissions` and optional `origin`, `flow.browser.clearPermissions`, and `flow.browser.geolocation` with latitude/longitude. Recording paths are controlled by evidence settings, rather than arbitrary browser path options. JavaScript logger callbacks are not JSON DSL settings.
 
 ## Assertions that wait for a condition
@@ -339,3 +343,39 @@ For later runs, use `--shard-history path/to/timings.json` from a previous compl
 Chromium's current stealth behavior can override an explicitly requested locale. Use Firefox or WebKit for locale-sensitive checks and verify the observed language. For HAR playback in Firefox/WebKit, leave forced browser-offline mode unset and stop the real server to verify the recording; combining forced offline mode and HAR can reject navigation before fulfillment.
 
 The maintained command reference, browser compatibility guide and API-to-UI examples are available in the [Flowstride documentation](https://docs.flowstride.io/guide/native-browser-workflows).
+
+## Assertion results and `And`
+
+Native checks `flow.assert.that`, `flow.network.expect`, `flow.download.expect`,
+`flow.stub.expect`, `flow.a11y.scan` and `flow.a11y.match` can appear under
+`Then` or `And`. State-changing browser, route and clock commands belong under
+`Given` or `When`.
+
+```flow
+Then "The login button is ready"
+  flow.assert.that {
+    "role": "button",
+    "name": "Submit",
+    "condition": "enabled",
+    "timeout": 10000
+  };
+And "The heading is visible"
+  flow.assert.that {
+    "role": "heading",
+    "name": "Welcome",
+    "condition": "visible"
+  };
+```
+
+Terminal, CI JSON/JUnit and dashboard evidence retain individual lookup and
+condition results. A failing condition does not erase successful target checks.
+Missing prerequisites and later steps are marked not evaluated / not tested.
+Expected and observed values, timeout, profile and source location explain a
+failure. These child diagnostics do not count as extra test steps.
+
+All command failures retain the original adapter error, call log and nested
+causes, plus command, file/line and relevant target/resource. This applies to
+browser actions, APIs, plugins, sessions, games, audio and email workflows.
+Timeouts are reported as observed timeouts, without inventing a root cause when
+the application does not provide one. Secrets and terminal control characters
+are protected in diagnostics.

package/NATIVE_CI.md

@@ -85,9 +85,9 @@ flow.use session "browser";
 
 Attribute comparisons wait up to the configured timeout. Exact matching is case-sensitive; `contains` checks a substring. Missing attributes fail even when the expected value is empty.
 
-Sessions capture cookies, local storage, session storage and the current HTTP(S) storage origin. Session storage is restored immediately on the matching origin or before its first matching navigation. It is not seeded into unrelated origins. The initial seed is then removed so later application changes and reloads are preserved.
+Sessions capture cookies, local storage, session storage and the current HTTP(S) storage origin. Local storage and session storage are restored immediately on the matching origin or before its first matching navigation. It is not seeded into unrelated origins. The initial seed is then removed so later application changes and reloads are preserved.
 
-Existing cookie/local-storage snapshots remain compatible. Older snapshots with session storage but no origin use the current application origin or configured `baseUrl`; open the application first or set `baseUrl` if neither is available. Restoration merges saved keys into storage. This is a single-origin storage snapshot.
+Existing cookie/local-storage snapshots remain compatible. Older snapshots with Web Storage but no origin prefer the configured application `baseUrl` (including `BASE_URL`), then an available current HTTP(S) application page. Configure the intended base URL before restoring a legacy record. Restoration merges saved keys into storage. This is a single-origin storage snapshot.
 
 ## Interactive history and debugging
 
@@ -96,3 +96,15 @@ Each completed flow tab restores its own last captured screen. Selecting an earl
 The local cURL preview remains `[REDACTED]`. Copy uses the original captured request held in interactive debugger memory. Already-redacted historical data cannot be recovered. CI and Cloud reports retain redaction.
 
 Review artifact access and test data: credential redaction does not remove every possible application secret, and screenshots or videos can show sensitive information.
+
+## Runnable core workflow examples
+
+[Core Flowstride workflows](NATIVE_WORKFLOWS.md) covers API + UI, email OTP, iFrames, audio/transcripts, tables/cells, variables and manual testing. The [shared setup](examples/native-workflows/README.md) explains the local demo application's lifecycle and CI configuration.
+
+After `npm ci` and matching browser installation, a CI job can run a named local example with:
+
+```sh
+npx --no-install flowstride run workflow-examples/api-and-ui/flows/api-and-ui.flow --ci
+```
+
+In CI, `--no-install` makes a missing local Flowstride installation fail rather than fetching a package. Ordinary interactive commands use `npx flowstride`. Configure the local app through `webServer`, and exclude `negative/` examples and unconfigured service templates from your passing CI target.

package/NATIVE_WORKFLOWS.md

@@ -0,0 +1,44 @@
+# Core Flowstride workflows
+
+Flowstride can call an API, extract data from its response, use that data in a browser, and verify the application outcome in the same `.flow` test. It also supports table/cell targeting, browser sessions, microphone input and visual manual testing.
+
+The examples below use the normal Flowstride CLI. Their small HTTP server is a local demonstration application; it does not replace the test runner.
+
+## Choose a workflow
+
+| Workflow | What you will do | Availability |
+| --- | --- | --- |
+| [API + UI in one test](examples/native-workflows/api-and-ui/README.md) | Create a user through an API, sign in through the browser, then verify backend state | OS and Cloud; Chromium, Firefox, WebKit |
+| [API + UI + email OTP](examples/native-workflows/api-ui-otp/README.md) | Use FlowMail to retrieve a delivered code and complete application authentication | Cloud; a supported inbox and an application that sends OTP email |
+| [iFrames](examples/native-workflows/iframes/README.md) | Find a readable child-frame target, assert inside an explicit frame, and extend an action with a focused plugin | OS and Cloud; Chromium, Firefox, WebKit |
+| [Audio-to-text workflows](examples/native-workflows/audio-to-text/README.md) | Inject microphone audio, drive recording controls and check the resulting transcript | OS and Cloud; audio injection requires Chromium |
+| [Tables and cells](examples/native-workflows/tables-and-cells/README.md) | Search a table, click a specific row action, extract a cell and reuse its value on another page | OS and Cloud; Chromium, Firefox, WebKit |
+| [Variables, reuse and saved sessions](examples/native-workflows/variables-and-reuse/README.md) | Reuse generated/extracted values, understand scope, and restore saved browser state | OS and Cloud; Chromium, Firefox, WebKit |
+| [Manual testing](examples/native-workflows/manual-testing/README.md) | Load a design, execute its steps, record defects/results and reopen saved history | OS and Cloud; local Manual Workspace |
+
+Start with the [shared setup](examples/native-workflows/README.md). It installs Flowstride with `npm i flowstride`, copies the examples already included in the package, and starts a loopback-only demo application. No separate starter download is required.
+
+## OS and Cloud
+
+OS works locally without an account. To connect Cloud, run:
+
+```sh
+npx flowstride login
+```
+
+Use your Cloud developer token when prompted and accept the authenticated engine installation when offered. Cloud has free accounts; availability and usage allowances depend on the workspace feature and plan. Email OTP retrieval uses the Cloud FlowMail service. The other local examples do not need a Cloud service connection.
+
+The public CLI selects a compatible, authorized Cloud engine when available and retains OS fallback. A Cloud-only command still requires its Cloud service prerequisites.
+
+## Reading and running the examples
+
+- `flows/` contains runnable examples for the shared demo application.
+- `negative/` contains deliberate failures. Run them individually and expect a nonzero exit code.
+- `templates/` contains application-specific workflows. Configure the documented application, credentials and selectors before using them.
+- Manual designs are JSON files; a human performs their actions and records the result.
+
+Run the named file from its chapter. Running the whole example tree also discovers intentional failures and service-dependent templates.
+
+Each chapter explains its prerequisites, expected result, negative check and limitations. For browser profiles, native assertions, network mocking, downloads, traces/HAR, accessibility and component testing, use [NATIVE_BROWSER.md](NATIVE_BROWSER.md). For CI, reports and games, use [NATIVE_CI.md](NATIVE_CI.md).
+
+The maintained full reference is at [docs.flowstride.io](https://docs.flowstride.io/).

package/README.md

@@ -7,7 +7,7 @@ Flowstride OS is an open source framework for browser, API and manual testing. W
 ## Requirements
 
 - Node.js 22.12 or newer.
-- Chromium installed through Flowstride for browser tests.
+- A matching Chromium, Firefox or WebKit installation for browser tests. Chromium is the default; audio-file microphone injection requires Chromium.
 
 ## Get started
 
@@ -41,6 +41,13 @@ Then "The sign-in button is visible"
 
 Replace the URL and assertion with values from your own application.
 
+## Workflow guides
+
+- [Core workflows](./NATIVE_WORKFLOWS.md): API + UI, email OTP, iFrames, audio-to-text, tables/cells, variables and manual testing.
+- [Runnable examples and local setup](./examples/native-workflows/README.md).
+- [Native browser workflows](./NATIVE_BROWSER.md): profiles, assertions, network control, downloads, traces/HAR, accessibility and components.
+- [Native CI and games](./NATIVE_CI.md).
+
 ## Native CI
 
 ```sh

package/dist/adapters/api/undici.d.ts

@@ -9,13 +9,15 @@ export declare class ApiAdapter {
     private config;
     private globalHeaders;
     private onUnauthorized?;
+    private unauthorizedStatus?;
+    private refreshing;
     private lastStatus;
     private lastBody;
     private lastHeaders;
     private lastResponseTime;
     constructor(config: FlowstrideConfig);
     setGlobalHeader(name: string, value: string): void;
-    setUnauthorizedHandler(handler: () => Promise<void>): void;
+    setUnauthorizedHandler(handler: () => Promise<void>, status?: number): void;
     getState(): ApiState;
     checkpointState(): {
         globalHeaders: Record<string, string>;

package/dist/adapters/api/undici.js

@@ -6,6 +6,8 @@ class ApiAdapter {
     config;
     globalHeaders = {};
     onUnauthorized;
+    unauthorizedStatus;
+    refreshing = false;
     lastStatus = null;
     lastBody = null;
     lastHeaders = null;
@@ -16,8 +18,12 @@ class ApiAdapter {
     setGlobalHeader(name, value) {
         this.globalHeaders[name] = value;
     }
-    setUnauthorizedHandler(handler) {
+    setUnauthorizedHandler(handler, status) {
+        if (status !== undefined && status !== 401 && status !== 403) {
+            throw new Error('Authentication refresh status must be 401 or 403.');
+        }
         this.onUnauthorized = handler;
+        this.unauthorizedStatus = status;
     }
     getState() {
         if (this.lastStatus === null) {
@@ -115,8 +121,16 @@ class ApiAdapter {
             };
         };
         let res = await makeRequest();
-        if ((res.status === 401 || res.status === 403) && this.onUnauthorized) {
-            await this.onUnauthorized();
+        if ((res.status === 401 || res.status === 403) && this.onUnauthorized &&
+            !this.refreshing && (this.unauthorizedStatus === undefined || res.status === this.unauthorizedStatus)) {
+            // A refresh can use this adapter too. Never recursively refresh its own rejection.
+            this.refreshing = true;
+            try {
+                await this.onUnauthorized();
+            }
+            finally {
+                this.refreshing = false;
+            }
             Object.assign(requestHeaders, this.globalHeaders);
             res = await makeRequest();
         }

package/dist/adapters/web/playwright.js

@@ -133,7 +133,8 @@ class WebAdapter {
         const profile = this.profiles.get(key);
         if (!profile)
             return;
-        await this.clearSessionStorageRestore(profile.page);
+        for (const page of profile.context.pages())
+            await this.clearSessionStorageRestore(page);
         if (profile.tracing)
             await this.endTrace(key);
         const video = profile.page.video();
@@ -208,6 +209,7 @@ class WebAdapter {
     page = null;
     discoveredPages = [];
     dialogHandler = null;
+    // One-shot initializers for both Web Storage types, owned by their exact page.
     sessionStorageRestores = new Map();
     get pendingSessionStorageRestore() { return this.sessionStorageRestores.values().next().value || null; }
     async clearSessionStorageRestore(target) {
@@ -216,6 +218,7 @@ class WebAdapter {
                 continue;
             this.sessionStorageRestores.delete(page);
             pending.page.off('framenavigated', pending.onNavigation);
+            pending.page.off('close', pending.onClose);
             try {
                 await pending.script.dispose();
             }
@@ -404,10 +407,11 @@ class WebAdapter {
                 return undefined;
             }
         };
+        const hasLocalStorage = !!localStorage && Object.keys(localStorage).length > 0;
         const hasSessionStorage = !!sessionStorage && Object.keys(sessionStorage).length > 0;
         const origin = storageOrigin !== undefined ? originOf(storageOrigin)
-            : originOf(page.url()) || originOf(this.config.baseUrl);
-        if (hasSessionStorage && !origin) {
+            : originOf(this.config.baseUrl) || originOf(page.url());
+        if ((hasLocalStorage || hasSessionStorage) && !origin) {
             throw new Error('Session storage restoration requires a saved HTTP(S) origin, an open application page, or baseUrl.');
         }
         if (cookies && cookies.length > 0) {
@@ -440,46 +444,36 @@ class WebAdapter {
             }
             await this.context.addCookies(formattedCookies);
         }
-        if (localStorage && Object.keys(localStorage).length > 0) {
-            await this.page.addInitScript((data) => {
-                for (const [k, v] of Object.entries(data)) {
-                    window.localStorage.setItem(k, v);
-                }
-            }, localStorage);
-            if (this.page.url() !== "about:blank") {
-                await this.page.evaluate((data) => {
-                    try {
-                        for (const [k, v] of Object.entries(data))
-                            window.localStorage.setItem(k, v);
-                    }
-                    catch (e) { }
-                }, localStorage);
-            }
-        }
-        if (hasSessionStorage) {
+        if (hasLocalStorage || hasSessionStorage) {
             const restore = (data) => {
+                // A matching iframe inside another site must never receive saved secrets.
                 if (window !== window.top || window.location.origin !== data.origin)
                     return;
-                for (const [key, value] of Object.entries(data.values))
+                for (const [key, value] of Object.entries(data.local))
+                    window.localStorage.setItem(key, value);
+                for (const [key, value] of Object.entries(data.session))
                     window.sessionStorage.setItem(key, value);
             };
-            const data = { origin: origin, values: sessionStorage };
+            const data = { origin: origin, local: localStorage || {}, session: sessionStorage || {} };
             if (originOf(page.url()) === origin) {
+                // Already on the saved origin: restore now without a persistent initializer.
                 await page.evaluate(restore, data);
             }
             else {
-                // Seed before application scripts run; remove the seed after the first
-                // matching document so reloads preserve later application changes.
+                // Seed before application scripts run; remove after the first matching
+                // main document so later reloads preserve application changes and logouts.
                 const script = await page.addInitScript(restore, data);
                 const onNavigation = (frame) => {
                     if (frame !== page.mainFrame() || originOf(frame.url()) !== origin)
                         return;
                     void this.clearSessionStorageRestore(page).catch(() => {
-                        console.warn('[Session]: Could not remove the completed session storage initializer.');
+                        console.warn('[Session]: Could not remove the completed storage initializer.');
                     });
                 };
-                this.sessionStorageRestores.set(page, { page, script, onNavigation });
+                const onClose = () => { void this.clearSessionStorageRestore(page).catch(() => { }); };
+                this.sessionStorageRestores.set(page, { page, script, onNavigation, onClose });
                 page.on('framenavigated', onNavigation);
+                page.on('close', onClose);
             }
         }
     }
@@ -678,53 +672,9 @@ class WebAdapter {
         const targetLoc = await this.checkAmbiguity(loc, selector);
         await targetLoc.waitFor({ state: "visible" });
         await targetLoc.scrollIntoViewIfNeeded();
-        await targetLoc.focus({ timeout: 3000 }).catch(() => { });
-        await targetLoc
-            .evaluate((node) => {
-            if (typeof node.focus === "function")
-                node.focus();
-        })
-            .catch(() => { });
-        let box = null;
-        try {
-            box = await targetLoc.boundingBox({ timeout: 3000 });
-        }
-        catch (e) { }
-        if (box) {
-            const centerX = box.x + box.width / 2;
-            const centerY = box.y + box.height / 2;
-            await this.page.mouse.move(centerX, centerY, { steps: 5 });
-        }
-        await targetLoc.hover({ force: true, timeout: 3000 }).catch(() => { });
-        await targetLoc
-            .evaluate((node) => {
-            const rect = node.getBoundingClientRect();
-            const x = rect.left + rect.width / 2;
-            const y = rect.top + rect.height / 2;
-            const events = [
-                "pointerover",
-                "pointerenter",
-                "mouseover",
-                "mouseenter",
-                "mousemove",
-            ];
-            events.forEach((type) => {
-                node.dispatchEvent(new MouseEvent(type, {
-                    view: window,
-                    bubbles: true,
-                    cancelable: true,
-                    clientX: x,
-                    clientY: y,
-                    screenX: x,
-                    screenY: y,
-                }));
-            });
-        })
-            .catch(() => { });
-        await targetLoc
-            .click({ delay: 50, force: true, timeout: 3000 })
-            .catch(() => { });
-        await this.page.waitForTimeout(600);
+        // A real pointer hover preserves browser actionability checks and must not
+        // focus, click, or synthesize duplicate application events.
+        await targetLoc.hover();
     }
     async type(selector, value, elementType) {
         const loc = await this.getLocator(selector, elementType, false, false);

package/dist/ci/runtime.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runNativeCI = runNativeCI;
+const assertion_result_1 = require("../reporting/assertion_result");
 const distribution_1 = require("./distribution");
 const node_crypto_1 = require("node:crypto");
 const projectPaths_1 = require("../utils/projectPaths");
@@ -210,7 +211,7 @@ async function runNativeCI(worker, orchestrator, target, config, engine) {
     config.artifactsDir = artifactRoot;
     node_fs_1.default.writeFileSync(node_path_1.default.join(artifactRoot, 'timings.json'), JSON.stringify(timings, null, 2));
     node_fs_1.default.writeFileSync(node_path_1.default.join(artifactRoot, 'summary.json'), JSON.stringify(result, null, 2));
-    const cases = results.map(step => `<testcase classname="${xml(step.fileName)}" name="${xml(step.description || step.id)}">${step.status === 'failed' ? `<failure message="${xml(step.error || 'Test step failed')}"/>` : ['skipped', 'not_tested'].includes(step.status) ? '<skipped/>' : ''}</testcase>`);
+    const cases = results.map(step => `<testcase classname="${xml(step.fileName)}" name="${xml(step.description || step.id)}">${step.status === 'failed' ? `<failure message="${xml(step.error || 'Test step failed')}"/>` : ['skipped', 'not_tested'].includes(step.status) ? '<skipped/>' : ''}${step.assertion ? `<system-out>${xml((0, assertion_result_1.assertionText)(step.assertion))}</system-out>` : ''}</testcase>`);
     for (const error of errors)
         cases.push(`<testcase name="execution"><error message="${xml(error)}"/></testcase>`);
     if (incomplete)
@@ -218,5 +219,12 @@ async function runNativeCI(worker, orchestrator, target, config, engine) {
     node_fs_1.default.writeFileSync(node_path_1.default.join(artifactRoot, 'junit.xml'), `<?xml version="1.0"?><testsuite name="Flowstride" tests="${cases.length}" failures="${metrics.failed + (incomplete ? 1 : 0)}" errors="${errors.length}" skipped="${metrics.skipped}">${cases.join('')}</testsuite>`);
     if (process.env.GITHUB_STEP_SUMMARY)
         node_fs_1.default.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `\n### Flowstride · ${config.device}\nResult: **${result.status}** (${engine})\n\nPassed: ${metrics.passed}; failed: ${metrics.failed}; skipped: ${metrics.skipped}; incomplete: ${metrics.incomplete}.\n`);
+    if (process.env.GITHUB_STEP_SUMMARY) {
+        const failures = results.filter(step => step.status === 'failed').map(step => `<details><summary>${xml(step.commandLabel || step.command || 'Step')} · ${xml(step.fileName)}</summary><pre>${xml(step.error || (step.assertion ? (0, assertion_result_1.assertionText)(step.assertion) : 'Failed without an adapter diagnostic.'))}</pre></details>`);
+        for (const error of errors)
+            failures.push(`<pre>${xml(error)}</pre>`);
+        if (failures.length)
+            node_fs_1.default.appendFileSync(process.env.GITHUB_STEP_SUMMARY, '\n' + failures.join('\n') + '\n');
+    }
     return result;
 }

package/dist/cli/commands/run.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runAction = runAction;
+const runtime_failure_1 = require("../../reporting/runtime_failure");
 const compatibility_1 = require("../../native/compatibility");
 const projectPaths_1 = require("../../utils/projectPaths");
 const config_1 = require("../../ci/config");
@@ -124,12 +125,14 @@ async function runAction(targetPath, options) {
                 throw new Error('Installed Pro engine does not support native CI protocol 1; install the matching Pro candidate.');
             if ((0, compatibility_1.needsNativeBrowserProtocol)(resolvedPath, config) && (proWorkerModule.FlowWorker.nativeBrowserProtocol !== 2 || proOrchModule.FlowOrchestrator.nativeBrowserProtocol !== 2))
                 throw new Error('Installed Cloud engine does not support these native browser capabilities. Install the matching Cloud archive; this run will use OS fallback.');
+            if ((0, compatibility_1.needsNativeBrowserProtocol)(resolvedPath, config) && (proWorkerModule.FlowWorker.nativeAssertionProtocol !== 1 || proOrchModule.FlowOrchestrator.nativeAssertionProtocol !== 1))
+                throw new Error('Installed Cloud engine predates structured assertion reporting; this run will use OS fallback. Install the matching Cloud archive to update.');
             ActiveFlowWorker = proWorkerModule.FlowWorker;
             ActiveFlowOrchestrator = proOrchModule.FlowOrchestrator;
             engineMode = "Enterprise (Pro)";
         }
         catch (err) {
-            console.warn(`\n[Warning]: Found @flowstride/pro but failed to boot it. Falling back to Open Source engine. (${err.message})`);
+            console.warn(`\n[Warning]: Found @flowstride/pro but failed to boot it. Falling back to Open Source engine. (${(0, runtime_failure_1.runtimeFailure)("run.setup", { path: resolvedPath }, err, { file: resolvedPath })})`);
         }
     }
     console.log(`\n[Engine]: Booting Flowstride in ${engineMode} mode...`);
@@ -140,9 +143,16 @@ async function runAction(targetPath, options) {
         console.log(`[Flowstride]: ${result.status}; reports: ${config.artifactsDir}`);
         process.exit(result.status === 'passed' ? 0 : result.status === 'interrupted' ? 130 : 1);
     }
+    const previousRunEvent = config.onRunEvent;
+    config.onRunEvent = event => {
+        previousRunEvent?.(event);
+        if (event.type === 'RUN_COMPLETE')
+            process.exitCode = event.payload?.status === 'success' ? 0 : ['aborted', 'interrupted'].includes(event.payload?.status) ? 130 : 1;
+    };
     try {
-        await orchestrator.start(resolvedPath);
-        console.log("\n[Flowstride]: Execution suite completed successfully.");
+        const isSuccess = await orchestrator.start(resolvedPath);
+        process.exitCode = isSuccess ? 0 : 1;
+        console.log(isSuccess ? "\n[Flowstride]: Execution suite completed successfully." : "\n[Flowstride]: Execution suite failed.");
         if (isCI) {
             const artifactsDir = path.resolve(root, "flowstride-artifacts");
             if (!fs.existsSync(artifactsDir)) {
@@ -157,7 +167,7 @@ async function runAction(targetPath, options) {
         }
     }
     catch (error) {
-        console.error("\n[Fatal Error]:", error.message);
+        console.error("\n[Fatal Error]:", (0, runtime_failure_1.runtimeFailure)("run.setup", { path: resolvedPath }, error, { file: resolvedPath }));
         if (isCI) {
             console.log(`[CI Alert]: Terminating pipeline with exit code 1 to block deployment.`);
         }