agent-scenario-loop 0.1.3 → 0.1.4

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/scripts/release-readiness.js

@@ -0,0 +1,520 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const REQUIRED_BIN_TARGETS = {
+    'agent-scenario-loop': 'dist/runner/check-plan.js',
+    'asl-agent-device': 'dist/runner/agent-device.js',
+    'asl-android-adb': 'dist/runner/android-adb.js',
+    'asl-argent': 'dist/runner/argent.js',
+    'asl-check-plan': 'dist/runner/check-plan.js',
+    'asl-compare': 'dist/runner/compare.js',
+    'asl-compare-latest': 'dist/runner/compare-latest.js',
+    'asl-demo-loop': 'dist/runner/demo-loop.js',
+    'asl-example-android-live': 'dist/runner/example-android-live.js',
+    'asl-example-ios-live': 'dist/runner/example-ios-live.js',
+    'asl-host-doctor': 'dist/runner/host-doctor.js',
+    'asl-init': 'dist/runner/init-project.js',
+    'asl-ios-simctl': 'dist/runner/ios-simctl.js',
+    'asl-live-android': 'dist/runner/live-android.js',
+    'asl-live-ios': 'dist/runner/live-ios.js',
+    'asl-live-proof': 'dist/runner/live-proof.js',
+    'asl-profile-android': 'dist/runner/profile-android.js',
+    'asl-profile-ios': 'dist/runner/profile-ios.js',
+    'asl-validate-project': 'dist/runner/validate-project.js',
+};
+const REQUIRED_EXPORTS = {
+    '.': {
+        require: './dist/index.js',
+        types: './dist/index.d.ts',
+        import: './dist/index.js',
+        default: './dist/index.js',
+    },
+    './app/profile-session': {
+        require: './app/profile-session.ts',
+        types: './app/profile-session.ts',
+        import: './app/profile-session.ts',
+        default: './app/profile-session.ts',
+    },
+    './examples/*': './examples/*',
+    './package.json': './package.json',
+    './runner/agent-device': {
+        require: './dist/runner/agent-device.js',
+        types: './dist/runner/agent-device.d.ts',
+        import: './dist/runner/agent-device.js',
+        default: './dist/runner/agent-device.js',
+    },
+    './runner/agent-device-driver': {
+        require: './dist/runner/agent-device-driver.js',
+        types: './dist/runner/agent-device-driver.d.ts',
+        import: './dist/runner/agent-device-driver.js',
+        default: './dist/runner/agent-device-driver.js',
+    },
+    './runner/argent-driver': {
+        require: './dist/runner/argent-driver.js',
+        types: './dist/runner/argent-driver.d.ts',
+        import: './dist/runner/argent-driver.js',
+        default: './dist/runner/argent-driver.js',
+    },
+    './runner/argent': {
+        require: './dist/runner/argent.js',
+        types: './dist/runner/argent.d.ts',
+        import: './dist/runner/argent.js',
+        default: './dist/runner/argent.js',
+    },
+    './runner/android-adb': {
+        require: './dist/runner/android-adb.js',
+        types: './dist/runner/android-adb.d.ts',
+        import: './dist/runner/android-adb.js',
+        default: './dist/runner/android-adb.js',
+    },
+    './runner/android-adb-driver': {
+        require: './dist/runner/android-adb-driver.js',
+        types: './dist/runner/android-adb-driver.d.ts',
+        import: './dist/runner/android-adb-driver.js',
+        default: './dist/runner/android-adb-driver.js',
+    },
+    './runner/check-plan': {
+        require: './dist/runner/check-plan.js',
+        types: './dist/runner/check-plan.d.ts',
+        import: './dist/runner/check-plan.js',
+        default: './dist/runner/check-plan.js',
+    },
+    './runner/compare': {
+        require: './dist/runner/compare.js',
+        types: './dist/runner/compare.d.ts',
+        import: './dist/runner/compare.js',
+        default: './dist/runner/compare.js',
+    },
+    './runner/compare-latest': {
+        require: './dist/runner/compare-latest.js',
+        types: './dist/runner/compare-latest.d.ts',
+        import: './dist/runner/compare-latest.js',
+        default: './dist/runner/compare-latest.js',
+    },
+    './runner/demo-loop': {
+        require: './dist/runner/demo-loop.js',
+        types: './dist/runner/demo-loop.d.ts',
+        import: './dist/runner/demo-loop.js',
+        default: './dist/runner/demo-loop.js',
+    },
+    './runner/example-android-live': {
+        require: './dist/runner/example-android-live.js',
+        types: './dist/runner/example-android-live.d.ts',
+        import: './dist/runner/example-android-live.js',
+        default: './dist/runner/example-android-live.js',
+    },
+    './runner/example-ios-live': {
+        require: './dist/runner/example-ios-live.js',
+        types: './dist/runner/example-ios-live.d.ts',
+        import: './dist/runner/example-ios-live.js',
+        default: './dist/runner/example-ios-live.js',
+    },
+    './runner/host-doctor': {
+        require: './dist/runner/host-doctor.js',
+        types: './dist/runner/host-doctor.d.ts',
+        import: './dist/runner/host-doctor.js',
+        default: './dist/runner/host-doctor.js',
+    },
+    './runner/init-project': {
+        require: './dist/runner/init-project.js',
+        types: './dist/runner/init-project.d.ts',
+        import: './dist/runner/init-project.js',
+        default: './dist/runner/init-project.js',
+    },
+    './runner/ios-simctl': {
+        require: './dist/runner/ios-simctl.js',
+        types: './dist/runner/ios-simctl.d.ts',
+        import: './dist/runner/ios-simctl.js',
+        default: './dist/runner/ios-simctl.js',
+    },
+    './runner/ios-simctl-driver': {
+        require: './dist/runner/ios-simctl-driver.js',
+        types: './dist/runner/ios-simctl-driver.d.ts',
+        import: './dist/runner/ios-simctl-driver.js',
+        default: './dist/runner/ios-simctl-driver.js',
+    },
+    './runner/live-android': {
+        require: './dist/runner/live-android.js',
+        types: './dist/runner/live-android.d.ts',
+        import: './dist/runner/live-android.js',
+        default: './dist/runner/live-android.js',
+    },
+    './runner/live-ios': {
+        require: './dist/runner/live-ios.js',
+        types: './dist/runner/live-ios.d.ts',
+        import: './dist/runner/live-ios.js',
+        default: './dist/runner/live-ios.js',
+    },
+    './runner/live-proof': {
+        require: './dist/runner/live-proof.js',
+        types: './dist/runner/live-proof.d.ts',
+        import: './dist/runner/live-proof.js',
+        default: './dist/runner/live-proof.js',
+    },
+    './runner/profile-android': {
+        require: './dist/runner/profile-android.js',
+        types: './dist/runner/profile-android.d.ts',
+        import: './dist/runner/profile-android.js',
+        default: './dist/runner/profile-android.js',
+    },
+    './runner/profile-ios': {
+        require: './dist/runner/profile-ios.js',
+        types: './dist/runner/profile-ios.d.ts',
+        import: './dist/runner/profile-ios.js',
+        default: './dist/runner/profile-ios.js',
+    },
+    './runner/validate-project': {
+        require: './dist/runner/validate-project.js',
+        types: './dist/runner/validate-project.d.ts',
+        import: './dist/runner/validate-project.js',
+        default: './dist/runner/validate-project.js',
+    },
+    './schemas/*': './schemas/*',
+    './templates/*': './templates/*',
+};
+const REQUIRED_PACKAGE_FILES = [
+    'LICENSE',
+    'README.md',
+    'app/profile-session.ts',
+    'core/config-template.json',
+    'dist',
+    'docs',
+    'examples',
+    'schemas',
+    'templates',
+];
+const REQUIRED_PACKAGE_EXCLUSIONS = [
+    '!dist/**/__tests__',
+    '!examples/mobile-app/.expo',
+    '!examples/mobile-app/.expo/**',
+    '!examples/mobile-app/android',
+    '!examples/mobile-app/android/**',
+    '!examples/mobile-app/artifacts',
+    '!examples/mobile-app/artifacts/**',
+    '!examples/mobile-app/ios',
+    '!examples/mobile-app/ios/**',
+    '!examples/mobile-app/node_modules',
+    '!examples/mobile-app/node_modules/**',
+];
+const REQUIRED_GITIGNORE_ENTRIES = [
+    'node_modules/',
+    '.agents/',
+    'dist/',
+    'core/artifacts/',
+    'artifacts/',
+    'examples/mobile-app/.expo/',
+    'examples/mobile-app/android/',
+    'examples/mobile-app/artifacts/',
+    'examples/mobile-app/ios/',
+    'examples/mobile-app/node_modules/',
+];
+const FORBIDDEN_TRACKED_PATH_PATTERNS = [
+    /^artifacts\//u,
+    /^core\/artifacts\//u,
+    /^dist\//u,
+    /^examples\/mobile-app\/(?:\.expo|android|artifacts|ios|node_modules)(?:\/|$)/u,
+];
+const REQUIRED_CONFIG_STRING_FIELDS = [
+    ['app', 'profileSessionScheme'],
+    ['app', 'iosBundleId'],
+    ['app', 'androidPackage'],
+    ['paths', 'artifactRoot'],
+    ['paths', 'iosArtifactsRoot'],
+    ['paths', 'androidArtifactsRoot'],
+    ['paths', 'scenarioRoot'],
+];
+const REQUIRED_PLATFORM_SCRIPT_PAIRS = [
+    ['asl:check:ios', 'asl:check:android'],
+    ['asl:profile:ios', 'asl:profile:android'],
+    ['asl:profile:ios:provider', 'asl:profile:android:provider'],
+    ['asl:profile:ios:live', 'asl:profile:android:live'],
+    ['asl:ios:live', 'asl:android:live'],
+    ['asl:ios:live:agent-device', 'asl:android:live:agent-device'],
+    ['asl:ios:live:argent', 'asl:android:live:argent'],
+    ['asl:ios:live:runners', 'asl:android:live:runners'],
+    ['asl:agent-device:ios', 'asl:agent-device:android'],
+    ['asl:argent:ios', 'asl:argent:android'],
+    ['asl:compare:ios', 'asl:compare:android'],
+    ['asl:live-proof:ios', 'asl:live-proof:android'],
+];
+const REQUIRED_STRICT_EXAMPLE_LIVE_SCRIPTS = [
+    'example:android:live',
+    'example:android:live:agent-device',
+    'example:android:live:argent',
+    'example:android:live:runners',
+    'example:ios:live',
+    'example:ios:live:agent-device',
+    'example:ios:live:argent',
+    'example:ios:live:runners',
+];
+/**
+ * Reads and parses a JSON object from disk.
+ *
+ * @param {string} filePath
+ * @returns {Record<string, unknown>}
+ */
+function readJsonObject(filePath) {
+    const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    assert.equal(typeof value, 'object', `${filePath} must contain a JSON object`);
+    assert.notEqual(value, null, `${filePath} must contain a JSON object`);
+    assert.equal(Array.isArray(value), false, `${filePath} must contain a JSON object`);
+    return value;
+}
+/**
+ * Reads a nested value from a JSON object.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {string[]} pathSegments
+ * @returns {unknown}
+ */
+function readNestedValue(object, pathSegments) {
+    let value = object;
+    for (const segment of pathSegments) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return undefined;
+        }
+        value = value[segment];
+    }
+    return value;
+}
+/**
+ * Returns a string map property from a JSON object.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {string} key
+ * @returns {Record<string, string>}
+ */
+function getStringMap(object, key) {
+    const value = object[key];
+    assert.equal(typeof value, 'object', `${key} must be an object`);
+    assert.notEqual(value, null, `${key} must be an object`);
+    assert.equal(Array.isArray(value), false, `${key} must be an object`);
+    for (const [entryKey, entryValue] of Object.entries(value)) {
+        assert.equal(typeof entryValue, 'string', `${key}.${entryKey} must be a string`);
+    }
+    return value;
+}
+/**
+ * Returns an object map property from a JSON object.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {string} key
+ * @returns {Record<string, unknown>}
+ */
+function getObjectMap(object, key) {
+    const value = object[key];
+    assert.equal(typeof value, 'object', `${key} must be an object`);
+    assert.notEqual(value, null, `${key} must be an object`);
+    assert.equal(Array.isArray(value), false, `${key} must be an object`);
+    return value;
+}
+/**
+ * Returns a string array property from a JSON object.
+ *
+ * @param {Record<string, unknown>} object
+ * @param {string} key
+ * @returns {string[]}
+ */
+function getStringArray(object, key) {
+    const value = object[key];
+    assert.equal(Array.isArray(value), true, `${key} must be an array`);
+    for (const entry of value) {
+        assert.equal(typeof entry, 'string', `${key} entries must be strings`);
+    }
+    return value;
+}
+/**
+ * Asserts that every expected value appears in an actual string list.
+ *
+ * @param {string[]} actual
+ * @param {string[]} expected
+ * @param {string} label
+ * @returns {void}
+ */
+function assertIncludesAll(actual, expected, label) {
+    for (const entry of expected) {
+        assert.equal(actual.includes(entry), true, `${label} is missing ${entry}`);
+    }
+}
+/**
+ * Asserts that package metadata still describes the intended public package.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {void}
+ */
+function assertPublicPackageMetadata(packageJson) {
+    assert.equal(packageJson.name, 'agent-scenario-loop');
+    assert.match(String(packageJson.version), /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u);
+    assert.equal(packageJson.private, false);
+    assert.equal(packageJson.license, 'MIT');
+    assert.equal(packageJson.type, 'commonjs');
+    assert.equal(packageJson.main, 'dist/index.js');
+    assert.equal(packageJson.types, 'dist/index.d.ts');
+    assert.equal(getObjectMap(packageJson, 'publishConfig').access, 'public');
+    assert.equal(getObjectMap(packageJson, 'engines').node, '>=20');
+}
+/**
+ * Asserts that release scripts keep npm publishing behind the full validation gate.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {void}
+ */
+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['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');
+    for (const scriptName of REQUIRED_STRICT_EXAMPLE_LIVE_SCRIPTS) {
+        assert.match(scripts[scriptName], /--compare-latest/u, `${scriptName} must write comparison evidence by default`);
+        assert.match(scripts[scriptName], /--fail-on-regression/u, `${scriptName} must fail on regressions by default`);
+    }
+    assert.match(scripts['example:mobile:live-proof'], /--require-platforms android,ios/u);
+    assert.match(scripts['example:mobile:live-proof'], /--out artifacts\/example-mobile-app\/live-proof-set/u);
+    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 public binaries and package subpath exports map to built files.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {void}
+ */
+function assertPublicEntrypoints(packageJson) {
+    assert.deepEqual(getStringMap(packageJson, 'bin'), REQUIRED_BIN_TARGETS);
+    assert.deepEqual(getObjectMap(packageJson, 'exports'), REQUIRED_EXPORTS);
+}
+/**
+ * Extracts documented runner subpath specifiers from the public API guide.
+ *
+ * @param {string} repoRoot
+ * @returns {string[]}
+ */
+function readDocumentedRunnerSubpaths(repoRoot) {
+    const apiDocs = fs.readFileSync(path.join(repoRoot, 'docs', 'api.md'), 'utf8');
+    const subpaths = new Set();
+    for (const match of apiDocs.matchAll(/`(agent-scenario-loop\/runner\/[^`]+)`/gu)) {
+        subpaths.add(match[1]);
+    }
+    return Array.from(subpaths).sort();
+}
+/**
+ * Extracts concrete runner subpath specifiers from package exports.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {string[]}
+ */
+function readExportedRunnerSubpaths(packageJson) {
+    return Object.keys(getObjectMap(packageJson, 'exports'))
+        .filter((subpath) => subpath.startsWith('./runner/'))
+        .map((subpath) => `agent-scenario-loop/${subpath.slice(2)}`)
+        .sort();
+}
+/**
+ * Asserts that the public API guide and package exports describe the same runner surface.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertPublicApiDocs(packageJson, repoRoot) {
+    assert.deepEqual(readDocumentedRunnerSubpaths(repoRoot), readExportedRunnerSubpaths(packageJson), 'docs/api.md runner subpaths must match package.json exports');
+}
+/**
+ * Asserts that package include/exclude metadata protects generated local state.
+ *
+ * @param {Record<string, unknown>} packageJson
+ * @returns {void}
+ */
+function assertPackageFileList(packageJson) {
+    const files = getStringArray(packageJson, 'files');
+    assertIncludesAll(files, REQUIRED_PACKAGE_FILES, 'package files');
+    assertIncludesAll(files, REQUIRED_PACKAGE_EXCLUSIONS, 'package files');
+    for (const forbidden of ['.github', 'scripts', 'runner', 'node_modules', 'artifacts']) {
+        assert.equal(files.includes(forbidden), false, `package files must not include ${forbidden}`);
+    }
+}
+/**
+ * Asserts that ignored local state paths remain explicit in the repository.
+ *
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertGitignoreState(repoRoot) {
+    const gitignore = fs.readFileSync(path.join(repoRoot, '.gitignore'), 'utf8').split(/\r?\n/u);
+    assertIncludesAll(gitignore, REQUIRED_GITIGNORE_ENTRIES, '.gitignore');
+}
+/**
+ * Asserts that generated runtime/native state is not tracked by git.
+ *
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertNoTrackedGeneratedState(repoRoot) {
+    const output = execFileSync('git', ['ls-files', '-z'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const trackedPaths = output.split('\0').filter(Boolean);
+    for (const trackedPath of trackedPaths) {
+        assert.equal(FORBIDDEN_TRACKED_PATH_PATTERNS.some((pattern) => pattern.test(trackedPath)), false, `generated state must not be tracked: ${trackedPath}`);
+    }
+}
+/**
+ * Asserts that shipped config templates contain identifiers needed by both mobile platforms.
+ *
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertConfigTemplates(repoRoot) {
+    for (const relativePath of ['core/config-template.json', 'templates/project.config.json']) {
+        const config = readJsonObject(path.join(repoRoot, relativePath));
+        for (const fieldPath of REQUIRED_CONFIG_STRING_FIELDS) {
+            const value = readNestedValue(config, fieldPath);
+            assert.equal(typeof value, 'string', `${relativePath} must include ${fieldPath.join('.')}`);
+            assert.notEqual(String(value).trim(), '', `${relativePath} must include non-empty ${fieldPath.join('.')}`);
+        }
+    }
+}
+/**
+ * Asserts that shipped package-script snippets expose paired iOS and Android lanes.
+ *
+ * @param {string} repoRoot
+ * @returns {void}
+ */
+function assertPlatformPackageScripts(repoRoot) {
+    for (const relativePath of ['templates/package-scripts.json', 'examples/mobile-app/asl/package-scripts.json']) {
+        const scripts = readJsonObject(path.join(repoRoot, relativePath));
+        for (const [iosScriptName, androidScriptName] of REQUIRED_PLATFORM_SCRIPT_PAIRS) {
+            assert.equal(typeof scripts[iosScriptName], 'string', `${relativePath} must include ${iosScriptName}`);
+            assert.equal(typeof scripts[androidScriptName], 'string', `${relativePath} must include ${androidScriptName}`);
+        }
+    }
+}
+/**
+ * Runs the release-readiness assertions for the current repository checkout.
+ *
+ * @returns {void}
+ */
+function main() {
+    const repoRoot = path.resolve(__dirname, '..', '..');
+    const packageJson = readJsonObject(path.join(repoRoot, 'package.json'));
+    assertPublicPackageMetadata(packageJson);
+    assertReleaseScripts(packageJson);
+    assertPublicEntrypoints(packageJson);
+    assertPublicApiDocs(packageJson, repoRoot);
+    assertPackageFileList(packageJson);
+    assertGitignoreState(repoRoot);
+    assertNoTrackedGeneratedState(repoRoot);
+    assertConfigTemplates(repoRoot);
+    assertPlatformPackageScripts(repoRoot);
+    process.stdout.write('release readiness passed\n');
+}
+main();

package/docs/adapters.md

@@ -102,6 +102,8 @@ The built-in adb and simctl adapters show the expected boundary:
 
 External tools such as agent-device, Argent, XcodeBuildMCP, axe, profilers, and custom scripts should plug in behind the same shape. The tactical tool can change; the scenario and artifact contract should not.
 
+Prefer capability-based orchestration over forcing one tool to own every surface. Use adb and simctl as the primary live profile capture lanes for app launch, logs, screenshots, profile-session truth, and causal timelines. Attach heavier or tool-specific diagnostics after the active profile window through provider commands or rehydration. Agent Device is a good fit for Android snapshots and cross-platform network/performance evidence when its session is bound to the target. Argent is a good fit for iOS accessibility descriptions when `describe` can return AXRuntime evidence; native hierarchy, video, trace, React DevTools, and long profiler captures should be explicit heavy lanes until a runner/provider maps them into stable ASL artifacts.
+
 ## Preserve Evidence
 
 Every run should leave agent-readable proof:
@@ -133,7 +135,7 @@ asl-profile-android \
   --capture screenshot:artifacts/provider/final-screen.png
 ```
 
-If the provider should run during profiling, declare `providerCommands` in its manifest. Commands run without a shell, preserve stdout/stderr/exit code, and inventory outputs in `manifest.artifacts.evidenceAttachments`. Runtime profiles reject a provider whose `platforms` do not include the selected platform before command execution, preserving the same active-provider semantics used by planner compatibility.
+If the provider should run during profile artifact assembly, declare `providerCommands` in its manifest. Profile runners execute provider commands after the selected platform evidence source is available, including live `--adb-capture` / `--simctl-capture` runs and later `--adb-artifacts` / `--simctl-artifacts` rehydration runs. Use `phase: "afterCapture"` for diagnostics collected from an existing capture sidecar; use `phase: "postRun"` for evidence that should be understood as post-profile enrichment. Commands run without a shell, preserve stdout/stderr/exit code, and inventory outputs in `manifest.artifacts.evidenceAttachments`. Provider command outputs may set `required: true` so the matching diagnostic inventory entry is required when the provider successfully captures that output; scenario-authored required artifacts and capabilities remain canonical too. Runtime profiles reject a provider whose `platforms` do not include the selected platform before command execution, preserving the same active-provider semantics used by planner compatibility.
 
 ## Acceptance Checklist
 

package/docs/api.md

@@ -80,11 +80,11 @@ For concrete runner and evidence-provider integration steps, see [Adapter Onboar
 
 ## App Helper
 
-`app/profile-session.ts` is shipped as source for React Native apps to copy into their own codebase. It is not a compiled CommonJS runtime export because it depends on app-side React Native modules, app bundling, and platform storage behavior.
+`agent-scenario-loop/app/profile-session` is shipped as React Native source. Apps can copy `app/profile-session.ts` into their own codebase or re-export the package subpath from an app-local helper module. It is not a compiled CommonJS runtime export because it depends on app-side React Native modules, app bundling, and platform storage behavior.
 
 The intended integration is:
 
-1. Copy `app/profile-session.ts` into the app.
+1. Copy `app/profile-session.ts` into the app, or re-export `agent-scenario-loop/app/profile-session` from an app-local helper.
 2. Wire `useProfileSessionBootstrap()` once near the app root.
 3. Emit app-owned truth events with `emitProfileEvent()`.
 4. Register optional command targets with `registerProfileCommandTargetHandler()`.

package/docs/authoring.md

@@ -80,12 +80,14 @@ Preferred fields:
 - `journey`: human-readable intent, actor, start state, and end state
 - `comparisonLane`: default historical baseline lane for runs of this scenario
 - `milestones`: named event checkpoints with phases and timeouts
-- `cycles`: iteration count and stop policy
+- `cycles`: iteration count, stop policy, and optional setup/body step ids
 - `budgets`: thresholds to evaluate only after truth-event health passes
 - `artifacts`: required and optional evidence outputs
 
 Use `comparisonLane` when a scenario should always compare within one stable proof mode, such as `feed-open-android-live`. Profile CLIs can also receive `--comparison-lane`; the CLI flag wins when one-off runs need a different lane.
 
+For repeated scenarios, separate setup from the measured body. Commands that clear state, navigate home, dismiss modals, or establish readiness should not be measured every iteration unless that cleanup is the journey under test. Use `cycles.setupStepIds` for leading setup commands that run once, or `cycles.bodyStepIds` to name the repeated command body. If neither is provided, ASL profile-session runners infer a conservative setup prefix from readiness waits and measured milestone budgets, but explicit ids are clearer for complex flows.
+
 ## Truth Events
 
 Treat truth events as app-owned facts, not runner observations. The app should emit them from the code path that actually represents the journey state.
@@ -105,6 +107,32 @@ Weak truth events:
 
 Timing is not trusted unless scenario health passes. If a required truth event is missing, the run can still write artifacts, but verdicts and comparisons must remain inconclusive.
 
+### Resume Scenarios
+
+`--lifecycle-phase resume` and related runner controls assert runner-owned lifecycle setup in `manifest.environment`; they do not create product truth events. If a scenario waits for `app_resumed`, `feed_restored_after_resume`, or another resumed-state milestone, the app must emit that event from the code path that proves resumed product readiness.
+
+## Budget Intervals
+
+Milestone budgets measure the interval the scenario names. A budget with only `toMilestone` measures elapsed time from the run or session clock origin to each matching milestone occurrence. That is correct for startup and first-usable-screen budgets, but it is cumulative for repeated interactions.
+
+For transition or gesture budgets, provide both ends of the interval:
+
+```json
+{
+  "name": "surface transition p95",
+  "source": "milestone",
+  "metric": "p95",
+  "unit": "ms",
+  "limit": 300,
+  "fromMilestone": "surfaceTransitionRequested",
+  "toMilestone": "surfaceSettled"
+}
+```
+
+Use app-owned truth events for both milestones. Do not use a command-delivered event as the start point unless that command delivery is the product fact being measured.
+
+When the start event is useful only as a timing anchor, keep it optional and keep scenario health tied to the completion truth. For repeated flows, set `metricEvents.milestone` or the completion-oriented cycle events to the truth that proves the iteration completed, then use the optional intent milestone as `fromMilestone` in the budget.
+
 ## Steps
 
 Use steps to describe intent and required adapter actions:
@@ -118,6 +146,8 @@ Use steps to describe intent and required adapter actions:
 
 Use `driverAction` only when the scenario truly requires a concrete operation such as `tap`, `scroll`, `assertVisible`, `screenshot`, `readLogs`, or `collectPerfSignals`. The planner fails early when no active runner or provider can satisfy a required driver action.
 
+For profile-session command transport, platform `waitMs` metadata is queue pacing. ASL preserves it in storage and deep-link command envelopes and waits before releasing the next queued command. App-owned milestones still provide the truth that a command produced the intended product state.
+
 Use `selector` to describe the intended app target without committing the scenario to one driver. Supported selector kinds are `testId`, `accessibilityId`, `accessibilityLabel`, `text`, `resourceId`, and `xpath`.
 
 ```json
@@ -161,10 +191,12 @@ asl-profile-android \
 
 Signals are copied into `signals/js`, `signals/memory`, or `signals/network` and listed in `manifest.json`. Captures are copied into `captures`; screenshots are listed in `artifacts.captures.screenshots`, while video and UI tree captures replace the matching named capture path in the manifest. Every attached file is also listed in `artifacts.evidenceAttachments` with kind, run-relative path, source filename, byte size, sha256 hash, completeness status, corruption status, redaction status, and transformation list. Attached provider evidence is preserved as proof, but timing verdicts still come from app-owned truth events and budgets.
 
-Provider manifests can also declare `providerCommands`. Profile runners execute those commands when passed with `--provider <manifest>`, but only when the provider manifest includes the selected platform. A provider with `platforms: ["ios"]` passed to an Android profile writes failed `health.json` with `provider_platform_unsupported` and does not run the command. Commands run without a shell, can use placeholders such as `{providerDir}`, `{runDir}`, `{runId}`, `{scenarioId}`, and `{platform}`, and must declare their output files. Provider-channel outputs are copied or preserved under `raw/providers/<provider-id>/` and inventoried in `artifacts.evidenceAttachments`; signal and capture outputs can still map into the standard `signals/*` or `captures/` folders. Command stdout, stderr, exit code, phase, and argv are preserved under `raw/provider-commands/`. When a provider command exits nonzero, the runner writes failed `health.json`, inconclusive `verdict.json`, and `agent-summary.md` with a next-action hint instead of making timing claims.
+Provider manifests can also declare `providerCommands`. Profile runners execute those commands when passed with `--provider <manifest>`, but only when the provider manifest includes the selected platform. Commands run after the platform evidence source has been collected or supplied, so heavy diagnostics can be attached in a post-loop rehydration run with `--adb-artifacts` or `--simctl-artifacts` instead of perturbing the measured command window. Use `phase: "afterCapture"` for capture-sidecar diagnostics and `phase: "postRun"` for post-profile enrichment; older `capture` phase values remain accepted for existing manifests. A provider with `platforms: ["ios"]` passed to an Android profile writes failed `health.json` with `provider_platform_unsupported` and does not run the command. Commands run without a shell, can use placeholders such as `{providerDir}`, `{runDir}`, `{runId}`, `{scenarioId}`, and `{platform}`, and must declare their output files. Provider-channel outputs are copied or preserved under `raw/providers/<provider-id>/` and inventoried in `artifacts.evidenceAttachments`; signal and capture outputs can still map into the standard `signals/*` or `captures/` folders. An output can set `required: true` when the provider treats that file as required evidence; matching entries in `manifest.artifacts.diagnostics` then remain marked required in addition to scenario-authored `artifacts.required` and `requiredCapabilities`. Command stdout, stderr, exit code, phase, and argv are preserved under `raw/provider-commands/`. When a provider command exits nonzero, the runner writes failed `health.json`, inconclusive `verdict.json`, and `agent-summary.md` with a next-action hint instead of making timing claims.
 
 The `examples/runners/script-*.json` manifests show package-neutral wrappers for accessibility, profiler, memory, and network evidence. They intentionally reference placeholder commands such as `capture-accessibility` or `capture-memory`; replace those with your project-local script, binary, or agent command. The contract that matters is the declared output path and evidence kind, not the specific tool used to create the file.
 
+For React Native profiling, prefer a provider that emits both the raw profiler export and a structured JSON summary. JSON outputs with `kind: "profiler"` are validated against ASL's profiler evidence schema, so include the provider id, platform, run id, scenario id, tool metadata, completeness status, and at least one content surface such as samples, metrics, events, traces, a profile object, summary, or attachment references. If profiler evidence depends on explicit start/stop commands, model it as lifecycle-owned evidence: declare `captureMode`, `profileKind`, `lifecycle`, `targetBinding`, and `comparability` so agents can distinguish passive existing reports from session captures, inline captures that may perturb budgets, and after-capture or rehydrated diagnostics. CPU summaries derived from a prior profiler session should not be attached as passive evidence unless the provider also preserves the session provenance and raw attachments. If your profiler only produces a native trace or flamegraph, attach it as preserved evidence and avoid making performance claims until a provider translates the relevant facts into structured metrics.
+
 ## Artifacts
 
 A completed profile run should leave the standard artifact set: