firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/recordings.js

@@ -0,0 +1,69 @@
+import { APP_ORIGIN } from './http.js';
+import { api, openBrowser } from './auth.js';
+import { auth, choosePaged, interactive, query } from './configuration.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+const states = { uploading: 'Upload pending', processing: 'Processing', review: 'Review before use',
+    accepted: 'Available for preparation', rejected: 'Could not process', revoked: 'Removed' };
+function describe(value) {
+    return [value.filename, value.id, `${value.format} · ${states[value.state] ?? 'Status unavailable'}`,
+        ...(value.summary.record_count !== undefined ? [`${value.summary.record_count.toLocaleString()} retained observations`] : []),
+        ...(value.summary.gaps ?? []), ...(value.failure ? [value.failure] : []), `Source: ${value.source_revision}`].map(terminalText).join('\n');
+}
+export async function recordingsCommand(args, options, output) {
+    let action = args[0] ?? (interactive(options) ? '' : 'list');
+    if (options.file || options.request || options.approve || options.status || args.length > 2)
+        throw new CliError('arguments_invalid', 'Use recordings list, show|records <id>, or open|upload. Upload and consent review open in the browser.', 2);
+    if (!action)
+        action = await selectOne('Recorded activity', [{ value: 'list', label: 'View recordings' },
+            { value: 'upload', label: 'Upload recorded activity in the browser' }, { value: 'open', label: 'Review preparation context in the browser' }], options.signal);
+    if (!['list', 'show', 'records', 'open', 'upload', 'request'].includes(action) || ['list', 'open', 'upload'].includes(action) && args[1]
+        || !['list', 'records'].includes(action) && (options.page || options.search))
+        throw new CliError('arguments_invalid', 'Use recording IDs from this world; page/search apply to list or records.', 2);
+    const context = await selectedWorld({ ...options, interactive: interactive(options) }), access = auth(context, options);
+    const url = new URL(`/worlds/${identifier(context.world)}`, APP_ORIGIN);
+    url.searchParams.set('workspace', context.workspace);
+    url.hash = 'recorded-activity';
+    if (action === 'request') {
+        if (!args[1])
+            throw new CliError('recording_request_required', 'Use the original recorded activity request UUID.', 2);
+        const key = identifier(args[1]);
+        const receipt = await api(`${context.prefix}/contexts/requests/${key}`, access);
+        if (receipt.request_key !== key || !['received', 'not_retained'].includes(receipt.state)
+            || (receipt.state === 'received') !== Boolean(receipt.recording))
+            throw new CliError('recording_request_unconfirmed', 'The original recording request could not be confirmed. No replacement was created.', 2);
+        url.searchParams.set('context_request', key);
+        output(receipt, (receipt.recording ? describe(receipt.recording) : 'No saved recording is retained yet. A delayed original request may still arrive.') + '\n' + url.href);
+        return;
+    }
+    if (action === 'open' || action === 'upload') {
+        if (action === 'upload')
+            url.searchParams.set('context', 'upload');
+        output({ browser_url: url.href, workspace_id: context.workspace, world_id: context.world }, `${url.href}\n${action === 'upload' ? 'Choose a recording and review sharing consent in the browser. Nothing was uploaded by this command.' : 'Review accepted and pending observations in this world.'}`);
+        if (interactive(options) && options.openBrowser)
+            await openBrowser(url.href);
+        return;
+    }
+    if (action === 'list') {
+        const value = await api(`${context.prefix}/contexts?${query(options)}`, access);
+        output(value, [...value.results.map(describe), ...(!value.count ? ['No matching recordings.'] : []),
+            `Page ${value.page}; ${value.count.toLocaleString()} recordings.`, ...(value.next ? [`Continue with --page ${value.page + 1} and the same search.`] : [])].join('\n\n'));
+        return;
+    }
+    const id = args[1] ?? (interactive(options) ? (await choosePaged('Recording', `${context.prefix}/contexts`, context, options, row => ({ label: row.filename, detail: states[row.state] ?? 'Status unavailable' })))?.id : undefined);
+    if (!id)
+        throw new CliError('recording_required', 'Choose a recording ID with firedrill recordings list.', 2);
+    const prefix = `${context.prefix}/contexts/${identifier(id)}`;
+    if (action === 'show') {
+        const value = await api(prefix, access);
+        output(value, describe(value) + '\n\n' + url.href);
+        return;
+    }
+    const value = await api(`${prefix}/records?${query(options)}`, access);
+    output(value, [...value.results.map(row => [terminalText(row.operation ?? row.name ?? 'Observation'), terminalText(row.kind),
+            `Source: ${terminalText(row.pointer)}`, ...(row.input !== null ? ['Recorded input: ' + terminalText(JSON.stringify(row.input))] : []),
+            ...(row.output !== null ? ['Recorded output: ' + terminalText(JSON.stringify(row.output))] : [])].join('\n')),
+        `Page ${value.page}; ${value.count.toLocaleString()} observations.`, ...(value.next ? [`Continue with --page ${value.page + 1} and the same search.`] : [])].join('\n\n'));
+}

package/dist/cli/src/registration-guide.js

@@ -0,0 +1,39 @@
+import { API_ORIGIN, CliError } from './http.js';
+/** Public discovery only. WorkOS owns registration, claim codes and token exchange. */
+export async function registrationGuide(signal, output) {
+    const url = new URL('/auth.md', API_ORIGIN);
+    const response = await fetch(url, { headers: { Accept: 'text/markdown, text/plain' }, credentials: 'omit',
+        redirect: 'error', signal: AbortSignal.any([signal, AbortSignal.timeout(15000)]) });
+    if (!response.ok || !response.body || !/^(text\/markdown|text\/plain)(;|$)/i.test(response.headers.get('content-type') ?? '')) {
+        await response.body?.cancel();
+        throw new CliError('agent_registration_unavailable', 'Agent registration instructions are not available yet. Use firedrill signup for browser authorization.', 2);
+    }
+    const reader = response.body.getReader(), chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > 256 * 1024)
+                throw new CliError('agent_registration_response_invalid', 'Registration instructions exceeded the supported size.', 2);
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    let instructions;
+    try {
+        instructions = new TextDecoder('utf8', { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new CliError('agent_registration_response_invalid', 'Registration instructions could not be read.', 2);
+    }
+    if (!instructions.trim() || /<html/i.test(instructions.slice(0, 512)))
+        throw new CliError('agent_registration_response_invalid', 'Registration instructions could not be confirmed.', 2);
+    output({ schema: 'firedrill.agent-registration-guide.v1', url: url.href, instructions,
+        default_terminal_command: 'firedrill signup', credential_storage: 'os_keyring',
+        payment_required: false, account_created: false, authorization_required: true }, instructions);
+}

package/dist/cli/src/report-exports.js

@@ -0,0 +1,213 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { link, lstat, open, realpath, unlink } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { access, api } from './auth.js';
+import { CliError, endpoint, responseError } from './http.js';
+import { selectOne } from './prompts.js';
+import { identifier } from './world-contracts.js';
+import { reportExportMatches, reportExportsPageMatches, reportExportRecoveryMatches } from '../../contracts/export-contracts.js';
+const actions = new Set(['list', 'create', 'show', 'request', 'cancel', 'download']);
+const semanticStatuses = { assessed: 'succeeded', 'not-assessable': 'not_assessable', 'not-applicable': 'not_applicable' };
+export function validateExport(args, options) {
+    const [action, value] = args;
+    if (args.length > 2 || action && !actions.has(action) || value && !['show', 'request', 'cancel', 'download'].includes(action)
+        || action && ['show', 'request', 'cancel', 'download'].includes(action) && !value
+        || (options.search !== undefined || options.scenario !== undefined || options.status !== undefined || options.checks !== undefined || options.requestKey !== undefined
+            || options.cohort !== undefined || options.scoreBucket !== undefined || options.assessmentStatus !== undefined) && action !== 'create'
+        || options.page !== undefined && action !== 'list'
+        || (options.into !== undefined || options.approveDownload !== undefined) && action !== 'download') {
+        throw new CliError('arguments_invalid', 'Use report <campaign> export list|create|show|request|cancel|download. Filters and --request-key apply to create; --page to list; --into and --approve-download to download.', 2);
+    }
+    if (value)
+        identifier(value);
+    if (options.requestKey)
+        identifier(options.requestKey);
+    if (options.cohort !== undefined)
+        identifier(options.cohort);
+    if ((options.scoreBucket !== undefined || options.assessmentStatus !== undefined) && !options.cohort) {
+        throw new CliError('arguments_invalid', 'Choose the exact score group with --cohort <assessment> before filtering its export.', 2);
+    }
+    if (options.scoreBucket !== undefined && !/^[0-8]$/.test(options.scoreBucket)
+        || options.assessmentStatus !== undefined && !Object.hasOwn(semanticStatuses, options.assessmentStatus)
+        || options.scoreBucket !== undefined && options.assessmentStatus !== undefined && options.assessmentStatus !== 'assessed') {
+        throw new CliError('arguments_invalid', 'Choose an assessed score interval or assessed, not-assessable or not-applicable status from the selected score group.', 2);
+    }
+    if (options.into !== undefined && (!options.into.trim() || /[\x00-\x1f\x7f]/.test(options.into))) {
+        throw new CliError('arguments_invalid', 'Choose a new report file using --into <file.jsonl>. Existing files are never replaced.', 2);
+    }
+}
+function readable(row) {
+    return [`Export ${row.id}: ${row.state.replaceAll('_', ' ')}`, `Original request: ${row.request_key}`,
+        ...(row.selection?.map(one => `${one.label}: ${one.value}`) ?? ['Selection details were not recorded.']),
+        ...(row.counts.trial !== undefined ? [`${row.counts.trial.toLocaleString()} drills recorded`] : []),
+        ...(row.problem ? [row.problem] : []), ...(row.file ? [`JSONL file: ${row.file.size.toLocaleString()} bytes`,
+            'Original evidence and media are referenced, not copied. Downloads still require workspace access and retained evidence.'] : [])].join('\n');
+}
+async function saveReport(path, row, scope, interactive, options) {
+    const metadata = row.file;
+    if (!metadata || !Number.isSafeInteger(metadata.size) || metadata.size < 1 || !/^[a-f0-9]{64}$/.test(metadata.sha256)) {
+        throw new CliError('report_export_unavailable', 'The exact saved report is not available. Inspect its status first.');
+    }
+    if (!options.into)
+        throw new CliError('arguments_invalid', 'Choose a new private report file with --into <file.jsonl>. Existing files are never replaced.', 2);
+    if (!options.approveDownload) {
+        if (!interactive)
+            throw new CliError('report_export_consent_required', 'Use --approve-download to save the selected private report on this device.', 2);
+        if (!await selectOne('Save this private report on this device?', [{ value: false, label: 'Cancel' },
+            { value: true, label: 'Download report', detail: 'Contains selected results and assessments. Original media stays in the cloud.' }], options.signal)) {
+            throw new CliError('canceled', 'No report was downloaded.', 130);
+        }
+    }
+    const chosen = resolve(options.into), parent = await realpath(dirname(chosen)), destination = join(parent, basename(chosen));
+    try {
+        await lstat(destination);
+        throw new CliError('report_file_exists', 'The chosen file already exists. Choose a different path.', 2);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    const partial = join(parent, `.firedrill-report-${randomUUID()}.partial`);
+    const file = await open(partial, 'wx', 0o600), identity = await file.stat();
+    try {
+        return await access(async (token) => {
+            const response = await fetch(endpoint(path), { redirect: 'error', credentials: 'omit',
+                headers: { Authorization: `Bearer ${token}`, 'X-Firedrill-Actor': scope.owner, 'X-Firedrill-Workspace': scope.workspace },
+                signal: AbortSignal.any([options.signal, AbortSignal.timeout(2 * 60 * 60 * 1000)]) });
+            if (response.status !== 200) {
+                await response.body?.cancel();
+                throw responseError(null, response.status);
+            }
+            if (response.headers.get('content-length') !== String(metadata.size) || response.headers.get('x-content-sha256') !== metadata.sha256
+                || response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/x-ndjson' || !response.body) {
+                await response.body?.cancel();
+                throw new CliError('report_export_integrity', 'The response did not match the saved report. No completed file was saved.');
+            }
+            const reader = response.body.getReader(), digest = createHash('sha256');
+            let size = 0;
+            try {
+                while (true) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    size += part.value.byteLength;
+                    if (size > metadata.size)
+                        throw new CliError('report_export_integrity', 'The report exceeded its recorded size. No completed file was saved.');
+                    digest.update(part.value);
+                    let offset = 0;
+                    while (offset < part.value.byteLength) {
+                        const result = await file.write(part.value, offset, part.value.byteLength - offset);
+                        if (!result.bytesWritten)
+                            throw new CliError('report_file_unavailable', 'The private report file could not be written.');
+                        offset += result.bytesWritten;
+                    }
+                }
+            }
+            finally {
+                await reader.cancel().catch(() => undefined);
+                reader.releaseLock();
+            }
+            if (size !== metadata.size || digest.digest('hex') !== metadata.sha256) {
+                throw new CliError('report_export_integrity', 'The report was incomplete or changed. No completed file was saved.');
+            }
+            await file.sync();
+            const current = await lstat(partial);
+            if (!current.isFile() || current.dev !== identity.dev || current.ino !== identity.ino)
+                throw new CliError('report_file_changed', 'The private file changed during download. Nothing was published to the chosen path.');
+            // A hard link publishes only complete bytes and refuses an existing path.
+            await link(partial, destination);
+            return { path: destination, size, sha256: metadata.sha256 };
+        });
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError('report_download_unconfirmed', 'The report download could not finish. Inspect the chosen file path before trying again; no existing file was replaced.');
+    }
+    finally {
+        await file.close().catch(() => undefined);
+        const current = await lstat(partial).catch(() => null);
+        if (current?.isFile() && current.dev === identity.dev && current.ino === identity.ino)
+            await unlink(partial).catch(() => undefined);
+    }
+}
+export async function reportExport(args, prefix, scope, interactive, options, output) {
+    validateExport(args, options);
+    const path = `${prefix}/report-exports`, auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const campaign = identifier(prefix.split('/').at(-1));
+    const selectedScope = { workspace: scope.workspace, campaign };
+    const unavailable = () => new CliError('report_export_response_invalid', 'The exact saved export could not be confirmed. Inspect the original request; no replacement export was requested.');
+    const action = args[0] ?? (interactive ? await selectOne('Report export', [{ value: 'list', label: 'Saved exports' },
+        { value: 'create', label: 'Create a JSONL report', detail: 'Selected results and assessments with original evidence references.' }], options.signal) : 'list');
+    let selected = args[1] ? identifier(args[1]) : undefined;
+    if (action === 'create') {
+        if (!interactive && !options.requestKey)
+            throw new CliError('request_key_required', 'Pass --request-key <uuid> and reuse it after an uncertain response. Do not create a new key to retry.', 2);
+        const request = options.requestKey ? identifier(options.requestKey) : randomUUID();
+        process.stderr.write(`Original export request: ${request}\nRecovery: firedrill report ${prefix.split('/').at(-1)} export request ${request} --workspace ${scope.workspace}\n`);
+        const filters = { q: options.search ?? '', status: options.status ?? '', checks: options.checks ?? '', scenario: options.scenario ?? '',
+            ...(options.cohort ? { cohort: identifier(options.cohort), score_bucket: options.scoreBucket ?? '',
+                assessment_status: options.assessmentStatus ? semanticStatuses[options.assessmentStatus] : '' } : {}) };
+        const row = await api(path, { ...auth, method: 'POST', idempotencyKey: request, body: { filters } });
+        if (!reportExportMatches(row, { ...selectedScope, actor: scope.owner }, { key: request, filters }))
+            throw unavailable();
+        const original = await api(`${path}?request_key=${request}`, auth);
+        if (!reportExportRecoveryMatches(original, { ...selectedScope, actor: scope.owner }, request)
+            || !reportExportMatches(original, selectedScope, { id: row.id, key: request, filters }))
+            throw unavailable();
+        output(original, readable(original));
+        return;
+    }
+    if (action === 'request') {
+        const row = await api(`${path}?request_key=${selected}`, auth);
+        if (!reportExportRecoveryMatches(row, { ...selectedScope, actor: scope.owner }, selected))
+            throw unavailable();
+        output(row, readable(row));
+        return;
+    }
+    if (action === 'list') {
+        let page = options.page ?? '1';
+        while (true) {
+            const data = await api(`${path}?page=${page}`, auth);
+            if (!reportExportsPageMatches(data, selectedScope))
+                throw unavailable();
+            if (!interactive) {
+                output(data, [...data.results.map(readable), `Page ${data.page} of ${Math.max(1, Math.ceil(data.count / data.page_size))}`,
+                    ...(data.next ? [`Continue: firedrill report ${campaign} export list --workspace ${scope.workspace} --page ${data.page + 1}${options.json ? ' --json' : ''}`] : [])].join('\n\n'));
+                return;
+            }
+            const choices = data.results.map(value => ({ value: value.id, label: new Date(value.created_at).toLocaleString(),
+                detail: [value.state.replaceAll('_', ' '), ...(value.selection?.map(one => `${one.label}: ${one.value}`) ?? [])].join('; ') }));
+            if (Number(page) > 1)
+                choices.unshift({ value: 'previous', label: 'Previous page', detail: '' });
+            if (data.next)
+                choices.push({ value: 'next', label: 'Next page', detail: '' });
+            if (!choices.length) {
+                output(data, 'No saved exports.');
+                return;
+            }
+            const choice = await selectOne('Saved report', choices, options.signal);
+            if (choice === 'previous' || choice === 'next') {
+                page = String(Number(page) + (choice === 'next' ? 1 : -1));
+                continue;
+            }
+            selected = identifier(choice);
+            break;
+        }
+    }
+    const row = await api(`${path}/${selected}`, auth);
+    if (!reportExportMatches(row, selectedScope, { id: selected }))
+        throw unavailable();
+    if (action === 'download') {
+        const saved = await saveReport(`${path}/${selected}/download`, row, scope, interactive, options);
+        output({ export_id: row.id, ...saved }, `Report saved to ${saved.path}\n${saved.size.toLocaleString()} bytes; SHA-256 ${saved.sha256}`);
+    }
+    else if (action === 'cancel') {
+        const changed = await api(`${path}/${selected}`, { ...auth, method: 'POST', body: { action: 'cancel' } });
+        if (!reportExportMatches(changed, { ...selectedScope, actor: scope.owner }, { id: row.id, key: row.request_key, filters: row.filters }))
+            throw unavailable();
+        output(changed, readable(changed));
+    }
+    else
+        output(row, readable(row));
+}

package/dist/cli/src/request-input.js

@@ -0,0 +1,47 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { CliError } from './http.js';
+/** Read one bounded, unchanged JSON object without rewriting number literals. */
+export async function requestInput(path, signal, maximumBytes = 8 * 1024 * 1024) {
+    if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 2 || maximumBytes > 8 * 1024 * 1024) {
+        throw new CliError('request_capacity_invalid', 'Choose a supported request capacity.', 2);
+    }
+    if (!path)
+        return '{}';
+    const before = await lstat(resolve(path));
+    if (!before.isFile() || before.isSymbolicLink() || before.size > maximumBytes) {
+        throw new CliError('request_file_invalid', 'Choose a regular JSON file within transport capacity.', 2);
+    }
+    const file = await open(resolve(path), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const held = await file.stat();
+        if (held.dev !== before.dev || held.ino !== before.ino || held.size !== before.size || held.mtimeMs !== before.mtimeMs)
+            throw new Error();
+        const chunks = [];
+        let size = 0;
+        for await (const chunk of file.createReadStream({ autoClose: false })) {
+            signal.throwIfAborted();
+            size += chunk.length;
+            if (size > maximumBytes)
+                throw new Error();
+            chunks.push(Buffer.from(chunk));
+        }
+        const after = await file.stat();
+        if (after.size !== held.size || after.mtimeMs !== held.mtimeMs || after.ctimeMs !== held.ctimeMs)
+            throw new Error();
+        const raw = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+        const value = JSON.parse(raw);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error();
+        return raw;
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        throw new CliError('request_file_invalid', 'The file changed or is not a JSON object. Nothing was submitted.', 2);
+    }
+    finally {
+        await file.close();
+    }
+}

package/dist/cli/src/resource-lifecycle.js

@@ -0,0 +1,141 @@
+import { randomUUID } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { api } from './auth.js';
+import { auth, choosePaged, interactive, line } from './configuration.js';
+import { readMetadata, record } from './configuration-intents.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { selectedWorkspace } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { resourceLifecycleBodyMatches, resourceLifecycleMetadataMatches, resourceLifecycleReceiptMatches, resourceLifecycleReceiptSame, resourceLifecyclePageMatches } from '../../contracts/resource-lifecycle-contracts.js';
+const invalid = () => new CliError('resource_change_unconfirmed', 'Inspect the original resource change before starting another. No success is implied.', 2);
+const canonical = (value) => JSON.stringify([value.kind, value.id, value.action, value.basis, value.confirm_name, value.retain_saved_data]);
+function bodyData(value, kind) {
+    if (!resourceLifecycleBodyMatches(value) || value.kind !== kind)
+        throw invalid();
+    return value;
+}
+function checked(value, scope, key, kind, body) {
+    if (!resourceLifecycleReceiptMatches(value, { actor: scope.owner, workspace: scope.workspace }, { key, kind, body }))
+        throw invalid();
+    return value;
+}
+function show(value, output) {
+    output(value, `${value.request_key}\n${value.state === 'accepted' ? `${value.body.confirm_name} · ${value.body.action} saved`
+        : value.state === 'withdrawn' ? 'Unsent request discarded.' : 'The original request is not confirmed. It may still arrive.'}`.split('\n').map(terminalText).join('\n'));
+}
+const location = async (scope, key) => join(await privateDirectory(), `resource-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}.json`);
+async function retained(scope, key, kind) {
+    const value = await readMetadata(await location(scope, key), true);
+    if (value.schema !== 'firedrill.resource-intent.v1' || value.actor !== scope.owner || value.workspace !== scope.workspace
+        || value.key !== key || Object.keys(value).sort().join(',') !== 'actor,body,key,schema,workspace')
+        throw invalid();
+    bodyData(value.body, kind);
+    return value;
+}
+async function save(value, scope, kind) {
+    try {
+        const file = await open(await location(scope, value.key), 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (!record(error) || error.code !== 'EEXIST')
+            throw error;
+        if (canonical((await retained(scope, value.key, kind)).body) !== canonical(value.body))
+            throw invalid();
+    }
+}
+async function approve(options, label) {
+    if (options.approve)
+        return;
+    if (!interactive(options))
+        throw new CliError('approval_required', 'Review the resource and pass --approve-change. No change was submitted.', 2);
+    if (!await selectOne(label, [{ value: false, label: 'Cancel' }, { value: true, label: 'Confirm' }], options.signal))
+        throw new CliError('canceled', 'No change was submitted.', 130);
+}
+async function submit(intent, scope, options, output) {
+    const base = `/api/workspaces/${scope.workspace}`, body = intent.body;
+    const original = checked(await api(`${base}/resource-requests/${intent.key}`, auth(scope, options)), scope, intent.key, body.kind, body);
+    if (original.state !== 'not_received') {
+        show(original, output);
+        return;
+    }
+    output({ phase: 'request_prepared', request_key: intent.key }, `Request ${intent.key}\nRecovery: firedrill ${body.kind} request ${intent.key} --workspace ${scope.workspace}`);
+    const { kind, id, ...fields } = body;
+    const data = fields;
+    const accepted = checked(await api(`${base}/resources/${kind}/${id}/lifecycle`, { ...auth(scope, options), method: 'POST',
+        idempotencyKey: intent.key, body: data }), scope, intent.key, kind, body);
+    const observed = checked(await api(`${base}/resource-requests/${intent.key}`, auth(scope, options)), scope, intent.key, kind, body);
+    if (!resourceLifecycleReceiptSame(accepted, observed))
+        throw invalid();
+    show(observed, output);
+}
+export async function resourceLifecycle(kind, args, options, output) {
+    const action = args[0];
+    if (args.length > 2 || !['archive', 'restore', 'remove', 'requests', 'request', 'resume', 'withdraw'].includes(action)
+        || (options.page !== undefined || options.search !== undefined || options.status !== undefined) && action !== 'requests'
+        || options.request !== undefined && !['archive', 'restore', 'remove'].includes(action)
+        || options.approve && ['requests', 'request'].includes(action) || action === 'requests' && args[1])
+        throw invalid();
+    const scope = await selectedWorkspace({ ...options, interactive: interactive(options) });
+    const base = `/api/workspaces/${scope.workspace}`, access = auth(scope, options);
+    if (action === 'requests') {
+        const page = options.page ?? '1';
+        const search = options.search ?? '', state = options.status ?? '';
+        if (!/^[1-9][0-9]{0,8}$/.test(page) || search.length > 120 || /[\u0000-\u001f\u007f]/.test(search) || !['', 'accepted', 'withdrawn'].includes(state))
+            throw invalid();
+        const value = await api(`${base}/resource-requests?${new URLSearchParams({ kind, page, q: search, state })}`, access);
+        if (!resourceLifecyclePageMatches(value, { actor: scope.owner, workspace: scope.workspace }, { kind, query: search, state, page: Number(page) }))
+            throw invalid();
+        output(value, [...value.results.map(row => `${row.request_key}\n${row.body?.confirm_name ?? 'Unsent request'} · ${row.body?.action ?? ''} · ${row.state}`),
+            `Page ${value.page}; ${value.count} requests.`, ...(value.next ? [`Continue with --page ${value.page + 1} and the same workspace/search/status filters.`] : [])].map(terminalText).join('\n\n'));
+        return;
+    }
+    if (['request', 'resume', 'withdraw'].includes(action)) {
+        const key = identifier(args[1] ?? ''), path = `${base}/resource-requests/${key}`;
+        const original = checked(await api(path, access), scope, key, kind);
+        if (action === 'request' || original.state !== 'not_received') {
+            show(original, output);
+            return;
+        }
+        await approve(options, action === 'withdraw' ? 'Discard the unsent original change? A change already saved will not be undone.' : 'Continue this exact original change?');
+        if (action === 'withdraw') {
+            const accepted = checked(await api(path, { ...access, method: 'DELETE', body: {} }), scope, key, kind);
+            const observed = checked(await api(path, access), scope, key, kind);
+            if (!resourceLifecycleReceiptSame(accepted, observed))
+                throw invalid();
+            show(observed, output);
+        }
+        else
+            await submit(await retained(scope, key, kind), scope, options, output);
+        return;
+    }
+    let id = args[1] ? identifier(args[1]) : undefined;
+    if (!id && interactive(options))
+        id = (await choosePaged(kind === 'agents' ? 'Agent' : 'World', `${base}/${kind}?lifecycle=all`, scope, options, row => ({ label: row.name, detail: row.archived_at ? 'Archived' : '' })))?.id;
+    if (!id)
+        throw new CliError('resource_required', `Pass an exact ${kind === 'agents' ? 'agent' : 'world'} ID or run interactively.`, 2);
+    const current = await api(`${base}/resources/${kind}/${id}/lifecycle`, access);
+    if (!resourceLifecycleMetadataMatches(current, { actor: scope.owner, workspace: scope.workspace, id, kind })
+        || current.removed || !current.can_write
+        || action === 'remove' && !current.can_remove)
+        throw invalid();
+    if (action === 'remove' && interactive(options) && await line('Type the exact record name to remove it', 120, options.signal) !== current.name)
+        throw new CliError('canceled', 'The name did not match. Nothing was submitted.', 130);
+    await approve(options, `${action} ${terminalText(current.name)}? ${action === 'remove'
+        ? 'Active work must finish first. Saved evidence follows its retention policy; no real-account effects are erased.'
+        : action === 'archive' ? 'This moves the record to Archived history and does not stop active work.' : 'No work will restart.'}`);
+    const intent = { schema: 'firedrill.resource-intent.v1', actor: scope.owner, workspace: scope.workspace,
+        key: options.request !== undefined ? identifier(options.request) : randomUUID(), body: { kind, id, action: action,
+            basis: current.revision, confirm_name: current.name, retain_saved_data: true } };
+    await save(intent, scope, kind);
+    await submit(intent, scope, options, output);
+}

package/dist/cli/src/revision-requests.js

@@ -0,0 +1,55 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+const text = (value, label) => `${value.request_key}\n${value.state === 'accepted'
+    ? value.resource_available ? `${value.name} · Revision ${value.revision}\n${value.item_id}` : `Saved change; ${label} no longer available.`
+    : value.state === 'withdrawn' ? 'Canceled unsaved request. No revision will be created by it.' : 'Not received yet. This is not proof that the original request cannot arrive.'}`;
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+export async function revisionRequests(kind, args, options, output) {
+    const label = kind === 'scenario' ? 'scenario' : 'criterion', command = kind === 'scenario' ? 'scenarios' : 'criteria';
+    const invalid = () => new CliError(`${kind}_request_invalid`, `The original ${label} request could not be confirmed. No change was repeated.`);
+    const action = args[0];
+    if (!['requests', 'request', 'withdraw-request'].includes(action) || args.length !== (action === 'requests' ? 1 : 2)
+        || action !== 'requests' && (options.page !== undefined || options.search !== undefined || options.status !== undefined)
+        || action !== 'withdraw-request' && options.approve)
+        throw new CliError('arguments_invalid', `Use ${command} requests, request <key> or withdraw-request <key> with world/workspace scope.`, 2);
+    const key = args[1] ?? '';
+    if (action !== 'requests' && !/^[A-Za-z0-9][A-Za-z0-9:._-]{0,127}$/.test(key))
+        throw invalid();
+    const page = options.page ?? '1', query = options.search ?? '', status = options.status ?? '';
+    if (!/^[1-9][0-9]{0,8}$/.test(page) || query.length > 200 || !['', 'accepted', 'withdrawn'].includes(status))
+        throw new CliError('arguments_invalid', 'Use a positive page, a search of up to 200 characters and accepted or withdrawn status.', 2);
+    const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    if (action === 'withdraw-request' && !options.approve) {
+        if (!interactive)
+            throw new CliError('approval_required', 'Use --approve-change to cancel this exact unsaved request. An accepted change is only inspected.', 2);
+        if (!await selectOne('Cancel this unsaved request? A change already saved will not be undone.', [
+            { value: false, label: 'Keep request' }, { value: true, label: 'Cancel unsaved request' }
+        ], options.signal))
+            return;
+    }
+    const scope = await selectedWorld({ ...options, interactive });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const checked = (value) => {
+        if (!value || value.schema !== `firedrill.${kind}-change-receipt.v1` || value.actor_id !== scope.owner
+            || value.workspace_id !== scope.workspace || value.world_id !== scope.world || key && value.request_key !== key
+            || !['not_received', 'accepted', 'withdrawn'].includes(value.state) || typeof value.resource_available !== 'boolean'
+            || value.resource_available && (value.state !== 'accepted' || typeof value.item_id !== 'string'
+                || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(value.item_id))
+            || !value.resource_available && value.item_id !== null)
+            throw invalid();
+        return value;
+    };
+    if (action === 'requests') {
+        const queryParams = new URLSearchParams({ page, q: query, status });
+        const result = await api(`${scope.prefix}/${kind}-requests?${queryParams}`, auth);
+        const next = `firedrill ${command} requests --world ${scope.world} --workspace ${scope.workspace} --page ${result.page + 1}${query ? ' --search ' + quote(query) : ''}${status ? ' --status ' + status : ''}${options.json ? ' --json' : ''}`;
+        output(result, (result.results.map(value => text(checked(value), label).split('\n').map(terminalText).join('\n')).join('\n\n') || `No matching ${label} changes.`)
+            + `\nPage ${result.page}, ${result.count} changes.${result.next ? '\nContinue: ' + next : ''}`);
+        return;
+    }
+    const body = { request_key: key };
+    const value = checked(await api(`${scope.prefix}/${kind}-request${action === 'request' ? '?request_key=' + encodeURIComponent(key) : ''}`, action === 'request' ? auth : { ...auth, method: 'POST', body }));
+    output(value, text(value, label).split('\n').map(terminalText).join('\n'));
+}

package/dist/cli/src/runner-abandon.js

@@ -0,0 +1,53 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { withUnstartedLocalClaim } from './runner-ownership.js';
+import { hasLocalContainerJournal } from './runner-container.js';
+import { savedLocalPermission } from './runner-grants.js';
+import { syncClosingReceipt } from './runner-completion.js';
+import { discardPrivateDataInputs } from './runner-inputs.js';
+import { localClosingReceiptMatches } from '../../contracts/local-evidence-contracts.js';
+/** Close only a retained pre-launch claim. No Docker/provider absence probe,
+ * replacement grant, target invocation or lease-expiry inference is involved. */
+export async function abandonLocalAssignment(context, device, job, signal) {
+    return withUnstartedLocalClaim(context, device, job, signal, async (journal, claim, fence, active) => {
+        const lease = journal.lease, attempt = journal.attempt;
+        if (await hasLocalContainerJournal(context, lease))
+            throw new CliError('local_resource_recovery_required', `A resource journal exists for ${lease}. Use runner cleanup and evidence sync instead of abandoning it as unstarted.`);
+        let image = journal.runtimeImage;
+        if (!image) {
+            const permission = await savedLocalPermission(context, journal.grantRequest, active);
+            if (permission.state === 'not_retained' || !permission.id || permission.id !== journal.grant || !permission.runtime?.image
+                || permission.device_key !== device || !permission.operations?.includes(claim.purpose)) {
+                throw new CliError('local_owner_identity_changed', 'The original runtime approval could not be reconciled. Nothing was closed.');
+            }
+            image = permission.runtime.image;
+        }
+        // Persist before any closing dispatch. Subsequent runner execute refuses
+        // this job even if receipt delivery is interrupted or returns uncertain.
+        await fence();
+        await discardPrivateDataInputs({ ...context, job, lease });
+        const path = `/api/workspaces/${context.workspace}/local-runners/${device}/jobs/${job}/claims/${journal.request}/completion`;
+        const receipt = await api(path, { actor: context.owner, workspace: context.workspace, signal: active });
+        const selected = { ...context, device, job, request: journal.request, lease, attempt, manifestSha256: receipt.manifest_sha256 };
+        if (!localClosingReceiptMatches(receipt, selected)
+            || receipt.manifest_sha256 !== null && !/^[a-f0-9]{64}$/.test(receipt.manifest_sha256)) {
+            throw new CliError('local_completion_unconfirmed', 'The original pre-launch closing receipt could not be reconciled. Keep its journal.');
+        }
+        const document = {
+            schema: claim.purpose === 'trial' ? 'firedrill.local-trial-container-receipt.v1'
+                : claim.purpose === 'world_session' ? 'firedrill.local-world-container-receipt.v1' : 'firedrill.local-container-receipt.v1',
+            operation_id: lease, container_id: null, name: 'fd-job-' + lease, image,
+            resource_state: 'not_dispatched', removed: false, launch: null, status: null, exit_code: null,
+        };
+        if (claim.purpose === 'trial')
+            document.evidence = null;
+        if (claim.purpose === 'world_session') {
+            if (!claim.world_session)
+                throw new CliError('local_owner_identity_changed', 'The original world-session identity is missing.');
+            document.world_session = claim.world_session;
+            document.session_released = false;
+            document.evidence = { schema: 'firedrill.local-world-closing-evidence.v1', native_status: null };
+        }
+        return syncClosingReceipt(context, { ...selected, document }, active, { wait: true });
+    });
+}