agent-scenario-loop 0.1.3 → 0.1.5

package/dist/runner/profile-ios.js

@@ -18,7 +18,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { hasHelpFlag } = require('./cli');
 const { buildScenarioExecutionPlan } = require('../core/execution-plan');
-const { buildProfileHealth, buildProfileVerdict, buildVerdictBudgetChecks, parseArgs, readScalarArg, runProfileCli, runProfileMobile, usage, } = require('./profile-mobile');
+const { buildProfileHealth, buildProfileVerdict, buildVerdictBudgetChecks, parseArgs, readScalarArg, resolveArtifactRoot, resolveProfileScenarioName, runProfileCompatibilityPreflight, runProfileCli, runProfileMobile, usage, } = require('./profile-mobile');
 exports.buildProfileHealth = buildProfileHealth;
 exports.buildProfileVerdict = buildProfileVerdict;
 exports.buildVerdictBudgetChecks = buildVerdictBudgetChecks;
@@ -28,7 +28,10 @@ const { runIosSimctlCapture } = require('./ios-simctl');
 const { runAgentDeviceCapture } = require('./agent-device');
 const { loadAslLocalEnv, readStringArgOrEnv } = require('./local-env');
 const PROFILE_SESSION_CAPTURE_BOOTSTRAP_MS = 1000;
-const PROFILE_SESSION_CAPTURE_MAX_MS = 30000;
+const PROFILE_SESSION_CAPTURE_COMMAND_OVERHEAD_MS = 250;
+const PROFILE_SESSION_CAPTURE_BUFFER_MIN_MS = 2000;
+const PROFILE_SESSION_CAPTURE_BUFFER_RATIO = 0.2;
+const PROFILE_SESSION_CAPTURE_MAX_MS = 10 * 60 * 1000;
 const DEFAULT_IOS_PROFILE_SESSION_STORAGE_KEY = 'agent-scenario-loop.profile-session.1';
 const DEFAULT_IOS_PROFILE_COMMAND_STORAGE_KEY = 'agent-scenario-loop.profile-commands.1';
 const DEFAULT_IOS_PROFILE_EVENT_STORAGE_KEY = 'agent-scenario-loop.profile-events.1';
@@ -49,6 +52,17 @@ const MANIFEST_LIFECYCLE_PHASES = new Set([
     'reboot',
     'relaunch',
 ]);
+const IOS_PROFILE_RUNNER_CAPABILITIES = {
+    schemaVersion: '1.0.0',
+    runnerId: 'ios-simctl-profile-runner',
+    kind: 'primary',
+    platforms: ['ios'],
+    capabilities: ['launch', 'sessionControl', 'command', 'logCapture', 'artifactWrite'],
+    driverActions: ['tap', 'scroll', 'assertVisible', 'inspectTree', 'screenshot', 'readLogs'],
+    artifactOutputs: ['logs', 'signals', 'screenshot', 'uiTree'],
+    uiContexts: ['app'],
+    lifecycle: ['prepare', 'launch', 'startSession', 'executeStep', 'waitForTruthEvent', 'captureEvidence', 'stopSession', 'finalize'],
+};
 /**
  * Reads and parses a JSON object from disk.
  *
@@ -171,7 +185,7 @@ function resolveIosConflictingBundleIds(config) {
  * @param {{config: Record<string, unknown>, action: 'start' | 'command', scenario: string, runId: string, command?: string}} options
  * @returns {string}
  */
-function buildProfileSessionUrl({ action, command, commandId, config, queueId, runId, scenario, sequence, waitForMilestone, waitTimeoutMs, }) {
+function buildProfileSessionUrl({ action, command, commandId, config, queueId, runId, scenario, sequence, waitForMilestone, waitMs, waitTimeoutMs, }) {
     const scheme = typeof config.app?.profileSessionScheme === 'string'
         ? config.app.profileSessionScheme
         : typeof config.app?.scheme === 'string'
@@ -192,6 +206,9 @@ function buildProfileSessionUrl({ action, command, commandId, config, queueId, r
         if (waitForMilestone) {
             params.set('waitForMilestone', waitForMilestone);
         }
+        if (typeof waitMs === 'number') {
+            params.set('waitMs', String(waitMs));
+        }
         if (typeof waitTimeoutMs === 'number') {
             params.set('waitTimeoutMs', String(waitTimeoutMs));
         }
@@ -215,24 +232,49 @@ function readStepWaitMs(step) {
     return readPositiveInteger(step.timeoutMs, 0);
 }
 /**
- * Derives a storage-backed profile capture window from scenario waits and cycles.
+ * Reads wait time from a profile-session command.
+ *
+ * @param {IosSimctlProfileCommand} command
+ * @returns {number}
+ */
+function readProfileCommandWindowMs(command) {
+    return readPositiveInteger(command.waitMs, 0) +
+        readPositiveInteger(command.waitTimeoutMs, 0) +
+        PROFILE_SESSION_CAPTURE_COMMAND_OVERHEAD_MS;
+}
+/**
+ * Reads execution-plan waits that are not already attached to a profile-session command.
  *
  * @param {Record<string, unknown>} scenario
  * @returns {number}
  */
-function deriveProfileSessionCaptureWaitMs(scenario) {
+function readUnattachedExecutionWaitMs(scenario) {
     const executionPlan = buildScenarioExecutionPlan(scenario);
     const iterations = readScenarioIterationCount(scenario);
-    const perIterationWaitMs = executionPlan.steps.reduce((total, step) => {
-        if (step.kind === 'command') {
-            return total + readStepWaitMs(step);
+    const perIterationWaitMs = executionPlan.steps.reduce((total, step, index) => {
+        if (step.portMethod !== 'waitForTruthEvent') {
+            return total;
         }
-        if (step.portMethod === 'waitForTruthEvent') {
-            return total + readPositiveInteger(step.timeoutMs, 0);
+        const previousStep = executionPlan.steps[index - 1];
+        if (previousStep?.portMethod === 'executeStep') {
+            return total;
         }
-        return total;
+        return total + readPositiveInteger(step.timeoutMs, 0);
     }, 0);
-    const derivedWaitMs = PROFILE_SESSION_CAPTURE_BOOTSTRAP_MS + (perIterationWaitMs * iterations);
+    return perIterationWaitMs * iterations;
+}
+/**
+ * Derives a storage-backed profile capture window from scenario waits, command gates, and cycles.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {number}
+ */
+function deriveProfileSessionCaptureWaitMs(scenario) {
+    const commands = resolveIosSimctlProfileCommands(scenario);
+    const commandWindowMs = commands.reduce((total, command) => total + readProfileCommandWindowMs(command), 0);
+    const executionWindowMs = commandWindowMs + readUnattachedExecutionWaitMs(scenario);
+    const bufferMs = Math.max(PROFILE_SESSION_CAPTURE_BUFFER_MIN_MS, Math.ceil(executionWindowMs * PROFILE_SESSION_CAPTURE_BUFFER_RATIO));
+    const derivedWaitMs = PROFILE_SESSION_CAPTURE_BOOTSTRAP_MS + executionWindowMs + bufferMs;
     return Math.min(Math.max(derivedWaitMs, PROFILE_SESSION_CAPTURE_BOOTSTRAP_MS), PROFILE_SESSION_CAPTURE_MAX_MS);
 }
 /**
@@ -271,16 +313,182 @@ function resolveExecutionPlanProfileCommands(scenario) {
             waitMs: readStepWaitMs(step),
             ...(nextStep?.portMethod === 'waitForTruthEvent' && typeof nextStep.milestone === 'string'
                 ? {
-                    waitForMilestone: nextStep.milestone,
+                    waitForMilestone: resolveMilestoneEventName(scenario, nextStep.milestone),
                     waitTimeoutMs: readPositiveInteger(nextStep.timeoutMs, 0),
                 }
                 : {}),
         });
     }
-    return Array.from({ length: repeat }).flatMap((_, iteration) => commands.map((command, commandIndex) => ({
+    return expandProfileCommandCycles(scenario, commands, repeat);
+}
+/**
+ * Returns true when a command is part of the setup prefix that establishes app readiness before repeated cycle work.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {IosSimctlProfileCommand} command
+ * @returns {boolean}
+ */
+function isReadinessSetupProfileCommand(scenario, command) {
+    if (typeof command.waitForMilestone !== 'string') {
+        return false;
+    }
+    const readyEvent = resolveScenarioReadinessEvent(scenario);
+    return typeof readyEvent === 'string' && command.waitForMilestone === readyEvent;
+}
+/**
+ * Reads a string id list from scenario cycles metadata.
+ *
+ * @param {unknown} value
+ * @returns {Set<string>}
+ */
+function readCycleStepIdSet(value) {
+    return new Set(Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : []);
+}
+/**
+ * Resolves the milestone ids that represent measured cycle boundaries.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {Set<string>}
+ */
+function resolveMeasuredCycleMilestoneEvents(scenario) {
+    const milestones = new Set();
+    for (const budget of Array.isArray(scenario.budgets) ? scenario.budgets : []) {
+        if (!budget || typeof budget !== 'object' || budget.source !== 'milestone') {
+            continue;
+        }
+        if (typeof budget.fromMilestone === 'string') {
+            milestones.add(resolveMilestoneEventName(scenario, budget.fromMilestone));
+        }
+        if (typeof budget.toMilestone === 'string') {
+            milestones.add(resolveMilestoneEventName(scenario, budget.toMilestone));
+        }
+    }
+    return milestones;
+}
+/**
+ * Resolves how many leading commands are setup-only before repeated cycle work.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {IosSimctlProfileCommand[]} commands
+ * @returns {number}
+ */
+function resolveSetupCommandCount(scenario, commands) {
+    const explicitSetupStepIds = readCycleStepIdSet(scenario.cycles?.setupStepIds);
+    if (explicitSetupStepIds.size > 0) {
+        let count = 0;
+        for (const command of commands) {
+            if (!command.commandId || !explicitSetupStepIds.has(command.commandId)) {
+                break;
+            }
+            count += 1;
+        }
+        return count;
+    }
+    const explicitBodyStepIds = readCycleStepIdSet(scenario.cycles?.bodyStepIds);
+    if (explicitBodyStepIds.size > 0) {
+        const firstBodyIndex = commands.findIndex((command) => (typeof command.commandId === 'string' && explicitBodyStepIds.has(command.commandId)));
+        return firstBodyIndex > 0 ? firstBodyIndex : 0;
+    }
+    let readinessSetupCommandCount = 0;
+    for (const command of commands) {
+        if (!isReadinessSetupProfileCommand(scenario, command)) {
+            break;
+        }
+        readinessSetupCommandCount += 1;
+    }
+    if (readinessSetupCommandCount > 0) {
+        return readinessSetupCommandCount;
+    }
+    const measuredMilestones = resolveMeasuredCycleMilestoneEvents(scenario);
+    if (measuredMilestones.size === 0) {
+        return 0;
+    }
+    const firstMeasuredCommandIndex = commands.findIndex((command) => (typeof command.waitForMilestone === 'string' && measuredMilestones.has(command.waitForMilestone)));
+    return firstMeasuredCommandIndex > 0 ? firstMeasuredCommandIndex : 0;
+}
+/**
+ * Expands commands so setup/readiness commands execute once while cycle-body commands repeat.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {IosSimctlProfileCommand[]} commands
+ * @param {number} repeat
+ * @returns {IosSimctlProfileCommand[]}
+ */
+function expandProfileCommandCycles(scenario, commands, repeat) {
+    const setupCommandCount = resolveSetupCommandCount(scenario, commands);
+    const setupCommands = commands.slice(0, setupCommandCount);
+    const cycleCommands = commands.slice(setupCommandCount);
+    const expandedCommands = cycleCommands.length === 0
+        ? setupCommands
+        : [
+            ...setupCommands,
+            ...Array.from({ length: repeat }).flatMap(() => cycleCommands),
+        ];
+    return expandedCommands.map((command, index) => ({
         ...command,
-        sequence: (iteration * commands.length) + commandIndex + 1,
-    })));
+        sequence: index + 1,
+    }));
+}
+/**
+ * Resolves a portable milestone id to the app truth event that releases command sequencing.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {string} milestone
+ * @returns {string}
+ */
+function resolveMilestoneEventName(scenario, milestone) {
+    const milestoneEntry = Array.isArray(scenario.milestones)
+        ? scenario.milestones.find((entry) => entry?.id === milestone)
+        : undefined;
+    if (typeof milestoneEntry?.event === 'string' && milestoneEntry.event.length > 0) {
+        return milestoneEntry.event;
+    }
+    const metricEvent = scenario.metricEvents?.[milestone];
+    return typeof metricEvent === 'string' && metricEvent.length > 0 ? metricEvent : milestone;
+}
+/**
+ * Resolves the scenario truth event that represents initial app readiness.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {string | null}
+ */
+function resolveScenarioReadinessEvent(scenario) {
+    const explicitReadyEvent = scenario.truthEvents?.ready?.event;
+    if (typeof explicitReadyEvent === 'string' && explicitReadyEvent.length > 0) {
+        return explicitReadyEvent;
+    }
+    const milestoneEntry = Array.isArray(scenario.milestones)
+        ? scenario.milestones.find((entry) => (String(entry?.event ?? '').includes('ready')))
+        : undefined;
+    return typeof milestoneEntry?.event === 'string' && milestoneEntry.event.length > 0
+        ? milestoneEntry.event
+        : null;
+}
+/**
+ * Applies wait gates from the normalized execution plan to platform-declared commands.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @param {IosSimctlProfileCommand[]} commands
+ * @returns {IosSimctlProfileCommand[]}
+ */
+function applyExecutionPlanCommandGates(scenario, commands) {
+    const planCommands = resolveExecutionPlanProfileCommands(scenario);
+    if (planCommands.length === 0) {
+        return commands;
+    }
+    return commands.map((command, index) => {
+        const planCommand = planCommands[index];
+        if (!planCommand || typeof planCommand.waitForMilestone !== 'string' || typeof command.waitForMilestone === 'string') {
+            return command;
+        }
+        return {
+            ...command,
+            waitForMilestone: planCommand.waitForMilestone,
+            ...(typeof command.waitTimeoutMs === 'number'
+                ? {}
+                : { waitTimeoutMs: readPositiveInteger(planCommand.waitTimeoutMs, 0) }),
+        };
+    });
 }
 /**
  * Expands scenario-declared iOS commands for a simctl capture profile session.
@@ -316,7 +524,7 @@ function resolveIosSimctlProfileCommands(scenario) {
             });
         }
     }
-    return commands;
+    return applyExecutionPlanCommandGates(scenario, commands);
 }
 /**
  * Returns true when the scenario asks iOS simctl capture to preserve a screenshot.
@@ -411,6 +619,23 @@ async function runProfileIos(args, options = {}) {
     const config = readJson(path.resolve(args.config));
     const scenario = readJson(path.resolve(args.scenario));
     const runId = typeof args['run-id'] === 'string' ? args['run-id'] : createRunId();
+    const scenarioName = resolveProfileScenarioName({ scenario, scenarioPath: path.resolve(args.scenario) });
+    const artifactRoot = resolveArtifactRoot({
+        args,
+        config,
+        configPath: path.resolve(args.config),
+        platform: 'ios',
+    });
+    await runProfileCompatibilityPreflight({
+        args,
+        artifactRoot,
+        platform: 'ios',
+        primaryRunner: IOS_PROFILE_RUNNER_CAPABILITIES,
+        runDir: path.join(artifactRoot, scenarioName, runId),
+        runId,
+        scenario,
+        scenarioName,
+    });
     const profileSessionEnabled = isEnabled(args['profile-session']);
     const profileSessionStorageEnabled = isEnabled(args['profile-session-storage']);
     const profileSessionStorageKey = readStringArgOrEnv(args['ios-profile-session-storage-key'], [
@@ -441,7 +666,6 @@ async function runProfileIos(args, options = {}) {
         'ASL_IOS_DEV_CLIENT_WAIT_MS',
         'ASL_EXAMPLE_IOS_DEV_CLIENT_WAIT_MS',
     ]), 1000);
-    const scenarioName = typeof scenario.name === 'string' ? scenario.name : path.basename(args.scenario, '.json');
     const profileSessionCommands = profileSessionEnabled ? resolveIosSimctlProfileCommands(scenario) : [];
     const iosDevClientDeepLinks = iosDevClientUrl
         ? [
@@ -476,6 +700,7 @@ async function runProfileIos(args, options = {}) {
                     ...(typeof profileCommand.queueId === 'string' ? { queueId: profileCommand.queueId } : {}),
                     ...(typeof profileCommand.sequence === 'number' ? { sequence: profileCommand.sequence } : {}),
                     ...(typeof profileCommand.waitForMilestone === 'string' ? { waitForMilestone: profileCommand.waitForMilestone } : {}),
+                    ...(typeof profileCommand.waitMs === 'number' ? { waitMs: profileCommand.waitMs } : {}),
                     ...(typeof profileCommand.waitTimeoutMs === 'number' ? { waitTimeoutMs: profileCommand.waitTimeoutMs } : {}),
                 }),
                 waitMs: profileCommand.waitMs,
@@ -514,6 +739,7 @@ async function runProfileIos(args, options = {}) {
                             ...(typeof profileCommand.queueId === 'string' ? { queueId: profileCommand.queueId } : {}),
                             ...(typeof profileCommand.sequence === 'number' ? { sequence: profileCommand.sequence } : {}),
                             ...(typeof profileCommand.waitForMilestone === 'string' ? { waitForMilestone: profileCommand.waitForMilestone } : {}),
+                            ...(typeof profileCommand.waitMs === 'number' ? { waitMs: profileCommand.waitMs } : {}),
                             ...(typeof profileCommand.waitTimeoutMs === 'number' ? { waitTimeoutMs: profileCommand.waitTimeoutMs } : {}),
                         })),
                         runId,
@@ -580,7 +806,11 @@ async function runProfileIos(args, options = {}) {
         : baseProfileArgs;
     const lifecyclePhase = resolveManifestLifecyclePhase(args);
     const environmentSource = agentDeviceCapture ? 'agent-device' : 'simctl';
-    const lifecycleArtifact = simctlCapture ? 'raw/ios-simctl-log.txt' : 'raw/interaction.log';
+    const copiedSimctlLogArtifact = simctlCapture &&
+        !fs.existsSync(path.join(simctlCapture.runDir, 'raw', 'ios-profile-events.log')) &&
+        fs.existsSync(path.join(simctlCapture.runDir, 'raw', 'ios-simctl-log.txt'))
+        ? 'raw/ios-simctl-log.txt'
+        : undefined;
     return runProfileMobile(profileArgs, {
         commandTransport: agentDeviceCapture
             ? 'agent-device'
@@ -596,13 +826,13 @@ async function runProfileIos(args, options = {}) {
                 value: 'foreground',
                 evidence: 'asserted',
                 source: environmentSource,
-                artifact: lifecycleArtifact,
+                ...(copiedSimctlLogArtifact ? { artifact: copiedSimctlLogArtifact } : {}),
             },
             lifecyclePhase: {
                 value: 'foreground',
                 evidence: 'asserted',
                 source: environmentSource,
-                artifact: lifecycleArtifact,
+                ...(copiedSimctlLogArtifact ? { artifact: copiedSimctlLogArtifact } : {}),
             },
         },
         environmentPreconditions: {
@@ -615,7 +845,7 @@ async function runProfileIos(args, options = {}) {
                 value: lifecyclePhase,
                 evidence: 'asserted',
                 source: environmentSource,
-                artifact: lifecycleArtifact,
+                ...(copiedSimctlLogArtifact ? { artifact: copiedSimctlLogArtifact } : {}),
             },
         },
         interactionDriver: agentDeviceCapture ? 'agent-device' : 'ios-simctl',

package/dist/runner/profile-mobile.d.ts

@@ -10,6 +10,7 @@ type CliArgs = {
     events?: string | boolean;
     out?: string | boolean;
     provider?: CliArgValue;
+    'profile-session-entries'?: string | boolean;
     'run-id'?: string | boolean;
     signal?: CliArgValue;
     [key: string]: CliArgValue | undefined;
@@ -19,6 +20,16 @@ type ProfileRunResult = {
     health: Record<string, unknown>;
     verdict: Record<string, unknown>;
 };
+type CompatibilityPreflightOptions = {
+    args: CliArgs;
+    artifactRoot: string;
+    platform: ProfilePlatform;
+    primaryRunner: Record<string, unknown>;
+    runDir: string;
+    runId: string;
+    scenario: Record<string, unknown>;
+    scenarioName: string;
+};
 type ProfilePlatform = 'android' | 'ios';
 type ProfileMobileOptions = {
     commandTransport?: string;
@@ -35,6 +46,25 @@ type ProviderEvidenceKind = 'accessibility' | 'logs' | 'profiler';
 type SignalEvidenceKind = 'js' | 'memory' | 'network';
 type EvidenceChannel = 'capture' | 'provider' | 'signal';
 type EvidenceKind = CaptureEvidenceKind | ProviderEvidenceKind | SignalEvidenceKind;
+type DiagnosticStatus = 'captured' | 'not_requested' | 'not_supported' | 'unavailable' | 'failed' | 'skipped' | 'missing';
+type DiagnosticKind = EvidenceKind | 'logs';
+type DiagnosticInventoryEntry = {
+    kind: DiagnosticKind;
+    status: DiagnosticStatus;
+    required: boolean;
+    name?: string;
+    provider?: string;
+    runnerId?: string;
+    path?: string;
+    reason?: string;
+    nextAction?: string;
+    sidecarRoot?: string;
+    evidenceDependency?: {
+        kind: string;
+        root?: 'run' | 'sidecar';
+        path: string;
+    };
+};
 type EvidenceAttachment = {
     channel: EvidenceChannel;
     completenessStatus: 'complete';
@@ -43,6 +73,7 @@ type EvidenceAttachment = {
     kind: EvidenceKind;
     manifestPath: string;
     redactionStatus: 'not-redacted';
+    required: boolean;
     sha256: string;
     sourcePath: string;
     sourceFileName: string;
@@ -54,6 +85,8 @@ type EvidenceAttachmentInput = {
     destinationPath: string;
     kind: EvidenceKind;
     manifestPath: string;
+    providerId?: string;
+    required?: boolean;
     sourcePath: string;
 };
 type AttachedEvidence = {
@@ -70,6 +103,7 @@ type ProviderCommandOutput = {
     channel: EvidenceChannel;
     kind: EvidenceKind;
     path: string;
+    required?: boolean;
 };
 type ProviderCommand = {
     args?: string[];
@@ -78,7 +112,7 @@ type ProviderCommand = {
     env?: Record<string, string>;
     id: string;
     outputs: ProviderCommandOutput[];
-    phase: 'prepare' | 'startWindow' | 'capture' | 'stopWindow' | 'finalize';
+    phase: 'prepare' | 'startWindow' | 'capture' | 'stopWindow' | 'afterCapture' | 'postRun' | 'finalize';
 };
 type ProviderCommandFailure = {
     commandId: string;
@@ -139,13 +173,18 @@ declare function resolveAttachedEvidence({ args, layout, providerInputs, }: {
 /**
  * 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>}
  */
-declare function buildProfileHealth({ scenario, runId, metrics, }: {
+declare function buildProfileHealth({ scenario, runId, metrics, diagnostics, profileEventCount, profileSessionEntryCount, commandTransport, sessionEntries, }: {
     scenario: Record<string, any>;
     runId: string;
     metrics: Record<string, any>;
+    diagnostics?: DiagnosticInventoryEntry[];
+    profileEventCount?: number;
+    profileSessionEntryCount?: number;
+    commandTransport?: string;
+    sessionEntries?: Record<string, any>[];
 }): Record<string, unknown>;
 /**
  * Builds failed scenario health from evidence-provider command failures.
@@ -231,6 +270,26 @@ declare function resolveEventLogPath({ args, platform }: {
     args: CliArgs;
     platform: ProfilePlatform;
 }): string | null;
+/**
+ * Resolves the profile scenario name from modern or legacy scenario identity fields.
+ *
+ * @param {{scenario: Record<string, unknown>, scenarioPath: string}} options
+ * @returns {string}
+ */
+declare function resolveProfileScenarioName({ scenario, scenarioPath, }: {
+    scenario: Record<string, unknown>;
+    scenarioPath: string;
+}): string;
+/**
+ * Runs planner compatibility before a live profile capture starts.
+ *
+ * Failed compatibility writes classified artifacts in the profile run folder so
+ * agents can stop before adb, simctl, or provider work consumes runtime time.
+ *
+ * @param {CompatibilityPreflightOptions} options
+ * @returns {Promise<void>}
+ */
+declare function runProfileCompatibilityPreflight({ args, artifactRoot, platform, primaryRunner, runDir, runId, scenario, scenarioName, }: CompatibilityPreflightOptions): Promise<void>;
 /**
  * Creates a stable fingerprint for the scenario contract used by one run.
  *
@@ -258,5 +317,5 @@ declare function runProfileCli({ argv, binaryName, defaultDriver, platform, }: {
     defaultDriver: string;
     platform: ProfilePlatform;
 }): Promise<void>;
-export { buildProfileHealth, buildProviderCommandFailureHealth, buildProfileVerdict, buildVerdictBudgetChecks, parseArgs, buildEvidenceAttachmentManifest, readScalarArg, resolveAppId, resolveArtifactRoot, resolveAttachedEvidence, resolveComparisonLane, resolveEventLogPath, resolveInteractionDriver, runProfileCli, runProfileMobile, hashScenarioContract, usage, };
+export { buildProfileHealth, buildProviderCommandFailureHealth, buildProfileVerdict, buildVerdictBudgetChecks, parseArgs, buildEvidenceAttachmentManifest, readScalarArg, resolveAppId, resolveArtifactRoot, resolveAttachedEvidence, resolveComparisonLane, resolveEventLogPath, resolveInteractionDriver, resolveProfileScenarioName, runProfileCompatibilityPreflight, runProfileCli, runProfileMobile, hashScenarioContract, usage, };
 export type { CliArgs, ProfileMobileOptions, ProfilePlatform, ProfileRunResult, };