agent-scenario-loop 0.1.3 → 0.1.4

package/dist/runner/profile-mobile.js

@@ -49,7 +49,7 @@ function usage({ binaryName, output = process.stderr, platform, }) {
     ];
     if (platform === 'android') {
         lines.push('Use --adb-artifacts <dir> to read raw/adb-logcat.txt from a prior asl-android-adb capture.');
-        lines.push('Use --adb-capture [--clear-logcat] [--launch] [--launch-wait-ms <ms>] [--wait-ms <ms>] to capture adb logcat before profiling.');
+        lines.push('Use --adb-capture [--clear-logcat] [--launch] [--launch-wait-ms <ms>] [--wait-ms <ms>] [--adb-command-timeout-ms <ms>] to capture adb logcat before profiling.');
         lines.push('Use --android-dev-client-url <url> [--android-dev-client-wait-ms <ms>] [--android-dev-client-ready-pattern <pattern>] with --adb-capture to open an Expo dev-client session before profile-session deep links.');
         lines.push('Use --android-profile-session-storage with --profile-session to seed startup control through Android AsyncStorage.');
         lines.push('Use --profile-session with --adb-capture to start the app profile session and execute scenario-declared Android commands.');
@@ -251,6 +251,8 @@ function buildProviderEvidenceInput({ layout, output, providerId, sourcePath, })
             destinationPath: path.join(layout.signals[kind], fileName),
             kind,
             manifestPath: `signals/${kind}/${fileName}`,
+            providerId,
+            ...(typeof output.required === 'boolean' ? { required: output.required } : {}),
             sourcePath,
         };
     }
@@ -263,6 +265,8 @@ function buildProviderEvidenceInput({ layout, output, providerId, sourcePath, })
             destinationPath: path.join(layout.captures, fileName),
             kind: output.kind,
             manifestPath: `captures/${fileName}`,
+            providerId,
+            ...(typeof output.required === 'boolean' ? { required: output.required } : {}),
             sourcePath,
         };
     }
@@ -274,9 +278,33 @@ function buildProviderEvidenceInput({ layout, output, providerId, sourcePath, })
         destinationPath: path.join(layout.raw, 'providers', providerId, fileName),
         kind: output.kind,
         manifestPath: `raw/providers/${providerId}/${fileName}`,
+        providerId,
+        ...(typeof output.required === 'boolean' ? { required: output.required } : {}),
         sourcePath,
     };
 }
+/**
+ * Validates structured profiler evidence when a provider emits JSON.
+ *
+ * Native traces and flamegraph files may be attached as profiler evidence, but
+ * JSON profiler files must carry enough envelope metadata for agents to reason
+ * about source, target, and completeness.
+ *
+ * @param {{kind: EvidenceKind, sourcePath: string}} options
+ * @returns {void}
+ */
+function validateStructuredProfilerEvidence({ kind, sourcePath, }) {
+    if (kind !== 'profiler' || path.extname(sourcePath).toLowerCase() !== '.json') {
+        return;
+    }
+    try {
+        assertValidJson(readJson(sourcePath), SCHEMAS.profiler, 'Profiler evidence artifact');
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Profiler evidence artifact is invalid: ${sourcePath}. ${detail}`);
+    }
+}
 /**
  * Fails when provider command ids would collide in raw command records.
  *
@@ -442,7 +470,7 @@ async function resolveAttachedEvidence({ args, layout, providerInputs = [], }) {
         },
     };
     const destinationPaths = new Set();
-    const addCopy = async ({ channel, destinationPath, kind, manifestPath, sourcePath, }) => {
+    const addCopy = async ({ channel, destinationPath, kind, manifestPath, required = false, sourcePath, }) => {
         const stat = await fsp.stat(sourcePath).catch(() => null);
         if (!stat?.isFile()) {
             throw new Error(`Evidence artifact does not exist or is not a file: ${sourcePath}`);
@@ -450,6 +478,7 @@ async function resolveAttachedEvidence({ args, layout, providerInputs = [], }) {
         if (destinationPaths.has(destinationPath)) {
             throw new Error(`Duplicate evidence artifact destination: ${manifestPath}`);
         }
+        validateStructuredProfilerEvidence({ kind, sourcePath });
         destinationPaths.add(destinationPath);
         const attachment = {
             channel,
@@ -459,6 +488,7 @@ async function resolveAttachedEvidence({ args, layout, providerInputs = [], }) {
             kind,
             manifestPath,
             redactionStatus: 'not-redacted',
+            required,
             sha256: await hashFileSha256(sourcePath),
             sourceFileName: path.basename(sourcePath),
             sourcePath,
@@ -578,20 +608,447 @@ function toPortablePathReference(targetPath) {
     }
     return path.basename(targetPath);
 }
+/**
+ * Returns a path reference from one run folder to an external sidecar.
+ *
+ * @param {{runDir: string, targetPath: string}} options
+ * @returns {string}
+ */
+function toRunPathReference({ runDir, targetPath }) {
+    const relativePath = path.relative(runDir, targetPath);
+    return relativePath.length > 0 ? relativePath : path.basename(targetPath);
+}
+/**
+ * Returns a sidecar dependency path that stays readable in rehydrated artifacts.
+ *
+ * @param {{runDir: string, sidecarRoot: string, targetPath: string}} options
+ * @returns {SidecarEvidenceDependency}
+ */
+function toSidecarEvidenceDependency({ runDir, sidecarRoot, targetPath, }) {
+    const sidecarRelativePath = path.relative(sidecarRoot, targetPath);
+    if (sidecarRelativePath.length > 0 &&
+        !sidecarRelativePath.startsWith('..') &&
+        !path.isAbsolute(sidecarRelativePath)) {
+        return {
+            kind: 'sidecar',
+            root: 'sidecar',
+            path: sidecarRelativePath,
+        };
+    }
+    return {
+        kind: 'sidecar',
+        path: toRunPathReference({ runDir, targetPath }),
+    };
+}
+/**
+ * Reads scenario string-list declarations into a set.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {string[]} pathSegments
+ * @returns {Set<string>}
+ */
+function readScenarioStringSet(scenario, pathSegments) {
+    const values = pathSegments.reduce((current, segment) => (current && typeof current === 'object' && !Array.isArray(current)
+        ? current[segment]
+        : undefined), scenario);
+    return new Set(Array.isArray(values)
+        ? values.filter((value) => typeof value === 'string')
+        : []);
+}
+/**
+ * Returns true when a scenario artifact declaration matches a diagnostic kind.
+ *
+ * @param {Set<string>} artifacts
+ * @param {string[]} aliases
+ * @returns {boolean}
+ */
+function artifactSetHasAny(artifacts, aliases) {
+    return aliases.some((alias) => artifacts.has(alias));
+}
+/**
+ * Resolves common aliases used by scenario artifact contracts.
+ *
+ * @param {DiagnosticKind} kind
+ * @returns {string[]}
+ */
+function diagnosticArtifactAliases(kind) {
+    const aliases = {
+        accessibility: ['accessibility'],
+        js: ['js', 'profileEvents', 'profileSession'],
+        logs: ['logs', 'deviceLog', 'interactionLog'],
+        memory: ['memory'],
+        network: ['network'],
+        profiler: ['profiler', 'profile'],
+        screenshot: ['screenshot', 'screenshots'],
+        uiTree: ['uiTree', 'ui-tree', 'accessibilityTree'],
+        video: ['video', 'recording'],
+    };
+    return aliases[kind];
+}
+/**
+ * Resolves common aliases used by runner capability declarations.
+ *
+ * @param {DiagnosticKind} kind
+ * @returns {string[]}
+ */
+function diagnosticCapabilityAliases(kind) {
+    const aliases = {
+        accessibility: ['accessibility', 'accessibilityCapture'],
+        js: ['js', 'profileSession', 'profileEvents'],
+        logs: ['logCapture', 'logs', 'deviceLog'],
+        memory: ['memory', 'memoryCapture'],
+        network: ['network', 'networkCapture'],
+        profiler: ['profiler', 'profile', 'profilerCapture'],
+        screenshot: ['screenshot', 'screenshots'],
+        uiTree: ['uiTree', 'ui-tree', 'accessibilityTree'],
+        video: ['video', 'recording'],
+    };
+    return aliases[kind];
+}
+/**
+ * Returns requirement/request metadata for one diagnostic kind.
+ *
+ * @param {{kind: DiagnosticKind, optionalArtifacts: Set<string>, optionalCapabilities: Set<string>, requiredArtifacts: Set<string>, requiredCapabilities: Set<string>}} options
+ * @returns {{required: boolean, requested: boolean}}
+ */
+function resolveDiagnosticRequest({ kind, optionalArtifacts, optionalCapabilities, requiredArtifacts, requiredCapabilities, }) {
+    const artifactAliases = diagnosticArtifactAliases(kind);
+    const capabilityAliases = diagnosticCapabilityAliases(kind);
+    const required = artifactSetHasAny(requiredArtifacts, artifactAliases) ||
+        artifactSetHasAny(requiredCapabilities, capabilityAliases);
+    return {
+        required,
+        requested: required ||
+            artifactSetHasAny(optionalArtifacts, artifactAliases) ||
+            artifactSetHasAny(optionalCapabilities, capabilityAliases),
+    };
+}
+/**
+ * Builds a status entry for one diagnostic surface.
+ *
+ * @param {DiagnosticInventoryEntry & {requested?: boolean}} entry
+ * @returns {DiagnosticInventoryEntry}
+ */
+function buildDiagnosticEntry(entry) {
+    const { requested = true, ...diagnostic } = entry;
+    if (diagnostic.status === 'captured' || requested || diagnostic.required) {
+        return diagnostic;
+    }
+    return {
+        ...diagnostic,
+        status: 'not_requested',
+        reason: diagnostic.reason ?? 'Scenario did not request this optional diagnostic surface.',
+    };
+}
+/**
+ * Builds the product-neutral diagnostic inventory for a profile run.
+ *
+ * @param {{args: CliArgs, attachedEvidence: AttachedEvidence, eventLogPath: string | null, platform: ProfilePlatform, profileSessionEntriesPath: string | null, runDir: string, scenario: Record<string, unknown>}} options
+ * @returns {DiagnosticInventoryEntry[]}
+ */
+function buildDiagnosticInventory({ args, attachedEvidence, eventLogPath, platform, profileSessionEntriesPath, runDir, scenario, }) {
+    const requiredArtifacts = readScenarioStringSet(scenario, ['artifacts', 'required']);
+    const optionalArtifacts = readScenarioStringSet(scenario, ['artifacts', 'optional']);
+    const requiredCapabilities = readScenarioStringSet(scenario, ['requiredCapabilities']);
+    const optionalCapabilities = readScenarioStringSet(scenario, ['optionalCapabilities']);
+    const requiredProviderDiagnostics = new Set(attachedEvidence.attachments
+        .filter((attachment) => attachment.required)
+        .map((attachment) => attachment.kind));
+    const sidecarRoot = typeof args['adb-artifacts'] === 'string'
+        ? path.resolve(args['adb-artifacts'])
+        : typeof args['simctl-artifacts'] === 'string'
+            ? path.resolve(args['simctl-artifacts'])
+            : null;
+    const sidecarRootRef = sidecarRoot ? toRunPathReference({ runDir, targetPath: sidecarRoot }) : undefined;
+    const adbScreenshotDependency = platform === 'android'
+        ? resolveAndroidAdbScreenshotDependency({ runDir, sidecarRoot })
+        : null;
+    const eventLogBaseName = eventLogPath ? path.basename(eventLogPath) : undefined;
+    const eventLogManifestPath = eventLogBaseName ? `raw/${eventLogBaseName}` : undefined;
+    const eventLogIsIosProfileEvents = platform === 'ios' && eventLogBaseName === 'ios-profile-events.log';
+    const simctlRuntimeLogPath = typeof args['simctl-artifacts'] === 'string'
+        ? path.resolve(args['simctl-artifacts'], 'raw', 'ios-simctl-log.txt')
+        : null;
+    const simctlRuntimeLogExists = Boolean(simctlRuntimeLogPath && fs.existsSync(simctlRuntimeLogPath));
+    const simctlRuntimeLogDependency = simctlRuntimeLogPath && simctlRuntimeLogExists
+        ? toSidecarEvidenceDependency({ runDir, sidecarRoot: path.resolve(args['simctl-artifacts']), targetPath: simctlRuntimeLogPath })
+        : undefined;
+    const copiedSimctlLogManifestPath = platform === 'ios' && eventLogPath && path.basename(eventLogPath) === 'ios-simctl-log.txt'
+        ? eventLogManifestPath
+        : undefined;
+    const explicitIosRuntimeLogManifestPath = platform === 'ios' &&
+        typeof args.events === 'string' &&
+        eventLogManifestPath &&
+        !eventLogIsIosProfileEvents
+        ? eventLogManifestPath
+        : undefined;
+    const eventLogDependency = eventLogPath && sidecarRoot
+        ? toSidecarEvidenceDependency({ runDir, sidecarRoot, targetPath: eventLogPath })
+        : undefined;
+    const jsProfilePath = attachedEvidence.signals.js[0] ?? eventLogManifestPath;
+    const profileSessionEntriesManifestPath = profileSessionEntriesPath
+        ? `raw/${path.basename(profileSessionEntriesPath)}`
+        : undefined;
+    const entries = [];
+    const pushDiagnostic = (kind, entry) => {
+        const request = resolveDiagnosticRequest({
+            kind,
+            optionalArtifacts,
+            optionalCapabilities,
+            requiredArtifacts,
+            requiredCapabilities,
+        });
+        entries.push(buildDiagnosticEntry({
+            kind,
+            ...entry,
+            required: request.required || requiredProviderDiagnostics.has(kind) || Boolean(entry.required),
+            requested: request.requested || requiredProviderDiagnostics.has(kind) || Boolean(entry.requested),
+        }));
+    };
+    const logCaptured = platform === 'ios'
+        ? Boolean(copiedSimctlLogManifestPath || simctlRuntimeLogDependency || explicitIosRuntimeLogManifestPath)
+        : Boolean(eventLogManifestPath);
+    pushDiagnostic('logs', {
+        name: platform === 'ios' ? 'simulator-runtime-log' : 'device-log',
+        ...(typeof args['adb-artifacts'] === 'string'
+            ? { provider: 'adb', runnerId: 'android-adb' }
+            : typeof args['simctl-artifacts'] === 'string'
+                ? { provider: 'simctl', runnerId: 'ios-simctl' }
+                : typeof args.events === 'string'
+                    ? { provider: 'fixture-log-ingest' }
+                    : {}),
+        status: logCaptured ? 'captured' : 'unavailable',
+        ...(platform === 'ios'
+            ? copiedSimctlLogManifestPath
+                ? { path: copiedSimctlLogManifestPath }
+                : simctlRuntimeLogDependency
+                    ? { path: simctlRuntimeLogDependency.path }
+                    : explicitIosRuntimeLogManifestPath
+                        ? { path: explicitIosRuntimeLogManifestPath }
+                        : {}
+            : eventLogManifestPath
+                ? { path: eventLogManifestPath }
+                : {}),
+        ...(sidecarRootRef ? { sidecarRoot: sidecarRootRef } : {}),
+        ...(platform === 'ios'
+            ? simctlRuntimeLogDependency
+                ? { evidenceDependency: simctlRuntimeLogDependency }
+                : {}
+            : eventLogDependency
+                ? { evidenceDependency: eventLogDependency }
+                : {}),
+        ...(logCaptured
+            ? {
+                reason: platform === 'ios'
+                    ? 'iOS simulator runtime log evidence was available from the simctl capture sidecar.'
+                    : 'Device or fixture log evidence was available to the profile runner.',
+            }
+            : {
+                reason: platform === 'ios'
+                    ? 'No iOS simulator runtime log was available in the selected simctl capture sidecar.'
+                    : 'No device log source was supplied to this profile run.',
+                nextAction: platform === 'ios'
+                    ? 'Run with --simctl-capture or provide --simctl-artifacts containing raw/ios-simctl-log.txt.'
+                    : 'Run with --events, --adb-artifacts, --adb-capture, or provide a runtime log artifact.',
+            }),
+    });
+    pushDiagnostic('js', {
+        name: 'profile-session-evidence',
+        status: eventLogManifestPath || attachedEvidence.signals.js.length > 0 ? 'captured' : 'unavailable',
+        ...(jsProfilePath ? { path: jsProfilePath } : {}),
+        ...(profileSessionEntriesManifestPath
+            ? {
+                evidenceDependency: {
+                    kind: 'profile-session-entries',
+                    path: profileSessionEntriesManifestPath,
+                },
+            }
+            : eventLogDependency
+                ? { evidenceDependency: eventLogDependency }
+                : {}),
+        ...(sidecarRootRef ? { sidecarRoot: sidecarRootRef } : {}),
+        ...(eventLogManifestPath || attachedEvidence.signals.js.length > 0
+            ? { reason: 'Profile or JS evidence was captured from runner input.' }
+            : {
+                reason: 'No profile-session event log or JS signal attachment was available.',
+                nextAction: 'Attach JS evidence with --signal js:<path> or run a profile-session capture that emits profile events.',
+            }),
+    });
+    const attachedScreenshotPath = attachedEvidence.captures.screenshots[0];
+    const sidecarScreenshotDependency = attachedScreenshotPath ? null : adbScreenshotDependency;
+    pushDiagnostic('screenshot', {
+        ...(sidecarScreenshotDependency ? { provider: 'adb', runnerId: 'android-adb' } : {}),
+        status: attachedScreenshotPath || sidecarScreenshotDependency ? 'captured' : 'unavailable',
+        ...(attachedScreenshotPath
+            ? { path: attachedScreenshotPath }
+            : sidecarScreenshotDependency
+                ? { path: sidecarScreenshotDependency.path }
+                : {}),
+        ...(sidecarScreenshotDependency && sidecarRootRef ? { sidecarRoot: sidecarRootRef } : {}),
+        ...(sidecarScreenshotDependency ? { evidenceDependency: sidecarScreenshotDependency.dependency } : {}),
+        ...(attachedScreenshotPath || sidecarScreenshotDependency
+            ? {
+                reason: sidecarScreenshotDependency
+                    ? 'Screenshot evidence was available from the adb capture sidecar.'
+                    : 'Screenshot capture was attached to the run.',
+            }
+            : {
+                reason: 'No screenshot capture was produced by the selected runner/provider set.',
+                nextAction: 'Use --capture screenshot:<path> or a runner/provider that produces screenshots.',
+            }),
+    });
+    pushDiagnostic('uiTree', {
+        status: attachedEvidence.captures.uiTree ? 'captured' : 'unavailable',
+        ...(attachedEvidence.captures.uiTree ? { path: attachedEvidence.captures.uiTree } : {}),
+        ...(attachedEvidence.captures.uiTree
+            ? { reason: 'UI tree capture was attached to the run.' }
+            : {
+                reason: 'No UI tree capture was produced by the selected runner/provider set.',
+                nextAction: 'Use --capture uiTree:<path> or add an accessibility/UI-tree provider.',
+            }),
+    });
+    pushDiagnostic('video', {
+        status: attachedEvidence.captures.video ? 'captured' : 'unavailable',
+        ...(attachedEvidence.captures.video ? { path: attachedEvidence.captures.video } : {}),
+        ...(attachedEvidence.captures.video
+            ? { reason: 'Video capture was attached to the run.' }
+            : {
+                reason: 'No video capture was produced by the selected runner/provider set.',
+                nextAction: 'Use --capture video:<path> or run a capture provider that records video.',
+            }),
+    });
+    for (const kind of ['memory', 'network']) {
+        pushDiagnostic(kind, {
+            status: attachedEvidence.signals[kind].length > 0 ? 'captured' : 'unavailable',
+            ...(attachedEvidence.signals[kind][0] ? { path: attachedEvidence.signals[kind][0] } : {}),
+            ...(attachedEvidence.signals[kind].length > 0
+                ? { reason: `${kind} signal evidence was attached to the run.` }
+                : {
+                    reason: `No ${kind} signal evidence was produced by the selected provider set.`,
+                    nextAction: `Attach ${kind} evidence with --signal ${kind}:<path> or add a provider command that emits it.`,
+                }),
+        });
+    }
+    for (const kind of ['accessibility', 'profiler']) {
+        const attachment = attachedEvidence.attachments.find((item) => item.kind === kind);
+        pushDiagnostic(kind, {
+            ...(attachment?.channel === 'provider' ? { provider: 'evidence-provider' } : {}),
+            status: attachment ? 'captured' : 'unavailable',
+            ...(attachment ? { path: attachment.manifestPath } : {}),
+            ...(attachment
+                ? { reason: `${kind} provider evidence was attached to the run.` }
+                : {
+                    reason: `No ${kind} provider attachment was produced by the selected provider set.`,
+                    nextAction: `Declare a provider command or attach ${kind} evidence before expecting this diagnostic.`,
+                }),
+        });
+    }
+    return entries.map((entry) => {
+        const cleaned = Object.entries(entry).filter(([, value]) => value !== undefined);
+        return Object.fromEntries(cleaned);
+    });
+}
+/**
+ * Converts uncaptured required diagnostics into health checks.
+ *
+ * @param {DiagnosticInventoryEntry[]} diagnostics
+ * @returns {Record<string, unknown>[]}
+ */
+function buildRequiredDiagnosticHealthChecks(diagnostics = []) {
+    return diagnostics
+        .filter((diagnostic) => diagnostic.required && diagnostic.status !== 'captured')
+        .map((diagnostic) => ({
+        name: `required_${diagnostic.kind}_diagnostic`,
+        status: 'failed',
+        source: 'evidence',
+        code: 'required_diagnostic_not_captured',
+        message: diagnostic.reason ?? `Required ${diagnostic.kind} diagnostic was not captured.`,
+        metadata: {
+            kind: diagnostic.kind,
+            status: diagnostic.status,
+            ...(diagnostic.name ? { name: diagnostic.name } : {}),
+            ...(diagnostic.nextAction ? { nextAction: diagnostic.nextAction } : {}),
+            ...(diagnostic.provider ? { provider: diagnostic.provider } : {}),
+            ...(diagnostic.runnerId ? { runnerId: diagnostic.runnerId } : {}),
+        },
+    }));
+}
 /**
  * Builds scenario health from profile metrics.
  *
- * @param {{scenario: Record<string, unknown>, runId: string, metrics: Record<string, unknown>}} options
+ * @param {{scenario: Record<string, unknown>, runId: string, metrics: Record<string, unknown>, diagnostics?: DiagnosticInventoryEntry[], profileEventCount?: number, profileSessionEntryCount?: number, commandTransport?: string, sessionEntries?: Record<string, unknown>[]}} options
  * @returns {Record<string, unknown>}
  */
-function buildProfileHealth({ scenario, runId, metrics, }) {
+function buildProfileHealth({ scenario, runId, metrics, diagnostics = [], profileEventCount, profileSessionEntryCount, commandTransport, sessionEntries = [], }) {
     const passed = metrics.status === 'passed';
+    const metadata = {
+        failures: typeof metrics.failures === 'number' ? metrics.failures : null,
+        timeouts: typeof metrics.timeouts === 'number' ? metrics.timeouts : null,
+    };
+    if (typeof profileEventCount === 'number') {
+        metadata.profileEventCount = profileEventCount;
+    }
+    if (typeof profileSessionEntryCount === 'number') {
+        metadata.profileSessionEntryCount = profileSessionEntryCount;
+    }
+    if (typeof commandTransport === 'string' && commandTransport.length > 0) {
+        metadata.commandTransport = commandTransport;
+    }
+    if (!passed &&
+        profileEventCount === 0 &&
+        profileSessionEntryCount === 0 &&
+        typeof commandTransport === 'string' &&
+        commandTransport.startsWith('profile-session')) {
+        metadata.nextActionCode = 'verify_profile_session_bootstrap';
+        metadata.nextAction =
+            'Verify the app loaded the expected bundle, mounted the profile-session bootstrap near the app root, and uses the configured storage keys or deep-link scheme before treating this as a product failure.';
+    }
+    const skippedCommands = sessionEntries.filter((entry) => (entry?.kind === 'command' && entry.status === 'skipped'));
+    const firstSkippedCommand = skippedCommands[0];
+    const firstSkippedReason = typeof firstSkippedCommand?.reason === 'string'
+        ? firstSkippedCommand.reason
+        : undefined;
+    const commandFailureCode = firstSkippedReason === 'wait-for-milestone-timeout'
+        ? 'profile_command_gate_timeout'
+        : 'profile_command_skipped';
+    const commandFailureMessage = firstSkippedReason === 'wait-for-milestone-timeout'
+        ? 'One or more profile-session commands waited for a milestone that was not observed before timeout.'
+        : 'One or more profile-session commands were skipped before the scenario completed.';
+    const commandChecks = skippedCommands.length > 0
+        ? [
+            {
+                name: 'profile_command_sequence',
+                status: 'failed',
+                source: 'runner',
+                code: commandFailureCode,
+                message: commandFailureMessage,
+                metadata: {
+                    skippedCommandCount: skippedCommands.length,
+                    ...(typeof firstSkippedCommand?.command === 'string' ? { command: firstSkippedCommand.command } : {}),
+                    ...(typeof firstSkippedCommand?.commandId === 'string' ? { commandId: firstSkippedCommand.commandId } : {}),
+                    ...(typeof firstSkippedCommand?.queueId === 'string' ? { queueId: firstSkippedCommand.queueId } : {}),
+                    ...(typeof firstSkippedCommand?.reason === 'string' ? { reason: firstSkippedCommand.reason } : {}),
+                    ...(typeof firstSkippedCommand?.sequence === 'number' ? { sequence: firstSkippedCommand.sequence } : {}),
+                    ...(typeof firstSkippedCommand?.waitForMilestone === 'string'
+                        ? { waitForMilestone: firstSkippedCommand.waitForMilestone }
+                        : {}),
+                    ...(typeof firstSkippedCommand?.waitTimeoutMs === 'number'
+                        ? { waitTimeoutMs: firstSkippedCommand.waitTimeoutMs }
+                        : {}),
+                },
+            },
+        ]
+        : [];
+    const commandChecksPassed = commandChecks.every((check) => check.status === 'passed');
+    const diagnosticChecks = buildRequiredDiagnosticHealthChecks(diagnostics);
+    const diagnosticChecksPassed = diagnosticChecks.every((check) => check.status === 'passed');
+    const healthPassed = passed && commandChecksPassed && diagnosticChecksPassed;
     return assertValidJson({
         schemaVersion: '1.0.0',
         scenarioId: scenario.name,
         ...(typeof scenario.flowId === 'string' ? { flowId: scenario.flowId } : {}),
         runId,
-        healthStatus: passed ? 'passed' : 'failed',
+        healthStatus: healthPassed ? 'passed' : 'failed',
         checks: [
             {
                 name: 'truth_events_complete',
@@ -601,11 +1058,10 @@ function buildProfileHealth({ scenario, runId, metrics, }) {
                 message: passed
                     ? 'Profile events completed every expected iteration.'
                     : 'Profile events did not complete every expected iteration.',
-                metadata: {
-                    failures: typeof metrics.failures === 'number' ? metrics.failures : null,
-                    timeouts: typeof metrics.timeouts === 'number' ? metrics.timeouts : null,
-                },
+                metadata,
             },
+            ...commandChecks,
+            ...diagnosticChecks,
         ],
     }, SCHEMAS.health, 'Health artifact');
 }
@@ -857,6 +1313,121 @@ function resolveProfileSessionEntriesPath({ args, platform }) {
     }
     return null;
 }
+/**
+ * Resolves the run id used by rehydrated sidecar evidence.
+ *
+ * A rehydrated artifact can intentionally have a new run id while ingesting a
+ * previously captured adb/simctl sidecar. Keep live runs strict, but allow an
+ * explicit sidecar with exactly one source run id for the scenario to provide
+ * the event filter.
+ *
+ * @param {{args: CliArgs, eventLogText: string, profileSessionEntriesPath: string | null, runId: string, scenarioName: string}} options
+ * @returns {string}
+ */
+function resolveEvidenceFilterRunId({ args, eventLogText, profileSessionEntriesPath, runId, scenarioName, }) {
+    const isRehydratedSidecar = typeof args['adb-artifacts'] === 'string' || typeof args['simctl-artifacts'] === 'string';
+    if (!isRehydratedSidecar) {
+        return runId;
+    }
+    const scenarioEvents = extractProfileEvents(eventLogText, { scenario: scenarioName });
+    const currentRunEvents = scenarioEvents.filter((event) => event.runId === runId);
+    if (currentRunEvents.length > 0) {
+        return runId;
+    }
+    const sourceRunIds = new Set(scenarioEvents
+        .map((event) => event.runId)
+        .filter((sourceRunId) => typeof sourceRunId === 'string' && sourceRunId.length > 0));
+    if (profileSessionEntriesPath && fs.existsSync(profileSessionEntriesPath)) {
+        const storedEntries = JSON.parse(fs.readFileSync(profileSessionEntriesPath, 'utf8'));
+        if (Array.isArray(storedEntries)) {
+            for (const entry of storedEntries) {
+                if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+                    continue;
+                }
+                const record = entry;
+                if (record.scenario !== scenarioName) {
+                    continue;
+                }
+                if (typeof record.runId === 'string' && record.runId.length > 0) {
+                    sourceRunIds.add(record.runId);
+                }
+            }
+        }
+    }
+    return sourceRunIds.size === 1 ? [...sourceRunIds][0] : runId;
+}
+/**
+ * Returns the first usable adb screenshot file from sidecar metadata.
+ *
+ * ADB can produce a valid PNG even when command metadata records a nonzero
+ * exit status from the host process. Treat the binary artifact as the capture
+ * authority, but only after validating the PNG signature and sidecar boundary.
+ *
+ * @param {{runDir: string, sidecarRoot: string | null}} options
+ * @returns {{dependency: SidecarEvidenceDependency, path: string} | null}
+ */
+function resolveAndroidAdbScreenshotDependency({ runDir, sidecarRoot, }) {
+    if (!sidecarRoot) {
+        return null;
+    }
+    const metadata = readOptionalJsonObject(path.resolve(sidecarRoot, 'raw', 'android-metadata.json'));
+    const actions = Array.isArray(metadata?.driverActions) ? metadata.driverActions : [];
+    for (const action of actions) {
+        if (!action || typeof action !== 'object' || Array.isArray(action)) {
+            continue;
+        }
+        const record = action;
+        if (record.driverAction !== 'screenshot') {
+            continue;
+        }
+        const sidecarRelativePath = typeof record.capturePath === 'string'
+            ? record.capturePath
+            : typeof record.rawPath === 'string'
+                ? record.rawPath
+                : null;
+        if (!sidecarRelativePath || path.isAbsolute(sidecarRelativePath)) {
+            continue;
+        }
+        const screenshotPath = path.resolve(sidecarRoot, sidecarRelativePath);
+        const relativeToSidecar = path.relative(sidecarRoot, screenshotPath);
+        if (relativeToSidecar.length === 0 ||
+            relativeToSidecar.startsWith('..') ||
+            path.isAbsolute(relativeToSidecar) ||
+            !isPngFile(screenshotPath)) {
+            continue;
+        }
+        const sidecarDependency = toSidecarEvidenceDependency({ runDir, sidecarRoot, targetPath: screenshotPath });
+        return {
+            dependency: sidecarDependency,
+            path: sidecarDependency.path,
+        };
+    }
+    return null;
+}
+/**
+ * Checks whether a file starts with the PNG signature.
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isPngFile(filePath) {
+    let signature;
+    try {
+        signature = fs.readFileSync(filePath, { flag: 'r' }).subarray(0, 8);
+    }
+    catch {
+        return false;
+    }
+    return signature.length === 8 &&
+        signature[0] === 0x89 &&
+        signature[1] === 0x50 &&
+        signature[2] === 0x4e &&
+        signature[3] === 0x47 &&
+        signature[4] === 0x0d &&
+        signature[5] === 0x0a &&
+        signature[6] === 0x1a &&
+        signature[7] === 0x0a;
+}
 /**
  * Reads a JSON artifact if it exists and contains an object.
  *
@@ -1045,6 +1616,46 @@ function findMilestoneEvent(scenario, milestoneId) {
     }
     return null;
 }
+/**
+ * Returns true when a milestone is explicitly optional.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {unknown} milestoneId
+ * @returns {boolean}
+ */
+function isOptionalMilestone(scenario, milestoneId) {
+    if (typeof milestoneId !== 'string' || !Array.isArray(scenario.milestones)) {
+        return false;
+    }
+    for (const milestone of scenario.milestones) {
+        if (!isRecord(milestone)) {
+            continue;
+        }
+        if (milestone.id === milestoneId) {
+            return milestone.required === false;
+        }
+    }
+    return false;
+}
+/**
+ * Returns true when a milestone represents one-time scenario readiness rather than a repeated cycle edge.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {unknown} milestoneId
+ * @param {string | null} milestoneEvent
+ * @returns {boolean}
+ */
+function isReadinessMilestone(scenario, milestoneId, milestoneEvent) {
+    const readyEvent = isRecord(scenario.truthEvents) && isRecord(scenario.truthEvents.ready)
+        ? scenario.truthEvents.ready.event
+        : undefined;
+    if (typeof readyEvent === 'string' && milestoneEvent === readyEvent) {
+        return true;
+    }
+    const id = typeof milestoneId === 'string' ? milestoneId.toLowerCase() : '';
+    const event = typeof milestoneEvent === 'string' ? milestoneEvent.toLowerCase() : '';
+    return id.includes('ready') || event.includes('ready');
+}
 /**
  * Builds a milestone-id to event-name lookup for schema-era scenarios.
  *
@@ -1100,6 +1711,16 @@ function resolveProfileMetricEvents(scenario) {
                 milestone: toEvent,
             };
         }
+        if (fromEvent && toEvent && isReadinessMilestone(scenario, budget.fromMilestone, fromEvent)) {
+            return {
+                milestone: toEvent,
+            };
+        }
+        if (fromEvent && toEvent && isOptionalMilestone(scenario, budget.fromMilestone)) {
+            return {
+                milestone: toEvent,
+            };
+        }
         if (fromEvent && toEvent) {
             return {
                 closeRequested: toEvent,
@@ -1112,7 +1733,59 @@ function resolveProfileMetricEvents(scenario) {
     return null;
 }
 /**
- * Maps schema-era milestone budget fields to the legacy profile budget keys.
+ * Resolves how many repeated completion milestone events prove one cycle body.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {Record<string, string> | null} metricEvents
+ * @returns {number}
+ */
+function resolveMilestoneEventsPerIteration(scenario, metricEvents) {
+    if (!metricEvents || typeof metricEvents.milestone !== 'string' || !Array.isArray(scenario.steps)) {
+        return 1;
+    }
+    const milestoneEvents = buildMilestoneEventLookup(scenario);
+    const matchingWaitStepIds = new Set();
+    for (const step of scenario.steps) {
+        if (!isRecord(step) || step.kind !== 'waitForMilestone' || typeof step.milestone !== 'string') {
+            continue;
+        }
+        const event = milestoneEvents[step.milestone] ?? step.milestone;
+        if (event === metricEvents.milestone && typeof step.id === 'string') {
+            matchingWaitStepIds.add(step.id);
+        }
+    }
+    if (matchingWaitStepIds.size === 0) {
+        return 1;
+    }
+    const bodyStepIds = isRecord(scenario.cycles) && Array.isArray(scenario.cycles.bodyStepIds)
+        ? new Set(scenario.cycles.bodyStepIds.filter((entry) => typeof entry === 'string'))
+        : null;
+    if (bodyStepIds && bodyStepIds.size > 0) {
+        let count = 0;
+        let bodyCommandPending = false;
+        for (const step of scenario.steps) {
+            if (!isRecord(step)) {
+                continue;
+            }
+            if (typeof step.id === 'string' && bodyStepIds.has(step.id) && step.kind === 'command') {
+                bodyCommandPending = true;
+                continue;
+            }
+            if (bodyCommandPending && typeof step.id === 'string' && matchingWaitStepIds.has(step.id)) {
+                count += 1;
+                bodyCommandPending = false;
+                continue;
+            }
+            if (bodyCommandPending && step.kind === 'command') {
+                bodyCommandPending = false;
+            }
+        }
+        return count > 1 ? count : 1;
+    }
+    return matchingWaitStepIds.size > 1 ? matchingWaitStepIds.size : 1;
+}
+/**
+ * Maps shorthand milestone budget fields to aggregate profile budget keys.
  *
  * @param {{budget: Record<string, unknown>, metric: string}} options
  * @returns {string | null}
@@ -1144,11 +1817,24 @@ function resolveProfileBudgets(scenario) {
         return null;
     }
     const pass = {};
+    const intervals = [];
     for (const budget of scenario.budgets) {
         if (!isRecord(budget) || typeof budget.limit !== 'number') {
             continue;
         }
         if (budget.metric === 'p95' || budget.metric === 'p50') {
+            const fromEvent = findMilestoneEvent(scenario, budget.fromMilestone);
+            const toEvent = findMilestoneEvent(scenario, budget.toMilestone);
+            if (fromEvent && toEvent) {
+                intervals.push({
+                    name: typeof budget.name === 'string' ? budget.name : `${String(budget.fromMilestone)} to ${String(budget.toMilestone)}`,
+                    metric: budget.metric,
+                    limit: budget.limit,
+                    fromEvent,
+                    toEvent,
+                });
+                continue;
+            }
             const budgetKey = resolveProfileBudgetKey({ budget, metric: budget.metric });
             if (budgetKey) {
                 pass[budgetKey] = budget.limit;
@@ -1161,10 +1847,11 @@ function resolveProfileBudgets(scenario) {
             pass.timeouts = budget.limit;
         }
     }
-    return Object.keys(pass).length > 0
+    return Object.keys(pass).length > 0 || intervals.length > 0
         ? {
             metric: 'milestone budget',
             pass,
+            ...(intervals.length > 0 ? { intervals } : {}),
         }
         : null;
 }
@@ -1287,6 +1974,7 @@ async function runProfileMobile(args, options) {
     const scenarioHash = hashScenarioContract(profileScenario);
     const expectedIterations = resolveExpectedIterations(profileScenario);
     const profileMetricEvents = resolveProfileMetricEvents(profileScenario);
+    const milestoneEventsPerIteration = resolveMilestoneEventsPerIteration(profileScenario, profileMetricEvents);
     const profileBudgets = resolveProfileBudgets(profileScenario);
     const runId = typeof args['run-id'] === 'string' ? args['run-id'] : createRunId();
     const artifactRoot = resolveArtifactRoot({ args, config, configPath, platform: options.platform });
@@ -1342,15 +2030,69 @@ async function runProfileMobile(args, options) {
             verdict,
         };
     }
-    const attachedEvidence = await resolveAttachedEvidence({ args, layout, providerInputs: providerExecution.inputs });
+    let attachedEvidence;
+    try {
+        attachedEvidence = await resolveAttachedEvidence({ args, layout, providerInputs: providerExecution.inputs });
+    }
+    catch (error) {
+        const providerInput = providerExecution.inputs.find((input) => error instanceof Error && error.message.includes(input.sourcePath));
+        const health = buildProviderCommandFailureHealth({
+            failures: [
+                {
+                    commandId: 'provider-evidence',
+                    code: 'provider_evidence_invalid',
+                    exitCode: null,
+                    message: error instanceof Error ? error.message : String(error),
+                    name: 'evidence_provider_output_valid',
+                    nextAction: 'Fix the provider output so it satisfies the ASL evidence contract, then rerun the profile.',
+                    nextActionCode: 'fix_provider_evidence_output',
+                    phase: 'afterCapture',
+                    providerId: providerInput?.providerId ?? 'unknown-provider',
+                    ...(providerInput?.manifestPath ? { rawPath: providerInput.manifestPath } : {}),
+                },
+            ],
+            runId,
+            scenario: profileScenario,
+        });
+        const verdict = buildProfileVerdict({ scenario: profileScenario, runId, health, metrics: {} });
+        const agentSummary = buildAgentSummaryMarkdown({ health, verdict });
+        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 {
+            runDir,
+            health,
+            verdict,
+        };
+    }
     const eventLogText = eventLogPath ? await fsp.readFile(eventLogPath, 'utf8') : '';
+    const evidenceFilterRunId = resolveEvidenceFilterRunId({
+        args,
+        eventLogText,
+        profileSessionEntriesPath,
+        runId,
+        scenarioName,
+    });
     const events = extractProfileEvents(eventLogText, {
         scenario: scenarioName,
-        runId,
+        runId: evidenceFilterRunId,
     });
     const logSessionEntries = extractProfileSessionEntries(eventLogText, {
         scenario: scenarioName,
-        runId,
+        runId: evidenceFilterRunId,
     });
     const storedSessionEntries = profileSessionEntriesPath
         ? JSON.parse(await fsp.readFile(profileSessionEntriesPath, 'utf8'))
@@ -1364,7 +2106,7 @@ async function runProfileMobile(args, options) {
                 }
                 const record = entry;
                 return ((!('scenario' in record) || record.scenario === scenarioName) &&
-                    (!('runId' in record) || record.runId === runId));
+                    (!('runId' in record) || record.runId === evidenceFilterRunId));
             })
             : []),
     ];
@@ -1376,11 +2118,16 @@ async function runProfileMobile(args, options) {
         expectedIterations,
         budgets: profileBudgets,
         cycleEventNames: profileMetricEvents,
+        milestoneEventsPerIteration,
         artifacts: {
             captures: attachedEvidence.captures,
             signals: attachedEvidence.signals,
         },
     });
+    const eventLogRawPath = eventLogPath ? `raw/${path.basename(eventLogPath)}` : undefined;
+    const eventLogIsProfileSessionEvidenceOnly = options.platform === 'ios' &&
+        eventLogPath &&
+        path.basename(eventLogPath) === 'ios-profile-events.log';
     const manifestArtifacts = {
         causalRun: 'causal-run.json',
         budgetVerdict: 'budget-verdict.json',
@@ -1389,13 +2136,20 @@ async function runProfileMobile(args, options) {
         summary: 'summary.md',
         scenario: toPortablePathReference(scenarioPath),
         raw: {
-            interactionLog: eventLogPath ? `raw/${path.basename(eventLogPath)}` : 'raw/interaction.log',
-            deviceLog: 'raw/device.log',
+            ...(eventLogRawPath && !eventLogIsProfileSessionEvidenceOnly
+                ? {
+                    interactionLog: eventLogRawPath,
+                    deviceLog: eventLogRawPath,
+                }
+                : {}),
+            ...(profileSessionEntriesPath
+                ? { profileSessionEntries: `raw/${path.basename(profileSessionEntriesPath)}` }
+                : {}),
         },
         captures: {
             screenshots: attachedEvidence.captures.screenshots,
-            video: attachedEvidence.captures.video ?? 'captures/run.mp4',
-            uiTree: attachedEvidence.captures.uiTree ?? 'captures/ui-tree.json',
+            ...(attachedEvidence.captures.video ? { video: attachedEvidence.captures.video } : {}),
+            ...(attachedEvidence.captures.uiTree ? { uiTree: attachedEvidence.captures.uiTree } : {}),
         },
         signals: {
             js: attachedEvidence.signals.js,
@@ -1403,8 +2157,18 @@ async function runProfileMobile(args, options) {
             network: attachedEvidence.signals.network,
         },
         evidenceAttachments: buildEvidenceAttachmentManifest(attachedEvidence.attachments),
+        diagnostics: buildDiagnosticInventory({
+            args,
+            attachedEvidence,
+            eventLogPath,
+            platform: options.platform,
+            profileSessionEntriesPath,
+            runDir,
+            scenario: profileScenario,
+        }),
     };
     const appId = resolveAppId({ config, platform: options.platform });
+    const commandTransport = resolveCommandTransport({ args, interactionDriver, options });
     const provenanceCohort = buildProfileProvenanceCohort({
         appId,
         args,
@@ -1465,7 +2229,16 @@ async function runProfileMobile(args, options) {
         runId,
         budgetEvaluation: metrics.budgetEvaluation ?? null,
     });
-    const health = buildProfileHealth({ scenario: profileScenario, runId, metrics });
+    const health = buildProfileHealth({
+        scenario: profileScenario,
+        runId,
+        metrics,
+        diagnostics: manifestArtifacts.diagnostics,
+        profileEventCount: events.length,
+        profileSessionEntryCount: sessionEntries.length,
+        commandTransport,
+        sessionEntries,
+    });
     const verdict = buildProfileVerdict({ scenario: profileScenario, runId, health, metrics });
     const agentSummary = buildAgentSummaryMarkdown({ health, verdict, manifest });
     const summary = buildSummaryMarkdown({ manifest, metrics });