firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/runner-world-observations.js

@@ -0,0 +1,50 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { signRunnerRequest } from './runner-identity.js';
+import { localWorldObservation } from './runner-world-session-protocol.js';
+import { localWorldClaimPath, localWorldClaimTime } from './runner-world-claim.js';
+import { localWorldIdentityMatches, LOCAL_WORLD_IDENTITY_KEYS } from '../../contracts/local-world-native-contracts.js';
+const MAX = 8 * 1024 ** 2;
+const invalid = () => new CliError('local_world_observation_unconfirmed', 'This exact local world observation was not confirmed in cloud history. No target was restarted.');
+const keys = (value, expected) => Object.keys(value).sort().join(',') === [...expected].sort().join(',');
+/** Host-serialized actual native observation, not original status-file bytes
+ * or independent attestation. Cloud scans BOTH private matcher sets before
+ * retaining exact upload bytes in GCS and recording their owned DB identity.
+ * A returned artifact receipt is not execution/cleanup or behavior assessment. */
+export async function retainLocalWorldObservation(owner, configuration, observation, signal) {
+    if (configuration.control.schema !== 'firedrill.world-session.v1' || !owner.evidenceUpload)
+        throw invalid();
+    localWorldObservation(observation, owner, configuration.control);
+    const raw = Buffer.from(JSON.stringify(observation));
+    try {
+        if (!raw.length || raw.length > MAX)
+            throw new CliError('local_world_observation_capacity', 'This native observation needs more transfer capacity. No replacement world was started.');
+        const digest = createHash('sha256').update(raw).digest('hex'), sent = await localWorldClaimTime(owner, signal);
+        const payload = { schema: 'firedrill.local-world-observation-write.v1',
+            job_id: owner.job, attempt_id: owner.attempt, lease_id: owner.lease, request_key: owner.request, device_key: owner.device,
+            native_session_id: owner.nativeSession, manifest_sha256: configuration.manifest_sha256, session_id: owner.session.session_id,
+            input_sha256: owner.session.input_sha256, write_key: randomUUID(), sent_at_ms: sent, size: raw.length,
+            sha256: digest, content_base64: raw.toString('base64') };
+        const proof = await signRunnerRequest(owner, owner.device, payload, signal);
+        const receipt = await api(localWorldClaimPath(owner) + '/world-observations', { actor: owner.owner, workspace: owner.workspace, signal, method: 'POST', body: proof });
+        if (!receipt || !localWorldIdentityMatches(receipt, owner, configuration.manifest_sha256)
+            || !keys(receipt, [...LOCAL_WORLD_IDENTITY_KEYS.filter(key => key !== 'manifest_sha256'), 'schema', 'session_id', 'lease_id', 'input_sha256', 'manifest_sha256', 'artifact', 'state',
+                'applied', 'server_time', 'provenance', 'target_invocation_observed', 'behavior_assessed'])
+            || receipt.schema !== 'firedrill.local-world-observation-receipt.v1' || receipt.session_id !== owner.session.session_id
+            || receipt.lease_id !== owner.lease || receipt.input_sha256 !== owner.session.input_sha256
+            || receipt.manifest_sha256 !== configuration.manifest_sha256 || receipt.provenance !== 'customer_device'
+            || receipt.target_invocation_observed !== false || receipt.behavior_assessed !== false || typeof receipt.applied !== 'boolean'
+            || receipt.state !== (observation.status?.state ?? null) || !Number.isFinite(Date.parse(receipt.server_time))
+            || !receipt.artifact || !keys(receipt.artifact, ['id', 'size', 'sha256', 'generation'])
+            || identifier(receipt.artifact.id) !== receipt.artifact.id || receipt.artifact.sha256 !== digest
+            || receipt.artifact.size !== raw.length || typeof receipt.artifact.generation !== 'string'
+            || !/^[1-9][0-9]{0,31}$/.test(receipt.artifact.generation))
+            throw invalid();
+        return receipt;
+    }
+    finally {
+        raw.fill(0); /* JS/HTTP strings are not zeroized memory. */
+    }
+}

package/dist/cli/src/runner-world-session-protocol.js

@@ -0,0 +1,134 @@
+import { CliError } from './http.js';
+import { checkpointResetBaselines } from './world-checkpoint-scopes.js';
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, names) => Object.keys(value).sort().join(',') === names.sort().join(',');
+const finiteCount = (value) => Number.isSafeInteger(value) && Number(value) >= 0;
+function sameValue(left, right) {
+    if (record(left) && record(right))
+        return Object.keys(left).length === Object.keys(right).length
+            && Object.entries(left).every(([key, value]) => Object.hasOwn(right, key) && sameValue(value, right[key]));
+    return left === right;
+}
+const invalid = () => new CliError('local_world_status_invalid', 'The native world status does not match this exact local session.');
+export function nativeFilterReference(value) {
+    if (!record(value) || !exact(value, ['schema', 'scope', 'sha256', 'size', 'pattern_count'])
+        || value.schema !== 'firedrill.native-filter-reference.v1' || value.scope !== 'native_database_credentials'
+        || typeof value.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.sha256)
+        || !finiteCount(value.size) || Number(value.size) < 1 || Number(value.size) > 64 * 1024 ** 2
+        || !finiteCount(value.pattern_count) || Number(value.pattern_count) > 65536)
+        throw invalid();
+}
+/** Native observations, not independent managed attestation or trial scoring. */
+export function localWorldStatus(value, owner, control) {
+    if (value === null)
+        return; // No startup status is not fabricated failure/cleanup.
+    if (record(value) && value.state === 'failed' && exact(value, ['schema', 'session_id', 'operation_id', 'state', 'code',
+        'target_invocation_observed', 'behavior_assessed'])) {
+        if (value.schema !== 'firedrill.world-session-status.v7' || value.session_id !== owner.session.session_id
+            || value.operation_id !== owner.lease || typeof value.code !== 'string' || !/^[a-z_]{1,64}$/.test(value.code)
+            || value.target_invocation_observed !== false || value.behavior_assessed !== false)
+            throw invalid();
+        return; // The original native fatal diagnostic has no topology/cleanup facts.
+    }
+    const fields = ['schema', 'session_id', 'operation_id', 'world_id', 'configuration_id', 'configuration_digest', 'bundle_digest',
+        'state', 'code', 'observed_at', 'elapsed_ms', 'completed_command_sequence', 'reset_count', 'native_cleanup_finished',
+        'isolation', 'topology', 'surface_declarations', 'checkpoint', 'native_filters', 'fork', 'dataset', 'target_invocation_observed', 'behavior_assessed'];
+    if (record(value) && Object.hasOwn(value, 'lease'))
+        fields.push('lease');
+    if (record(value) && (Object.hasOwn(value, 'application_checkpoint') || Object.hasOwn(value, 'application_resume')))
+        fields.push('application_checkpoint', 'application_resume');
+    if (!record(value) || !exact(value, fields) || value.schema !== 'firedrill.world-session-status.v7'
+        || value.session_id !== owner.session.session_id || value.operation_id !== owner.lease || value.world_id !== owner.world
+        || value.configuration_id !== owner.session.configuration_id || value.configuration_digest !== owner.configurationDigest
+        || value.bundle_digest !== control.bundle_digest
+        || !['starting', 'active', 'resetting', 'checkpointing', 'stopping', 'stopped', 'failed'].includes(String(value.state))
+        || typeof value.code !== 'string' || value.code !== '' && !/^[a-z][a-z0-9_]{0,127}$/.test(value.code)
+        || typeof value.observed_at !== 'string' || !Number.isFinite(Date.parse(value.observed_at))
+        || !finiteCount(value.elapsed_ms) || !finiteCount(value.completed_command_sequence) || !finiteCount(value.reset_count)
+        || typeof value.native_cleanup_finished !== 'boolean' || !record(value.isolation)
+        || value.topology !== null && !record(value.topology) || !Array.isArray(value.surface_declarations)
+        || value.surface_declarations.some(item => !record(item)) || !record(value.checkpoint)
+        || value.target_invocation_observed !== false || value.behavior_assessed !== false)
+        throw invalid();
+    if (value.lease !== undefined && (!record(value.lease) || !exact(value.lease, ['revision', 'expires_at'])
+        || value.lease.revision !== 0 || value.lease.expires_at !== control.expires_at))
+        throw invalid();
+    if (value.application_checkpoint !== undefined) {
+        const declaration = value.application_checkpoint;
+        if (!record(declaration) || (declaration.available === false ? !exact(declaration, ['available'])
+            : declaration.available !== true || !exact(declaration, ['available', 'driver_digest', 'recipe'])
+                || typeof declaration.driver_digest !== 'string' || !/^[a-f0-9]{64}$/.test(declaration.driver_digest) || !record(declaration.recipe)))
+            throw invalid();
+        const resume = value.application_resume, selected = control.application_checkpoint;
+        if (selected === null && resume !== null || selected !== null && value.state === 'active' && resume === null)
+            throw invalid();
+        if (resume !== null && (!selected || !record(resume) || !exact(resume, ['checkpoint_id', 'checkpoint_session_id', 'sha256', 'driver_digest', 'request_id',
+            'new_execution_id', 'event_watermark', 'applied_at', 'components', 'excluded', 'continuity'])
+            || ['checkpoint_id', 'checkpoint_session_id', 'sha256', 'driver_digest', 'event_watermark'].some(key => resume[key] !== selected[key])
+            || resume.new_execution_id !== owner.session.session_id || resume.continuity !== 'application_supported_new_process'
+            || typeof resume.applied_at !== 'string' || !Number.isFinite(Date.parse(resume.applied_at))
+            || Date.parse(resume.applied_at) > Date.parse(value.observed_at)))
+            throw invalid();
+    }
+    if (control.dataset !== null && value.state === 'active' && value.dataset === null)
+        throw invalid();
+    if (control.initial_checkpoint === null && value.fork !== null
+        || control.initial_checkpoint !== null && value.state === 'active' && value.fork === null)
+        throw invalid();
+    if (value.fork !== null) {
+        const proof = value.fork, saved = control.initial_checkpoint;
+        if (!saved || !record(proof) || !exact(proof, ['schema', 'session_id', 'checkpoint_id', 'checkpoint_session_id', 'sha256',
+            'schema_sha256', 'clock_mode', 'scope', 'target_state_complete', 'before_source_start', 'applied_at', 'reset_baseline'])
+            || proof.schema !== 'firedrill.world-fork-origin.v1' || proof.session_id !== owner.session.session_id
+            || ['checkpoint_id', 'checkpoint_session_id', 'sha256', 'schema_sha256', 'clock_mode', 'scope'].some(key => proof[key] !== saved[key])
+            || proof.reset_baseline !== checkpointResetBaselines[saved.scope]
+            || proof.target_state_complete !== false || proof.before_source_start !== true
+            || typeof proof.applied_at !== 'string' || !Number.isFinite(Date.parse(proof.applied_at))
+            || Date.parse(proof.applied_at) > Date.parse(value.observed_at))
+            throw invalid();
+    }
+    if (value.dataset !== null) {
+        const proof = value.dataset;
+        if (control.dataset === null || !record(proof) || !exact(proof, ['schema', 'selection', 'applications', 'latest_worlds', 'scope',
+            'process_memory_included', 'before_source_start', 'real_account_effects'])
+            || proof.schema !== 'firedrill.world-dataset-application.v1' || !record(proof.selection)
+            || !sameValue(proof.selection, control.dataset)
+            || !finiteCount(proof.applications) || Number(proof.applications) < 1
+            || !['typed_edits_to_owned_native_postgres_seed', 'typed_edits_to_declared_sqlite_files',
+                'typed_edits_to_owned_postgres_and_declared_sqlite_files'].includes(String(proof.scope))
+            || proof.process_memory_included !== false || proof.before_source_start !== (proof.scope === 'typed_edits_to_owned_native_postgres_seed')
+            || proof.real_account_effects !== false
+            || !Array.isArray(proof.latest_worlds) || proof.latest_worlds.length !== 1
+            || proof.latest_worlds.some(row => !record(row) || !exact(row, ['world_index', 'application', 'applied_at', 'affected_rows',
+                'schema_sha256', 'prepared_sha256', 'applied_sha256']) || row.world_index !== 0
+                || !finiteCount(row.application) || row.application !== proof.applications
+                || !finiteCount(row.affected_rows) || Number(row.affected_rows) > Number(control.dataset.edit_count)
+                || typeof row.applied_at !== 'string' || !Number.isFinite(Date.parse(row.applied_at)) || Date.parse(row.applied_at) > Date.parse(value.observed_at)
+                || ['schema_sha256', 'prepared_sha256', 'applied_sha256'].some(key => typeof row[key] !== 'string' || !/^[a-f0-9]{64}$/.test(row[key]))))
+            throw invalid();
+    }
+    if (value.native_filters !== null) {
+        nativeFilterReference(value.native_filters);
+    }
+}
+export function localWorldObservation(value, owner, control) {
+    if (value.operation_id !== owner.lease || value.session_id !== owner.session.session_id)
+        throw invalid();
+    localWorldStatus(value.status, owner, control);
+    const launch = value.launch;
+    if (launch === null)
+        return;
+    if (!record(launch) || launch.launch_id !== owner.lease)
+        throw invalid();
+    if (launch.state === 'claimed' || launch.state === 'running') {
+        if (!exact(launch, ['launch_id', 'state', 'process_present']) || typeof launch.process_present !== 'boolean')
+            throw invalid();
+    }
+    else if (launch.state === 'exited') {
+        if (!exact(launch, ['launch_id', 'state', 'exit_code']) || !Number.isSafeInteger(launch.exit_code)
+            || Number(launch.exit_code) < -128 || Number(launch.exit_code) > 255)
+            throw invalid();
+    }
+    else if (launch.state !== 'launch_failed' || !exact(launch, ['launch_id', 'state']))
+        throw invalid();
+}

package/dist/cli/src/saved-records.js

@@ -0,0 +1,40 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { savedRecordSelection, savedCollectionsPageMatches, savedRecordsPageMatches, savedRecordDetailMatches } from '../../contracts/saved-record-contracts.js';
+export async function readSavedRecords(prefix, observation, collection, position, options, command, output) {
+    if (collection !== undefined && !/^[a-f0-9]{64}$/.test(collection)
+        || position !== undefined && (!/^(0|[1-9][0-9]{0,14})$/.test(position) || !Number.isSafeInteger(Number(position)))
+        || position !== undefined && (options.page !== undefined || options.search !== undefined)
+        || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page) || (options.search?.length ?? 0) > 200) {
+        throw new CliError('arguments_invalid', 'Use the saved collection key and zero-based record position. --page and --search apply only to lists.', 2);
+    }
+    const selected = savedRecordSelection(prefix, options.workspace, observation);
+    if (!selected)
+        throw new CliError('saved_record_selection_invalid', 'Choose a saved capture in the current workspace.', 2);
+    const auth = { actor: options.actor, workspace: options.workspace, signal: options.signal, maximumResponseBytes: 16 * 1024 ** 2 };
+    const base = `${prefix}/state/collections`, query = `observation=${observation}&page=${options.page ?? '1'}&q=${encodeURIComponent(options.search ?? '')}`;
+    const unconfirmed = () => new CliError('state_observation_changed', 'The selected saved records could not be confirmed. Open the capture again.', 2);
+    const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+    const continuation = (page) => `\nPage ${page.page}; ${page.count.toLocaleString()} matching entries.${page.next
+        ? `\nContinue: ${command}${collection ? ' ' + collection : ''} --page ${page.page + 1}${options.search ? ' --search ' + quote(options.search) : ''}${options.json ? ' --json' : ''}` : ''}`;
+    if (!collection) {
+        const value = await api(`${base}?${query}`, auth);
+        if (!savedCollectionsPageMatches(value, selected, options.search))
+            throw unconfirmed();
+        output('saved_collections', value, (value.results.map(row => `${row.key}\n${row.store ? row.store + ' / ' : ''}${row.name} · ${row.row_count.toLocaleString()} records`).join('\n\n')
+            || 'No matching collections in this capture.') + continuation(value));
+        return;
+    }
+    const path = `${base}/${collection}/records`;
+    if (position !== undefined) {
+        const value = await api(`${path}/${position}?observation=${observation}`, auth);
+        if (!savedRecordDetailMatches(value, selected, collection, Number(position)))
+            throw unconfirmed();
+        output('saved_record', value, JSON.stringify(value, null, 2));
+        return;
+    }
+    const value = await api(`${path}?${query}`, auth);
+    if (!savedRecordsPageMatches(value, selected, collection, options.search))
+        throw unconfirmed();
+    output('saved_records', value, JSON.stringify(value, null, 2) + continuation(value));
+}

package/dist/cli/src/scenario-authoring.js

@@ -0,0 +1,212 @@
+import { randomUUID } from 'node:crypto';
+import { createInterface } from 'node:readline/promises';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectMany, selectOne } from './prompts.js';
+import { requestInput } from './request-input.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorld } from './world-access.js';
+import { preparation } from './world-agent.js';
+const actions = ['create', 'edit', 'duplicate', 'archive', 'restore', 'definition', 'history'];
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+function editableNumbers(value) {
+    if (typeof value === 'number' && (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value)))
+        throw new CliError('scenario_number_capacity', 'This definition contains numbers that cannot be safely edited in this terminal. Use an original JSON file with --file; its number literals are sent unchanged.', 2);
+    if (Array.isArray(value))
+        value.forEach(editableNumbers);
+    else if (object(value))
+        Object.values(value).forEach(editableNumbers);
+}
+async function line(label, maximum, signal, initial = '', optional = false) {
+    const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+    try {
+        const entered = (await prompt.question(`${label}${initial ? ' (blank to keep)' : ''}: `, { signal })).trim();
+        const value = entered || initial;
+        if ((!optional && !value) || value.length > maximum || /[\u0000-\u001f\u007f-\u009f]/u.test(value))
+            throw new CliError('scenario_input_invalid', 'Use text within the field capacity. Use --file for multiline or larger scenario inputs.', 2);
+        return value;
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function chooseScenario(scope, action, options) {
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    let page = 1, search = options.search ?? '';
+    while (true) {
+        const values = await api(`${scope.prefix}/scenarios?${new URLSearchParams({ page: String(page), q: search,
+            status: action === 'restore' ? 'archived' : ['history', 'definition'].includes(action) ? 'all' : 'active' })}`, auth);
+        const choices = values.results.map(row => ({ value: row.id, label: row.name, detail: `Revision ${row.revision} · ${row.state}` }));
+        if (page > 1)
+            choices.unshift({ value: 'previous', label: 'Previous page', detail: '' });
+        if (values.next)
+            choices.push({ value: 'next', label: 'Next page', detail: '' });
+        choices.push({ value: 'search', label: 'Search scenarios', detail: search }, { value: 'cancel', label: 'Cancel', detail: '' });
+        const selected = await selectOne('Scenario', choices, options.signal);
+        if (selected === 'next') {
+            page++;
+            continue;
+        }
+        if (selected === 'previous') {
+            page--;
+            continue;
+        }
+        if (selected === 'search') {
+            search = await line('Find a scenario (blank for all)', 200, options.signal, '', true);
+            page = 1;
+            continue;
+        }
+        if (selected === 'cancel')
+            throw new CliError('canceled', 'No scenario was changed.', 130);
+        return identifier(selected);
+    }
+}
+async function participant(signal, current) {
+    const original = current ?? null;
+    const action = await selectOne('Synthetic user', [...(original ? [{ value: 'keep', label: 'Keep current synthetic user' }] : []),
+        { value: 'remove', label: original ? 'Remove synthetic user' : 'No synthetic user' }, { value: 'edit', label: original ? 'Edit synthetic user' : 'Configure a synthetic user' }], signal);
+    if (action === 'keep')
+        return original;
+    if (action === 'remove')
+        return null;
+    const previous = (field) => original?.[field] ?? '';
+    return { ...original, name: await line('Name', 240, signal, previous('name')), personality: await line('Behavior', 4000, signal, previous('personality')),
+        communication_style: await line('Communication style', 4000, signal, previous('communication_style')),
+        initial_message: await line('Opening message', 4000, signal, previous('initial_message')) };
+}
+async function interactiveDefinition(scope, options, original) {
+    const current = await preparation(scope, options.signal);
+    if (original && (!original.current || original.world_revision !== current.basis.world_revision || original.definition_locked || !object(original.editor)))
+        throw new CliError('scenario_revision_conflict', 'Open the current editable scenario revision before changing it.', 2);
+    const definition = { ...(original?.editor ?? {}) };
+    editableNumbers(definition);
+    const fixture = object(definition.fixture) ? { ...definition.fixture } : {};
+    const task = object(fixture.http_task) && fixture.http_task.schema === 'firedrill.http-task.v1';
+    let single = task;
+    if (!original) {
+        const values = await api(`${scope.prefix}/scenarios?page_size=1`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+        if (!['conversation', 'browser_chat', 'single_request'].includes(values.invocation_mode ?? '')) {
+            const mode = await selectOne('Scenario input', [{ value: 'conversation', label: 'Conversational turns' },
+                { value: 'single_request', label: 'One task request' }, { value: 'cancel', label: 'Cancel' }], options.signal);
+            if (mode === 'cancel')
+                return null;
+            single = mode === 'single_request';
+        }
+        else
+            single = values.invocation_mode === 'single_request';
+    }
+    let title = original?.name ?? '';
+    const fields = original ? await selectMany('Fields to change', [
+        { value: 'title', label: 'Name' }, { value: 'instruction', label: 'Task and goal' },
+        ...(single ? [{ value: 'task', label: 'Task input JSON' }] : [{ value: 'max_turns', label: 'Maximum turns' }, { value: 'persona', label: 'Synthetic user' }]),
+    ], options.signal) : ['title', 'instruction', single ? 'task' : 'max_turns', ...(single ? [] : ['persona'])];
+    if (!fields.length)
+        return null;
+    if (fields.includes('title'))
+        title = await line('Scenario name', 255, options.signal, title);
+    if (fields.includes('instruction'))
+        definition.instruction = await line('Task and goal', 16000, options.signal, typeof definition.instruction === 'string' ? definition.instruction : '');
+    if (fields.includes('max_turns')) {
+        const turns = Number(await line('Maximum turns', 6, options.signal, String(definition.max_turns ?? 10)));
+        if (!Number.isSafeInteger(turns) || turns < 1 || turns > 100000)
+            throw new CliError('scenario_turns_invalid', 'Use a positive whole number within runtime capacity.', 2);
+        definition.max_turns = turns;
+    }
+    if (fields.includes('persona'))
+        definition.persona = await participant(options.signal, definition.persona);
+    if (fields.includes('task')) {
+        const raw = await line('Task input JSON', 32000, options.signal);
+        let body;
+        try {
+            body = JSON.parse(raw);
+        }
+        catch {
+            throw new CliError('scenario_input_invalid', 'Use a JSON object for task input.', 2);
+        }
+        if (!object(body))
+            throw new CliError('scenario_input_invalid', 'Use a JSON object for task input.', 2);
+        editableNumbers(body);
+        definition.fixture = { ...fixture, http_task: { schema: 'firedrill.http-task.v1', body } };
+        definition.max_turns = 1;
+        definition.persona = null;
+    }
+    return { title, world_revision: current.basis.world_revision, ...(original ? { revision: original.revision } : {}), definition };
+}
+export async function scenarioAuthoring(args, options, output) {
+    const action = args[0], interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    if (!actions.includes(action) || args.length > (action === 'create' ? 1 : 2)
+        || options.file && !['create', 'edit'].includes(action) || options.approve && ['history', 'definition'].includes(action)
+        || action !== 'history' && options.page !== undefined || (options.search?.length ?? 0) > 200
+        || options.search !== undefined && (action === 'create' || Boolean(args[1])))
+        throw new CliError('arguments_invalid', 'Use scenarios create, edit, duplicate, archive, restore, definition or history. --file applies to create/edit.', 2);
+    const page = options.page ?? '1';
+    if (!/^[1-9][0-9]{0,8}$/.test(page))
+        throw new CliError('arguments_invalid', 'Choose a positive history page.', 2);
+    if (!interactive && action !== 'create' && !args[1])
+        throw new CliError('scenario_required', 'Choose a scenario ID and --world.', 2);
+    if (!interactive && ['create', 'edit'].includes(action) && !options.file)
+        throw new CliError('scenario_file_required', 'Pass --file with the reviewed canonical scenario change.', 2);
+    if (!interactive && !['definition', 'history'].includes(action) && !options.approve)
+        throw new CliError('approval_required', 'Use --approve-change to save the reviewed scenario change. No agent will run.', 2);
+    const scope = await selectedWorld({ ...options, interactive });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const id = action === 'create' ? null : args[1] ? identifier(args[1]) : await chooseScenario(scope, action, options);
+    if (action === 'history') {
+        const result = await api(`${scope.prefix}/scenarios/${id}/history?page=${page}`, auth);
+        output('scenario_history', result, (result.results.map(row => `${row.id}\n${row.name} · Revision ${row.revision}${row.current ? ' (current)' : ''} · ${row.state}`).join('\n\n') || 'No retained revisions.')
+            + `\nPage ${result.page}, ${result.count} revisions.${result.next ? ` Continue with --page ${result.page + 1}.` : ''}`);
+        return;
+    }
+    const original = id ? await api(`${scope.prefix}/scenarios/${id}?editor=1`, auth) : undefined;
+    if (original && (original.id !== id || original.world_id !== scope.world || !Number.isSafeInteger(original.revision)))
+        throw new CliError('scenario_response_invalid', 'The original scenario could not be confirmed. No change was submitted.');
+    if (action === 'definition') {
+        if (!object(original?.editor))
+            throw new CliError('scenario_definition_unavailable', 'The editable definition is not available. Source-comparison definitions remain frozen.', 2);
+        editableNumbers(original.editor);
+        const value = { title: original.name, world_revision: original.world_revision, revision: original.revision, definition: original.editor };
+        output('scenario_definition', value, JSON.stringify(value, null, 2));
+        return;
+    }
+    let body, bodyJson;
+    if (['create', 'edit'].includes(action)) {
+        // Keep file-authored number literals and nested inputs unchanged on the wire.
+        // Parsed values below are used only for the closed envelope/review checks.
+        if (options.file)
+            bodyJson = await requestInput(options.file, options.signal, 1024 * 1024);
+        const value = bodyJson !== undefined ? JSON.parse(bodyJson)
+            : await interactiveDefinition(scope, options, original);
+        if (value === null) {
+            output('scenario_unchanged', { changed: false }, 'No scenario was changed.');
+            return;
+        }
+        if (!object(value) || Object.keys(value).some(key => !['title', 'world_revision', 'revision', 'definition'].includes(key))
+            || typeof value.world_revision !== 'number' || !Number.isSafeInteger(value.world_revision) || value.world_revision < 1
+            || !object(value.definition) || typeof value.title !== 'string' || !value.title.trim()
+            || action === 'create' && value.revision !== undefined && value.revision !== null
+            || action === 'edit' && value.revision !== original?.revision)
+            throw new CliError('scenario_input_invalid', 'Use title, world_revision, definition and, for editing, the original revision. Export scenarios definition to review the current input.', 2);
+        body = value;
+    }
+    else {
+        if (!original?.current || original.definition_locked)
+            throw new CliError('scenario_revision_conflict', 'Choose the current editable scenario revision.', 2);
+        body = { action, title: action === 'duplicate' ? `${original.name.slice(0, 245)} (copy)` : original.name,
+            world_revision: original.world_revision, revision: original.revision };
+    }
+    output('scenario_review', { action, item_id: id, world_id: scope.world, world_revision: body.world_revision,
+        revision: body.revision ?? null, title: body.title }, `${action === 'create' ? 'Create' : action[0].toUpperCase() + action.slice(1)}: ${String(body.title)}\nWorld revision ${body.world_revision}${body.revision ? ` · Scenario revision ${body.revision}` : ''}\nA saved change requires world validation before a future simulation. Existing plans and results are unchanged.`);
+    if (!options.approve && !await selectOne('Save this scenario change?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Save change' }], options.signal))
+        return;
+    const key = randomUUID();
+    output('scenario_request', { request_key: key, world_id: scope.world, workspace_id: scope.workspace }, `Recovery: firedrill scenarios request ${key} --world ${scope.world} --workspace ${scope.workspace}\nInspect this original request if its reply is interrupted. Do not repeat the save.`);
+    const saved = await api(`${scope.prefix}/scenarios${id ? '/' + id : ''}`, { ...auth, method: 'POST', idempotencyKey: key,
+        ...(bodyJson === undefined ? { body } : { bodyJson }) });
+    const receipt = await api(`${scope.prefix}/scenario-request?request_key=${key}`, auth);
+    if (!saved || typeof saved.id !== 'string' || saved.world_id !== scope.world || !Number.isSafeInteger(saved.revision)
+        || receipt.schema !== 'firedrill.scenario-change-receipt.v1' || receipt.actor_id !== scope.owner || receipt.workspace_id !== scope.workspace
+        || receipt.world_id !== scope.world || receipt.request_key !== key || receipt.state !== 'accepted' || receipt.resource_available !== true
+        || receipt.item_id !== saved.id || receipt.revision !== saved.revision)
+        throw new CliError('scenario_response_invalid', 'The original save could not be confirmed. Inspect the printed recovery request. No change was repeated.');
+    output('scenario_saved', { request: receipt, scenario: saved }, `${saved.name} · Revision ${saved.revision} · ${saved.state}\n${saved.id}\nScenario saved. No agent was run.`);
+}