@midscene/test 0.0.0 → 1.10.4-beta-20260723055511.0

package/dist/es/cli/index.mjs

@@ -0,0 +1,1926 @@
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { require as api_require } from "tsx/cjs/api";
+import { tsImport } from "tsx/esm/api";
+import { z } from "zod/v4";
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { globSync } from "tinyglobby";
+import { JSON_SCHEMA, load } from "js-yaml";
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+class WorkflowError extends Error {
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            ...void 0 === this.details ? {} : {
+                details: this.details
+            }
+        };
+    }
+    constructor(message, options = {}){
+        super(message, {
+            cause: options.cause
+        }), _define_property(this, "code", void 0), _define_property(this, "details", void 0);
+        this.name = new.target.name;
+        this.code = options.code ?? 'WORKFLOW_ERROR';
+        this.details = options.details;
+    }
+}
+class WorkflowParseError extends WorkflowError {
+    constructor(message, details, cause){
+        super(message, {
+            code: 'WORKFLOW_PARSE_ERROR',
+            details,
+            cause
+        });
+    }
+}
+class NodeDefinitionError extends WorkflowError {
+    constructor(message, details){
+        super(message, {
+            code: 'NODE_DEFINITION_ERROR',
+            details
+        });
+    }
+}
+class DuplicateNodeError extends WorkflowError {
+    constructor(node){
+        super(`Node "${node}" is already registered.`, {
+            code: 'DUPLICATE_NODE',
+            details: {
+                node
+            }
+        }), _define_property(this, "node", void 0);
+        this.node = node;
+    }
+}
+class NodeNotFoundError extends WorkflowError {
+    constructor(node){
+        super(`Node "${node}" is not registered.`, {
+            code: 'NODE_NOT_FOUND',
+            details: {
+                node
+            }
+        }), _define_property(this, "node", void 0);
+        this.node = node;
+    }
+}
+class NodeInputValidationError extends WorkflowError {
+    static fromZod(node, error) {
+        const issues = error.issues.map((issue)=>({
+                code: issue.code,
+                path: issue.path.map(String).join('.'),
+                message: issue.message
+            }));
+        const firstIssue = issues[0];
+        const path = firstIssue?.path || '<root>';
+        const message = firstIssue?.message ?? 'invalid input';
+        return new NodeInputValidationError(`Node "${node}" input validation failed at "${path}": ${message}`, {
+            node,
+            issues
+        });
+    }
+    constructor(message, details){
+        super(message, {
+            code: 'NODE_INPUT_VALIDATION_ERROR',
+            details
+        });
+    }
+}
+class StepTimeoutError extends WorkflowError {
+    constructor(timeoutMs, node){
+        super(node ? `Node "${node}" timed out after ${timeoutMs}ms.` : `Step timed out after ${timeoutMs}ms.`, {
+            code: 'STEP_TIMEOUT',
+            details: {
+                timeoutMs,
+                ...void 0 === node ? {} : {
+                    node
+                }
+            }
+        }), _define_property(this, "timeoutMs", void 0), _define_property(this, "node", void 0);
+        this.timeoutMs = timeoutMs;
+        this.node = node;
+    }
+}
+class NodeExecutionError extends WorkflowError {
+    constructor(node, cause){
+        const causeMessage = cause instanceof Error ? cause.message : String(cause ?? 'Unknown error');
+        super(`Node "${node}" failed: ${causeMessage}`, {
+            code: 'NODE_EXECUTION_ERROR',
+            details: {
+                node
+            },
+            cause
+        }), _define_property(this, "node", void 0);
+        this.node = node;
+    }
+}
+class WorkflowLifecycleError extends WorkflowError {
+    constructor(message, details){
+        super(message, {
+            code: 'WORKFLOW_LIFECYCLE_ERROR',
+            details
+        });
+    }
+}
+class ProjectSetupError extends WorkflowError {
+    constructor(cause, details){
+        const causeMessage = cause instanceof Error ? cause.message : String(cause ?? 'Unknown error');
+        super(`Project "${details.projectName}" setup failed: ${causeMessage}`, {
+            code: 'PROJECT_SETUP_ERROR',
+            details,
+            cause
+        });
+    }
+}
+class ProjectTeardownError extends WorkflowError {
+    constructor(cause, details){
+        const causeMessage = cause instanceof Error ? cause.message : String(cause ?? 'Unknown error');
+        super(`Project "${details.projectName}" teardown failed: ${causeMessage}`, {
+            code: 'PROJECT_TEARDOWN_ERROR',
+            details,
+            cause
+        });
+    }
+}
+class NodeScopeTeardownError extends WorkflowError {
+    constructor(cause, details){
+        const causeMessage = cause instanceof Error ? cause.message : String(cause ?? 'Unknown error');
+        super(`${'case' === details.scope ? 'Case attempt' : 'Workflow document'} node teardown failed for "${details.node}": ${causeMessage}`, {
+            code: 'NODE_SCOPE_TEARDOWN_ERROR',
+            details,
+            cause
+        });
+    }
+}
+class FatalDeviceError extends WorkflowError {
+    constructor(message, cause){
+        super(message, {
+            code: 'FATAL_DEVICE_ERROR',
+            cause
+        });
+    }
+}
+const isFatalDeviceError = (error)=>{
+    if (error instanceof FatalDeviceError) return true;
+    if (error instanceof WorkflowError && 'FATAL_DEVICE_ERROR' === error.code) return true;
+    if (error instanceof Error && /device offline|device not found|(?:adb|bdc|device) connection (?:was )?closed/i.test(error.message)) return true;
+    return error instanceof Error && void 0 !== error.cause ? isFatalDeviceError(error.cause) : false;
+};
+function normalizeNodeExecutionError(error, node) {
+    return error instanceof WorkflowError ? error : new NodeExecutionError(node, error);
+}
+const validateOptionalText = (value, field, node)=>{
+    if (void 0 !== value && ('string' != typeof value || 0 === value.trim().length)) throw new NodeDefinitionError(`Node "${node}" ${field} must be a non-empty string.`, {
+        node,
+        field
+    });
+};
+const validateInputSchema = (schema, node)=>{
+    if (void 0 === schema) return;
+    if (!(schema instanceof z.ZodObject)) throw new NodeDefinitionError(`Node "${node}" inputSchema must be a Zod object schema.`, {
+        node,
+        field: 'inputSchema'
+    });
+    if ('$' in schema.shape) throw new NodeDefinitionError(`Node "${node}" inputSchema must not declare "$" as an input property.`, {
+        node,
+        field: 'inputSchema.$'
+    });
+};
+const validateDefinition = (options)=>{
+    if (!options || 'object' != typeof options) throw new NodeDefinitionError('Node definition must be an object.');
+    if ('string' != typeof options.name || 0 === options.name.trim().length) throw new NodeDefinitionError('Node name must be a non-empty string.');
+    validateOptionalText(options.title, 'title', options.name);
+    validateOptionalText(options.description, "description", options.name);
+    validateInputSchema(options.inputSchema, options.name);
+    if ('function' != typeof options.execute) throw new NodeDefinitionError(`Node "${options.name}" must provide an execute function.`, {
+        node: options.name
+    });
+};
+function defineNode(options) {
+    validateDefinition(options);
+    return options;
+}
+function _check_private_redeclaration(obj, privateCollection) {
+    if (privateCollection.has(obj)) throw new TypeError("Cannot initialize the same private elements twice on an object");
+}
+function _class_apply_descriptor_get(receiver, descriptor) {
+    if (descriptor.get) return descriptor.get.call(receiver);
+    return descriptor.value;
+}
+function _class_extract_field_descriptor(receiver, privateMap, action) {
+    if (!privateMap.has(receiver)) throw new TypeError("attempted to " + action + " private field on non-instance");
+    return privateMap.get(receiver);
+}
+function _class_private_field_get(receiver, privateMap) {
+    var descriptor = _class_extract_field_descriptor(receiver, privateMap, "get");
+    return _class_apply_descriptor_get(receiver, descriptor);
+}
+function _class_private_field_init(obj, privateMap, value) {
+    _check_private_redeclaration(obj, privateMap);
+    privateMap.set(obj, value);
+}
+var _nodes = /*#__PURE__*/ new WeakMap();
+class NodeRegistry {
+    register(node) {
+        defineNode(node);
+        if (_class_private_field_get(this, _nodes).has(node.name)) throw new DuplicateNodeError(node.name);
+        _class_private_field_get(this, _nodes).set(node.name, node);
+        return this;
+    }
+    get(name) {
+        return _class_private_field_get(this, _nodes).get(name);
+    }
+    require(name) {
+        const node = this.get(name);
+        if (!node) throw new NodeNotFoundError(name);
+        return node;
+    }
+    has(name) {
+        return _class_private_field_get(this, _nodes).has(name);
+    }
+    names() {
+        return [
+            ..._class_private_field_get(this, _nodes).keys()
+        ];
+    }
+    definitions() {
+        return [
+            ..._class_private_field_get(this, _nodes).values()
+        ];
+    }
+    constructor(nodes = []){
+        _class_private_field_init(this, _nodes, {
+            writable: true,
+            value: new Map()
+        });
+        for (const node of nodes)this.register(node);
+    }
+}
+const defineTestProject = (definition)=>definition;
+const defineProjectSetup = (definition)=>definition;
+const getDefaultExport = (loaded, absolutePath)=>{
+    if ('object' == typeof loaded && null !== loaded && 'default' in loaded) {
+        const defaultExport = loaded.default;
+        if ('object' == typeof defaultExport && null !== defaultExport && '__esModule' in defaultExport) {
+            if ('default' in defaultExport) return defaultExport.default;
+            throw new TypeError(`Midscene config "${absolutePath}" must have a default export.`);
+        }
+        return defaultExport;
+    }
+    throw new TypeError(`Midscene config "${absolutePath}" must have a default export.`);
+};
+const isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
+const rejectUnknownKeys = (value, allowedKeys, label)=>{
+    const allowed = new Set(allowedKeys);
+    const unknown = Object.keys(value).find((key)=>!allowed.has(key));
+    if (unknown) throw new TypeError(`Midscene config ${label}.${unknown} is not supported.`);
+};
+const isAbsolutePattern = (pattern)=>isAbsolute(pattern) || /^[A-Za-z]:[\\/]/.test(pattern) || pattern.startsWith('\\\\');
+const validatePatterns = (value, field, label = 'files', allowEmptyInclude = false)=>{
+    if (!Array.isArray(value)) throw new TypeError(`Midscene config ${label}.${field} must be an array.`);
+    if ('include' === field && 0 === value.length && !allowEmptyInclude) throw new TypeError(`Midscene config ${label}.include must be a non-empty array.`);
+    return value.map((pattern, index)=>{
+        if ('string' != typeof pattern || 0 === pattern.trim().length) throw new TypeError(`Midscene config ${label}.${field}[${index}] must be a non-empty string.`);
+        if (isAbsolutePattern(pattern)) throw new TypeError(`Midscene config ${label}.${field}[${index}] must be relative to the project root.`);
+        if (pattern.split(/[\\/]/).includes('..')) throw new TypeError(`Midscene config ${label}.${field}[${index}] must not contain a ".." path segment.`);
+        if (pattern.includes('\\')) throw new TypeError(`Midscene config ${label}.${field}[${index}] must use POSIX path separators (/).`);
+        if (pattern.startsWith('!')) {
+            if ('include' === field) throw new TypeError(`Midscene config ${label}.include[${index}] must not be a negated pattern. Use files.exclude instead.`);
+            throw new TypeError(`Midscene config ${label}.exclude[${index}] must not be a negated pattern.`);
+        }
+        return pattern;
+    });
+};
+const validateTestFileSelection = (value, label = 'files')=>{
+    if (void 0 === value) return;
+    if (!isRecord(value)) throw new TypeError(`Midscene config ${label} must be an object.`);
+    const include = validatePatterns(value.include, 'include', label);
+    const exclude = void 0 === value.exclude ? void 0 : validatePatterns(value.exclude, 'exclude', label);
+    return Object.freeze({
+        include: Object.freeze(include),
+        ...exclude ? {
+            exclude: Object.freeze(exclude)
+        } : {}
+    });
+};
+const validateTagList = (value, field, label)=>{
+    if (void 0 === value) return [];
+    if (!Array.isArray(value)) throw new TypeError(`Midscene config ${label}.${field} must be an array.`);
+    return value.map((tag, index)=>{
+        if ('string' != typeof tag || 0 === tag.trim().length) throw new TypeError(`Midscene config ${label}.${field}[${index}] must be a non-empty string.`);
+        return tag;
+    });
+};
+const validateTagSelection = (value, label)=>{
+    if (void 0 === value) return Object.freeze({
+        include: [],
+        exclude: []
+    });
+    if (!isRecord(value)) throw new TypeError(`Midscene config ${label} must be an object.`);
+    return Object.freeze({
+        include: Object.freeze(validateTagList(value.include, 'include', label)),
+        exclude: Object.freeze(validateTagList(value.exclude, 'exclude', label))
+    });
+};
+function assertJsonValue(value, path, seen) {
+    if (null === value || 'string' == typeof value || 'boolean' == typeof value) return;
+    if ('number' == typeof value) {
+        if (Number.isFinite(value)) return;
+        throw new TypeError(`Midscene config ${path} must be JSON-compatible.`);
+    }
+    if ('object' != typeof value || void 0 === value) throw new TypeError(`Midscene config ${path} must be JSON-compatible.`);
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && null !== Object.getPrototypeOf(value)) throw new TypeError(`Midscene config ${path} must be JSON-compatible.`);
+    if (seen.has(value)) throw new TypeError(`Midscene config ${path} must not contain cycles.`);
+    seen.add(value);
+    if (Array.isArray(value)) value.forEach((item, index)=>assertJsonValue(item, `${path}[${index}]`, seen));
+    else for (const [key, child] of Object.entries(value))assertJsonValue(child, `${path}.${key}`, seen);
+    seen.delete(value);
+}
+const deepFreezeJson = (value)=>{
+    if ('object' == typeof value && null !== value) {
+        for (const child of Object.values(value))deepFreezeJson(child);
+        Object.freeze(value);
+    }
+    return value;
+};
+const validateVariables = (value, label)=>{
+    if (void 0 === value) return Object.freeze({});
+    if (!isRecord(value)) throw new TypeError(`Midscene config ${label} must be an object.`);
+    assertJsonValue(value, label, new Set());
+    return deepFreezeJson(value);
+};
+const platforms = new Set([
+    'web',
+    'android',
+    'ios',
+    'computer'
+]);
+const validatePlatform = (value, label)=>{
+    if ('string' != typeof value || !platforms.has(value)) throw new TypeError(`Midscene config ${label} must be one of web, android, ios, computer.`);
+    return value;
+};
+const validateProjectSetup = (value, projectPlatform, label)=>{
+    if (void 0 === value) return;
+    if (!isRecord(value)) throw new TypeError(`Midscene config ${label} must be an object.`);
+    if ('string' != typeof value.name || 0 === value.name.trim().length) throw new TypeError(`Midscene config ${label}.name must be non-empty.`);
+    if ('function' != typeof value.setup) throw new TypeError(`Midscene config ${label}.setup must be a function.`);
+    const supported = void 0 === value.platform ? void 0 : Array.isArray(value.platform) ? value.platform.map((item, index)=>validatePlatform(item, `${label}.platform[${index}]`)) : [
+        validatePlatform(value.platform, `${label}.platform`)
+    ];
+    if (supported && !supported.includes(projectPlatform)) throw new TypeError(`Midscene config ${label} does not support project platform "${projectPlatform}".`);
+    return value;
+};
+const validatePositiveInteger = (value, fallback, label)=>{
+    if (void 0 === value) return fallback;
+    if (!Number.isInteger(value) || value <= 0) throw new TypeError(`Midscene config ${label} must be a positive integer.`);
+    return value;
+};
+const validateNonNegativeInteger = (value, fallback, label)=>{
+    if (void 0 === value) return fallback;
+    if (!Number.isInteger(value) || value < 0) throw new TypeError(`Midscene config ${label} must be a non-negative integer.`);
+    return value;
+};
+const validateExecutionProjects = (value, defaultSetup)=>{
+    if (void 0 === value) {
+        let platform = 'web';
+        if (void 0 !== defaultSetup) {
+            if (!isRecord(defaultSetup)) throw new TypeError('Midscene config setup must be an object.');
+            if (Array.isArray(defaultSetup.platform)) {
+                if (1 !== defaultSetup.platform.length) throw new TypeError('Midscene config setup.platform must select exactly one platform when projects is omitted.');
+                platform = validatePlatform(defaultSetup.platform[0], 'setup.platform[0]');
+            } else if (void 0 !== defaultSetup.platform) platform = validatePlatform(defaultSetup.platform, 'setup.platform');
+        }
+        const setup = validateProjectSetup(defaultSetup, platform, 'setup');
+        return {
+            hasExplicitProjects: false,
+            projects: Object.freeze([
+                Object.freeze({
+                    name: 'default',
+                    platform,
+                    ...setup ? {
+                        setup
+                    } : {},
+                    tags: Object.freeze({
+                        include: [],
+                        exclude: []
+                    }),
+                    retry: 0,
+                    variables: Object.freeze({})
+                })
+            ])
+        };
+    }
+    if (void 0 !== defaultSetup) throw new TypeError('Midscene config setup cannot be used together with projects. Move setup to projects[].setup.');
+    if (!Array.isArray(value) || 0 === value.length) throw new TypeError('Midscene config projects must be a non-empty array when declared.');
+    const names = new Set();
+    const projects = value.map((candidate, index)=>{
+        const label = `projects[${index}]`;
+        if (!isRecord(candidate)) throw new TypeError(`Midscene config ${label} must be an object.`);
+        rejectUnknownKeys(candidate, [
+            'name',
+            'platform',
+            'setup',
+            'files',
+            'tags',
+            'retry',
+            'variables'
+        ], label);
+        if ('string' != typeof candidate.name || 0 === candidate.name.trim().length) throw new TypeError(`Midscene config ${label}.name must be non-empty.`);
+        if (names.has(candidate.name)) throw new TypeError(`Midscene config project name "${candidate.name}" must be unique.`);
+        names.add(candidate.name);
+        const platform = validatePlatform(candidate.platform, `${label}.platform`);
+        const files = validateTestFileSelection(candidate.files, `${label}.files`);
+        return Object.freeze({
+            name: candidate.name,
+            platform,
+            ...files ? {
+                files
+            } : {},
+            tags: validateTagSelection(candidate.tags, `${label}.tags`),
+            retry: validateNonNegativeInteger(candidate.retry, 0, `${label}.retry`),
+            variables: validateVariables(candidate.variables, `${label}.variables`),
+            ...void 0 === candidate.setup ? {} : {
+                setup: validateProjectSetup(candidate.setup, platform, `${label}.setup`)
+            }
+        });
+    });
+    return {
+        projects: Object.freeze(projects),
+        hasExplicitProjects: true
+    };
+};
+const validateTestOptions = (value)=>{
+    if (void 0 !== value && !isRecord(value)) throw new TypeError('Midscene config test must be an object.');
+    const candidate = value ?? {};
+    const maxConcurrency = candidate.maxConcurrency;
+    if (void 0 !== maxConcurrency && 1 !== maxConcurrency) throw new TypeError('Midscene config test.maxConcurrency currently only supports 1.');
+    return Object.freeze({
+        maxConcurrency: 1,
+        bail: validateNonNegativeInteger(candidate.bail, 0, 'test.bail'),
+        testTimeout: validatePositiveInteger(candidate.testTimeout, 120000, 'test.testTimeout')
+    });
+};
+const validateOutputPath = (value, fallback, label)=>{
+    if (void 0 === value) return fallback;
+    if ('string' != typeof value || 0 === value.trim().length) throw new TypeError(`Midscene config ${label} must be non-empty.`);
+    return value;
+};
+const validateOutput = (value)=>{
+    if (void 0 !== value && !isRecord(value)) throw new TypeError('Midscene config output must be an object.');
+    const candidate = value ?? {};
+    return Object.freeze({
+        summary: validateOutputPath(candidate.summary, './midscene_run/output/summary.json', 'output.summary'),
+        reportDir: validateOutputPath(candidate.reportDir, './midscene_run/report', 'output.reportDir')
+    });
+};
+const validateTestProjectDefinition = (definition)=>{
+    if (!isRecord(definition) || !('nodes' in definition) || !Array.isArray(definition.nodes)) throw new TypeError('Midscene config must default export an object with a nodes array.');
+    if ('setupWorkflow' in definition) throw new TypeError('Midscene config setupWorkflow is no longer supported. Use setup or projects[].setup instead.');
+    if ('setupDocument' in definition) throw new TypeError('Midscene config setupDocument is not supported. Use setup or projects[].setup for resources, and beforeAll/afterAll for document lifecycle steps.');
+    if ('root' in definition) throw new TypeError('Midscene config root is not supported. Pass the Test Project directory to midscene-test instead.');
+    if ('files' in definition) throw new TypeError('Midscene config files is not supported at the root. Move it to projects[].files.');
+    if ('testRunner' in definition) throw new TypeError('Midscene config testRunner is not supported. Rename it to test.');
+    rejectUnknownKeys(definition, [
+        'setup',
+        'projects',
+        'test',
+        'output',
+        'nodes'
+    ], 'root');
+    const resolvedProjects = validateExecutionProjects(definition.projects, definition.setup);
+    const nodes = new NodeRegistry(definition.nodes);
+    return {
+        ...resolvedProjects,
+        test: validateTestOptions(definition.test),
+        output: validateOutput(definition.output),
+        nodes,
+        resolveNode: (name)=>nodes.get(name)
+    };
+};
+const assertTypeScriptConfig = (absolutePath)=>{
+    if (!absolutePath.endsWith('.ts')) {
+        const extension = absolutePath.match(/(\.[^./\\]+)$/)?.[1] ?? '(none)';
+        throw new TypeError(`Unsupported Midscene config extension: ${extension}. Supported extension: .ts.`);
+    }
+};
+const canRetryWithCjsLoader = (error)=>error instanceof SyntaxError && (/^Unexpected (?:identifier|reserved word|token)/.test(error.message) || 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX' === error.code);
+async function loadTestProject(configPath) {
+    if (!configPath) return validateTestProjectDefinition({
+        nodes: []
+    });
+    const absolutePath = resolve(configPath);
+    assertTypeScriptConfig(absolutePath);
+    let loaded;
+    try {
+        loaded = await tsImport(absolutePath, {
+            parentURL: pathToFileURL(`${dirname(absolutePath)}${sep}`).href,
+            tsconfig: false
+        });
+    } catch (error) {
+        try {
+            if (!canRetryWithCjsLoader(error)) throw error;
+            loaded = api_require(absolutePath, pathToFileURL(absolutePath));
+        } catch (fallbackError) {
+            const message = fallbackError instanceof Error ? `: ${fallbackError.message}` : '';
+            throw new Error(`Failed to load Midscene config "${absolutePath}"${message}`, {
+                cause: fallbackError
+            });
+        }
+    }
+    return validateTestProjectDefinition(getDefaultExport(loaded, absolutePath));
+}
+const createProjectRuntime = (options)=>{
+    const startedAt = new Date();
+    const controller = new AbortController();
+    const parentSignal = options.signal;
+    const abortFromParent = ()=>controller.abort(parentSignal?.reason);
+    if (parentSignal?.aborted) abortFromParent();
+    else parentSignal?.addEventListener('abort', abortFromParent, {
+        once: true
+    });
+    const teardownStack = [];
+    let context;
+    let setupError;
+    let started = false;
+    let acceptingTeardowns = void 0 !== options.setup;
+    let finishedResult;
+    const createResult = (requestedStatus, teardownErrors = [])=>{
+        const endedAt = new Date();
+        return {
+            projectName: options.project.name,
+            platform: options.project.platform,
+            status: 'failed' === requestedStatus || setupError || teardownErrors.length > 0 ? 'failed' : 'success',
+            ...setupError ? {
+                setupError
+            } : {},
+            ...teardownErrors.length > 0 ? {
+                teardownErrors
+            } : {},
+            startedAt: startedAt.toISOString(),
+            endedAt: endedAt.toISOString(),
+            durationMs: Math.max(0, endedAt.getTime() - startedAt.getTime())
+        };
+    };
+    const onTeardown = (teardown)=>{
+        if (!acceptingTeardowns) throw new WorkflowLifecycleError('onTeardown() can only be called while Project setup is running.', {
+            projectName: options.project.name
+        });
+        if ('function' != typeof teardown) throw new WorkflowLifecycleError('Project onTeardown() requires a teardown function.', {
+            projectName: options.project.name
+        });
+        teardownStack.push({
+            registrationIndex: teardownStack.length,
+            teardown
+        });
+    };
+    return {
+        get context () {
+            return context;
+        },
+        get signal () {
+            return controller.signal;
+        },
+        get canRun () {
+            return started && !setupError && !controller.signal.aborted;
+        },
+        async start () {
+            if (started) throw new WorkflowLifecycleError('Project runtime has already started.', {
+                projectName: options.project.name
+            });
+            started = true;
+            if (controller.signal.aborted) {
+                acceptingTeardowns = false;
+                return createResult('failed');
+            }
+            if (options.setup) try {
+                context = await options.setup.setup({
+                    project: options.project,
+                    env: Object.freeze({
+                        ...process.env
+                    }),
+                    signal: controller.signal,
+                    onTeardown
+                });
+            } catch (error) {
+                setupError = new ProjectSetupError(error, {
+                    projectName: options.project.name
+                });
+            } finally{
+                acceptingTeardowns = false;
+            }
+            return createResult(setupError ? 'failed' : 'success');
+        },
+        async finish (requestedStatus = 'success') {
+            if (finishedResult) return finishedResult;
+            if (!started) throw new WorkflowLifecycleError('Project runtime must start before it can finish.', {
+                projectName: options.project.name
+            });
+            const statusBeforeTeardown = createResult(requestedStatus).status;
+            const teardownErrors = [];
+            for (const { registrationIndex, teardown } of teardownStack.reverse())try {
+                await teardown({
+                    project: options.project,
+                    context,
+                    status: statusBeforeTeardown,
+                    ...setupError ? {
+                        setupError
+                    } : {}
+                });
+            } catch (error) {
+                teardownErrors.push(new ProjectTeardownError(error, {
+                    projectName: options.project.name,
+                    registrationIndex
+                }));
+            }
+            parentSignal?.removeEventListener('abort', abortFromParent);
+            finishedResult = createResult(requestedStatus, teardownErrors);
+            return finishedResult;
+        },
+        abort (reason) {
+            controller.abort(reason);
+        }
+    };
+};
+const supportedMetaKeys = new Set([
+    'timeout',
+    'continue-on-error'
+]);
+function isMapping(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || null === Object.getPrototypeOf(value));
+}
+function formatStep(index) {
+    return `step ${index + 1}`;
+}
+function normalizeMeta(value, index) {
+    if (void 0 === value) return {
+        continueOnError: false
+    };
+    if (!isMapping(value)) throw new WorkflowParseError(`${formatStep(index)} "$" must be a mapping.`, {
+        index
+    });
+    for (const key of Object.keys(value))if (!supportedMetaKeys.has(key)) throw new WorkflowParseError(`${formatStep(index)} has unsupported engine metadata "${key}".`, {
+        index,
+        key
+    });
+    const timeout = value.timeout;
+    if (void 0 !== timeout && ('number' != typeof timeout || !Number.isFinite(timeout) || timeout <= 0)) throw new WorkflowParseError(`${formatStep(index)} "$.timeout" must be a positive number of milliseconds.`, {
+        index,
+        timeout
+    });
+    const continueOnError = value['continue-on-error'];
+    if (void 0 !== continueOnError && 'boolean' != typeof continueOnError) throw new WorkflowParseError(`${formatStep(index)} "$.continue-on-error" must be a boolean.`, {
+        index,
+        continueOnError
+    });
+    return {
+        ...void 0 === timeout ? {} : {
+            timeoutMs: timeout
+        },
+        continueOnError: continueOnError ?? false
+    };
+}
+function validateCommonNodeInput(input, index) {
+    if (void 0 !== input.prompt && 'string' != typeof input.prompt) throw new WorkflowParseError(`${formatStep(index)} "prompt" must be a string.`, {
+        index,
+        prompt: input.prompt
+    });
+}
+function normalizeStep(value, index = 0) {
+    if (!isMapping(value)) throw new WorkflowParseError(`${formatStep(index)} must be a mapping.`, {
+        index
+    });
+    const entries = Object.entries(value);
+    if (1 !== entries.length) throw new WorkflowParseError(`${formatStep(index)} must contain exactly one node.`, {
+        index,
+        nodes: Object.keys(value)
+    });
+    const [node, rawValue] = entries[0];
+    if (0 === node.trim().length) throw new WorkflowParseError(`${formatStep(index)} node name must not be empty.`, {
+        index
+    });
+    if ('string' == typeof rawValue) return {
+        node,
+        input: {
+            prompt: rawValue
+        },
+        meta: {
+            continueOnError: false
+        }
+    };
+    if (!isMapping(rawValue)) throw new WorkflowParseError(`${formatStep(index)} value must be a string shorthand or a mapping.`, {
+        index,
+        node
+    });
+    const { $: rawMeta, ...input } = rawValue;
+    validateCommonNodeInput(input, index);
+    return {
+        node,
+        input,
+        meta: normalizeMeta(rawMeta, index)
+    };
+}
+function normalizeSteps(steps) {
+    if (!Array.isArray(steps)) throw new WorkflowParseError('Steps must be an array.');
+    return steps.map((step, index)=>normalizeStep(step, index));
+}
+const assertJsonSerializable = (value, label, node)=>{
+    const visit = (candidate, path, seen)=>{
+        if (null === candidate || 'string' == typeof candidate || 'boolean' == typeof candidate) return;
+        if ('number' == typeof candidate) {
+            if (Number.isFinite(candidate)) return;
+            throw new TypeError(`${path} contains a non-finite number.`);
+        }
+        if (void 0 === candidate) throw new TypeError(`${path} contains undefined.`);
+        if ('object' != typeof candidate) throw new TypeError(`${path} is not JSON-serializable.`);
+        if (!Array.isArray(candidate) && Object.getPrototypeOf(candidate) !== Object.prototype && null !== Object.getPrototypeOf(candidate)) throw new TypeError(`${path} must contain only plain objects.`);
+        if (seen.has(candidate)) throw new TypeError(`${path} contains a cycle.`);
+        seen.add(candidate);
+        if (Array.isArray(candidate)) candidate.forEach((child, index)=>visit(child, `${path}[${index}]`, seen));
+        else for (const [key, child] of Object.entries(candidate))visit(child, `${path}.${key}`, seen);
+        seen.delete(candidate);
+    };
+    try {
+        visit(value, label, new Set());
+    } catch (error) {
+        throw new NodeExecutionError(node, error);
+    }
+};
+const cloneAndFreezeJson = (value)=>{
+    if (Array.isArray(value)) return Object.freeze(value.map(cloneAndFreezeJson));
+    if ('object' == typeof value && null !== value) return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, child])=>[
+            key,
+            cloneAndFreezeJson(child)
+        ])));
+    return value;
+};
+const toHistoryEntry = (result, scope)=>{
+    assertJsonSerializable(result.input, 'input', result.node);
+    if (result.output?.data !== void 0) assertJsonSerializable(result.output.data, 'output.data', result.node);
+    return Object.freeze({
+        scope,
+        phase: result.phase,
+        stepIndex: result.stepIndex,
+        node: result.node,
+        input: cloneAndFreezeJson(result.input),
+        ...'string' == typeof result.input?.prompt ? {
+            intent: result.input.prompt
+        } : {},
+        status: 'success' === result.status ? 'passed' : 'failed',
+        ...result.output?.summary === void 0 ? {} : {
+            summary: result.output.summary
+        },
+        ...result.output?.data === void 0 ? {} : {
+            data: cloneAndFreezeJson(result.output.data)
+        },
+        ...result.error ? {
+            error: Object.freeze({
+                name: result.error.name,
+                message: result.error.message
+            })
+        } : {}
+    });
+};
+const createHistory = (prefix, results, scope)=>Object.freeze([
+        ...prefix,
+        ...results.map((result)=>toHistoryEntry(result, scope))
+    ]);
+function validateNodeOutput(output, node) {
+    if (void 0 === output) return;
+    if ('object' != typeof output || null === output || Array.isArray(output)) throw new NodeExecutionError(node, new TypeError('Node output must be an object or undefined.'));
+    if ('summary' in output && void 0 !== output.summary && 'string' != typeof output.summary) throw new NodeExecutionError(node, new TypeError('Node output summary must be a string.'));
+    if ('data' in output && void 0 !== output.data) assertJsonSerializable(output.data, 'output.data', node);
+    return output;
+}
+function createStepResultBase(step, startedAt, phase, stepIndex) {
+    const endedAt = new Date();
+    return {
+        node: step.node,
+        phase,
+        stepIndex,
+        input: step.input,
+        meta: step.meta,
+        startedAt: startedAt.toISOString(),
+        endedAt: endedAt.toISOString(),
+        durationMs: Math.max(0, endedAt.getTime() - startedAt.getTime())
+    };
+}
+async function executeNode(step, execute, phase, stepIndex, options) {
+    validateCommonNodeInput(step.input, stepIndex);
+    const startedAt = new Date();
+    const abortController = new AbortController();
+    const parentSignal = options.parentSignal;
+    const abortFromParent = ()=>abortController.abort(parentSignal?.reason ?? new Error('Workflow execution aborted.'));
+    if (parentSignal?.aborted) abortFromParent();
+    else parentSignal?.addEventListener('abort', abortFromParent, {
+        once: true
+    });
+    const timeoutMs = step.meta.timeoutMs ?? options.defaultTimeoutMs;
+    let timeout;
+    let timeoutError;
+    const execution = Promise.resolve().then(()=>{
+        if (abortController.signal.aborted) throw abortController.signal.reason ?? new Error('Workflow execution aborted.');
+        return execute(abortController.signal);
+    });
+    const timedExecution = void 0 === timeoutMs ? execution : Promise.race([
+        execution,
+        new Promise((_, reject)=>{
+            timeout = setTimeout(()=>{
+                timeoutError = new StepTimeoutError(timeoutMs, step.node);
+                abortController.abort(timeoutError);
+                reject(timeoutError);
+            }, timeoutMs);
+        })
+    ]);
+    try {
+        const output = validateNodeOutput(await timedExecution, step.node);
+        return {
+            ...createStepResultBase(step, startedAt, phase, stepIndex),
+            status: 'success',
+            continuedAfterError: false,
+            ...void 0 === output ? {} : {
+                output
+            }
+        };
+    } catch (error) {
+        return {
+            ...createStepResultBase(step, startedAt, phase, stepIndex),
+            status: 'failed',
+            continuedAfterError: step.meta.continueOnError,
+            error: normalizeNodeExecutionError(timeoutError ?? error, step.node)
+        };
+    } finally{
+        if (void 0 !== timeout) clearTimeout(timeout);
+        parentSignal?.removeEventListener('abort', abortFromParent);
+    }
+}
+async function parseNodeInput(node, input) {
+    if (!node.inputSchema) return input;
+    const parsed = await node.inputSchema.safeParseAsync(input);
+    if (!parsed.success) throw NodeInputValidationError.fromZod(node.name, parsed.error);
+    return parsed.data;
+}
+async function executeStep(step, node, target, context, execution = {}) {
+    const phase = 'case' === target.scope ? target.case.phase : target.document.phase;
+    const stepIndex = 'case' === target.scope ? target.case.stepIndex : target.document.stepIndex;
+    return executeNode(step, async (signal)=>{
+        const input = await parseNodeInput(node, step.input);
+        const common = {
+            input,
+            $: step.meta,
+            signal,
+            context,
+            history: execution.history ?? Object.freeze([]),
+            onTeardown: (teardown)=>{
+                if (!execution.onTeardown) throw new NodeExecutionError(step.node, new Error('The current execution scope cannot register teardown.'));
+                execution.onTeardown(step.node, teardown);
+            }
+        };
+        return 'case' === target.scope ? node.execute({
+            ...common,
+            scope: 'case',
+            case: target.case
+        }) : node.execute({
+            ...common,
+            scope: 'document',
+            document: target.document
+        });
+    }, phase, stepIndex, {
+        parentSignal: execution.signal,
+        defaultTimeoutMs: execution.defaultTimeoutMs
+    });
+}
+const reportPathsFromTeardown = (result)=>{
+    if (void 0 === result) return [];
+    if ('object' != typeof result || null === result || Array.isArray(result)) throw new TypeError('Node teardown result must be an object or undefined.');
+    const paths = result.reportPaths;
+    if (void 0 === paths) return [];
+    if (!Array.isArray(paths)) throw new TypeError('Node teardown reportPaths must be an array.');
+    return paths.map((path, index)=>{
+        if ('string' != typeof path || 0 === path.trim().length) throw new TypeError(`Node teardown reportPaths[${index}] must be a non-empty string.`);
+        if (!isAbsolute(path)) throw new TypeError(`Node teardown reportPaths[${index}] must be an absolute path.`);
+        return path;
+    });
+};
+function createDocumentRuntime(document, options) {
+    const documentRunId = options.createDocumentRunId?.() ?? randomUUID();
+    const startedAt = new Date();
+    const beforeAll = [];
+    const afterAll = [];
+    const completedNodes = [];
+    const nodes = {
+        beforeAll: document.lifecycle.beforeAll.map((step)=>options.resolveNode(step.node)),
+        afterAll: document.lifecycle.afterAll.map((step)=>options.resolveNode(step.node))
+    };
+    const project = options.project ?? Object.freeze({
+        name: document.projectId,
+        platform: 'web',
+        tags: Object.freeze({
+            include: [],
+            exclude: []
+        }),
+        retry: 0,
+        variables: Object.freeze({})
+    });
+    const context = options.projectContext;
+    const signal = options.signal ?? new AbortController().signal;
+    const nodeTeardownStack = [];
+    let acceptingNodeTeardowns = true;
+    let started = false;
+    let finishedResult;
+    const reportPaths = new Set();
+    const createResult = (teardownErrors = [])=>{
+        const endedAt = new Date();
+        return {
+            documentId: document.documentId,
+            documentRunId,
+            projectId: document.projectId,
+            projectName: project.name,
+            sourcePath: document.sourcePath,
+            status: completedNodes.some((step)=>'failed' === step.status) || teardownErrors.length > 0 ? 'failed' : 'success',
+            startedAt: startedAt.toISOString(),
+            endedAt: endedAt.toISOString(),
+            durationMs: Math.max(0, endedAt.getTime() - startedAt.getTime()),
+            beforeAll: [
+                ...beforeAll
+            ],
+            afterAll: [
+                ...afterAll
+            ],
+            ...teardownErrors.length > 0 ? {
+                teardownErrors
+            } : {},
+            ...reportPaths.size > 0 ? {
+                reportPaths: [
+                    ...reportPaths
+                ]
+            } : {}
+        };
+    };
+    const runPhase = async (phase, results, executionSignal = signal)=>{
+        for (const [stepIndex, step] of document.lifecycle[phase].entries()){
+            const documentContext = {
+                documentId: document.documentId,
+                documentRunId,
+                projectId: document.projectId,
+                projectName: project.name,
+                sourcePath: document.sourcePath,
+                phase,
+                stepIndex,
+                completedNodes: Object.freeze([
+                    ...completedNodes
+                ])
+            };
+            const stepInfo = {
+                scope: 'document',
+                node: step.node,
+                stepCount: document.lifecycle[phase].length,
+                document: documentContext
+            };
+            await options.onStepStart?.(stepInfo);
+            const result = await executeStep(step, nodes[phase][stepIndex], {
+                scope: 'document',
+                document: documentContext
+            }, context, {
+                history: createHistory([], completedNodes, 'document'),
+                signal: executionSignal,
+                defaultTimeoutMs: options.defaultTimeoutMs,
+                onTeardown (node, teardown) {
+                    if (!acceptingNodeTeardowns) throw new WorkflowLifecycleError('Node teardown can only be registered while a workflow document is running.', {
+                        documentId: document.documentId,
+                        documentRunId,
+                        node
+                    });
+                    if ('function' != typeof teardown) throw new WorkflowLifecycleError('Node onTeardown() requires a teardown function.', {
+                        documentId: document.documentId,
+                        documentRunId,
+                        node
+                    });
+                    nodeTeardownStack.push({
+                        registrationIndex: nodeTeardownStack.length,
+                        node,
+                        teardown
+                    });
+                }
+            });
+            await options.onStepResult?.(stepInfo, result);
+            results.push(result);
+            completedNodes.push(result);
+            if ('failed' === result.status && !result.continuedAfterError) break;
+        }
+    };
+    return {
+        get context () {
+            return context;
+        },
+        get history () {
+            return createHistory([], completedNodes, 'document');
+        },
+        get canRunCases () {
+            return started && !signal.aborted && !beforeAll.some((step)=>'failed' === step.status);
+        },
+        async start () {
+            if (started) throw new WorkflowLifecycleError('Workflow document runtime has already started.', {
+                documentId: document.documentId,
+                documentRunId
+            });
+            started = true;
+            if (!signal.aborted) await runPhase('beforeAll', beforeAll);
+            return createResult();
+        },
+        async finish () {
+            if (finishedResult) return finishedResult;
+            if (!started) throw new WorkflowLifecycleError('Workflow document runtime must start before it can finish.', {
+                documentId: document.documentId,
+                documentRunId
+            });
+            let finishError;
+            try {
+                await runPhase('afterAll', afterAll, signal.aborted ? new AbortController().signal : signal);
+            } catch (error) {
+                finishError = error;
+            }
+            acceptingNodeTeardowns = false;
+            const teardownErrors = [];
+            for (const { registrationIndex, node, teardown } of nodeTeardownStack.reverse())try {
+                for (const path of reportPathsFromTeardown(await teardown()))reportPaths.add(path);
+            } catch (error) {
+                teardownErrors.push(new NodeScopeTeardownError(error, {
+                    scope: 'document',
+                    scopeId: documentRunId,
+                    node,
+                    registrationIndex
+                }));
+            }
+            finishedResult = createResult(teardownErrors);
+            if (finishError) throw finishError;
+            await options.onResult?.(finishedResult);
+            return finishedResult;
+        }
+    };
+}
+async function runCollectedCase(collectedCase, options) {
+    const phases = {
+        beforeEach: options.beforeEach ?? [],
+        steps: collectedCase.definition.steps,
+        afterEach: options.afterEach ?? []
+    };
+    const nodes = {
+        beforeEach: phases.beforeEach.map((step)=>options.resolveNode(step.node)),
+        steps: phases.steps.map((step)=>options.resolveNode(step.node)),
+        afterEach: phases.afterEach.map((step)=>options.resolveNode(step.node))
+    };
+    const runId = options.createRunId?.() ?? randomUUID();
+    const startedAt = new Date();
+    const beforeEach = [];
+    const steps = [];
+    const afterEach = [];
+    const completedNodes = [];
+    const teardownStack = [];
+    let acceptingTeardowns = true;
+    const onTeardown = (node, teardown)=>{
+        if (!acceptingTeardowns) throw new WorkflowLifecycleError('Node teardown can only be registered while a case attempt is running.', {
+            runId,
+            node
+        });
+        if ('function' != typeof teardown) throw new WorkflowLifecycleError('Node onTeardown() requires a teardown function.', {
+            runId,
+            node
+        });
+        teardownStack.push({
+            registrationIndex: teardownStack.length,
+            node,
+            teardown
+        });
+    };
+    const runPhase = async (phase, results, signal = options.signal)=>{
+        for (const [stepIndex, step] of phases[phase].entries()){
+            const caseContext = {
+                caseId: collectedCase.caseId,
+                runId,
+                projectName: options.projectName ?? collectedCase.projectId,
+                attemptIndex: options.attemptIndex ?? 0,
+                name: collectedCase.definition.name,
+                sourcePath: collectedCase.sourcePath,
+                caseIndex: collectedCase.caseIndex,
+                phase,
+                stepIndex,
+                completedSteps: Object.freeze([
+                    ...steps
+                ]),
+                completedNodes: Object.freeze([
+                    ...completedNodes
+                ])
+            };
+            const stepInfo = {
+                scope: 'case',
+                node: step.node,
+                stepCount: phases[phase].length,
+                case: caseContext
+            };
+            await options.onStepStart?.(stepInfo);
+            const result = await executeStep(step, nodes[phase][stepIndex], {
+                scope: 'case',
+                case: caseContext
+            }, options.context, {
+                history: createHistory(options.documentHistory ?? [], completedNodes, 'case'),
+                signal,
+                defaultTimeoutMs: options.defaultTimeoutMs,
+                onTeardown
+            });
+            await options.onStepResult?.(stepInfo, result);
+            results.push(result);
+            completedNodes.push(result);
+            if ('failed' === result.status && !result.continuedAfterError) break;
+        }
+    };
+    let executionError;
+    try {
+        await runPhase('beforeEach', beforeEach);
+        if (!beforeEach.some((step)=>'failed' === step.status)) await runPhase('steps', steps);
+    } catch (error) {
+        executionError = error;
+    }
+    try {
+        const cleanupSignal = options.signal?.aborted ? new AbortController().signal : options.signal;
+        await runPhase('afterEach', afterEach, cleanupSignal);
+    } catch (error) {
+        executionError ??= error;
+    }
+    acceptingTeardowns = false;
+    const teardownErrors = [];
+    const reportPaths = new Set();
+    for (const { registrationIndex, node, teardown } of teardownStack.reverse())try {
+        for (const path of reportPathsFromTeardown(await teardown()))reportPaths.add(path);
+    } catch (error) {
+        teardownErrors.push(new NodeScopeTeardownError(error, {
+            scope: 'case',
+            scopeId: runId,
+            node,
+            registrationIndex
+        }));
+    }
+    if (executionError) throw executionError;
+    const endedAt = new Date();
+    const result = {
+        caseId: collectedCase.caseId,
+        runId,
+        projectName: options.projectName ?? collectedCase.projectId,
+        attemptIndex: options.attemptIndex ?? 0,
+        name: collectedCase.definition.name,
+        sourcePath: collectedCase.sourcePath,
+        caseIndex: collectedCase.caseIndex,
+        status: completedNodes.some((step)=>'failed' === step.status) || teardownErrors.length > 0 ? 'failed' : 'success',
+        beforeEach,
+        steps,
+        afterEach,
+        ...teardownErrors.length > 0 ? {
+            teardownErrors
+        } : {},
+        ...reportPaths.size > 0 ? {
+            reportPaths: [
+                ...reportPaths
+            ]
+        } : {},
+        startedAt: startedAt.toISOString(),
+        endedAt: endedAt.toISOString(),
+        durationMs: Math.max(0, endedAt.getTime() - startedAt.getTime())
+    };
+    await options.onResult?.(result);
+    return result;
+}
+const asNotRun = (collectedCase, projectName, reason)=>({
+        caseId: collectedCase.caseId,
+        projectName,
+        name: collectedCase.definition.name,
+        sourcePath: collectedCase.sourcePath,
+        caseIndex: collectedCase.caseIndex,
+        status: 'not-run',
+        notRunReason: reason
+    });
+async function runWorkflowDocument(document, options) {
+    const createDocumentRunId = options.createDocumentRunId;
+    const createCaseRunId = options.createCaseRunId;
+    const projectName = options.project?.name ?? document.projectId;
+    const retry = options.retry ?? options.project?.retry ?? 0;
+    if (!Number.isInteger(retry) || retry < 0) throw new TypeError('Workflow document retry must be a non-negative integer.');
+    const runtime = createDocumentRuntime(document, {
+        resolveNode: options.resolveNode,
+        project: options.project,
+        projectContext: options.projectContext,
+        signal: options.signal,
+        defaultTimeoutMs: options.defaultTimeoutMs,
+        onStepStart: options.onStepStart,
+        onStepResult: options.onStepResult,
+        onResult: options.onDocumentResult,
+        createDocumentRunId: createDocumentRunId ? ()=>createDocumentRunId(document) : void 0
+    });
+    const cases = [];
+    let runtimeStarted = false;
+    let documentResult;
+    let executionError;
+    let fatalError = false;
+    try {
+        runtimeStarted = true;
+        await runtime.start();
+        if (runtime.canRunCases) for (const collectedCase of document.cases){
+            if (fatalError || options.shouldStop?.()) {
+                const outcome = asNotRun(collectedCase, projectName, fatalError ? 'fatal-error' : options.stopReason?.() ?? 'interrupted');
+                cases.push(outcome);
+                await options.onCaseOutcome?.(outcome);
+                continue;
+            }
+            await options.onCaseStart?.(collectedCase);
+            const attempts = [];
+            for(let attemptIndex = 0; attemptIndex <= retry; attemptIndex += 1){
+                const run = await runCollectedCase(collectedCase, {
+                    resolveNode: options.resolveNode,
+                    beforeEach: document.lifecycle.beforeEach,
+                    afterEach: document.lifecycle.afterEach,
+                    context: runtime.context,
+                    projectName,
+                    attemptIndex,
+                    documentHistory: runtime.history,
+                    signal: options.signal,
+                    defaultTimeoutMs: options.defaultTimeoutMs,
+                    onStepStart: options.onStepStart,
+                    onStepResult: options.onStepResult,
+                    onResult: options.onCaseResult,
+                    createRunId: createCaseRunId ? ()=>createCaseRunId(collectedCase, attemptIndex) : void 0
+                });
+                attempts.push(run);
+                fatalError = options.isFatalError?.(run) ?? false;
+                if ('success' === run.status || fatalError) break;
+            }
+            const run = attempts.at(-1);
+            const outcome = {
+                caseId: collectedCase.caseId,
+                projectName,
+                name: collectedCase.definition.name,
+                sourcePath: collectedCase.sourcePath,
+                caseIndex: collectedCase.caseIndex,
+                status: run.status,
+                run,
+                attempts
+            };
+            cases.push(outcome);
+            await options.onCaseOutcome?.(outcome);
+        }
+        else {
+            const reason = options.signal?.aborted ? options.stopReason?.() ?? 'interrupted' : 'document-start-failed';
+            cases.push(...document.cases.map((collectedCase)=>asNotRun(collectedCase, projectName, reason)));
+        }
+    } catch (error) {
+        executionError = error;
+    } finally{
+        if (runtimeStarted) try {
+            documentResult = await runtime.finish();
+        } catch (error) {
+            executionError ??= error;
+        }
+    }
+    if (executionError) throw executionError;
+    if (!documentResult) throw new Error(`Workflow document "${document.sourcePath}" did not produce a result.`);
+    return {
+        document: documentResult,
+        cases
+    };
+}
+const interpolationExpression = /\$\{\{([A-Za-z_][A-Za-z0-9_]*)\}\}|\$\{([^{}]+)\}/g;
+const exactEnvExpression = /^\$\{\{([A-Za-z_][A-Za-z0-9_]*)\}\}$/;
+const exactProjectExpression = /^\$\{([^{}]+)\}$/;
+const missingVariable = (kind, name, options)=>{
+    throw new WorkflowParseError(`Undefined ${kind} variable "${name}" in ${options.location.sourcePath}.`, {
+        ...options.location,
+        variable: name,
+        variableKind: kind
+    });
+};
+const projectVariable = (name, options)=>{
+    if (!Object.hasOwn(options.variables ?? {}, name)) return missingVariable('project', name, options);
+    return options.variables[name];
+};
+const environmentVariable = (name, options)=>{
+    const value = options.env?.[name];
+    if (void 0 === value) return missingVariable('environment', name, options);
+    return value;
+};
+const interpolationValue = (name, value, options)=>{
+    if ('object' == typeof value && null !== value) throw new WorkflowParseError(`Project variable "${name}" must be a primitive when embedded in a string.`, {
+        ...options.location,
+        variable: name,
+        variableKind: 'project'
+    });
+    return String(value);
+};
+const resolveString = (value, options)=>{
+    const exactEnv = exactEnvExpression.exec(value);
+    if (exactEnv) return environmentVariable(exactEnv[1], options);
+    const exactProject = exactProjectExpression.exec(value);
+    if (exactProject) return projectVariable(exactProject[1], options);
+    return value.replace(interpolationExpression, (_match, environmentName, projectName)=>environmentName ? environmentVariable(environmentName, options) : interpolationValue(projectName, projectVariable(projectName, options), options));
+};
+const resolveWorkflowVariables = (value, options)=>{
+    if ('string' == typeof value) return resolveString(value, options);
+    if (Array.isArray(value)) return value.map((child)=>resolveWorkflowVariables(child, options));
+    if ('object' == typeof value && null !== value) return Object.fromEntries(Object.entries(value).map(([key, child])=>[
+            key,
+            resolveWorkflowVariables(child, options)
+        ]));
+    return value;
+};
+const collect_isMapping = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
+const collect_rejectUnknownKeys = (value, allowed, label)=>{
+    const allowedSet = new Set(allowed);
+    const unknown = Object.keys(value).filter((key)=>!allowedSet.has(key));
+    if (unknown.length) throw new WorkflowParseError(`${label} has unsupported field "${unknown[0]}".`, {
+        field: unknown[0]
+    });
+};
+const createCaseId = (projectId, sourcePath, caseIndex)=>createHash('sha256').update(JSON.stringify([
+        projectId,
+        sourcePath,
+        caseIndex
+    ])).digest('hex');
+const createWorkflowDocumentId = (projectId, sourcePath)=>createHash('sha256').update(JSON.stringify([
+        projectId,
+        sourcePath
+    ])).digest('hex');
+function collectWorkflowDocument(source, options) {
+    let parsed;
+    try {
+        parsed = load(readFileSync(source.absolutePath, 'utf8'), {
+            schema: JSON_SCHEMA
+        });
+    } catch (error) {
+        throw new WorkflowParseError(`Failed to parse workflow document "${source.sourcePath}".`, {
+            sourcePath: source.sourcePath
+        }, error);
+    }
+    if (!collect_isMapping(parsed)) throw new WorkflowParseError('Workflow document must be a mapping.');
+    collect_rejectUnknownKeys(parsed, [
+        'beforeAll',
+        'beforeEach',
+        'cases',
+        'afterEach',
+        'afterAll'
+    ], 'Workflow document');
+    if (!Array.isArray(parsed.cases) || 0 === parsed.cases.length) throw new WorkflowParseError('Workflow document must contain a non-empty cases array.');
+    const sourcePath = source.sourcePath.split(sep).join('/');
+    const resolveStepVariables = (step, phase, stepIndex, caseIndex)=>({
+            ...step,
+            input: resolveWorkflowVariables(step.input, {
+                variables: options.variables,
+                env: options.env ?? process.env,
+                location: {
+                    projectName: source.projectId,
+                    sourcePath,
+                    phase,
+                    stepIndex,
+                    ...void 0 === caseIndex ? {} : {
+                        caseIndex
+                    }
+                }
+            })
+        });
+    const normalizeLifecycle = (phase)=>{
+        const value = parsed[phase];
+        if (void 0 === value) return [];
+        if (!Array.isArray(value)) throw new WorkflowParseError(`Workflow document ${phase} must be an array.`, {
+            phase
+        });
+        return normalizeSteps(value).map((normalized, stepIndex)=>{
+            const resolved = options.resolveNode(normalized.node);
+            if (!resolved) throw new WorkflowParseError(`Workflow document ${phase} step ${stepIndex + 1} references unknown node "${normalized.node}".`, {
+                phase,
+                stepIndex,
+                node: normalized.node
+            });
+            return resolveStepVariables(normalized, phase, stepIndex);
+        });
+    };
+    const lifecycle = {
+        beforeAll: normalizeLifecycle('beforeAll'),
+        beforeEach: normalizeLifecycle('beforeEach'),
+        afterEach: normalizeLifecycle('afterEach'),
+        afterAll: normalizeLifecycle('afterAll')
+    };
+    const ids = new Set();
+    const cases = parsed.cases.map((definition, caseIndex)=>{
+        if (!collect_isMapping(definition)) throw new WorkflowParseError(`Case ${caseIndex + 1} must be a mapping.`, {
+            caseIndex
+        });
+        collect_rejectUnknownKeys(definition, [
+            'name',
+            'tags',
+            'steps'
+        ], `Case ${caseIndex + 1}`);
+        if ('string' != typeof definition.name || 0 === definition.name.trim().length) throw new WorkflowParseError(`Case ${caseIndex + 1} name must be a non-empty string.`, {
+            caseIndex
+        });
+        if (!Array.isArray(definition.steps) || 0 === definition.steps.length) throw new WorkflowParseError(`Case ${caseIndex + 1} steps must be a non-empty array.`, {
+            caseIndex
+        });
+        const tags = definition.tags ?? [];
+        if (!Array.isArray(tags) || tags.some((tag)=>'string' != typeof tag || 0 === tag.trim().length)) throw new WorkflowParseError(`Case ${caseIndex + 1} tags must be an array of non-empty strings.`, {
+            caseIndex
+        });
+        const steps = normalizeSteps(definition.steps).map((normalized, stepIndex)=>{
+            if (!options.resolveNode(normalized.node)) throw new WorkflowParseError(`Case ${caseIndex + 1} step ${stepIndex + 1} references unknown node "${normalized.node}".`, {
+                caseIndex,
+                stepIndex,
+                node: normalized.node
+            });
+            return resolveStepVariables(normalized, 'steps', stepIndex, caseIndex);
+        });
+        const caseId = createCaseId(source.projectId, sourcePath, caseIndex);
+        if (ids.has(caseId)) throw new WorkflowParseError(`Case id collision: ${caseId}.`, {
+            caseId
+        });
+        ids.add(caseId);
+        return {
+            caseId,
+            projectId: source.projectId,
+            sourcePath,
+            caseIndex,
+            definition: {
+                name: definition.name,
+                tags: tags,
+                steps
+            }
+        };
+    });
+    return {
+        documentId: createWorkflowDocumentId(source.projectId, sourcePath),
+        projectId: source.projectId,
+        sourcePath,
+        lifecycle,
+        cases
+    };
+}
+const writeJson = (path, value)=>{
+    mkdirSync(dirname(path), {
+        recursive: true
+    });
+    writeFileSync(path, JSON.stringify(value, null, 2));
+};
+const toPosix = (value)=>value.split(sep).join('/');
+const caseRunResultPath = (result)=>toPosix(join('runs', result.caseId, `${result.runId}.json`));
+const workflowDocumentRunResultPath = (result)=>toPosix(join('documents', result.documentId, `${result.documentRunId}.json`));
+const collectionErrorPath = (projectName, sourcePath)=>{
+    const id = createHash('sha256').update(JSON.stringify([
+        projectName,
+        sourcePath
+    ])).digest('hex');
+    return toPosix(join('collection-errors', `${id}.json`));
+};
+const writeWorkflowDocumentRunResult = (resultDir, result)=>{
+    writeJson(join(resultDir, workflowDocumentRunResultPath(result)), result);
+};
+const writeCaseRunResult = (resultDir, result)=>{
+    writeJson(join(resultDir, caseRunResultPath(result)), result);
+};
+const writeCollectionError = (resultDir, collectionError)=>{
+    writeJson(join(resultDir, collectionErrorPath(collectionError.projectName, collectionError.sourcePath)), {
+        kind: 'collection-error',
+        ...collectionError
+    });
+};
+const relativeToSummary = (summaryPath, target)=>{
+    const value = relative(dirname(summaryPath), target);
+    return toPosix(value || '.');
+};
+const errorJson = (error)=>error instanceof Error && 'toJSON' in error ? error.toJSON() : error;
+const writeTestProjectRunResult = (options)=>{
+    const { result } = options;
+    const fact = (path)=>toPosix(join(relativeToSummary(result.summaryPath, result.resultDir), path));
+    writeJson(result.summaryPath, {
+        schemaVersion: result.schemaVersion,
+        runId: result.runId,
+        startedAt: result.startedAt,
+        endedAt: result.endedAt,
+        durationMs: result.durationMs,
+        status: result.status,
+        exitCode: result.exitCode,
+        projectRoot: options.projectRoot,
+        ...options.configPath ? {
+            configPath: options.configPath
+        } : {},
+        factsRoot: relativeToSummary(result.summaryPath, result.resultDir),
+        reportDir: relativeToSummary(result.summaryPath, result.reportDir),
+        summary: result.summary,
+        projects: result.projects.map((project)=>({
+                name: project.name,
+                platform: project.platform,
+                status: project.status,
+                retry: project.retry,
+                fileSelection: project.fileSelection,
+                tagSelection: project.tagSelection,
+                sourceCount: project.sourceCount,
+                selectedCaseCount: project.selectedCaseCount,
+                filteredCaseCount: project.filteredCaseCount,
+                ...project.lifecycle ? {
+                    lifecycle: {
+                        status: project.lifecycle.status,
+                        startedAt: project.lifecycle.startedAt,
+                        endedAt: project.lifecycle.endedAt,
+                        durationMs: project.lifecycle.durationMs,
+                        ...project.lifecycle.setupError ? {
+                            setupError: errorJson(project.lifecycle.setupError)
+                        } : {},
+                        ...project.lifecycle.teardownErrors ? {
+                            teardownErrors: project.lifecycle.teardownErrors.map(errorJson)
+                        } : {}
+                    }
+                } : {},
+                cases: project.cases.map((outcome)=>({
+                        caseId: outcome.caseId,
+                        sourcePath: outcome.sourcePath,
+                        caseIndex: outcome.caseIndex,
+                        name: outcome.name,
+                        status: outcome.status,
+                        ...outcome.notRunReason ? {
+                            notRunReason: outcome.notRunReason
+                        } : {},
+                        ...outcome.attempts ? {
+                            attempts: outcome.attempts.map((attempt)=>({
+                                    runId: attempt.runId,
+                                    attemptIndex: attempt.attemptIndex,
+                                    status: attempt.status,
+                                    resultFile: fact(caseRunResultPath(attempt)),
+                                    ...attempt.reportPaths?.length ? {
+                                        reports: attempt.reportPaths.map((path)=>relativeToSummary(result.summaryPath, path))
+                                    } : {}
+                                }))
+                        } : {}
+                    })),
+                documents: project.documents.map((document)=>({
+                        documentId: document.documentId,
+                        documentRunId: document.documentRunId,
+                        sourcePath: document.sourcePath,
+                        status: document.status,
+                        resultFile: fact(workflowDocumentRunResultPath(document)),
+                        ...document.reportPaths?.length ? {
+                            reports: document.reportPaths.map((path)=>relativeToSummary(result.summaryPath, path))
+                        } : {}
+                    })),
+                collectionErrors: project.collectionErrors.map((error)=>({
+                        sourcePath: error.sourcePath,
+                        errorFile: fact(collectionErrorPath(error.projectName, error.sourcePath))
+                    }))
+            }))
+    });
+};
+const CONFIG_NAME = 'midscene.config.ts';
+const CONFIG_PREFIX = 'midscene.config.';
+const ALWAYS_IGNORED_PATTERNS = [
+    '.git/**',
+    '.midscene/**',
+    'midscene_run/**',
+    'node_modules/**',
+    '**/.git/**',
+    '**/.midscene/**',
+    '**/midscene_run/**',
+    '**/node_modules/**'
+];
+const DEFAULT_TEST_FILE_SELECTION = {
+    include: [
+        '**/*.{yaml,yml}'
+    ]
+};
+const test_project_runner_toPosix = (value)=>value.split(sep).join('/');
+const discoverTestFiles = (projectRoot, selection = DEFAULT_TEST_FILE_SELECTION)=>{
+    const root = resolve(projectRoot);
+    const normalized = validateTestFileSelection(selection);
+    if (!normalized) throw new TypeError('Test file selection is required.');
+    const files = globSync(normalized.include, {
+        absolute: true,
+        caseSensitiveMatch: false,
+        cwd: root,
+        dot: true,
+        expandDirectories: false,
+        followSymbolicLinks: false,
+        ignore: [
+            ...ALWAYS_IGNORED_PATTERNS,
+            ...normalized.exclude ?? []
+        ],
+        onlyFiles: true
+    }).filter((file)=>/\.ya?ml$/i.test(file));
+    return [
+        ...new Set(files.map((file)=>resolve(file)))
+    ].sort((a, b)=>{
+        const relativeA = test_project_runner_toPosix(relative(root, a));
+        const relativeB = test_project_runner_toPosix(relative(root, b));
+        return relativeA < relativeB ? -1 : relativeA > relativeB ? 1 : 0;
+    });
+};
+const discoverTestConfig = (projectRoot)=>{
+    const root = resolve(projectRoot);
+    const candidates = readdirSync(root).filter((name)=>name.startsWith(CONFIG_PREFIX)).sort();
+    const unsupported = candidates.filter((name)=>name !== CONFIG_NAME);
+    if (unsupported.length > 0) throw new Error([
+        `Unsupported or conflicting Midscene configs found in ${root}:`,
+        ...candidates.map((name)=>`- ${name}`),
+        `Only ${CONFIG_NAME} is supported.`
+    ].join('\n'));
+    return candidates.includes(CONFIG_NAME) ? join(root, CONFIG_NAME) : void 0;
+};
+const defaultResultDir = (projectRoot)=>join(projectRoot, '.midscene', 'test-results', `${Date.now()}-${process.pid}`);
+const assertDirectory = (path, label)=>{
+    if (!existsSync(path) || !statSync(path).isDirectory()) throw new Error(`${label} does not exist or is not a directory: ${path}`);
+};
+const asCollectionError = (projectName, sourcePath, error)=>({
+        projectName,
+        sourcePath,
+        error: error instanceof WorkflowError ? error : new WorkflowParseError(`Failed to collect workflow document "${sourcePath}": ${error instanceof Error ? error.message : String(error)}`, {
+            projectName,
+            sourcePath
+        }, error)
+    });
+const matchesTags = (tags, selection)=>{
+    if (selection.exclude.some((tag)=>tags.includes(tag))) return false;
+    return 0 === selection.include.length || selection.include.some((tag)=>tags.includes(tag));
+};
+const filterDocumentCases = (document, project)=>{
+    const cases = document.cases.filter((item)=>matchesTags(item.definition.tags ?? [], project.tags));
+    const filtered = document.cases.length - cases.length;
+    return 0 === cases.length ? {
+        filtered
+    } : {
+        document: {
+            ...document,
+            cases
+        },
+        filtered
+    };
+};
+const test_project_runner_asNotRun = (collectedCase, projectName, reason)=>({
+        caseId: collectedCase.caseId,
+        projectName,
+        name: collectedCase.definition.name,
+        sourcePath: collectedCase.sourcePath,
+        caseIndex: collectedCase.caseIndex,
+        status: 'not-run',
+        notRunReason: reason
+    });
+const summarize = (projects)=>{
+    const cases = projects.flatMap((project)=>project.cases);
+    const documents = projects.flatMap((project)=>project.documents);
+    return {
+        total: cases.length,
+        passed: cases.filter((item)=>'success' === item.status).length,
+        failed: cases.filter((item)=>'failed' === item.status).length,
+        notRun: cases.filter((item)=>'not-run' === item.status).length,
+        filtered: projects.reduce((total, project)=>total + project.filteredCaseCount, 0),
+        collectionErrors: projects.reduce((total, project)=>total + project.collectionErrors.length, 0),
+        documentFailures: documents.filter((document)=>'failed' === document.status).length,
+        projectFailures: projects.filter((project)=>'failed' === project.status).length
+    };
+};
+const stepPosition = (info)=>'case' === info.scope ? info.case : info.document;
+const test_project_runner_formatStep = (info)=>{
+    const position = stepPosition(info);
+    const phase = 'steps' === position.phase ? 'step' : position.phase;
+    return `${phase} ${position.stepIndex + 1}/${info.stepCount}: ${info.node}`;
+};
+const formatStepResult = (info, result)=>{
+    const indent = 'case' === info.scope ? '      ' : '    ';
+    const symbol = 'success' === result.status ? '✓' : '✗';
+    const error = result.error ? ` — ${result.error.message}` : '';
+    const continuation = result.continuedAfterError ? '; continuing' : '';
+    return `${indent}${symbol} ${test_project_runner_formatStep(info)} (${result.durationMs} ms)${error}${continuation}`;
+};
+const caseHasFatalError = (outcome)=>(outcome.attempts ?? []).some((attempt)=>[
+            ...attempt.beforeEach,
+            ...attempt.steps,
+            ...attempt.afterEach
+        ].some((step)=>step.error && isFatalDeviceError(step.error)) || (attempt.teardownErrors ?? []).some(isFatalDeviceError));
+const selectProjects = (projects, names)=>{
+    if (!names || 0 === names.length) return projects;
+    const requested = new Set(names);
+    if (requested.size !== names.length) throw new Error('Each --project name may only be specified once.');
+    const known = new Set(projects.map((project)=>project.name));
+    const unknown = names.find((name)=>!known.has(name));
+    if (unknown) throw new Error(`Unknown Midscene project: ${unknown}`);
+    return projects.filter((project)=>requested.has(project.name));
+};
+const prepareProject = (project, projectRoot, resolveNode, resultDir)=>{
+    const fileSelection = project.files ?? DEFAULT_TEST_FILE_SELECTION;
+    const files = discoverTestFiles(projectRoot, fileSelection);
+    const sources = files.map((absolutePath)=>({
+            projectId: project.name,
+            sourcePath: test_project_runner_toPosix(relative(projectRoot, absolutePath)),
+            absolutePath
+        }));
+    const collectionErrors = [];
+    const documents = [];
+    let filteredCaseCount = 0;
+    if (0 === sources.length) {
+        const error = asCollectionError(project.name, '<project>', new WorkflowParseError(`No workflow YAML files found for project "${project.name}" in ${projectRoot}.`, {
+            projectName: project.name,
+            projectRoot
+        }));
+        collectionErrors.push(error);
+        writeCollectionError(resultDir, error);
+    }
+    for (const source of sources)try {
+        const collected = collectWorkflowDocument(source, {
+            resolveNode,
+            variables: project.variables,
+            env: process.env
+        });
+        const filtered = filterDocumentCases(collected, project);
+        filteredCaseCount += filtered.filtered;
+        if (filtered.document) documents.push(filtered.document);
+    } catch (error) {
+        const collectionError = asCollectionError(project.name, source.sourcePath, error);
+        collectionErrors.push(collectionError);
+        writeCollectionError(resultDir, collectionError);
+    }
+    return {
+        project,
+        fileSelection,
+        sources,
+        documents,
+        collectionErrors,
+        selectedCaseCount: documents.reduce((total, document)=>total + document.cases.length, 0),
+        filteredCaseCount
+    };
+};
+const notRunSuite = (prepared, reason)=>prepared.documents.flatMap((document)=>document.cases.map((item)=>test_project_runner_asNotRun(item, prepared.project.name, reason)));
+async function runTestProject(options = {}) {
+    const startedAt = new Date();
+    const runId = randomUUID();
+    const cwd = resolve(options.cwd ?? process.cwd());
+    assertDirectory(cwd, 'Test working directory');
+    const cliProjectRoot = options.projectRoot ? resolve(cwd, options.projectRoot) : void 0;
+    if (cliProjectRoot) assertDirectory(cliProjectRoot, 'Test project directory');
+    const configSearchRoot = cliProjectRoot ?? cwd;
+    const configPath = options.configPath ? resolve(configSearchRoot, options.configPath) : discoverTestConfig(configSearchRoot);
+    if (options.configPath && (!configPath || !existsSync(configPath))) throw new Error(`Midscene config does not exist: ${configPath}`);
+    const definition = await loadTestProject(configPath);
+    const projectRoot = cliProjectRoot ?? cwd;
+    const resultDir = options.resultDir ? resolve(cwd, options.resultDir) : defaultResultDir(projectRoot);
+    const summaryPath = resolve(projectRoot, definition.output.summary);
+    const reportDir = resolve(projectRoot, definition.output.reportDir);
+    mkdirSync(resultDir, {
+        recursive: true
+    });
+    mkdirSync(reportDir, {
+        recursive: true
+    });
+    const selectedProjects = selectProjects(definition.projects, options.projectNames);
+    const preparedProjects = selectedProjects.map((project)=>prepareProject(project, projectRoot, definition.resolveNode, resultDir));
+    const progress = options.onProgress ?? (()=>{});
+    const totalDocuments = preparedProjects.reduce((total, prepared)=>total + prepared.documents.length, 0);
+    const totalCases = preparedProjects.reduce((total, prepared)=>total + prepared.selectedCaseCount, 0);
+    const totalErrors = preparedProjects.reduce((total, prepared)=>total + prepared.collectionErrors.length, 0);
+    progress(`midscene-test: preflighted ${preparedProjects.length} projects, ${totalDocuments} documents, ${totalCases} cases, ${totalErrors} collection errors`);
+    const rootController = new AbortController();
+    const handleSignal = (signal)=>{
+        rootController.abort(new Error(`Workflow interrupted by ${signal}.`));
+    };
+    const sigint = ()=>handleSignal('SIGINT');
+    const sigterm = ()=>handleSignal('SIGTERM');
+    process.on('SIGINT', sigint);
+    process.on('SIGTERM', sigterm);
+    const projectResults = [];
+    let failedCaseCount = 0;
+    const bailReached = ()=>definition.test.bail > 0 && failedCaseCount >= definition.test.bail;
+    try {
+        for (const [projectIndex, prepared] of preparedProjects.entries()){
+            const { project } = prepared;
+            progress(`[project ${projectIndex + 1}/${preparedProjects.length}] ${project.name} (${project.platform})`);
+            const cases = [];
+            const documents = [];
+            let lifecycle;
+            let projectFatal = false;
+            if (prepared.collectionErrors.length > 0) cases.push(...notRunSuite(prepared, 'project-preflight-failed'));
+            else if (rootController.signal.aborted) cases.push(...notRunSuite(prepared, 'interrupted'));
+            else if (bailReached()) cases.push(...notRunSuite(prepared, 'bail'));
+            else {
+                const runtime = createProjectRuntime({
+                    project,
+                    setup: project.setup,
+                    signal: rootController.signal
+                });
+                let projectExecutionError;
+                try {
+                    await runtime.start();
+                    if (runtime.canRun) for (const [documentIndex, document] of prepared.documents.entries()){
+                        if (rootController.signal.aborted || bailReached() || projectFatal) {
+                            const reason = rootController.signal.aborted ? 'interrupted' : projectFatal ? 'fatal-error' : 'bail';
+                            cases.push(...document.cases.map((item)=>test_project_runner_asNotRun(item, project.name, reason)));
+                            continue;
+                        }
+                        progress(`  [document ${documentIndex + 1}/${prepared.documents.length}] ${document.sourcePath}`);
+                        const execution = await runWorkflowDocument(document, {
+                            resolveNode: definition.nodes.require.bind(definition.nodes),
+                            project,
+                            projectContext: runtime.context,
+                            retry: project.retry,
+                            signal: runtime.signal,
+                            defaultTimeoutMs: definition.test.testTimeout,
+                            shouldStop: ()=>rootController.signal.aborted || bailReached() || projectFatal,
+                            stopReason: ()=>rootController.signal.aborted ? 'interrupted' : projectFatal ? 'fatal-error' : 'bail',
+                            isFatalError: (run)=>[
+                                    ...run.beforeEach,
+                                    ...run.steps,
+                                    ...run.afterEach
+                                ].some((step)=>step.error && isFatalDeviceError(step.error)) || (run.teardownErrors ?? []).some(isFatalDeviceError),
+                            onCaseStart: (collectedCase)=>{
+                                progress(`    [case ${collectedCase.caseIndex + 1}/${document.cases.length}] ${collectedCase.definition.name}`);
+                            },
+                            onStepStart: (info)=>{
+                                const indent = 'case' === info.scope ? '      ' : '    ';
+                                progress(`${indent}→ ${test_project_runner_formatStep(info)}`);
+                            },
+                            onStepResult: (info, result)=>progress(formatStepResult(info, result)),
+                            onCaseResult: (attempt)=>{
+                                writeCaseRunResult(resultDir, attempt);
+                                progress(`    ${'success' === attempt.status ? '✓' : '✗'} attempt ${attempt.attemptIndex + 1}/${project.retry + 1}: ${attempt.name} (${attempt.durationMs} ms)`);
+                            },
+                            onCaseOutcome: (outcome)=>{
+                                if ('failed' === outcome.status) failedCaseCount += 1;
+                                if (caseHasFatalError(outcome)) projectFatal = true;
+                            },
+                            onDocumentResult: (documentResult)=>writeWorkflowDocumentRunResult(resultDir, documentResult)
+                        });
+                        cases.push(...execution.cases);
+                        documents.push(execution.document);
+                    }
+                    else cases.push(...notRunSuite(prepared, rootController.signal.aborted ? 'interrupted' : 'project-setup-failed'));
+                } catch (error) {
+                    projectExecutionError = error;
+                } finally{
+                    const hasFailure = void 0 !== projectExecutionError || cases.some((item)=>'success' !== item.status) || documents.some((item)=>'failed' === item.status) || projectFatal || rootController.signal.aborted;
+                    lifecycle = await runtime.finish(hasFailure ? 'failed' : 'success');
+                }
+                if (projectExecutionError) throw projectExecutionError;
+            }
+            const projectFailed = prepared.collectionErrors.length > 0 || cases.some((item)=>'success' !== item.status) || documents.some((item)=>'failed' === item.status) || lifecycle?.status === 'failed';
+            projectResults.push({
+                name: project.name,
+                platform: project.platform,
+                status: projectFailed ? 'failed' : 'success',
+                retry: project.retry,
+                fileSelection: prepared.fileSelection,
+                tagSelection: project.tags,
+                sourceCount: prepared.sources.length,
+                selectedCaseCount: prepared.selectedCaseCount,
+                filteredCaseCount: prepared.filteredCaseCount,
+                ...lifecycle ? {
+                    lifecycle
+                } : {},
+                cases,
+                documents,
+                collectionErrors: prepared.collectionErrors
+            });
+        }
+    } finally{
+        process.off('SIGINT', sigint);
+        process.off('SIGTERM', sigterm);
+    }
+    const summary = summarize(projectResults);
+    const failed = rootController.signal.aborted || summary.failed > 0 || summary.notRun > 0 || summary.collectionErrors > 0 || summary.documentFailures > 0 || summary.projectFailures > 0;
+    const endedAt = new Date();
+    const result = {
+        schemaVersion: 1,
+        runId,
+        startedAt: startedAt.toISOString(),
+        endedAt: endedAt.toISOString(),
+        durationMs: Math.max(0, endedAt.getTime() - startedAt.getTime()),
+        status: failed ? 'failed' : 'success',
+        exitCode: failed ? 1 : 0,
+        resultDir,
+        summaryPath,
+        reportDir,
+        summary,
+        projects: projectResults,
+        cases: projectResults.flatMap((project)=>project.cases),
+        documents: projectResults.flatMap((project)=>project.documents),
+        collectionErrors: projectResults.flatMap((project)=>project.collectionErrors)
+    };
+    writeTestProjectRunResult({
+        projectRoot,
+        ...configPath ? {
+            configPath
+        } : {},
+        result
+    });
+    return result;
+}
+export { DEFAULT_TEST_FILE_SELECTION, defineProjectSetup, defineTestProject, discoverTestConfig, discoverTestFiles, loadTestProject, runTestProject, validateTestFileSelection };
+
+//# sourceMappingURL=index.mjs.map