agent-scenario-loop 0.1.4 → 0.1.6

package/dist/core/artifact-layout.d.ts

@@ -7,6 +7,7 @@ declare const ARTIFACT_FILENAMES: {
     liveProofSet: string;
     plannerCompatibility: string;
     projectValidation: string;
+    runPlan: string;
     verdict: string;
 };
 declare const PROFILE_ARTIFACT_FILENAMES: {
@@ -34,6 +35,7 @@ type ArtifactLayout = {
     liveProofSet: string;
     plannerCompatibility: string;
     projectValidation: string;
+    runPlan: string;
     raw: string;
     captures: string;
     signals: {

package/dist/core/artifact-layout.js

@@ -13,6 +13,7 @@ const ARTIFACT_FILENAMES = {
     liveProofSet: 'live-proof-set.json',
     plannerCompatibility: 'planner-compatibility.json',
     projectValidation: 'project-validation.json',
+    runPlan: 'run-plan.json',
     verdict: 'verdict.json',
 };
 exports.ARTIFACT_FILENAMES = ARTIFACT_FILENAMES;
@@ -49,6 +50,7 @@ function createArtifactLayout({ outputDir }) {
         liveProofSet: path.join(outputDir, ARTIFACT_FILENAMES.liveProofSet),
         plannerCompatibility: path.join(outputDir, ARTIFACT_FILENAMES.plannerCompatibility),
         projectValidation: path.join(outputDir, ARTIFACT_FILENAMES.projectValidation),
+        runPlan: path.join(outputDir, ARTIFACT_FILENAMES.runPlan),
         raw: path.join(outputDir, 'raw'),
         captures: path.join(outputDir, 'captures'),
         signals: {

package/dist/core/planner.js

@@ -724,14 +724,15 @@ function validatePrimaryRunner({ runner, errors, }) {
  * @returns {string[]}
  */
 function resolveEffectivePlatforms({ scenario, runner, platform, errors, }) {
-    const scenarioPlatforms = asArray(scenario?.platforms);
+    const declaredScenarioPlatforms = asArray(scenario?.platforms);
     const runnerPlatforms = asArray(runner?.platforms);
+    const scenarioPlatforms = declaredScenarioPlatforms.length > 0 ? declaredScenarioPlatforms : runnerPlatforms;
     if (platform) {
-        if (!scenarioPlatforms.includes(platform)) {
+        if (declaredScenarioPlatforms.length > 0 && !declaredScenarioPlatforms.includes(platform)) {
             errors.push(createIssue('platform_not_supported_by_scenario', 'The scenario does not support the selected platform.', {
                 scenarioId: getScenarioId(scenario),
                 platform,
-                supportedPlatforms: uniqueSorted(scenarioPlatforms),
+                supportedPlatforms: uniqueSorted(declaredScenarioPlatforms),
             }));
         }
         if (!runnerPlatforms.includes(platform)) {

package/dist/runner/profile-android.js

@@ -17,7 +17,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { hasHelpFlag } = require('./cli');
 const { ANDROID_DEVICE_EPOCH_MS_PLACEHOLDER, parsePositiveInteger, runAndroidAdbPreflight, } = require('./android-adb');
-const { parseArgs, readScalarArg, runProfileMobile, usage, } = require('./profile-mobile');
+const { parseArgs, readScalarArg, resolveArtifactRoot, resolveProfileScenarioName, runProfileCompatibilityPreflight, runProfileMobile, usage, } = require('./profile-mobile');
 exports.parseArgs = parseArgs;
 exports.usage = usage;
 const { buildScenarioExecutionPlan } = require('../core/execution-plan');
@@ -46,6 +46,17 @@ const MANIFEST_LIFECYCLE_PHASES = new Set([
     'reboot',
     'relaunch',
 ]);
+const ANDROID_PROFILE_RUNNER_CAPABILITIES = {
+    schemaVersion: '1.0.0',
+    runnerId: 'android-adb-profile-runner',
+    kind: 'primary',
+    platforms: ['android'],
+    capabilities: ['launch', 'sessionControl', 'command', 'logCapture', 'artifactWrite'],
+    driverActions: ['tap', 'scroll', 'assertVisible', 'inspectTree', 'screenshot', 'record', 'readLogs'],
+    artifactOutputs: ['logs', 'signals', 'screenshot', 'video', 'uiTree'],
+    uiContexts: ['app'],
+    lifecycle: ['prepare', 'launch', 'startSession', 'executeStep', 'waitForTruthEvent', 'captureEvidence', 'stopSession', 'finalize'],
+};
 /**
  * Reads and parses a JSON object from disk.
  *
@@ -753,8 +764,32 @@ async function runProfileAndroid(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: 'android',
+    });
     const adbCaptureEnabled = isEnabled(args['adb-capture']);
     const agentDeviceCaptureEnabled = isEnabled(args['agent-device-capture']);
+    const driverSteps = adbCaptureEnabled ? resolveAndroidAdbDriverSteps(scenario) : [];
+    if (adbCaptureEnabled) {
+        const driverStepErrors = validateAndroidAdbDriverSteps(driverSteps);
+        if (driverStepErrors.length > 0) {
+            throw new Error(`Invalid Android adb driver step metadata: ${driverStepErrors.join(' ')}`);
+        }
+    }
+    await runProfileCompatibilityPreflight({
+        args,
+        artifactRoot,
+        platform: 'android',
+        primaryRunner: ANDROID_PROFILE_RUNNER_CAPABILITIES,
+        runDir: path.join(artifactRoot, scenarioName, runId),
+        runId,
+        scenario,
+        scenarioName,
+    });
     const profileSessionEnabled = isEnabled(args['profile-session']);
     const profileSessionStorageEnabled = isEnabled(args['android-profile-session-storage']);
     const profileSessionStorageKey = readStringArgOrEnv(args['android-profile-session-storage-key'], [
@@ -793,14 +828,6 @@ async function runProfileAndroid(args, options = {}) {
         'ASL_ANDROID_ADB_COMMAND_TIMEOUT_MS',
         'ASL_EXAMPLE_ANDROID_ADB_COMMAND_TIMEOUT_MS',
     ]), 30000);
-    const scenarioName = typeof scenario.name === 'string' ? scenario.name : path.basename(args.scenario, '.json');
-    const driverSteps = adbCaptureEnabled ? resolveAndroidAdbDriverSteps(scenario) : [];
-    if (adbCaptureEnabled) {
-        const driverStepErrors = validateAndroidAdbDriverSteps(driverSteps);
-        if (driverStepErrors.length > 0) {
-            throw new Error(`Invalid Android adb driver step metadata: ${driverStepErrors.join(' ')}`);
-        }
-    }
     const profileSessionCommands = profileSessionEnabled ? resolveAndroidAdbProfileCommands(scenario) : [];
     const commandWaitMs = parsePositiveInteger(readScalarArg(args['command-wait-ms']), 250);
     const profileSessionDeepLinks = profileSessionEnabled && !profileSessionStorageEnabled

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;
@@ -52,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.
  *
@@ -608,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'], [
@@ -638,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
         ? [

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;
@@ -259,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.
  *
@@ -286,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, };

package/dist/runner/profile-mobile.js

@@ -14,11 +14,13 @@ exports.resolveAttachedEvidence = resolveAttachedEvidence;
 exports.resolveComparisonLane = resolveComparisonLane;
 exports.resolveEventLogPath = resolveEventLogPath;
 exports.resolveInteractionDriver = resolveInteractionDriver;
+exports.resolveProfileScenarioName = resolveProfileScenarioName;
+exports.runProfileCompatibilityPreflight = runProfileCompatibilityPreflight;
 exports.runProfileCli = runProfileCli;
 exports.runProfileMobile = runProfileMobile;
 exports.hashScenarioContract = hashScenarioContract;
 exports.usage = usage;
-const { execFile } = require('node:child_process');
+const { spawn } = require('node:child_process');
 const fs = require('node:fs');
 const fsp = require('node:fs/promises');
 const path = require('node:path');
@@ -26,12 +28,14 @@ const crypto = require('node:crypto');
 const { buildAgentSummaryMarkdown } = require('../core/agent-summary');
 const { createArtifactLayout } = require('../core/artifact-layout');
 const { writeJsonArtifact, writeTextArtifact } = require('../core/artifact-writer');
+const { buildCompatibilityHealth, buildUnevaluatedVerdict, evaluateRunnerCompatibility, } = require('../core/planner');
 const { buildBudgetVerdict, buildCausalRun, buildCausalTimeline, buildManifest, buildMetricsFromProfileEvents, buildSummaryMarkdown, extractProfileEvents, extractProfileSessionEntries, } = require('../core/artifact-contract');
 const { SCHEMAS, assertValidJson } = require('../core/schema-validator');
 const { writeUsage } = require('./cli');
 const CAPTURE_EVIDENCE_KINDS = new Set(['screenshot', 'uiTree', 'video']);
 const PROVIDER_EVIDENCE_KINDS = new Set(['accessibility', 'logs', 'profiler']);
 const SIGNAL_EVIDENCE_KINDS = new Set(['js', 'memory', 'network']);
+const DEFAULT_PROVIDER_COMMAND_TIMEOUT_MS = 180_000;
 /**
  * Prints CLI usage to stderr.
  *
@@ -145,6 +149,15 @@ function readRepeatableArgValues(args, key) {
         return entry;
     });
 }
+/**
+ * Reads whether a boolean-style CLI flag was supplied.
+ *
+ * @param {CliArgValue | undefined} value
+ * @returns {boolean}
+ */
+function isEnabled(value) {
+    return value === true || value === 'true';
+}
 /**
  * Parses a `kind:path` evidence attachment value.
  *
@@ -176,23 +189,83 @@ async function hashFileSha256(filePath) {
     return crypto.createHash('sha256').update(content).digest('hex');
 }
 /**
- * Runs one provider command without a shell and captures its output.
+ * Resolves the timeout applied to provider commands.
  *
- * @param {{command: string, args: string[], cwd?: string, env?: Record<string, string>}} options
+ * @returns {number}
+ */
+function resolveProviderCommandTimeoutMs() {
+    return readPositiveInteger(process.env.ASL_PROVIDER_COMMAND_TIMEOUT_MS, DEFAULT_PROVIDER_COMMAND_TIMEOUT_MS);
+}
+/**
+ * Runs one provider command without a shell, streaming output to raw files.
+ *
+ * @param {{command: string, args: string[], cwd?: string, env?: Record<string, string>, stderrPath: string, stdoutPath: string, timeoutMs: number}} options
  * @returns {Promise<ProviderCommandResult>}
  */
-function execProviderCommand({ args, command, cwd, env, }) {
+function execProviderCommand({ args, command, cwd, env, stderrPath, stdoutPath, timeoutMs, }) {
     return new Promise((resolve) => {
-        execFile(command, args, {
+        const child = spawn(command, args, {
             ...(cwd ? { cwd } : {}),
             env: env ? { ...process.env, ...env } : process.env,
-        }, (error, stdout, stderr) => {
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        let timedOut = false;
+        let settled = false;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            setTimeout(() => {
+                if (!settled) {
+                    child.kill('SIGKILL');
+                }
+            }, 1000).unref();
+        }, timeoutMs);
+        timeout.unref();
+        child.stdout.on('data', (chunk) => {
+            stdoutChunks.push(chunk);
+            fs.appendFileSync(stdoutPath, chunk);
+        });
+        child.stderr.on('data', (chunk) => {
+            stderrChunks.push(chunk);
+            fs.appendFileSync(stderrPath, chunk);
+        });
+        child.on('error', (error) => {
+            if (settled) {
+                return;
+            }
+            clearTimeout(timeout);
+            settled = true;
+            const stderr = error.message;
+            fs.appendFileSync(stderrPath, `${stderr}\n`, 'utf8');
+            resolve({
+                args,
+                command,
+                exitCode: 1,
+                signal: null,
+                stderr,
+                stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+                timedOut,
+            });
+        });
+        child.on('close', (exitCode, signal) => {
+            if (settled) {
+                return;
+            }
+            clearTimeout(timeout);
+            settled = true;
+            const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+            const stderr = Buffer.concat(stderrChunks).toString('utf8');
             resolve({
                 args,
                 command,
-                exitCode: error && typeof error.code === 'number' ? error.code : error ? 1 : 0,
+                exitCode: typeof exitCode === 'number' ? exitCode : timedOut ? 124 : 1,
+                signal,
                 stderr,
                 stdout,
+                timedOut,
             });
         });
     });
@@ -384,32 +457,66 @@ async function executeProviderCommands({ args, layout, platform, runDir, runId,
                 ? resolveProviderPath({ context, manifestDir, value: providerCommand.cwd })
                 : manifestDir;
             const resolvedEnv = Object.fromEntries(Object.entries(providerCommand.env ?? {}).map(([key, value]) => [key, applyProviderPlaceholders(value, context)]));
+            const commandRecordFileName = `${providerId}-${providerCommand.id}.json`;
+            const stdoutFileName = `${providerId}-${providerCommand.id}.stdout.txt`;
+            const stderrFileName = `${providerId}-${providerCommand.id}.stderr.txt`;
+            const commandRecordPath = path.join(commandRecordDir, commandRecordFileName);
+            const stdoutPath = path.join(commandRecordDir, stdoutFileName);
+            const stderrPath = path.join(commandRecordDir, stderrFileName);
+            const timeoutMs = resolveProviderCommandTimeoutMs();
+            const startedAt = new Date().toISOString();
+            await fsp.writeFile(stdoutPath, '', 'utf8');
+            await fsp.writeFile(stderrPath, '', 'utf8');
+            await fsp.writeFile(commandRecordPath, `${JSON.stringify({
+                args: resolvedArgs,
+                command: resolvedCommand,
+                phase: providerCommand.phase,
+                providerId,
+                startedAt,
+                status: 'started',
+                stderrPath: `raw/provider-commands/${stderrFileName}`,
+                stdoutPath: `raw/provider-commands/${stdoutFileName}`,
+                timeoutMs,
+            }, null, 2)}\n`, 'utf8');
             const commandResult = await execProviderCommand({
                 args: resolvedArgs,
                 command: resolvedCommand,
                 cwd: resolvedCwd,
                 env: resolvedEnv,
+                stderrPath,
+                stdoutPath,
+                timeoutMs,
             });
-            const commandRecordFileName = `${providerId}-${providerCommand.id}.json`;
-            const commandRecordPath = path.join(commandRecordDir, commandRecordFileName);
             await fsp.writeFile(commandRecordPath, `${JSON.stringify({
                 args: commandResult.args,
                 command: commandResult.command,
+                endedAt: new Date().toISOString(),
                 exitCode: commandResult.exitCode,
                 phase: providerCommand.phase,
                 providerId,
+                signal: commandResult.signal,
                 stderr: commandResult.stderr,
+                stderrPath: `raw/provider-commands/${stderrFileName}`,
+                status: commandResult.timedOut ? 'timed_out' : commandResult.exitCode === 0 ? 'completed' : 'failed',
                 stdout: commandResult.stdout,
+                stdoutPath: `raw/provider-commands/${stdoutFileName}`,
+                timedOut: commandResult.timedOut,
+                timeoutMs,
             }, null, 2)}\n`, 'utf8');
             if (commandResult.exitCode !== 0) {
+                const timedOut = commandResult.timedOut;
                 failures.push({
                     commandId: providerCommand.id,
-                    code: 'provider_command_failed',
+                    code: timedOut ? 'provider_liveness_timeout' : 'provider_command_failed',
                     exitCode: commandResult.exitCode,
-                    message: `Evidence provider command ${providerId}/${providerCommand.id} failed with exit code ${commandResult.exitCode}.`,
+                    message: timedOut
+                        ? `Evidence provider command ${providerId}/${providerCommand.id} did not finish before the ${timeoutMs}ms timeout.`
+                        : `Evidence provider command ${providerId}/${providerCommand.id} failed with exit code ${commandResult.exitCode}.`,
                     name: 'evidence_provider_command_completed',
-                    nextAction: `Inspect raw/provider-commands/${commandRecordFileName}, fix the provider command or its environment, then rerun the profile.`,
-                    nextActionCode: 'fix_provider_command',
+                    nextAction: timedOut
+                        ? `Inspect raw/provider-commands/${commandRecordFileName}, raw/provider-commands/${stdoutFileName}, and raw/provider-commands/${stderrFileName}; fix the provider liveness issue or increase ASL_PROVIDER_COMMAND_TIMEOUT_MS only if the provider is making progress.`
+                        : `Inspect raw/provider-commands/${commandRecordFileName}, fix the provider command or its environment, then rerun the profile.`,
+                    nextActionCode: timedOut ? 'fix_provider_liveness' : 'fix_provider_command',
                     phase: providerCommand.phase,
                     providerId,
                     rawPath: `raw/provider-commands/${commandRecordFileName}`,
@@ -608,6 +715,127 @@ function toPortablePathReference(targetPath) {
     }
     return path.basename(targetPath);
 }
+/**
+ * Resolves the evidence input mode before profile parsing starts.
+ *
+ * @param {{args: CliArgs, platform: ProfilePlatform}} options
+ * @returns {string}
+ */
+function resolveProfileInputMode({ args, platform }) {
+    if (typeof args.events === 'string') {
+        return 'fixture-event-log';
+    }
+    if (platform === 'android') {
+        if (typeof args['adb-artifacts'] === 'string') {
+            return 'adb-sidecar';
+        }
+        if (isEnabled(args['adb-capture'])) {
+            return 'adb-live-capture';
+        }
+    }
+    if (typeof args['simctl-artifacts'] === 'string') {
+        return 'simctl-sidecar';
+    }
+    if (isEnabled(args['simctl-capture'])) {
+        return 'simctl-live-capture';
+    }
+    return 'no-profile-evidence';
+}
+/**
+ * Reads unique scenario step kinds for early operator visibility.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {string[]}
+ */
+function readScenarioStepKinds(scenario) {
+    if (!Array.isArray(scenario.steps)) {
+        return [];
+    }
+    return Array.from(new Set(scenario.steps
+        .filter(isRecord)
+        .map((step) => step.kind)
+        .filter((kind) => typeof kind === 'string')))
+        .sort();
+}
+/**
+ * Reads wait milestone ids from scenario steps.
+ *
+ * @param {Record<string, unknown>} scenario
+ * @returns {string[]}
+ */
+function readScenarioWaitMilestones(scenario) {
+    if (!Array.isArray(scenario.steps)) {
+        return [];
+    }
+    return Array.from(new Set(scenario.steps
+        .filter(isRecord)
+        .filter((step) => step.kind === 'waitForMilestone')
+        .map((step) => step.milestone)
+        .filter((milestone) => typeof milestone === 'string')))
+        .sort();
+}
+/**
+ * Builds the early run plan artifact before provider commands or event parsing.
+ *
+ * @param {{args: CliArgs, artifactRoot: string, comparisonLane?: string | undefined, expectedIterations: number, interactionDriver: string, layout: ReturnType<typeof createArtifactLayout>, milestoneEventsPerIteration: number, options: ProfileMobileOptions, profileScenario: Record<string, unknown>, runDir: string, runId: string, scenarioHash: string, scenarioPath: string}} options
+ * @returns {ProfileRunPlan}
+ */
+function buildProfileRunPlan({ args, artifactRoot, comparisonLane, expectedIterations, interactionDriver, layout, milestoneEventsPerIteration, options, profileScenario, runDir, runId, scenarioHash, scenarioPath, }) {
+    return {
+        artifactVersion: '1.0.0',
+        runId,
+        scenarioId: resolveProfileScenarioName({ scenario: profileScenario, scenarioPath }),
+        scenarioHash,
+        platform: options.platform,
+        inputMode: resolveProfileInputMode({ args, platform: options.platform }),
+        artifactRoot,
+        runDir,
+        interactionDriver,
+        ...(comparisonLane ? { comparisonLane } : {}),
+        expectedIterations,
+        milestoneEventsPerIteration,
+        commandTransport: resolveCommandTransport({ args, interactionDriver, options }),
+        providers: readRepeatableArgValues(args, 'provider').map((providerPath) => ({
+            path: toPortablePathReference(path.resolve(providerPath)),
+        })),
+        requestedDiagnostics: {
+            required: Array.from(readScenarioStringSet(profileScenario, ['artifacts', 'required'])).sort(),
+            optional: Array.from(readScenarioStringSet(profileScenario, ['artifacts', 'optional'])).sort(),
+        },
+        scenarioShape: {
+            budgets: Array.isArray(profileScenario.budgets) ? profileScenario.budgets.length : 0,
+            steps: Array.isArray(profileScenario.steps) ? profileScenario.steps.length : 0,
+            stepKinds: readScenarioStepKinds(profileScenario),
+            waitForMilestones: readScenarioWaitMilestones(profileScenario),
+        },
+        evidenceSources: {
+            ...(typeof args.events === 'string' ? { events: toPortablePathReference(path.resolve(args.events)) } : {}),
+            ...(typeof args['profile-session-entries'] === 'string'
+                ? { profileSessionEntries: toPortablePathReference(path.resolve(args['profile-session-entries'])) }
+                : {}),
+            ...(typeof args['adb-artifacts'] === 'string'
+                ? { adbArtifacts: toPortablePathReference(path.resolve(args['adb-artifacts'])) }
+                : {}),
+            ...(typeof args['simctl-artifacts'] === 'string'
+                ? { simctlArtifacts: toPortablePathReference(path.resolve(args['simctl-artifacts'])) }
+                : {}),
+            adbCapture: isEnabled(args['adb-capture']),
+            simctlCapture: isEnabled(args['simctl-capture']),
+            signals: readRepeatableArgValues(args, 'signal').length,
+            captures: readRepeatableArgValues(args, 'capture').length,
+        },
+    };
+}
+/**
+ * Writes the early profile run plan artifact and a compact status heartbeat.
+ *
+ * @param {{layout: ReturnType<typeof createArtifactLayout>, plan: ProfileRunPlan}} options
+ * @returns {Promise<void>}
+ */
+async function writeProfileRunPlan({ layout, plan, }) {
+    await fsp.writeFile(layout.runPlan, `${JSON.stringify(plan, null, 2)}\n`, 'utf8');
+    process.stderr.write(`profile run plan: ${plan.platform}/${plan.scenarioId} mode=${plan.inputMode} providers=${plan.providers.length} requiredDiagnostics=${plan.requestedDiagnostics.required.length} runPlan=${path.relative(process.cwd(), layout.runPlan)}\n`);
+}
 /**
  * Returns a path reference from one run folder to an external sidecar.
  *
@@ -1535,6 +1763,66 @@ function resolveProfileScenarioName({ scenario, scenarioPath, }) {
     }
     return path.basename(scenarioPath, '.json');
 }
+/**
+ * Reads evidence-provider manifests for profile compatibility preflight.
+ *
+ * @param {CliArgs} args
+ * @returns {Record<string, unknown>[]}
+ */
+function readEvidenceProviderManifests(args) {
+    return readRepeatableArgValues(args, 'provider').map((providerPath, index) => assertValidJson(readJson(path.resolve(providerPath)), SCHEMAS.runnerCapabilities, `Evidence provider manifest ${index + 1}`));
+}
+/**
+ * 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>}
+ */
+async function runProfileCompatibilityPreflight({ args, artifactRoot, platform, primaryRunner, runDir, runId, scenario, scenarioName, }) {
+    const layout = createArtifactLayout({ outputDir: runDir });
+    const compatibility = evaluateRunnerCompatibility({
+        scenario,
+        runner: primaryRunner,
+        evidenceProviders: readEvidenceProviderManifests(args),
+        platform,
+    });
+    await writeJsonArtifact({
+        filePath: layout.plannerCompatibility,
+        value: compatibility,
+        schema: {
+            type: 'object',
+            additionalProperties: true,
+        },
+        label: 'Planner compatibility artifact',
+    });
+    if (compatibility.compatible) {
+        process.stderr.write(`profile preflight passed: ${platform}/${scenarioName} artifactRoot=${artifactRoot} planner=${path.relative(process.cwd(), layout.plannerCompatibility)}\n`);
+        return;
+    }
+    const health = buildCompatibilityHealth({ scenario, runId, compatibility });
+    const verdict = buildUnevaluatedVerdict({ scenario, runId, health });
+    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,
+    });
+    throw new Error(`Profile compatibility preflight failed; inspect ${runDir}/agent-summary.md.`);
+}
 /**
  * Serializes JSON with stable object key ordering for reproducible hashes.
  *
@@ -1992,6 +2280,22 @@ async function runProfileMobile(args, options) {
     await ensureDir(layout.signals.js);
     await ensureDir(layout.signals.memory);
     await ensureDir(layout.signals.network);
+    const runPlan = buildProfileRunPlan({
+        args,
+        artifactRoot,
+        comparisonLane,
+        expectedIterations,
+        interactionDriver,
+        layout,
+        milestoneEventsPerIteration,
+        options,
+        profileScenario,
+        runDir,
+        runId,
+        scenarioHash,
+        scenarioPath,
+    });
+    await writeProfileRunPlan({ layout, plan: runPlan });
     const providerExecution = await executeProviderCommands({
         args,
         layout,

package/dist/scripts/consumer-rehearsal.d.ts

@@ -15,6 +15,14 @@ type FailedRunOutput = {
  * @returns {NodeJS.ProcessEnv}
  */
 declare function createRehearsalEnv(tempRoot: string): NodeJS.ProcessEnv;
+/**
+ * Resolves an existing tarball from the environment, when a parent release gate
+ * has already packed the current package.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string | null}
+ */
+declare function resolveProvidedTarball(env: NodeJS.ProcessEnv): string | null;
 /**
  * Runs a command and returns stdout while preserving child stderr on failure.
  *
@@ -116,4 +124,4 @@ declare function rehearseConsumerInstall({ appRoot, env, tarballPath, }: {
     env: NodeJS.ProcessEnv;
     tarballPath: string;
 }): void;
-export { createRehearsalEnv, mergeGeneratedScripts, packageBinPath, packPackage, readJson, rehearseConsumerInstall, replaceConfigPlaceholders, run, runExpectFailure, writeFakeArgent, writeExistingAppFixture, writeProfileEventFixtures, writeJson, };
+export { createRehearsalEnv, mergeGeneratedScripts, packageBinPath, packPackage, readJson, rehearseConsumerInstall, replaceConfigPlaceholders, resolveProvidedTarball, run, runExpectFailure, writeFakeArgent, writeExistingAppFixture, writeProfileEventFixtures, writeJson, };

package/dist/scripts/consumer-rehearsal.js

@@ -8,6 +8,7 @@ exports.packPackage = packPackage;
 exports.readJson = readJson;
 exports.rehearseConsumerInstall = rehearseConsumerInstall;
 exports.replaceConfigPlaceholders = replaceConfigPlaceholders;
+exports.resolveProvidedTarball = resolveProvidedTarball;
 exports.run = run;
 exports.runExpectFailure = runExpectFailure;
 exports.writeFakeArgent = writeFakeArgent;
@@ -39,6 +40,22 @@ function createRehearsalEnv(tempRoot) {
     env.npm_config_update_notifier = 'false';
     return env;
 }
+/**
+ * Resolves an existing tarball from the environment, when a parent release gate
+ * has already packed the current package.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string | null}
+ */
+function resolveProvidedTarball(env) {
+    const tarballPath = env.ASL_PACKAGE_TARBALL ? path.resolve(env.ASL_PACKAGE_TARBALL) : '';
+    if (!tarballPath) {
+        return null;
+    }
+    assert.equal(fs.existsSync(tarballPath), true, `ASL_PACKAGE_TARBALL does not exist: ${tarballPath}`);
+    assert.match(path.basename(tarballPath), /^agent-scenario-loop-.+\.tgz$/u, 'ASL_PACKAGE_TARBALL must point to an agent-scenario-loop tarball');
+    return tarballPath;
+}
 /**
  * Resolves the per-command timeout for package gate child processes.
  *
@@ -729,7 +746,7 @@ function main() {
     const appRoot = path.join(tempRoot, 'existing-mobile-app');
     fs.mkdirSync(appRoot, { recursive: true });
     try {
-        const tarballPath = packPackage({
+        const tarballPath = resolveProvidedTarball(env) ?? packPackage({
             env,
             packageRoot,
             packDir: path.join(tempRoot, 'pack'),

package/dist/scripts/package-smoke.d.ts

@@ -36,6 +36,14 @@ declare function isAllowedPackedFile(filePath: string): boolean;
  * @returns {NodeJS.ProcessEnv}
  */
 declare function createSmokeEnv(tempRoot: string): NodeJS.ProcessEnv;
+/**
+ * Resolves an existing tarball from the environment, when a parent release gate
+ * has already packed the current package.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string | null}
+ */
+declare function resolveProvidedTarball(env: NodeJS.ProcessEnv): string | null;
 /**
  * Runs a command and returns stdout while preserving stderr for failures.
  *
@@ -93,4 +101,4 @@ declare function typescriptBinPath(repoRoot: string): string;
  * @returns {void}
  */
 declare function main(): void;
-export { createSmokeEnv, listFiles, main, isAllowedPackedFile, packageBinPath, run, runExpectFailure, typescriptBinPath, writeFakeAdb, writeSmokeRun, };
+export { createSmokeEnv, listFiles, main, isAllowedPackedFile, packageBinPath, resolveProvidedTarball, run, runExpectFailure, typescriptBinPath, writeFakeAdb, writeSmokeRun, };

package/dist/scripts/package-smoke.js

@@ -6,6 +6,7 @@ exports.listFiles = listFiles;
 exports.main = main;
 exports.isAllowedPackedFile = isAllowedPackedFile;
 exports.packageBinPath = packageBinPath;
+exports.resolveProvidedTarball = resolveProvidedTarball;
 exports.run = run;
 exports.runExpectFailure = runExpectFailure;
 exports.typescriptBinPath = typescriptBinPath;
@@ -137,6 +138,22 @@ function createSmokeEnv(tempRoot) {
     env.npm_config_update_notifier = 'false';
     return env;
 }
+/**
+ * Resolves an existing tarball from the environment, when a parent release gate
+ * has already packed the current package.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {string | null}
+ */
+function resolveProvidedTarball(env) {
+    const tarballPath = env.ASL_PACKAGE_TARBALL ? path.resolve(env.ASL_PACKAGE_TARBALL) : '';
+    if (!tarballPath) {
+        return null;
+    }
+    assert.equal(fs.existsSync(tarballPath), true, `ASL_PACKAGE_TARBALL does not exist: ${tarballPath}`);
+    assert.match(path.basename(tarballPath), /^agent-scenario-loop-.+\.tgz$/u, 'ASL_PACKAGE_TARBALL must point to an agent-scenario-loop tarball');
+    return tarballPath;
+}
 /**
  * Resolves the per-command timeout for package gate child processes.
  *
@@ -556,14 +573,18 @@ function main() {
     try {
         assert.equal(fs.existsSync(path.join(repoRoot, '.npmignore')), true, 'root .npmignore must exist so npm pack never falls back to .gitignore');
         assert.equal(fs.existsSync(path.join(repoRoot, 'examples', 'mobile-app', '.npmignore')), true, 'example app .npmignore must exist so npm pack never falls back to the app-local .gitignore');
-        const packOutput = run('npm', ['pack', '--pack-destination', packDir], {
-            cwd: repoRoot,
-            env,
-        });
-        const tarballName = packOutput.trim().split(/\n/u).pop();
-        assert.ok(tarballName, 'npm pack did not print a tarball name');
-        const tarballPath = path.join(packDir, tarballName);
-        assert.equal(fs.existsSync(tarballPath), true, `missing packed tarball: ${tarballPath}`);
+        const providedTarballPath = resolveProvidedTarball(env);
+        const tarballPath = providedTarballPath ?? (() => {
+            const packOutput = run('npm', ['pack', '--pack-destination', packDir], {
+                cwd: repoRoot,
+                env,
+            });
+            const tarballName = packOutput.trim().split(/\n/u).pop();
+            assert.ok(tarballName, 'npm pack did not print a tarball name');
+            const packedTarballPath = path.join(packDir, tarballName);
+            assert.equal(fs.existsSync(packedTarballPath), true, `missing packed tarball: ${packedTarballPath}`);
+            return packedTarballPath;
+        })();
         run('npm', ['init', '-y'], {
             cwd: installDir,
             env,
@@ -1888,7 +1909,7 @@ function main() {
             "assert.deepEqual(documentedRunnerSubpaths(), exportedRunnerSubpaths(), 'installed docs/api.md runner subpaths must match package exports');",
             "assert.equal(asl.ARTIFACT_LAYOUT_VERSION, '1.0.0');",
             "assert.equal(asl.ARTIFACT_FILENAMES.health, 'health.json');",
-            "assert.deepEqual(asl.ARTIFACT_FILENAMES, { agentSummary: 'agent-summary.md', comparison: 'comparison.json', health: 'health.json', liveProof: 'live-proof.json', liveProofSet: 'live-proof-set.json', plannerCompatibility: 'planner-compatibility.json', projectValidation: 'project-validation.json', verdict: 'verdict.json' });",
+            "assert.deepEqual(asl.ARTIFACT_FILENAMES, { agentSummary: 'agent-summary.md', comparison: 'comparison.json', health: 'health.json', liveProof: 'live-proof.json', liveProofSet: 'live-proof-set.json', plannerCompatibility: 'planner-compatibility.json', projectValidation: 'project-validation.json', runPlan: 'run-plan.json', verdict: 'verdict.json' });",
             "assert.equal(asl.PROFILE_ARTIFACT_FILENAMES.metrics, 'metrics.json');",
             "assert.deepEqual(asl.PROFILE_ARTIFACT_FILENAMES, { budgetVerdict: 'budget-verdict.json', causalRun: 'causal-run.json', manifest: 'manifest.json', metrics: 'metrics.json', summary: 'summary.md' });",
             "assert.equal(typeof asl.createArtifactLayout, 'function');",
@@ -1901,6 +1922,7 @@ function main() {
             "assert.equal(layout.liveProofSet, 'run/live-proof-set.json');",
             "assert.equal(layout.plannerCompatibility, 'run/planner-compatibility.json');",
             "assert.equal(layout.projectValidation, 'run/project-validation.json');",
+            "assert.equal(layout.runPlan, 'run/run-plan.json');",
             "assert.equal(layout.raw, 'run/raw');",
             "assert.equal(layout.captures, 'run/captures');",
             "assert.equal(layout.signals.js, 'run/signals/js');",

package/dist/scripts/release-check.d.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+type RunOptions = {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+};
+/**
+ * Creates a clean npm environment for repeatable release gates.
+ *
+ * @param {string} tempRoot
+ * @returns {NodeJS.ProcessEnv}
+ */
+declare function createReleaseEnv(tempRoot: string): NodeJS.ProcessEnv;
+/**
+ * Resolves the per-command timeout for release gate child processes.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {number}
+ */
+declare function resolveCommandTimeoutMs(env: NodeJS.ProcessEnv): number;
+/**
+ * Runs a release command with inherited output.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @param {RunOptions} options
+ * @returns {void}
+ */
+declare function run(command: string, args: string[], options: RunOptions): void;
+/**
+ * Packs the package once for downstream release gates.
+ *
+ * @param {{env: NodeJS.ProcessEnv, packageRoot: string, packDir: string}} options
+ * @returns {string}
+ */
+declare function packReleasePackage({ env, packageRoot, packDir, }: {
+    env: NodeJS.ProcessEnv;
+    packageRoot: string;
+    packDir: string;
+}): string;
+/**
+ * Runs the full release check while reusing one package tarball for install
+ * smoke and consumer rehearsal.
+ *
+ * @returns {void}
+ */
+declare function main(): void;
+export { createReleaseEnv, main, packReleasePackage, resolveCommandTimeoutMs, run, };

package/dist/scripts/release-check.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReleaseEnv = createReleaseEnv;
+exports.main = main;
+exports.packReleasePackage = packReleasePackage;
+exports.resolveCommandTimeoutMs = resolveCommandTimeoutMs;
+exports.run = run;
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const DEFAULT_COMMAND_TIMEOUT_MS = 180_000;
+/**
+ * Creates a clean npm environment for repeatable release gates.
+ *
+ * @param {string} tempRoot
+ * @returns {NodeJS.ProcessEnv}
+ */
+function createReleaseEnv(tempRoot) {
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase().startsWith('npm_config_')) {
+            delete env[key];
+        }
+    }
+    env.npm_config_audit = 'false';
+    env.npm_config_cache = path.join(tempRoot, 'npm-cache');
+    env.npm_config_fund = 'false';
+    env.npm_config_update_notifier = 'false';
+    return env;
+}
+/**
+ * Resolves the per-command timeout for release gate child processes.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {number}
+ */
+function resolveCommandTimeoutMs(env) {
+    const timeoutMs = Number.parseInt(env.ASL_PACKAGE_GATE_TIMEOUT_MS ?? '', 10);
+    return Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? timeoutMs
+        : DEFAULT_COMMAND_TIMEOUT_MS;
+}
+/**
+ * Runs a release command with inherited output.
+ *
+ * @param {string} command
+ * @param {string[]} args
+ * @param {RunOptions} options
+ * @returns {void}
+ */
+function run(command, args, options) {
+    execFileSync(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: 'inherit',
+        timeout: resolveCommandTimeoutMs(options.env),
+    });
+}
+/**
+ * Packs the package once for downstream release gates.
+ *
+ * @param {{env: NodeJS.ProcessEnv, packageRoot: string, packDir: string}} options
+ * @returns {string}
+ */
+function packReleasePackage({ env, packageRoot, packDir, }) {
+    fs.mkdirSync(packDir, { recursive: true });
+    const packOutput = execFileSync('npm', ['pack', '--pack-destination', packDir], {
+        cwd: packageRoot,
+        encoding: 'utf8',
+        env,
+        stdio: ['ignore', 'pipe', 'inherit'],
+        timeout: resolveCommandTimeoutMs(env),
+    });
+    const tarballName = packOutput.trim().split(/\n/u).pop();
+    assert.ok(tarballName, 'npm pack did not print a tarball name');
+    const tarballPath = path.join(packDir, tarballName);
+    assert.equal(fs.existsSync(tarballPath), true, `missing packed tarball: ${tarballPath}`);
+    return tarballPath;
+}
+/**
+ * Runs the full release check while reusing one package tarball for install
+ * smoke and consumer rehearsal.
+ *
+ * @returns {void}
+ */
+function main() {
+    const repoRoot = path.resolve(__dirname, '..', '..');
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'asl-release-check-'));
+    const env = createReleaseEnv(tempRoot);
+    try {
+        run('pnpm', ['test'], { cwd: repoRoot, env });
+        run(process.execPath, [path.join(repoRoot, 'dist', 'scripts', 'release-readiness.js')], { cwd: repoRoot, env });
+        const tarballPath = packReleasePackage({
+            env,
+            packageRoot: repoRoot,
+            packDir: path.join(tempRoot, 'pack'),
+        });
+        const gateEnv = {
+            ...env,
+            ASL_PACKAGE_TARBALL: tarballPath,
+        };
+        run(process.execPath, [path.join(repoRoot, 'dist', 'scripts', 'package-smoke.js')], { cwd: repoRoot, env: gateEnv });
+        run(process.execPath, [path.join(repoRoot, 'dist', 'scripts', 'consumer-rehearsal.js')], { cwd: repoRoot, env: gateEnv });
+        process.stdout.write(`release check passed: ${tarballPath}\n`);
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+    catch (error) {
+        console.error(`release check temp kept at: ${tempRoot}`);
+        throw error;
+    }
+}
+if (require.main === module) {
+    main();
+}

package/dist/scripts/release-readiness.js

@@ -367,7 +367,7 @@ function assertReleaseScripts(packageJson) {
     const scripts = getStringMap(packageJson, 'scripts');
     assert.equal(scripts.prepublishOnly, 'pnpm release:check');
     assert.equal(scripts['release:readiness'], 'pnpm build && node dist/scripts/release-readiness.js');
-    assert.equal(scripts['release:check'], 'pnpm test && pnpm release:readiness && pnpm package:smoke && pnpm consumer:rehearse');
+    assert.equal(scripts['release:check'], 'pnpm build && node dist/scripts/release-check.js');
     assert.equal(scripts['package:smoke'], 'pnpm build && node dist/scripts/package-smoke.js');
     assert.equal(scripts['consumer:rehearse'], 'pnpm build && node dist/scripts/consumer-rehearsal.js');
     assert.equal(scripts['downstream:local-package'], 'pnpm build && node dist/scripts/downstream-local-package-gate.js');
@@ -380,6 +380,24 @@ function assertReleaseScripts(packageJson) {
     assert.match(scripts['example:mobile:live-proof'], /--fail-on-regression/u);
     assert.match(scripts['example:app:start:isolated'], /--port 8097 --host localhost --clear/u);
 }
+/**
+ * Asserts that pushed semver tags synchronize GitHub Releases from npm package truth.
+ *
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertGithubReleaseWorkflow(repoRoot) {
+    const workflowPath = path.join(repoRoot, '.github', 'workflows', 'github-release.yml');
+    const workflow = fs.readFileSync(workflowPath, 'utf8');
+    assert.match(workflow, /tags:\n\s+- 'v\*\.\*\.\*'/u);
+    assert.match(workflow, /contents: write/u);
+    assert.match(workflow, /VERSION="\$\{GITHUB_REF_NAME#v\}"/u);
+    assert.match(workflow, /PACKAGE_VERSION="\$\(node -p "require\('\.\/package\.json'\)\.version"\)"/u);
+    assert.match(workflow, /npm view agent-scenario-loop@"\$VERSION" version/u);
+    assert.match(workflow, /gh release create "\$GITHUB_REF_NAME"/u);
+    assert.match(workflow, /--generate-notes/u);
+    assert.match(workflow, /--verify-tag/u);
+}
 /**
  * Asserts that public binaries and package subpath exports map to built files.
  *
@@ -508,6 +526,7 @@ function main() {
     const packageJson = readJsonObject(path.join(repoRoot, 'package.json'));
     assertPublicPackageMetadata(packageJson);
     assertReleaseScripts(packageJson);
+    assertGithubReleaseWorkflow(repoRoot);
     assertPublicEntrypoints(packageJson);
     assertPublicApiDocs(packageJson, repoRoot);
     assertPackageFileList(packageJson);

package/docs/consumer-rehearsal.md

@@ -16,6 +16,12 @@ Package gates run child package-manager and CLI commands with a bounded timeout.
 ASL_PACKAGE_GATE_TIMEOUT_MS=300000 pnpm consumer:rehearse
 ```
 
+When a parent release gate has already packed the current package, pass that tarball through `ASL_PACKAGE_TARBALL` to reuse it instead of packing again:
+
+```bash
+ASL_PACKAGE_TARBALL=/path/to/agent-scenario-loop-0.1.4.tgz pnpm consumer:rehearse
+```
+
 ## Downstream Local-Package Gate
 
 Before publishing a release candidate, validate the packed local package inside at least one real downstream app when that app has already adopted durable ASL scenarios. This catches package, runner, schema, and helper regressions before npm distribution.

package/docs/live-proofs.md

@@ -35,6 +35,8 @@ pnpm check-plan -- --scenario examples/scenarios/mobile/app-startup.json --runne
 
 This validates the input manifests, writes schema-checked `health.json` and `verdict.json`, writes `agent-summary.md`, and includes the raw planner match in `planner-compatibility.json`.
 
+Live profile wrappers also run this compatibility check before adb, simctl, agent-device, or provider capture starts. A compatible run writes `planner-compatibility.json` as the first profile artifact, then continues into the platform capture. An incompatible run writes failed `health.json`, inconclusive `verdict.json`, `agent-summary.md`, and the planner artifact in the profile run folder, then exits before touching the device runtime. This keeps missing required diagnostics, unsupported platforms, and impossible runner/provider plans out of the long capture loop.
+
 ## Host/Device Access
 
 Keep deterministic validation and live device proof as separate execution lanes.
@@ -338,7 +340,7 @@ Before publishing, run:
 pnpm release:check
 ```
 
-That gate runs tests, readiness checks, package smoke, installed-binary checks, fake-device example proofs, schema/example/template/doc packaging checks, and the packed-package consumer rehearsal.
+That gate builds the release scripts, runs tests and readiness checks, packs the package once, then reuses that tarball for package smoke, installed-binary checks, fake-device example proofs, schema/example/template/doc packaging checks, and the packed-package consumer rehearsal. Reusing one tarball keeps the release path closer to npm publish behavior and avoids repeated clean/build/pack cycles.
 
 Package smoke and consumer rehearsal keep child commands bounded so package-manager stalls fail with the temporary rehearsal directory preserved. Set `ASL_PACKAGE_GATE_TIMEOUT_MS` to raise the per-command timeout when a local registry, proxy, or cold package cache is slow:
 
@@ -346,6 +348,10 @@ Package smoke and consumer rehearsal keep child commands bounded so package-mana
 ASL_PACKAGE_GATE_TIMEOUT_MS=300000 pnpm release:check
 ```
 
+## Run Plan First
+
+Profile runs write `run-plan.json` before provider commands, evidence ingest, and final health classification. Inspect it first when a live loop stalls or fails early: it records the scenario id, scenario hash, input mode (`fixture-event-log`, `adb-sidecar`, `simctl-sidecar`, or live capture), expected iterations, command transport, provider manifests, requested diagnostics, and evidence source paths. The profile CLIs also print a compact run-plan heartbeat to stderr while keeping stdout reserved for the run directory.
+
 ## Side References
 
 - [Consumer App Rehearsal](consumer-rehearsal.md) for adoption inside an existing app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-scenario-loop",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "description": "Scenario orchestration and evidence collection for agent-driven software development. Bring your own runner. Keep your scenarios. Keep your evidence.",
   "license": "MIT",
@@ -232,7 +232,7 @@
     "downstream:local-package": "pnpm build && node dist/scripts/downstream-local-package-gate.js",
     "package:smoke": "pnpm build && node dist/scripts/package-smoke.js",
     "prepublishOnly": "pnpm release:check",
-    "release:check": "pnpm test && pnpm release:readiness && pnpm package:smoke && pnpm consumer:rehearse",
+    "release:check": "pnpm build && node dist/scripts/release-check.js",
     "release:readiness": "pnpm build && node dist/scripts/release-readiness.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "pnpm clean && pnpm typecheck && pnpm exec tsc -p tsconfig.json && node --test dist/core/__tests__/*.test.js dist/runner/__tests__/*.test.js",