agent-scenario-loop 0.1.0

package/dist/runner/agent-device.js

@@ -0,0 +1,1271 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentDeviceDriverActionCode = agentDeviceDriverActionCode;
+exports.buildAgentDeviceHealth = buildAgentDeviceHealth;
+exports.buildAgentDeviceVerdict = buildAgentDeviceVerdict;
+exports.buildAgentDeviceSelectorHealthMetadata = buildAgentDeviceSelectorHealthMetadata;
+exports.checkAgentDeviceAvailability = checkAgentDeviceAvailability;
+exports.defaultAgentDeviceCaptureFileName = defaultAgentDeviceCaptureFileName;
+exports.defaultAgentDeviceRawFileName = defaultAgentDeviceRawFileName;
+exports.execFileCommand = execFileCommand;
+exports.execFileCommandWithTimeout = execFileCommandWithTimeout;
+exports.isAgentDeviceSelector = isAgentDeviceSelector;
+exports.main = main;
+exports.parseArgs = parseArgs;
+exports.parseAgentDeviceSessionMode = parseAgentDeviceSessionMode;
+exports.parseRequiredPlatforms = parseRequiredPlatforms;
+exports.readAgentDeviceSessions = readAgentDeviceSessions;
+exports.readAgentDeviceStepOptions = readAgentDeviceStepOptions;
+exports.resolveAgentDeviceDriverSteps = resolveAgentDeviceDriverSteps;
+exports.runAgentDeviceCapture = runAgentDeviceCapture;
+exports.runAgentDeviceDriverStep = runAgentDeviceDriverStep;
+exports.usage = usage;
+exports.validateAgentDeviceDriverSteps = validateAgentDeviceDriverSteps;
+exports.writeAgentDeviceAvailabilityArtifacts = writeAgentDeviceAvailabilityArtifacts;
+const { execFile } = require('node:child_process');
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const { buildAgentSummaryMarkdown } = require('../core/agent-summary');
+const { createArtifactLayout } = require('../core/artifact-layout');
+const { writeJsonArtifact, writeTextArtifact } = require('../core/artifact-writer');
+const { buildScenarioExecutionPlan } = require('../core/execution-plan');
+const { SCHEMAS, assertValidJson } = require('../core/schema-validator');
+const { hasHelpFlag, writeUsage } = require('./cli');
+const { createAgentDeviceDriver, formatAgentDeviceRawOutput, } = require('./agent-device-driver');
+const { loadAslLocalEnv, readStringArgOrEnv } = require('./local-env');
+const DEFAULT_AGENT_DEVICE_REQUIRED_COMMANDS = [
+    'open',
+    'snapshot',
+    'screenshot',
+    'is',
+    'click',
+    'scroll',
+    'logs',
+    'devices',
+    'session list',
+];
+/**
+ * Prints CLI usage.
+ *
+ * @returns {void}
+ */
+function usage(output = process.stderr) {
+    writeUsage([
+        'Usage: asl-agent-device --platform <ios|android> --scenario <path> [--out <dir>] [--run-id <id>]',
+        '',
+        'Executes scenario-declared portable driver actions through the external agent-device CLI.',
+        'Writes health.json, verdict.json, agent-summary.md, raw command transcripts, and capture artifacts.',
+        'Use --check --out <dir> to verify the configured agent-device command surface and preserve availability artifacts.',
+        'Use --open --app <bundle-or-package> to open the app before running driver actions.',
+        'Use --udid <id> for iOS simulators or --serial <id> for Android devices.',
+        'Use --session <name> [--session-mode reuse|bind] to reuse an existing session or bind a named session to direct target flags.',
+        'Use --command-timeout-ms <ms> to bound each external agent-device invocation.',
+        'Use --require-platforms ios,android with --check when device discovery must prove booted OS targets.',
+    ], output);
+}
+/**
+ * Parses `--key value` CLI arguments.
+ *
+ * @param {string[]} argv
+ * @returns {CliArgs}
+ */
+function parseArgs(argv) {
+    const args = {};
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === '--') {
+            continue;
+        }
+        if (!token?.startsWith('--')) {
+            continue;
+        }
+        const key = token.slice(2);
+        const value = argv[index + 1];
+        if (value && !value.startsWith('--')) {
+            args[key] = value;
+            index += 1;
+        }
+        else {
+            args[key] = true;
+        }
+    }
+    return args;
+}
+/**
+ * Reads and parses a JSON object from disk.
+ *
+ * @param {string} filePath
+ * @returns {Record<string, unknown>}
+ */
+function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+/**
+ * Checks whether a boolean-style flag is enabled.
+ *
+ * @param {string | boolean | undefined} value
+ * @returns {boolean}
+ */
+function isEnabled(value) {
+    return value === true || value === 'true';
+}
+/**
+ * Reads a positive integer from CLI or scenario metadata.
+ *
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function readPositiveInteger(value, fallback) {
+    const parsed = typeof value === 'string' ? Number(value) : value;
+    return typeof parsed === 'number' && Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+/**
+ * Reads a finite number from adapter metadata.
+ *
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+function readFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Creates a short random run id.
+ *
+ * @returns {string}
+ */
+function createRunId() {
+    return crypto.randomBytes(6).toString('hex');
+}
+/**
+ * Runs a command and captures stdout, stderr, and exit code without throwing.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<CommandResult>}
+ */
+function execFileCommand(command, args) {
+    return execFileCommandWithTimeout(command, args);
+}
+/**
+ * Runs a command with a bounded timeout and captures stdout, stderr, and exit code without throwing.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @param {number} [timeoutMs]
+ * @returns {Promise<CommandResult>}
+ */
+function execFileCommandWithTimeout(command, args, timeoutMs = 60_000) {
+    return new Promise((resolve) => {
+        execFile(command, args, { timeout: timeoutMs }, (error, stdout, stderr) => {
+            resolve({
+                command,
+                args,
+                exitCode: error && typeof error.code === 'number' ? error.code : error ? 1 : 0,
+                stderr: [
+                    stderr,
+                    error?.killed || error?.signal === 'SIGTERM' ? `agent-device command timed out after ${timeoutMs}ms.` : '',
+                ].filter(Boolean).join('\n'),
+                stdout,
+            });
+        });
+    });
+}
+/**
+ * Returns a compact single-line preview for command diagnostics.
+ *
+ * @param {string} value
+ * @returns {string | undefined}
+ */
+function previewCommandOutput(value) {
+    const preview = value.replace(/\s+/gu, ' ').trim();
+    return preview.length > 240 ? `${preview.slice(0, 237)}...` : preview || undefined;
+}
+/**
+ * Classifies an agent-device availability failure into the next operational step.
+ *
+ * @param {CommandResult} result
+ * @returns {Record<string, string>}
+ */
+function classifyAgentDeviceAvailabilityFailure(result) {
+    const diagnostic = `${result.stderr}\n${result.stdout}`;
+    if (/operation not permitted|permission denied|sandbox|eacces|eperm|daemon|\.agent-device|cannot bind|smartsocket/iu.test(diagnostic)) {
+        return {
+            failureClass: 'host_access',
+            nextAction: 'Rerun agent-device availability with host/device access before treating this as an app, scenario, or runner regression.',
+            nextActionCode: 'rerun_with_host_access',
+        };
+    }
+    if (/timed out|timeout/iu.test(diagnostic)) {
+        return {
+            failureClass: 'timeout',
+            nextAction: 'Confirm agent-device can run without prompts, increase --command-timeout-ms if it is legitimately slow, then rerun the availability check.',
+            nextActionCode: 'increase_agent_device_timeout',
+        };
+    }
+    if (/enoent|not found|command not found|no such file or directory/iu.test(diagnostic)) {
+        return {
+            failureClass: 'missing_binary',
+            nextAction: 'Install agent-device or pass the correct binary with --agent-device before starting live proof.',
+            nextActionCode: 'configure_agent_device_binary',
+        };
+    }
+    return {
+        failureClass: 'command_surface',
+        nextAction: 'Inspect the failed agent-device command output, fix the command surface, then rerun the availability check before starting live proof.',
+        nextActionCode: 'inspect_agent_device_availability',
+    };
+}
+/**
+ * Parses a comma-separated platform requirement list for availability checks.
+ *
+ * @param {unknown} value
+ * @returns {import('./agent-device-driver').AgentDevicePlatform[]}
+ */
+function parseRequiredPlatforms(value) {
+    if (typeof value !== 'string') {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((platform) => platform.trim())
+        .filter((platform) => ['android', 'apple', 'ios', 'linux', 'macos'].includes(platform));
+}
+/**
+ * Parses how a named agent-device session should participate in target selection.
+ *
+ * @param {unknown} value
+ * @returns {AgentDeviceSessionMode}
+ */
+function parseAgentDeviceSessionMode(value) {
+    if (value === undefined || value === false) {
+        return 'reuse';
+    }
+    if (value === 'bind' || value === 'reuse') {
+        return value;
+    }
+    throw new Error('--session-mode must be either reuse or bind.');
+}
+/**
+ * Builds one availability check result from an agent-device command execution.
+ *
+ * @param {{code: string, expectedPattern: RegExp, name: string, result: CommandResult}} options
+ * @returns {AgentDeviceAvailabilityCheck}
+ */
+function buildAgentDeviceAvailabilityCheck({ code, expectedPattern, name, result, }) {
+    const output = `${result.stdout}\n${result.stderr}`;
+    const passed = result.exitCode === 0 && expectedPattern.test(output);
+    const check = {
+        args: result.args,
+        code,
+        command: result.command,
+        exitCode: result.exitCode,
+        message: passed ? `${name} is available.` : `${name} did not return the expected agent-device output.`,
+        name,
+        status: passed ? 'passed' : 'failed',
+    };
+    if (!passed) {
+        const stderrPreview = previewCommandOutput(result.stderr);
+        const stdoutPreview = previewCommandOutput(result.stdout);
+        check.metadata = classifyAgentDeviceAvailabilityFailure(result);
+        if (stderrPreview) {
+            check.stderrPreview = stderrPreview;
+        }
+        if (stdoutPreview) {
+            check.stdoutPreview = stdoutPreview;
+        }
+    }
+    return check;
+}
+/**
+ * Parses agent-device device discovery JSON.
+ *
+ * @param {CommandResult} result
+ * @returns {Array<Record<string, unknown>>}
+ */
+function readAgentDeviceDiscoveryDevices(result) {
+    if (result.exitCode !== 0 || result.stdout.trim().length === 0) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const data = parsed.data && typeof parsed.data === 'object' && !Array.isArray(parsed.data)
+            ? parsed.data
+            : null;
+        return Array.isArray(data?.devices)
+            ? data.devices.filter((device) => Boolean(device) && typeof device === 'object' && !Array.isArray(device))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Parses agent-device active session JSON.
+ *
+ * @param {CommandResult} result
+ * @returns {Array<Record<string, unknown>>}
+ */
+function readAgentDeviceSessions(result) {
+    if (result.exitCode !== 0 || result.stdout.trim().length === 0) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const data = parsed.data && typeof parsed.data === 'object' && !Array.isArray(parsed.data)
+            ? parsed.data
+            : parsed;
+        const sessions = Array.isArray(data.sessions)
+            ? data.sessions
+            : Array.isArray(parsed.sessions)
+                ? parsed.sessions
+                : [];
+        return sessions.filter((session) => Boolean(session) && typeof session === 'object' && !Array.isArray(session));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Formats active agent-device sessions for compact health metadata.
+ *
+ * @param {Array<Record<string, unknown>>} sessions
+ * @returns {string}
+ */
+function summarizeAgentDeviceSessions(sessions) {
+    return sessions
+        .slice(0, 8)
+        .map((session, index) => {
+        const name = typeof session.name === 'string'
+            ? session.name
+            : typeof session.id === 'string'
+                ? session.id
+                : `session-${index + 1}`;
+        const platform = typeof session.platform === 'string' ? session.platform : null;
+        const target = typeof session.target === 'string' ? session.target : null;
+        const device = typeof session.device === 'string'
+            ? session.device
+            : typeof session.deviceId === 'string'
+                ? session.deviceId
+                : typeof session.udid === 'string'
+                    ? session.udid
+                    : typeof session.serial === 'string'
+                        ? session.serial
+                        : null;
+        return [name, platform, target, device].filter(Boolean).join(':');
+    })
+        .join(', ');
+}
+/**
+ * Returns the stable session name that agent-device accepts.
+ *
+ * @param {Record<string, unknown>} session
+ * @returns {string | null}
+ */
+function readAgentDeviceSessionName(session) {
+    return typeof session.name === 'string' && session.name.length > 0
+        ? session.name
+        : typeof session.id === 'string' && session.id.length > 0
+            ? session.id
+            : null;
+}
+/**
+ * Returns known device identifiers attached to one agent-device session.
+ *
+ * @param {Record<string, unknown>} session
+ * @returns {string[]}
+ */
+function readAgentDeviceSessionTargets(session) {
+    return [
+        session.id,
+        session.deviceId,
+        session.device_id,
+        session.device_udid,
+        session.serial,
+        session.udid,
+    ].filter((value) => typeof value === 'string' && value.length > 0);
+}
+/**
+ * Selects a single active session for the requested platform and device target.
+ *
+ * @param {{platform: import('./agent-device-driver').AgentDevicePlatform, requestedTarget: string | null, sessions: Array<Record<string, unknown>>, target: string}} options
+ * @returns {string | null}
+ */
+function selectAgentDeviceSession({ platform, requestedTarget, sessions, target, }) {
+    const platformCandidates = sessions.filter((session) => session.platform === platform &&
+        (typeof session.target !== 'string' || session.target === target));
+    const targetCandidates = requestedTarget
+        ? platformCandidates.filter((session) => readAgentDeviceSessionTargets(session).includes(requestedTarget))
+        : platformCandidates;
+    if (targetCandidates.length !== 1) {
+        return null;
+    }
+    const [selectedSession] = targetCandidates;
+    return selectedSession ? readAgentDeviceSessionName(selectedSession) : null;
+}
+/**
+ * Builds an agent-readable availability addendum with device and session counts.
+ *
+ * @param {AgentDeviceAvailabilityResult} result
+ * @returns {string}
+ */
+function buildAgentDeviceAvailabilitySummary(result) {
+    const sessionSummary = summarizeAgentDeviceSessions(result.sessions);
+    return [
+        '',
+        '## agent-device availability',
+        '',
+        `- Devices: ${result.devices.length}`,
+        `- Active sessions: ${result.sessions.length}`,
+        ...(sessionSummary ? [`- Session hints: ${sessionSummary}`] : []),
+        '',
+    ].join('\n');
+}
+/**
+ * Checks whether device discovery found a booted mobile target for one platform.
+ *
+ * @param {Array<Record<string, unknown>>} devices
+ * @param {import('./agent-device-driver').AgentDevicePlatform} platform
+ * @returns {boolean}
+ */
+function hasBootedMobilePlatform(devices, platform) {
+    return devices.some((device) => device.platform === platform &&
+        device.target === 'mobile' &&
+        device.booted === true);
+}
+/**
+ * Verifies that the configured agent-device command exposes ASL-required surfaces.
+ *
+ * @param {AgentDeviceAvailabilityOptions} options
+ * @returns {Promise<AgentDeviceAvailabilityResult>}
+ */
+async function checkAgentDeviceAvailability({ agentDevicePath = 'agent-device', commandTimeoutMs = 30_000, executor, requiredCommands = DEFAULT_AGENT_DEVICE_REQUIRED_COMMANDS, requiredPlatforms = [], } = {}) {
+    const run = executor ?? ((command, args) => execFileCommandWithTimeout(command, args, commandTimeoutMs));
+    const checks = [];
+    const help = await run(agentDevicePath, ['--help']);
+    checks.push(buildAgentDeviceAvailabilityCheck({
+        code: 'agent_device_help_available',
+        expectedPattern: /CLI to control iOS and Android devices/u,
+        name: 'agent_device_help',
+        result: help,
+    }));
+    for (const commandName of requiredCommands) {
+        const commandLabel = commandName.replace(/\s+/gu, '_');
+        const pattern = commandName === 'session list'
+            ? /\bsession\s+list\b/u
+            : new RegExp(`\\b${commandName.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')}\\b`, 'u');
+        checks.push(buildAgentDeviceAvailabilityCheck({
+            code: `agent_device_command_${commandLabel}_available`,
+            expectedPattern: pattern,
+            name: `agent_device_command_${commandLabel}`,
+            result: help,
+        }));
+    }
+    const devicesResult = await run(agentDevicePath, ['devices', '--json']);
+    const devices = readAgentDeviceDiscoveryDevices(devicesResult);
+    const discoveryPassed = devicesResult.exitCode === 0 && devices.length > 0;
+    const devicesCheck = {
+        args: devicesResult.args,
+        code: 'agent_device_devices_available',
+        command: devicesResult.command,
+        exitCode: devicesResult.exitCode,
+        message: discoveryPassed
+            ? `agent-device discovered ${devices.length} device(s).`
+            : 'agent-device did not return any discoverable devices.',
+        name: 'agent_device_devices',
+        status: discoveryPassed ? 'passed' : 'failed',
+    };
+    if (!discoveryPassed) {
+        const stderrPreview = previewCommandOutput(devicesResult.stderr);
+        const stdoutPreview = previewCommandOutput(devicesResult.stdout);
+        devicesCheck.metadata = classifyAgentDeviceAvailabilityFailure(devicesResult);
+        if (stderrPreview) {
+            devicesCheck.stderrPreview = stderrPreview;
+        }
+        if (stdoutPreview) {
+            devicesCheck.stdoutPreview = stdoutPreview;
+        }
+    }
+    checks.push(devicesCheck);
+    const sessionsResult = await run(agentDevicePath, ['session', 'list', '--json']);
+    const sessions = readAgentDeviceSessions(sessionsResult);
+    const sessionsPassed = sessionsResult.exitCode === 0;
+    const sessionsCheck = {
+        args: sessionsResult.args,
+        code: 'agent_device_sessions_available',
+        command: sessionsResult.command,
+        exitCode: sessionsResult.exitCode,
+        message: sessionsPassed
+            ? `agent-device reported ${sessions.length} active session(s).`
+            : 'agent-device could not list active sessions.',
+        metadata: {
+            sessionCount: sessions.length,
+            ...(sessions.length > 0 ? { activeSessions: summarizeAgentDeviceSessions(sessions) } : {}),
+        },
+        name: 'agent_device_sessions',
+        status: sessionsPassed ? 'passed' : 'failed',
+    };
+    if (!sessionsPassed) {
+        const stderrPreview = previewCommandOutput(sessionsResult.stderr);
+        const stdoutPreview = previewCommandOutput(sessionsResult.stdout);
+        sessionsCheck.metadata = {
+            ...sessionsCheck.metadata,
+            ...classifyAgentDeviceAvailabilityFailure(sessionsResult),
+        };
+        if (stderrPreview) {
+            sessionsCheck.stderrPreview = stderrPreview;
+        }
+        if (stdoutPreview) {
+            sessionsCheck.stdoutPreview = stdoutPreview;
+        }
+    }
+    checks.push(sessionsCheck);
+    for (const platform of requiredPlatforms) {
+        const passed = hasBootedMobilePlatform(devices, platform);
+        checks.push({
+            args: devicesResult.args,
+            code: `agent_device_booted_${platform}_available`,
+            command: devicesResult.command,
+            exitCode: devicesResult.exitCode,
+            message: passed
+                ? `agent-device discovered a booted ${platform} mobile target.`
+                : `agent-device did not discover a booted ${platform} mobile target.`,
+            name: `agent_device_booted_${platform}`,
+            status: passed ? 'passed' : 'failed',
+        });
+    }
+    const status = checks.every((check) => check.status === 'passed') ? 'passed' : 'failed';
+    return {
+        agentDevicePath,
+        checks,
+        devices,
+        requiredCommands,
+        requiredPlatforms,
+        sessions,
+        status,
+    };
+}
+/**
+ * Waits for the requested capture window.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function delay(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/**
+ * Creates scalar health-check metadata for an agent-readable next action.
+ *
+ * @param {string} nextActionCode
+ * @param {string} nextAction
+ * @returns {NextActionHint}
+ */
+function nextActionHint(nextActionCode, nextAction) {
+    return {
+        nextAction,
+        nextActionCode,
+    };
+}
+/**
+ * Normalizes CLI diagnostic text into scalar health metadata.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeAgentDeviceDiagnosticText(value) {
+    return value.replace(/\s+/gu, ' ').trim().slice(0, 500);
+}
+/**
+ * Reads structured agent-device JSON errors from stdout or stderr.
+ *
+ * @param {{stdout: string, stderr: string}} result
+ * @returns {AgentDeviceErrorMetadata}
+ */
+function readAgentDeviceErrorMetadata(result) {
+    for (const content of [result.stdout, result.stderr]) {
+        const trimmed = content.trim();
+        if (!trimmed.startsWith('{')) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            const error = parsed.error && typeof parsed.error === 'object' && !Array.isArray(parsed.error)
+                ? parsed.error
+                : null;
+            if (!error) {
+                continue;
+            }
+            return {
+                ...(typeof error.code === 'string'
+                    ? { agentDeviceErrorCode: normalizeAgentDeviceDiagnosticText(error.code) }
+                    : {}),
+                ...(typeof error.message === 'string'
+                    ? { agentDeviceErrorMessage: normalizeAgentDeviceDiagnosticText(error.message) }
+                    : {}),
+                ...(typeof error.hint === 'string'
+                    ? { agentDeviceErrorHint: normalizeAgentDeviceDiagnosticText(error.hint) }
+                    : {}),
+                ...(typeof error.diagnosticId === 'string'
+                    ? { agentDeviceDiagnosticId: normalizeAgentDeviceDiagnosticText(error.diagnosticId) }
+                    : {}),
+            };
+        }
+        catch {
+            continue;
+        }
+    }
+    return {};
+}
+/**
+ * Reads a quoted agent-device session name from a diagnostic message.
+ *
+ * @param {string | undefined} message
+ * @returns {string | null}
+ */
+function readDiagnosticSessionName(message) {
+    if (!message) {
+        return null;
+    }
+    return /session "([^"]+)"/u.exec(message)?.[1] ?? null;
+}
+/**
+ * Builds the most specific next-action hint available from an agent-device failure.
+ *
+ * @param {AgentDeviceFailureHintOptions} options
+ * @returns {NextActionHint}
+ */
+function buildAgentDeviceFailureHint({ defaultNextAction, defaultNextActionCode, errorMetadata, rawFileName, }) {
+    const errorCode = errorMetadata.agentDeviceErrorCode;
+    const errorMessage = errorMetadata.agentDeviceErrorMessage;
+    const sessionName = readDiagnosticSessionName(errorMessage);
+    if (errorCode === 'DEVICE_IN_USE') {
+        return nextActionHint('reuse_agent_device_session', sessionName
+            ? `Device is already owned by agent-device session "${sessionName}". Reuse that session with --agent-device-session ${sessionName}, close it, or choose another device before rerunning.`
+            : 'Device is already owned by another agent-device session. Reuse the owning session with --agent-device-session, close it, or choose another device before rerunning.');
+    }
+    if (errorMessage && /bound to .* cannot be used with --platform=/u.test(errorMessage)) {
+        return nextActionHint('select_agent_device_session', 'The selected agent-device session is bound to another platform or device. Use a platform-specific --agent-device-session, close the bound session, or rerun without the conflicting session.');
+    }
+    if (errorMessage && /No active session\. Run open first/u.test(errorMessage)) {
+        return nextActionHint('open_agent_device_session', `agent-device has no active session for this action. Inspect raw/${rawFileName}, make the app open step pass, or pass an existing --agent-device-session before rerunning.`);
+    }
+    if (errorMessage && /session lock policy/u.test(errorMessage)) {
+        return nextActionHint('fix_agent_device_session_lock', 'agent-device rejected the command because session lock policy conflicts with target selectors. Reuse the locked session directly, remove conflicting target selectors, or close the session before rerunning.');
+    }
+    return nextActionHint(defaultNextActionCode, defaultNextAction);
+}
+/**
+ * Builds a health artifact from agent-device capture checks.
+ *
+ * @param {{runId: string, checks: Record<string, unknown>[]}} options
+ * @returns {Record<string, unknown>}
+ */
+function buildAgentDeviceHealth({ runId, checks }) {
+    const failed = checks.some((check) => check.status === 'failed');
+    return assertValidJson({
+        schemaVersion: '1.0.0',
+        scenarioId: 'agent-device-capture',
+        flowId: 'agent-device-capture',
+        runId,
+        healthStatus: failed ? 'failed' : 'passed',
+        checks,
+    }, SCHEMAS.health, 'Health artifact');
+}
+/**
+ * Builds a verdict artifact for agent-device capture readiness.
+ *
+ * @param {{runId: string, health: Record<string, unknown>}} options
+ * @returns {Record<string, unknown>}
+ */
+function buildAgentDeviceVerdict({ runId, health }) {
+    const passed = health.healthStatus === 'passed';
+    return assertValidJson({
+        schemaVersion: '1.0.0',
+        scenarioId: 'agent-device-capture',
+        flowId: 'agent-device-capture',
+        runId,
+        healthStatus: health.healthStatus,
+        verdictStatus: passed ? 'not_evaluated' : 'inconclusive',
+        budgetChecks: [],
+        summary: passed
+            ? 'agent-device capture passed; no product budget has been evaluated.'
+            : 'agent-device capture failed; runtime scenario execution is not ready.',
+    }, SCHEMAS.verdict, 'Verdict artifact');
+}
+/**
+ * Converts one agent-device availability check into a schema-safe health check.
+ *
+ * @param {AgentDeviceAvailabilityCheck} check
+ * @returns {Record<string, unknown>}
+ */
+function agentDeviceAvailabilityHealthCheck(check) {
+    return {
+        name: check.name,
+        status: check.status,
+        source: 'runner',
+        code: check.code,
+        message: check.message,
+        metadata: {
+            command: check.command,
+            args: check.args.join(' '),
+            exitCode: check.exitCode,
+            ...(check.stderrPreview ? { stderrPreview: check.stderrPreview } : {}),
+            ...(check.stdoutPreview ? { stdoutPreview: check.stdoutPreview } : {}),
+            ...(check.metadata ?? {}),
+        },
+    };
+}
+/**
+ * Writes ASL artifacts for an agent-device command-surface availability check.
+ *
+ * @param {AgentDeviceAvailabilityArtifactOptions} options
+ * @returns {Promise<{agentSummary: string, health: Record<string, unknown>, runDir: string, verdict: Record<string, unknown>}>}
+ */
+async function writeAgentDeviceAvailabilityArtifacts({ outputDir, result, runId = createRunId(), }) {
+    const runDir = path.resolve(outputDir);
+    const layout = createArtifactLayout({ outputDir: runDir });
+    const checks = result.checks.map(agentDeviceAvailabilityHealthCheck);
+    const health = assertValidJson({
+        schemaVersion: '1.0.0',
+        scenarioId: 'agent-device-availability',
+        flowId: 'agent-device-availability',
+        runId,
+        healthStatus: result.status,
+        checks,
+    }, SCHEMAS.health, 'Health artifact');
+    const verdict = assertValidJson({
+        schemaVersion: '1.0.0',
+        scenarioId: 'agent-device-availability',
+        flowId: 'agent-device-availability',
+        runId,
+        healthStatus: health.healthStatus,
+        verdictStatus: result.status === 'passed' ? 'not_evaluated' : 'inconclusive',
+        budgetChecks: [],
+        summary: result.status === 'passed'
+            ? 'agent-device command surface is available; no product budget has been evaluated.'
+            : 'agent-device command surface is unavailable; fix runner environment health before live proof.',
+    }, SCHEMAS.verdict, 'Verdict artifact');
+    const agentSummary = [
+        buildAgentSummaryMarkdown({ health, verdict }).trimEnd(),
+        buildAgentDeviceAvailabilitySummary(result),
+    ].join('\n');
+    await fsp.mkdir(layout.raw, { recursive: true });
+    await writeJsonArtifact({
+        filePath: layout.health,
+        value: health,
+        schema: SCHEMAS.health,
+        label: 'Health artifact',
+    });
+    await writeJsonArtifact({
+        filePath: layout.verdict,
+        value: verdict,
+        schema: SCHEMAS.verdict,
+        label: 'Verdict artifact',
+    });
+    await writeTextArtifact({
+        filePath: layout.agentSummary,
+        content: agentSummary,
+    });
+    await fsp.writeFile(path.join(layout.raw, 'agent-device-availability.json'), `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+    return {
+        agentSummary,
+        health,
+        runDir,
+        verdict,
+    };
+}
+/**
+ * Reads agent-device adapter metadata from a normalized scenario step.
+ *
+ * @param {ScenarioExecutionStep} step
+ * @returns {Record<string, unknown>}
+ */
+function readAgentDeviceStepOptions(step) {
+    const agentDeviceOptions = step.adapterOptions?.agentDevice;
+    return agentDeviceOptions && typeof agentDeviceOptions === 'object' && !Array.isArray(agentDeviceOptions)
+        ? agentDeviceOptions
+        : {};
+}
+/**
+ * Returns true when a normalized step has a portable selector.
+ *
+ * @param {unknown} value
+ * @returns {value is import('./agent-device-driver').AgentDeviceSelector}
+ */
+function isAgentDeviceSelector(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const selector = value;
+    return typeof selector.kind === 'string' && typeof selector.value === 'string' && selector.value.length > 0;
+}
+/**
+ * Returns the default raw file name for one agent-device action.
+ *
+ * @param {{driverAction: AgentDeviceDriverStep['driverAction'], index: number}} options
+ * @returns {string}
+ */
+function defaultAgentDeviceRawFileName({ driverAction, index, }) {
+    return `agent-device-${driverAction}-${index}.txt`;
+}
+/**
+ * Returns the default capture file name for one agent-device action.
+ *
+ * @param {{driverAction: AgentDeviceDriverStep['driverAction'], index: number}} options
+ * @returns {string}
+ */
+function defaultAgentDeviceCaptureFileName({ driverAction, index, }) {
+    return `agent-device-${driverAction}-${index}.png`;
+}
+/**
+ * Expands normalized scenario steps into agent-device driver actions.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {AgentDeviceDriverStep[]}
+ */
+function resolveAgentDeviceDriverSteps(scenario) {
+    const executionPlan = buildScenarioExecutionPlan(scenario);
+    return executionPlan.steps
+        .filter((step) => ['assertVisible', 'inspectTree', 'readLogs', 'screenshot', 'scroll', 'tap'].includes(String(step.driverAction)))
+        .map((step, index) => {
+        const agentDeviceOptions = readAgentDeviceStepOptions(step);
+        const action = step.driverAction;
+        const actionIndex = index + 1;
+        return {
+            driverAction: action,
+            ...(typeof agentDeviceOptions.amount === 'string' ? { amount: agentDeviceOptions.amount } : {}),
+            ...(typeof agentDeviceOptions.captureFileName === 'string' && agentDeviceOptions.captureFileName.length > 0
+                ? { captureFileName: agentDeviceOptions.captureFileName }
+                : action === 'screenshot'
+                    ? { captureFileName: defaultAgentDeviceCaptureFileName({ driverAction: action, index: actionIndex }) }
+                    : {}),
+            ...(typeof agentDeviceOptions.direction === 'string' ? { direction: agentDeviceOptions.direction } : {}),
+            ...(typeof readFiniteNumber(agentDeviceOptions.durationMs) === 'number'
+                ? { durationMs: readFiniteNumber(agentDeviceOptions.durationMs) }
+                : {}),
+            ...(typeof readFiniteNumber(agentDeviceOptions.endX) === 'number' ? { endX: readFiniteNumber(agentDeviceOptions.endX) } : {}),
+            ...(typeof readFiniteNumber(agentDeviceOptions.endY) === 'number' ? { endY: readFiniteNumber(agentDeviceOptions.endY) } : {}),
+            ...(typeof readFiniteNumber(agentDeviceOptions.pixels) === 'number' ? { pixels: readFiniteNumber(agentDeviceOptions.pixels) } : {}),
+            rawFileName: typeof agentDeviceOptions.rawFileName === 'string' && agentDeviceOptions.rawFileName.length > 0
+                ? agentDeviceOptions.rawFileName
+                : defaultAgentDeviceRawFileName({ driverAction: action, index: actionIndex }),
+            ...(typeof agentDeviceOptions.ref === 'string' ? { ref: agentDeviceOptions.ref } : {}),
+            required: step.required !== false,
+            ...(isAgentDeviceSelector(step.selector) ? { selector: step.selector } : {}),
+            stepId: step.id,
+            ...(typeof readFiniteNumber(agentDeviceOptions.startX) === 'number' ? { startX: readFiniteNumber(agentDeviceOptions.startX) } : {}),
+            ...(typeof readFiniteNumber(agentDeviceOptions.startY) === 'number' ? { startY: readFiniteNumber(agentDeviceOptions.startY) } : {}),
+            waitMs: readPositiveInteger(agentDeviceOptions.waitMs ?? step.timeoutMs, 0),
+            ...(typeof readFiniteNumber(agentDeviceOptions.x) === 'number' ? { x: readFiniteNumber(agentDeviceOptions.x) } : {}),
+            ...(typeof readFiniteNumber(agentDeviceOptions.y) === 'number' ? { y: readFiniteNumber(agentDeviceOptions.y) } : {}),
+        };
+    });
+}
+/**
+ * Returns profile-time validation errors for agent-device driver steps.
+ *
+ * @param {AgentDeviceDriverStep[]} driverSteps
+ * @returns {string[]}
+ */
+function validateAgentDeviceDriverSteps(driverSteps) {
+    const errors = [];
+    for (const step of driverSteps) {
+        const stepLabel = step.stepId ? `step \`${step.stepId}\`` : 'unnamed step';
+        if (step.driverAction === 'tap' && !step.selector && !step.ref && (typeof step.x !== 'number' || typeof step.y !== 'number')) {
+            errors.push(`${stepLabel} uses driverAction \`tap\` but is missing a selector, adapterOptions.agentDevice.ref, or adapterOptions.agentDevice.x/y.`);
+        }
+        if (step.driverAction === 'assertVisible' && !step.selector) {
+            errors.push(`${stepLabel} uses driverAction \`assertVisible\` but is missing a portable selector.`);
+        }
+    }
+    return errors;
+}
+/**
+ * Builds scalar health metadata for one portable selector.
+ *
+ * @param {import('./agent-device-driver').AgentDeviceSelector | undefined} selector
+ * @returns {Record<string, string>}
+ */
+function buildAgentDeviceSelectorHealthMetadata(selector) {
+    if (!selector) {
+        return {};
+    }
+    return {
+        selectorKind: selector.kind,
+        selectorValue: selector.value,
+        ...(selector.match ? { selectorMatch: selector.match } : {}),
+    };
+}
+/**
+ * Runs one agent-device driver action.
+ *
+ * @param {{capturesDir: string, driver: import('./agent-device-driver').AgentDeviceDriver, driverStep: AgentDeviceDriverStep}} options
+ * @returns {Promise<import('./agent-device-driver').AgentDeviceCommandResult>}
+ */
+async function runAgentDeviceDriverStep({ capturesDir, driver, driverStep, }) {
+    if (driverStep.driverAction === 'assertVisible' && driverStep.selector) {
+        return driver.assertVisible({
+            selector: driverStep.selector,
+            ...(driverStep.rawFileName ? { rawFileName: driverStep.rawFileName } : {}),
+        });
+    }
+    if (driverStep.driverAction === 'inspectTree') {
+        return driver.inspectTree({
+            ...(driverStep.rawFileName ? { rawFileName: driverStep.rawFileName } : {}),
+        });
+    }
+    if (driverStep.driverAction === 'readLogs') {
+        return driver.readLogs({
+            ...(driverStep.rawFileName ? { rawFileName: driverStep.rawFileName } : {}),
+        });
+    }
+    if (driverStep.driverAction === 'screenshot') {
+        return driver.screenshot({
+            outputPath: path.join(capturesDir, driverStep.captureFileName ?? 'agent-device-screenshot.png'),
+            ...(driverStep.rawFileName ? { rawFileName: driverStep.rawFileName } : {}),
+        });
+    }
+    if (driverStep.driverAction === 'scroll') {
+        return driver.scroll({
+            ...(driverStep.amount ? { amount: driverStep.amount } : {}),
+            ...(driverStep.direction ? { direction: driverStep.direction } : {}),
+            ...(typeof driverStep.durationMs === 'number' ? { durationMs: driverStep.durationMs } : {}),
+            ...(typeof driverStep.endX === 'number' ? { endX: driverStep.endX } : {}),
+            ...(typeof driverStep.endY === 'number' ? { endY: driverStep.endY } : {}),
+            ...(typeof driverStep.pixels === 'number' ? { pixels: driverStep.pixels } : {}),
+            ...(driverStep.rawFileName ? { rawFileName: driverStep.rawFileName } : {}),
+            ...(typeof driverStep.startX === 'number' ? { startX: driverStep.startX } : {}),
+            ...(typeof driverStep.startY === 'number' ? { startY: driverStep.startY } : {}),
+        });
+    }
+    if (driverStep.driverAction === 'tap') {
+        return driver.tap({
+            ...(driverStep.rawFileName ? { rawFileName: driverStep.rawFileName } : {}),
+            ...(driverStep.ref ? { ref: driverStep.ref } : {}),
+            ...(driverStep.selector ? { selector: driverStep.selector } : {}),
+            ...(typeof driverStep.x === 'number' ? { x: driverStep.x } : {}),
+            ...(typeof driverStep.y === 'number' ? { y: driverStep.y } : {}),
+        });
+    }
+    throw new Error(`Unsupported agent-device driver action: ${driverStep.driverAction}`);
+}
+/**
+ * Builds a stable health code suffix for one agent-device driver action.
+ *
+ * @param {AgentDeviceDriverStep['driverAction']} driverAction
+ * @returns {string}
+ */
+function agentDeviceDriverActionCode(driverAction) {
+    return driverAction.replace(/[A-Z]/gu, (match) => `_${match.toLowerCase()}`);
+}
+/**
+ * Runs scenario-declared portable actions through agent-device and writes artifacts.
+ *
+ * @param {AgentDeviceCaptureOptions} options
+ * @returns {Promise<AgentDeviceCaptureResult>}
+ */
+async function runAgentDeviceCapture({ agentDevicePath = 'agent-device', app = null, commandTimeoutMs = 60_000, delay: wait = delay, device = null, driverSteps, executor, open = false, outputDir = path.resolve('artifacts/agent-device-capture'), platform, runId = createRunId(), scenario = null, serial = null, session = null, sessionMode = 'reuse', target = 'mobile', udid = null, waitMs = 0, }) {
+    const run = executor ?? ((command, args) => execFileCommandWithTimeout(command, args, commandTimeoutMs));
+    const runDir = path.resolve(outputDir);
+    const layout = createArtifactLayout({ outputDir: runDir });
+    const rawDir = layout.raw;
+    await fsp.mkdir(rawDir, { recursive: true });
+    await fsp.mkdir(layout.captures, { recursive: true });
+    const raw = {};
+    const captures = {
+        screenshots: [],
+    };
+    const checks = [];
+    const driverActionMetadata = [];
+    const resolvedDriverSteps = driverSteps ?? (scenario ? resolveAgentDeviceDriverSteps(scenario) : []);
+    const driverStepErrors = validateAgentDeviceDriverSteps(resolvedDriverSteps);
+    if (driverStepErrors.length > 0) {
+        throw new Error(`Invalid agent-device driver step metadata: ${driverStepErrors.join(' ')}`);
+    }
+    const requestedTarget = udid ?? serial ?? device ?? null;
+    let sessionName = typeof session === 'string' && session.length > 0 ? session : null;
+    let sessionSelectionMode = sessionName ? 'explicit' : 'none';
+    if (!sessionName) {
+        const sessionList = await run(agentDevicePath, ['session', 'list', '--json']);
+        raw['agent-device-session-list.txt'] = formatAgentDeviceRawOutput(sessionList);
+        if (sessionList.exitCode === 0) {
+            const selectedSession = selectAgentDeviceSession({
+                platform,
+                requestedTarget,
+                sessions: readAgentDeviceSessions(sessionList),
+                target,
+            });
+            if (selectedSession) {
+                sessionName = selectedSession;
+                sessionSelectionMode = 'auto';
+                checks.push({
+                    name: 'agent_device_session_selected',
+                    status: 'passed',
+                    source: 'runner',
+                    code: 'agent_device_session_auto_selected',
+                    message: `Selected agent-device session ${selectedSession} for ${platform}.`,
+                });
+            }
+        }
+    }
+    const normalizedSessionMode = parseAgentDeviceSessionMode(sessionMode);
+    const sessionOwnsTarget = Boolean(sessionName) && (normalizedSessionMode === 'reuse' || !requestedTarget);
+    const driver = createAgentDeviceDriver({
+        agentDevicePath,
+        ...(!sessionOwnsTarget && device ? { device } : {}),
+        executor: run,
+        platform,
+        ...(!sessionOwnsTarget && serial ? { serial } : {}),
+        ...(sessionName ? { session: sessionName } : {}),
+        ...(!sessionOwnsTarget ? { target } : {}),
+        ...(!sessionOwnsTarget && udid ? { udid } : {}),
+    });
+    const metadata = {
+        app,
+        device,
+        driverActions: [],
+        open,
+        platform,
+        ...(requestedTarget ? { requestedTarget } : {}),
+        selectedTarget: sessionOwnsTarget ? sessionName : requestedTarget,
+        session: sessionName,
+        sessionSelectionMode,
+        sessionMode: normalizedSessionMode,
+        target,
+        targetSelectionMode: sessionOwnsTarget ? 'session' : sessionName ? 'session_bind' : 'direct',
+    };
+    if (open) {
+        if (!app) {
+            checks.push({
+                name: 'agent_device_opened',
+                status: 'failed',
+                source: 'runner',
+                code: 'agent_device_open_missing_app',
+                message: 'agent-device app open was requested, but no app id or URL was provided.',
+                metadata: nextActionHint('provide_agent_device_app', 'Pass --app with a bundle id, package name, app name, or URL before requesting --open.'),
+            });
+        }
+        else {
+            const openResult = await driver.open({ appOrUrl: app });
+            raw[openResult.rawFileName] = formatAgentDeviceRawOutput(openResult);
+            const errorMetadata = openResult.exitCode !== 0 ? readAgentDeviceErrorMetadata(openResult) : {};
+            checks.push({
+                name: 'agent_device_opened',
+                status: openResult.exitCode === 0 ? 'passed' : 'failed',
+                source: 'runner',
+                code: openResult.exitCode === 0 ? 'agent_device_opened' : 'agent_device_open_failed',
+                message: openResult.exitCode === 0 ? `Opened ${app} with agent-device.` : `Failed to open ${app} with agent-device.`,
+                ...(openResult.exitCode !== 0
+                    ? {
+                        metadata: {
+                            ...buildAgentDeviceFailureHint({
+                                defaultNextAction: `Inspect raw/${openResult.rawFileName}, confirm the selected device is available, and rerun the capture.`,
+                                defaultNextActionCode: 'inspect_agent_device_open',
+                                errorMetadata,
+                                rawFileName: openResult.rawFileName,
+                            }),
+                            ...errorMetadata,
+                        },
+                    }
+                    : {}),
+            });
+        }
+    }
+    if (waitMs > 0) {
+        await wait(waitMs);
+        checks.push({
+            name: 'agent_device_capture_window_waited',
+            status: 'passed',
+            source: 'runner',
+            code: 'agent_device_capture_window_waited',
+            message: `Waited ${waitMs}ms before running agent-device driver actions.`,
+        });
+    }
+    for (const driverStep of resolvedDriverSteps) {
+        if (driverStep.waitMs && driverStep.waitMs > 0) {
+            await wait(driverStep.waitMs);
+            checks.push({
+                name: 'agent_device_driver_action_waited',
+                status: 'passed',
+                source: 'runner',
+                code: 'agent_device_driver_action_waited',
+                message: `Waited ${driverStep.waitMs}ms before running agent-device driver action ${driverStep.driverAction}.`,
+                metadata: {
+                    driverAction: driverStep.driverAction,
+                    ...(driverStep.stepId ? { stepId: driverStep.stepId } : {}),
+                },
+            });
+        }
+        const driverResult = await runAgentDeviceDriverStep({
+            capturesDir: layout.captures,
+            driver,
+            driverStep,
+        });
+        raw[driverResult.rawFileName] = formatAgentDeviceRawOutput(driverResult);
+        const failed = driverResult.exitCode !== 0;
+        const errorMetadata = failed ? readAgentDeviceErrorMetadata(driverResult) : {};
+        const codeSuffix = agentDeviceDriverActionCode(driverStep.driverAction);
+        checks.push({
+            name: `agent_device_${codeSuffix}`,
+            status: failed && driverStep.required === false ? 'warning' : failed ? 'failed' : 'passed',
+            source: 'runner',
+            code: driverResult.exitCode === 0 ? `agent_device_${codeSuffix}_completed` : `agent_device_${codeSuffix}_failed`,
+            message: driverResult.exitCode === 0
+                ? `Completed agent-device driver action ${driverStep.driverAction}.`
+                : `agent-device driver action ${driverStep.driverAction} failed.`,
+            metadata: {
+                driverAction: driverStep.driverAction,
+                ...(failed
+                    ? buildAgentDeviceFailureHint({
+                        defaultNextAction: `Inspect raw/${driverResult.rawFileName}, confirm the device is interactive and the action metadata is valid, then rerun the capture.`,
+                        defaultNextActionCode: 'inspect_agent_device_driver_action',
+                        errorMetadata,
+                        rawFileName: driverResult.rawFileName,
+                    })
+                    : {}),
+                ...(failed ? errorMetadata : {}),
+                ...buildAgentDeviceSelectorHealthMetadata(driverStep.selector),
+                ...(driverStep.stepId ? { stepId: driverStep.stepId } : {}),
+            },
+        });
+        const actionMetadata = {
+            args: driverResult.args,
+            driverAction: driverStep.driverAction,
+            exitCode: driverResult.exitCode,
+            ...(driverResult.capturePath
+                ? { capturePath: `captures/${path.basename(driverResult.capturePath)}` }
+                : {}),
+            rawPath: `raw/${driverResult.rawFileName}`,
+            ...(driverStep.selector ? { selector: driverStep.selector } : {}),
+            ...(driverStep.stepId ? { stepId: driverStep.stepId } : {}),
+        };
+        driverActionMetadata.push(actionMetadata);
+        if (driverStep.driverAction === 'screenshot' && driverResult.exitCode === 0 && driverResult.capturePath) {
+            captures.screenshots.push(`captures/${path.basename(driverResult.capturePath)}`);
+        }
+    }
+    metadata.driverActions = driverActionMetadata;
+    metadata.captures = captures;
+    const health = buildAgentDeviceHealth({ runId, checks });
+    const verdict = buildAgentDeviceVerdict({ runId, health });
+    const agentSummary = buildAgentSummaryMarkdown({ health, verdict });
+    await Promise.all(Object.entries(raw).map(([fileName, content]) => fsp.writeFile(path.join(rawDir, fileName), `${content.trimEnd()}\n`, 'utf8')));
+    await fsp.writeFile(path.join(rawDir, 'agent-device-metadata.json'), `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+    await writeJsonArtifact({
+        filePath: layout.health,
+        value: health,
+        schema: SCHEMAS.health,
+        label: 'Health artifact',
+    });
+    await writeJsonArtifact({
+        filePath: layout.verdict,
+        value: verdict,
+        schema: SCHEMAS.verdict,
+        label: 'Verdict artifact',
+    });
+    await writeTextArtifact({
+        filePath: layout.agentSummary,
+        content: agentSummary,
+    });
+    return {
+        agentSummary,
+        captures,
+        health,
+        metadata,
+        raw,
+        runDir,
+        verdict,
+    };
+}
+/**
+ * Runs the agent-device capture CLI.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+    const argv = process.argv.slice(2);
+    if (hasHelpFlag(argv)) {
+        usage(process.stdout);
+        return;
+    }
+    loadAslLocalEnv();
+    const args = parseArgs(argv);
+    const commandTimeoutMsValue = readStringArgOrEnv(args['command-timeout-ms'], ['ASL_AGENT_DEVICE_COMMAND_TIMEOUT_MS']);
+    const commandTimeoutMs = readPositiveInteger(commandTimeoutMsValue, 60_000);
+    const agentDevicePath = readStringArgOrEnv(args['agent-device'], ['ASL_AGENT_DEVICE_BIN']);
+    if (args.check === true || args.check === 'true') {
+        const requiredPlatforms = readStringArgOrEnv(args['require-platforms'], ['ASL_AGENT_DEVICE_REQUIRED_PLATFORMS']);
+        const result = await checkAgentDeviceAvailability({
+            ...(agentDevicePath ? { agentDevicePath } : {}),
+            commandTimeoutMs,
+            requiredPlatforms: parseRequiredPlatforms(requiredPlatforms),
+        });
+        if (typeof args.out === 'string') {
+            await writeAgentDeviceAvailabilityArtifacts({
+                outputDir: args.out,
+                result,
+                ...(typeof args['run-id'] === 'string' ? { runId: args['run-id'] } : {}),
+            });
+        }
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        if (result.status !== 'passed') {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (typeof args.platform !== 'string' || typeof args.scenario !== 'string') {
+        usage();
+        process.exitCode = 1;
+        return;
+    }
+    if (!['android', 'apple', 'ios', 'linux', 'macos'].includes(args.platform)) {
+        throw new Error('--platform must be one of android, ios, macos, linux, or apple.');
+    }
+    const platform = args.platform;
+    const app = readStringArgOrEnv(args.app, platform === 'android'
+        ? ['ASL_ANDROID_APP_ID', 'ASL_EXAMPLE_ANDROID_APP_ID']
+        : ['ASL_IOS_APP_ID', 'ASL_EXAMPLE_IOS_APP_ID']);
+    const serial = readStringArgOrEnv(args.serial, ['ASL_ANDROID_SERIAL', 'ASL_EXAMPLE_ANDROID_SERIAL']);
+    const session = readStringArgOrEnv(args.session, platform === 'android'
+        ? ['ASL_ANDROID_AGENT_DEVICE_SESSION', 'ASL_EXAMPLE_ANDROID_AGENT_DEVICE_SESSION']
+        : ['ASL_IOS_AGENT_DEVICE_SESSION', 'ASL_EXAMPLE_IOS_AGENT_DEVICE_SESSION']);
+    const sessionMode = readStringArgOrEnv(args['session-mode'], platform === 'android'
+        ? ['ASL_ANDROID_AGENT_DEVICE_SESSION_MODE', 'ASL_EXAMPLE_ANDROID_AGENT_DEVICE_SESSION_MODE']
+        : ['ASL_IOS_AGENT_DEVICE_SESSION_MODE', 'ASL_EXAMPLE_IOS_AGENT_DEVICE_SESSION_MODE']);
+    const udid = readStringArgOrEnv(args.udid, ['ASL_IOS_UDID', 'ASL_EXAMPLE_IOS_UDID']);
+    const result = await runAgentDeviceCapture({
+        ...(agentDevicePath ? { agentDevicePath } : {}),
+        ...(app ? { app } : {}),
+        commandTimeoutMs,
+        ...(typeof args.device === 'string' ? { device: args.device } : {}),
+        ...(typeof args.out === 'string' ? { outputDir: args.out } : {}),
+        open: isEnabled(args.open),
+        platform,
+        ...(typeof args['run-id'] === 'string' ? { runId: args['run-id'] } : {}),
+        scenario: readJson(path.resolve(args.scenario)),
+        ...(serial ? { serial } : {}),
+        ...(session ? { session } : {}),
+        ...(sessionMode ? { sessionMode: parseAgentDeviceSessionMode(sessionMode) } : {}),
+        ...(typeof args.target === 'string' && ['desktop', 'mobile', 'tv'].includes(args.target)
+            ? { target: args.target }
+            : {}),
+        ...(udid ? { udid } : {}),
+        waitMs: readPositiveInteger(args['wait-ms'], 0),
+    });
+    process.stdout.write(`${result.runDir}\n`);
+    if (result.health.healthStatus !== 'passed') {
+        process.exitCode = 1;
+    }
+}
+if (require.main === module) {
+    main().catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    });
+}