firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/campaign-world.js

@@ -0,0 +1,156 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { randomUUID } from 'node:crypto';
+import { selectOne, terminalText } from './prompts.js';
+import { requestInput } from './request-input.js';
+import { identifier } from './world-contracts.js';
+import { drillWorldPageMatches, runtimeRenewalPageMatches, worldControlInputMatches, worldControlMatches } from '../../contracts/campaign-world-contracts.js';
+const eventKinds = { record: 'State change', operation: 'Service operation', ingress: 'Incoming event', message: 'Conversation' };
+function elapsedTime(value) {
+    const milliseconds = BigInt(value), seconds = milliseconds / 1000n;
+    if (milliseconds < 1000n)
+        return `${milliseconds}ms`;
+    const days = seconds / 86400n;
+    return `${days ? `${days}d ` : ''}${seconds / 3600n % 24n}h ${seconds / 60n % 60n}m ${seconds % 60n}s`;
+}
+function eventOutcome(event) {
+    const value = event.result?.observation;
+    if (!value)
+        return event.state.replaceAll('_', ' ');
+    if (event.kind === 'operation')
+        return typeof value.http_status === 'number' ? `HTTP ${value.http_status}`
+            : value.mcp_is_error === true ? 'Tool returned an error'
+                : value.schema_status === 'mismatch' || value.schema_status === 'missing_structured' ? 'Response schema differs' : 'Tool response recorded';
+    if (event.kind === 'ingress')
+        return value.completion === 'failed' ? 'Task failed' : value.completion === 'rejected' ? 'Task rejected' : 'Task completed';
+    return 'Conversation turn recorded';
+}
+export async function campaignWorldReport(prefix, scope, options, output) {
+    if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page)
+        || (options.search?.length ?? 0) > 200 || options.status !== undefined
+        && !['pending', 'applying', 'applied', 'unmet', 'uncertain', 'canceled'].includes(options.status))
+        throw new CliError('arguments_invalid', 'Use world-events with --page, --search and an event --status.', 2);
+    const value = await api(`${prefix}/world-events?page=${options.page ?? '1'}&q=${encodeURIComponent(options.search ?? '')}&state=${options.status ?? ''}`, { actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+    if (!drillWorldPageMatches(value) || value.results.some(one => one.result?.download_path
+        && one.result.download_path !== `${prefix}/evidence/${one.result.evidence_id}/bytes`))
+        throw new CliError('world_events_unavailable', 'The original world history could not be confirmed.');
+    const c = value.continuity;
+    const parts = prefix.split('/'), campaign = parts.at(-3), execution = parts.at(-1);
+    output(value, [c.mode ? `Continuous world: ${c.state}` : 'No continuous world schedule selected.',
+        ...(c.started_at ? [`World started: ${c.started_at}`] : []),
+        ...(c.interaction ? [`Last input activity: ${c.interaction.state === 'waiting_for_input' ? 'Waiting for next input' : c.interaction.state === 'active' ? 'Handling input' : 'Input channel closed'} at ${c.interaction.observed_at}`] : []),
+        ...(c.elapsed_ms !== null ? [`Actual elapsed: ${elapsedTime(c.elapsed_ms)}`] : []),
+        ...(c.event_state !== 'active' ? [`Future events: ${c.event_state === 'paused' ? 'Paused' : 'Canceled'}${c.state === 'running' ? '; original execution remains active' : ''}`] : []),
+        ...(c.resource_deadline_at ? [`Execution deadline: ${c.resource_deadline_at}`] : []),
+        ...(c.next_event ? [`Next event: ${c.next_event.key}${c.next_event.due_at ? ` at ${c.next_event.due_at}` : ''}`] : []),
+        ...value.results.map(one => `${terminalText(one.key)}  ${eventKinds[one.kind]}  ${eventOutcome(one)}  ${one.due_at ?? `after ${one.due_after_ms}ms`}`
+            + (one.result?.download_path ? `\nEvidence: firedrill report ${campaign} drill ${execution} evidence ${one.result.evidence_id}` : '')),
+        `Page ${value.page}; ${value.count} events.`, ...(value.next ? ['More events are available with --page.'] : [])].join('\n'));
+}
+export async function campaignRuntimeReport(prefix, scope, options, output) {
+    if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page))
+        throw new CliError('arguments_invalid', 'Choose a valid runtime-history page.', 2);
+    const value = await api(`${prefix}/runtime-renewals?page=${options.page ?? '1'}`, { actor: scope.owner, signal: options.signal });
+    if (!runtimeRenewalPageMatches(value))
+        throw new CliError('runtime_history_unavailable', 'The original runtime history could not be confirmed.');
+    output(value, value.count ? [...value.results.map(one => `${one.sequence}  ${one.state}  ${one.confirmed_expires_at ?? one.requested_expires_at}`),
+        `Page ${value.page}; ${value.count} renewals.`].join('\n') : 'No allocation renewals recorded.');
+}
+const actions = { pause: 'pause', resume: 'resume', 'cancel-future': 'cancel_future', 'revise-future': 'revise_future' };
+const actionLabels = { pause: 'Pause future events', resume: 'Resume future events', cancel_future: 'Cancel future events', revise_future: 'Replace future events' };
+const stateLabels = { queued: 'Requested', publishing: 'Sending', unknown: 'Awaiting confirmation', observed: 'Applied', rejected: 'Not applied', ended: 'Not applied' };
+const commandName = (value) => `${actionLabels[value.action]}: ${stateLabels[value.state]}\nOriginal request: ${value.request_key}${value.problem ? '\n' + terminalText(value.problem) : ''}`;
+export async function campaignWorldCommand(args, prefix, scope, options, output) {
+    const action = args[0] ?? 'list', interactive = !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    const parts = prefix.split('/');
+    const campaign = parts[parts.length - 3], execution = parts[parts.length - 1];
+    identifier(campaign);
+    identifier(execution);
+    const selectedScope = { workspace: scope.workspace, campaign, execution };
+    if (args.length > (action === 'request' ? 2 : 1) || action === 'request' && !args[1]
+        || !['list', 'controls', 'request', 'runtime', ...Object.keys(actions)].includes(action)
+        || options.page !== undefined && !['list', 'controls', 'runtime'].includes(action)
+        || options.search !== undefined && action !== 'list' || options.status !== undefined && action !== 'list'
+        || options.file !== undefined && !actions[action] || options.change && !actions[action]
+        || options.requestKey !== undefined && !actions[action])
+        throw new CliError('arguments_invalid', 'Use world-events [list|controls|runtime|request <original-key>|pause|resume|cancel-future|revise-future]. Mutations support --file, --request-key and --approve-change.', 2);
+    if (action === 'list')
+        return campaignWorldReport(prefix, scope, options, output);
+    if (action === 'runtime')
+        return campaignRuntimeReport(prefix, scope, options, output);
+    if (action === 'request') {
+        const key = identifier(args[1]);
+        const value = await api(`${prefix}/world-controls/requests/${key}`, { actor: scope.owner, signal: options.signal });
+        if (value.state === 'not_received') {
+            if (value.request_key !== key || Object.keys(value).sort().join(',') !== 'request_key,state')
+                throw new CliError('world_control_unavailable', 'The original request could not be confirmed.');
+            return output(value, 'The original request has not been received. Retry only its exact original body and key.');
+        }
+        if (!worldControlMatches(value, { ...selectedScope, actor: scope.owner }, { key }))
+            throw new CliError('world_control_unavailable', 'The original world control could not be confirmed.');
+        return output(value, commandName(value));
+    }
+    if (action === 'controls') {
+        if (options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page))
+            throw new CliError('arguments_invalid', 'Choose a valid history page.', 2);
+        const value = await api(`${prefix}/world-controls?page=${options.page ?? '1'}`, { actor: scope.owner, signal: options.signal });
+        if (!Number.isSafeInteger(value.count) || value.count < 0 || !Array.isArray(value.results) || value.results.length > 100
+            || !value.results.every(row => worldControlMatches(row, selectedScope)))
+            throw new CliError('world_control_unavailable', 'World control history could not be confirmed.');
+        return output(value, [...value.results.map(commandName), `Page ${value.page}; ${value.count} controls.`].join('\n'));
+    }
+    let body;
+    if (options.file) {
+        const value = JSON.parse(await requestInput(options.file, options.signal, 4096));
+        if (!worldControlInputMatches(value) || value.action !== actions[action])
+            throw new CliError('world_control_input_invalid', 'Provide this exact action, previous revision, expected watermark and optional next scenario revision.', 2);
+        body = value;
+    }
+    else {
+        if (!interactive)
+            throw new CliError('interaction_required', 'Automation needs the exact reviewed --file body, --request-key and --approve-change.', 2);
+        const current = await api(`${prefix}/world-events?page=1`, { actor: scope.owner, signal: options.signal });
+        if (!drillWorldPageMatches(current) || current.continuity.state !== 'running' || !current.continuity.revision)
+            throw new CliError('world_control_not_ready', 'This drill has no current continuous world.');
+        let candidate = null;
+        if (action === 'revise-future') {
+            let page = 1;
+            while (candidate === null) {
+                const rows = await api(`${prefix}/world-controls/candidates?page=${page}`, { actor: scope.owner, signal: options.signal });
+                if (!Number.isSafeInteger(rows.count) || !Array.isArray(rows.results) || rows.results.length > 100 || !rows.results.every(row => typeof row.id === 'string' && typeof row.name === 'string' && Number.isSafeInteger(row.revision) && row.revision > 0))
+                    throw new CliError('world_revisions_unavailable', 'Available revisions could not be confirmed.');
+                if (!rows.count)
+                    throw new CliError('world_revisions_unavailable', 'Save a reviewed scenario revision with new future events first.');
+                const choices = rows.results.map(row => ({ value: { id: identifier(row.id) },
+                    label: row.name, detail: `Revision ${row.revision}; ${row.event_count} events` }));
+                if (page > 1)
+                    choices.unshift({ value: { page: page - 1 }, label: 'Previous page', detail: '' });
+                if (rows.next)
+                    choices.push({ value: { page: page + 1 }, label: 'Next page', detail: '' });
+                const selected = await selectOne('Choose the reviewed future timeline', choices, options.signal);
+                if ('id' in selected)
+                    candidate = selected.id;
+                else
+                    page = selected.page;
+            }
+        }
+        body = { action: actions[action], previous_revision: current.continuity.revision, expected_watermark: current.continuity.applied_watermark,
+            expected_sequence: current.continuity.control_sequence, next_scenario_id: candidate };
+    }
+    const approved = options.change || interactive && await selectOne('Change future events only. The agent keeps running.', [
+        { value: false, label: 'Cancel', detail: 'Leave the current timeline unchanged.' },
+        { value: true, label: action === 'revise-future' ? 'Replace future events' : `${action} events`, detail: 'Applied history and original runtime permission stay unchanged.' },
+    ], options.signal);
+    if (!approved)
+        throw new CliError('approval_required', 'Nothing was changed. Automation requires --approve-change.', 2);
+    if (!interactive && !options.requestKey)
+        throw new CliError('request_key_required', 'Keep a fixed --request-key for original-request recovery.', 2);
+    const key = options.requestKey ? identifier(options.requestKey) : randomUUID();
+    if (interactive)
+        process.stderr.write(`Original request: ${terminalText(key)}\nRecover with report ${campaign} drill ${execution} world-events request ${key}\n`);
+    const value = await api(`${prefix}/world-controls`, { actor: scope.owner, signal: options.signal, method: 'POST',
+        workspace: scope.workspace, idempotencyKey: key, body });
+    if (!worldControlMatches(value, { ...selectedScope, actor: scope.owner }, { key, body }))
+        throw new CliError('world_control_unavailable', `Inspect original request ${key} before another action.`);
+    output(value, commandName(value));
+}

package/dist/cli/src/candidate-copy.js

@@ -0,0 +1,376 @@
+import { workspaceLink } from './browser-links.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, opendir, realpath, rename, rmdir, unlink } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { trustedPython } from './local-source.js';
+import { selectOne } from './prompts.js';
+import { bindSavedProject } from './source-connection.js';
+import { processLifetimeLock } from './runner-process-lock.js';
+import { identifier } from './world-contracts.js';
+import { candidateSourceMatches, sourceChangeMatches, patchSourceFileMatches } from '../../contracts/agent-change-contracts.js';
+import { nativeMetadataCanonical } from '../../contracts/local-value-source-contracts.js';
+const hash = /^[a-f0-9]{64}$/;
+const path = (scope, campaign, change) => `/api/workspaces/${identifier(scope.workspace)}/campaigns/${identifier(campaign)}/source-changes/${identifier(change)}`;
+const auth = (scope, options) => ({ actor: scope.owner, workspace: scope.workspace, signal: options.signal });
+async function folder(scope, key) {
+    const root = join(await privateDirectory(), `candidate-copy-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(key)}`);
+    await mkdir(root, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+        throw error; });
+    const stat = await lstat(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || process.getuid && stat.uid !== process.getuid()
+        || process.platform !== 'win32' && !!(stat.mode & 0o077))
+        throw new CliError('candidate_copy_cache_unsafe', 'Use a private candidate-copy request directory owned by this OS user.');
+    return root;
+}
+async function owned(path, maximum) {
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > maximum || process.getuid && before.uid !== process.getuid()
+        || process.platform !== 'win32' && !!(before.mode & 0o077))
+        throw new CliError('candidate_copy_cache_unsafe', 'The private candidate-copy input cannot be confirmed.');
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const actual = await file.stat();
+    if (actual.dev !== before.dev || actual.ino !== before.ino || actual.size !== before.size || actual.mtimeMs !== before.mtimeMs) {
+        await file.close();
+        throw new CliError('candidate_copy_cache_changed', 'The private candidate input changed. No existing destination file was overwritten.');
+    }
+    return file;
+}
+async function savedIntent(root, scope, key) {
+    const file = await owned(join(root, 'intent.json'), 65536);
+    try {
+        const value = JSON.parse(await file.readFile('utf8'));
+        if (value.schema !== 'firedrill.native-candidate-copy.v1' || value.key !== key || value.owner !== scope.owner || value.workspace !== scope.workspace
+            || identifier(value.campaign) !== value.campaign || identifier(value.change) !== value.change || !hash.test(value.scope_sha256)
+            || !hash.test(value.draft_sha256) || value.download_source_consent !== true || typeof value.destination !== 'string'
+            || !isAbsolute(value.destination) || value.destination !== resolve(value.destination))
+            throw new Error();
+        return value;
+    }
+    catch {
+        throw new CliError('candidate_copy_request_invalid', 'The exact candidate-copy request cannot be confirmed. It was not submitted.');
+    }
+    finally {
+        await file.close();
+    }
+}
+function identity(value, intent) {
+    if (!candidateSourceMatches(value, intent.workspace, intent.campaign, intent.change)
+        || value.scope_sha256 !== intent.scope_sha256 || value.draft_sha256 !== intent.draft_sha256
+        || ![value.files_sha256, value.snapshot?.sha256].every(one => typeof one === 'string' && hash.test(one))
+        || !/^[1-9][0-9]{0,30}$/.test(value.snapshot.generation) || value.target_executed !== false || value.vault_access_inherited !== false
+        || !Object.values(value.capacity ?? {}).every(one => Number.isSafeInteger(one) && one > 0)
+        || ['files', 'file_bytes', 'expanded_bytes', 'archive_bytes', 'directory_bytes'].some(key => !(key in value.capacity))
+        || !Number.isSafeInteger(value.file_count) || value.file_count < 1 || value.file_count > value.capacity.files
+        || !Number.isSafeInteger(value.expanded_bytes) || value.expanded_bytes < 0 || value.expanded_bytes > value.capacity.expanded_bytes
+        || !Number.isSafeInteger(value.snapshot.size) || value.snapshot.size < 1 || value.snapshot.size > value.capacity.archive_bytes) {
+        throw new CliError('candidate_copy_identity_invalid', 'The saved candidate source identity cannot be confirmed.');
+    }
+    for (const id of [value.source_id, value.world_id, value.agent_id, value.snapshot.id])
+        identifier(id);
+}
+async function writeMetadata(root, name, value) {
+    const temporary = join(root, name + '.' + randomUUID() + '.tmp');
+    const file = await open(temporary, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    try {
+        await rename(temporary, join(root, name));
+        const directory = await open(root, constants.O_RDONLY | constants.O_DIRECTORY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            await directory.sync();
+        }
+        finally {
+            await directory.close();
+        }
+    }
+    finally {
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+async function download(root, value, signed, signal) {
+    const existing = await owned(join(root, 'source.zip'), value.capacity.archive_bytes).catch(error => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (existing) {
+        try {
+            const hashed = createHash('sha256');
+            let bytes = 0;
+            for await (const chunk of existing.createReadStream({ autoClose: false })) {
+                signal.throwIfAborted();
+                bytes += chunk.length;
+                hashed.update(chunk);
+            }
+            if (bytes !== value.snapshot.size || hashed.digest('hex') !== value.snapshot.sha256)
+                throw new CliError('candidate_copy_cache_changed', 'The retained candidate archive changed. It was not overwritten.');
+            return;
+        }
+        finally {
+            await existing.close();
+        }
+    }
+    const url = new URL(signed);
+    if (url.protocol !== 'https:' || url.hostname !== 'storage.googleapis.com' || url.port || url.username || url.password || url.hash) {
+        throw new CliError('candidate_copy_destination_refused', 'The candidate download destination is not allowed.');
+    }
+    const temporary = join(root, 'source.' + randomUUID() + '.tmp');
+    const file = await open(temporary, 'wx', 0o600);
+    try {
+        const response = await fetch(url, { credentials: 'omit', redirect: 'error', referrerPolicy: 'no-referrer', signal: AbortSignal.any([signal, AbortSignal.timeout(300000)]) });
+        if (!response.ok || !response.body)
+            throw new CliError('candidate_copy_download_incomplete', 'The candidate download did not finish. Resume the original copy request.');
+        const hashed = createHash('sha256');
+        let bytes = 0;
+        const reader = response.body.getReader();
+        try {
+            while (true) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                bytes += part.value.length;
+                if (bytes > value.snapshot.size)
+                    throw new CliError('candidate_copy_integrity_failed', 'The candidate download exceeds its exact archive size.');
+                hashed.update(part.value);
+                let at = 0;
+                while (at < part.value.length) {
+                    const written = await file.write(part.value, at, part.value.length - at);
+                    if (!written.bytesWritten)
+                        throw new Error();
+                    at += written.bytesWritten;
+                }
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
+        }
+        if (bytes !== value.snapshot.size || hashed.digest('hex') !== value.snapshot.sha256)
+            throw new CliError('candidate_copy_integrity_failed', 'The candidate archive does not match its retained size and hash.');
+        await file.sync();
+        // The source is private request cache, not the user destination. Competing
+        // copies are serialized by the cache lock below.
+        await file.close();
+        await rename(temporary, join(root, 'source.zip'));
+    }
+    finally {
+        await file.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+async function copyFiles(root, intent, options) {
+    if (process.platform === 'win32')
+        throw new CliError('candidate_copy_host_unsupported', 'Candidate copying currently requires a POSIX host with no-follow directory operations. No destination files were changed.', 2);
+    const runtime = await trustedPython(await realpath(process.cwd()), options.signal, !options.json);
+    const within = relative(intent.destination, runtime);
+    if (!isAbsolute(within) && within !== '..' && !within.startsWith('..' + sep))
+        throw new CliError('python_runtime_refused', 'Use Python installed outside the candidate folder.', 2);
+    const script = fileURLToPath(new URL('../runtime/candidate_copy.py', import.meta.url));
+    return new Promise((accept, refuse) => {
+        const chunks = [];
+        let bytes = 0;
+        const child = spawn(runtime, ['-I', '-B', script, '--cache', root], { shell: false, windowsHide: true,
+            env: Object.fromEntries(['PATH', 'SYSTEMROOT'].flatMap(key => process.env[key] === undefined ? [] : [[key, process.env[key]]])),
+            signal: options.signal, stdio: ['ignore', 'pipe', 'pipe'] });
+        child.stdout.on('data', (chunk) => { bytes += chunk.length; if (bytes <= 65536)
+            chunks.push(chunk);
+        else
+            child.kill('SIGTERM'); });
+        child.stderr.resume();
+        child.once('error', () => refuse(new CliError(options.signal.aborted ? 'canceled' : 'candidate_copy_unavailable', 'Candidate copying stopped. Recover the original copy request; no destination file was overwritten.', options.signal.aborted ? 130 : 1)));
+        child.once('close', code => {
+            try {
+                const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                if (code !== 0 || bytes > 65536 || result.ok !== true || result.data?.schema !== 'firedrill.candidate-copy.v1'
+                    || result.data.destination !== intent.destination || result.data.target_executed !== false || result.data.original_files_changed !== false)
+                    throw new Error();
+                accept(result.data);
+            }
+            catch {
+                refuse(new CliError('candidate_copy_refused', 'The exact candidate copy could not be confirmed. Changed, extra or unknown destination files are never overwritten or removed. Inspect the retained copy request before resuming.'));
+            }
+        });
+    });
+}
+async function copyOwnership(intent, root) {
+    const legacy = await lstat(join(root, 'copy.lock')).then(() => true, error => {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    });
+    if (legacy)
+        throw new CliError('candidate_copy_pending', 'This original copy has a retained legacy lock. Preserve it for inspection. No source copy or removal was repeated.');
+    // Outside the erasable cache: forgetting recovery bytes must never unlink
+    // the shared kernel-lock inode or create two owners of a recreated directory.
+    return processLifetimeLock(join(await privateDirectory(), `candidate-copy-${identifier(intent.owner)}-${identifier(intent.workspace)}-${identifier(intent.key)}.lock`));
+}
+async function continueCopy(intent, root, scope, options, output) {
+    const lock = await copyOwnership(intent, root);
+    options = { ...options, signal: AbortSignal.any([options.signal, lock.signal]) };
+    try {
+        lock.assertHeld();
+        options.signal.throwIfAborted();
+        output('candidate_copy_request', { request_key: intent.key, campaign_id: intent.campaign, change_id: intent.change, destination: intent.destination }, `Copy request: ${intent.key}\nDestination: ${intent.destination}\nIf interrupted: firedrill changes copy-resume --workspace ${scope.workspace} --request-key ${intent.key}`);
+        const endpoint = path(scope, intent.campaign, intent.change) + '/export';
+        const response = await api(endpoint, { ...auth(scope, options), method: 'POST', idempotencyKey: intent.key,
+            body: { scope_sha256: intent.scope_sha256, draft_sha256: intent.draft_sha256, download_source_consent: true } });
+        const { download_url: transportOnly, request_key: key, ...value } = response;
+        if (key !== intent.key || typeof transportOnly !== 'string')
+            throw new CliError('candidate_copy_identity_invalid', 'The candidate download receipt does not match this request.');
+        identity(value, intent);
+        let retained = 0, pages = 0;
+        const manifestHash = createHash('sha256');
+        manifestHash.update('[');
+        const pageSet = randomUUID();
+        for (let page = 1;; page++) {
+            const result = await api(`${endpoint}?page=${page}&page_size=100`, auth(scope, options));
+            if (result.page !== page || result.page_size !== 100 || result.count !== value.file_count || nativeMetadataCanonical(result.identity) !== nativeMetadataCanonical(value)
+                || !Array.isArray(result.results) || !result.results.length || result.results.length > result.page_size
+                || !result.results.every(patchSourceFileMatches) || retained + result.results.length > value.file_count
+                || Boolean(result.next) !== (retained + result.results.length < value.file_count)
+                || result.next && result.results.length !== 100)
+                throw new CliError('candidate_copy_manifest_changed', 'The candidate source manifest changed. No destination files were changed.');
+            for (const item of result.results) {
+                if (retained++)
+                    manifestHash.update(',');
+                manifestHash.update(nativeMetadataCanonical(item));
+            }
+            await writeMetadata(root, `manifest-${pageSet}-${page}.json`, { page, entries: result.results });
+            pages = page;
+            output('candidate_copy_progress', { stage: 'manifest', retained_files: retained, expected_files: value.file_count }, `Source manifest: ${retained} / ${value.file_count} files`);
+            if (!result.next)
+                break;
+        }
+        manifestHash.update(']');
+        if (retained !== value.file_count || manifestHash.digest('hex') !== value.files_sha256)
+            throw new CliError('candidate_copy_manifest_incomplete', 'The candidate source manifest is incomplete or differs from its retained digest.');
+        // Commit the bounded page set only after its whole ordered digest matches.
+        // Python rechecks it while building a disk-backed index, never one giant list.
+        await writeMetadata(root, 'manifest.json', { schema: 'firedrill.candidate-manifest-pages.v1', identity: value, page_set: pageSet, pages });
+        // Remove only previous private manifest page sets after the new head is
+        // durable. Interrupted downloads can resume without unbounded cache growth.
+        for await (const entry of await opendir(root)) {
+            if (/^manifest-[a-f0-9-]{36}-[1-9][0-9]*\.json$/.test(entry.name) && !entry.name.startsWith(`manifest-${pageSet}-`)) {
+                const file = await owned(join(root, entry.name), 1024 * 1024);
+                await file.close();
+                await unlink(join(root, entry.name));
+            }
+        }
+        // Fetch a current short-lived URL after paging, without dispatching a new
+        // export intent. This also rechecks authority before copying source bytes.
+        const fresh = await api(endpoint, { ...auth(scope, options), method: 'POST', idempotencyKey: intent.key,
+            body: { scope_sha256: intent.scope_sha256, draft_sha256: intent.draft_sha256, download_source_consent: true } });
+        const { download_url: freshTransport, request_key: freshKey, ...freshIdentity } = fresh;
+        identity(freshIdentity, intent);
+        if (freshKey !== intent.key || nativeMetadataCanonical(freshIdentity) !== nativeMetadataCanonical(value)
+            || typeof freshTransport !== 'string')
+            throw new CliError('candidate_copy_identity_invalid', 'The current candidate no longer matches this copy request.');
+        await download(root, value, fresh.download_url, options.signal);
+        output('candidate_copy_progress', { stage: 'archive_verified', bytes: value.snapshot.size }, 'Candidate archive downloaded and hash-checked.');
+        const result = await copyFiles(root, intent, options);
+        if (result.source_id !== value.source_id || result.world_id !== value.world_id || result.agent_id !== value.agent_id
+            || result.files_sha256 !== value.files_sha256 || result.file_count !== value.file_count)
+            throw new CliError('candidate_copy_identity_invalid', 'The local copy receipt does not match the accepted candidate. It was not bound to a world.');
+        lock.assertHeld();
+        options.signal.throwIfAborted();
+        await bindSavedProject(scope, result.destination, { world: value.world_id, source: value.source_id, agent: value.agent_id, content_digest: value.files_sha256 });
+        output('result', { ...result, request_key: intent.key }, `Candidate saved to ${result.destination}\n${result.file_count} files verified. Original working copy unchanged.\n${workspaceLink(scope.workspace, `/worlds/${identifier(value.world_id)}`)}\nNo dependencies installed, Vault values or .env files copied, agent run, commit or PR created. Review candidate configuration and execution separately.`);
+    }
+    finally {
+        await lock.close();
+    }
+}
+export async function candidateCopy(scope, campaign, change, options, output) {
+    const key = options.request ? identifier(options.request) : randomUUID(), root = await folder(scope, key);
+    let intent = await savedIntent(root, scope, key).catch(error => { if (error.code === 'ENOENT')
+        return null; throw error; });
+    if (!campaign || !change) {
+        if (!options.request || options.into || !intent)
+            throw new CliError('candidate_copy_request_required', 'Use copy-resume with --request-key for the exact saved copy request.', 2);
+    }
+    else {
+        if (!options.into)
+            throw new CliError('candidate_copy_destination_required', 'Use --into <new-folder>. Candidate copying never overwrites the current project.', 2);
+        const destination = resolve(await realpath(dirname(resolve(options.into))), resolve(options.into).split(sep).at(-1));
+        const project = await realpath(process.cwd()), inside = relative(project, destination);
+        if (!isAbsolute(inside) && inside !== '..' && !inside.startsWith('..' + sep)) {
+            throw new CliError('candidate_copy_destination_required', 'Choose a new folder outside the current working copy. Existing project files and directories are not used as the copy destination.', 2);
+        }
+        if (intent && (intent.campaign !== campaign || intent.change !== change || intent.destination !== destination))
+            throw new CliError('candidate_copy_request_conflict', 'This key belongs to another destination or source. Resume its original request.', 2);
+        if (!intent) {
+            const row = await api(path(scope, campaign, change), auth(scope, options));
+            if (!sourceChangeMatches(row, scope.workspace, campaign, change) || row.state !== 'accepted' || !row.current || !hash.test(row.scope_sha256)
+                || !row.draft_sha256 || !hash.test(row.draft_sha256))
+                throw new CliError('candidate_copy_unavailable', 'Save a current reviewed candidate before copying it.');
+            const consent = options.approveDownload || !options.json && process.stdin.isTTY && process.stderr.isTTY
+                && await selectOne(`Download this private candidate source into ${destination}? Keep local recovery metadata and a private archive. This does not execute it.`, [{ value: false, label: 'Cancel' }, { value: true, label: 'Download separate candidate' }], options.signal);
+            if (!consent)
+                throw new CliError('candidate_copy_consent_required', 'No candidate source was downloaded. Use --approve-download only after reviewing source disclosure and destination.', 2);
+            intent = { schema: 'firedrill.native-candidate-copy.v1', ...scope, key, campaign, change, destination, scope_sha256: row.scope_sha256,
+                draft_sha256: row.draft_sha256, download_source_consent: true };
+            const file = await open(join(root, 'intent.json'), 'wx', 0o600);
+            try {
+                await file.writeFile(JSON.stringify(intent));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+        }
+    }
+    await continueCopy(intent, root, scope, options, output);
+}
+export async function forgetCandidateCopy(scope, options, output) {
+    if (!options.request)
+        throw new CliError('candidate_copy_request_required', 'Choose the exact private copy request with --request-key.', 2);
+    const key = identifier(options.request), root = await folder(scope, key);
+    const intent = await savedIntent(root, scope, key);
+    const consent = options.approveDownload || !options.json && process.stdin.isTTY && process.stderr.isTTY
+        && await selectOne('Remove this private downloaded archive and copy-recovery files? Keep the candidate folder and all cloud records.', [{ value: false, label: 'Keep private recovery files' }, { value: true, label: 'Remove private recovery files' }], options.signal);
+    if (!consent)
+        throw new CliError('candidate_copy_consent_required', 'Private recovery files were kept. Use --approve-download only after reviewing this exact local removal.', 2);
+    const lock = await copyOwnership(intent, root);
+    options = { ...options, signal: AbortSignal.any([options.signal, lock.signal]) };
+    try {
+        lock.assertHeld();
+        options.signal.throwIfAborted();
+        for await (const entry of await opendir(root)) {
+            const name = entry.name;
+            if (!/^(?:intent\.json|manifest\.json|manifest-[a-f0-9-]{36}-[1-9][0-9]*\.json|source\.zip|copy-receipt\.json|copy\.lock|(?:source\.[a-f0-9-]+|manifest(?:-[a-f0-9-]{36}-[1-9][0-9]*)?\.json\.[a-f0-9-]+)\.tmp|receipt-[A-Za-z0-9_-]+)$/.test(name)) {
+                throw new CliError('candidate_copy_cache_unsafe', 'The private cache contains an unexpected item. No automatic recursive removal is permitted.');
+            }
+            const file = await owned(join(root, name), Number.MAX_SAFE_INTEGER);
+            await file.close();
+        }
+        // Intent is removed last, preserving scoped recovery through an interrupted
+        // removal. Only exact flat regular files in this owned cache are touched.
+        for await (const entry of await opendir(root)) {
+            const name = entry.name;
+            if (['intent.json', 'copy.lock'].includes(name))
+                continue;
+            lock.assertHeld();
+            options.signal.throwIfAborted();
+            await unlink(join(root, name));
+        }
+        lock.assertHeld();
+        options.signal.throwIfAborted();
+        await unlink(join(root, 'intent.json'));
+        await rmdir(root);
+    }
+    finally {
+        await lock.close();
+    }
+    output('result', { request_key: intent.key, local_cache_removed: true, candidate_folder_removed: false }, 'Private downloaded archive and recovery files removed. The candidate folder and cloud source/history are unchanged.');
+}

package/dist/cli/src/catalog-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/catalog-contracts.js';

package/dist/cli/src/ci-access-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/ci-access-contracts.js';

package/dist/cli/src/ci-configuration-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/ci-configuration-contracts.js';

package/dist/cli/src/ci-coverage.js

@@ -0,0 +1,64 @@
+import { api } from './auth.js';
+import { workspaceLink } from './browser-links.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { ciCoverageMatches, ciCoverageScenariosMatch, ciCoverageFilesMatch } from '../../contracts/ci-coverage-contracts.js';
+import { ciCoverageReason, ciCoverageLinkLabel, ciCoverageFileLabel } from '../../contracts/ci-coverage-labels.js';
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+export async function ciCoverage(run, detail, scope, options, output) {
+    if (detail !== undefined && !['scenarios', 'files'].includes(detail)
+        || !detail && [options.page, options.search, options.status].some(value => value !== undefined)
+        || options.status !== undefined && (detail !== 'scenarios' || !['all', 'selected', 'skipped'].includes(options.status))
+        || (options.search?.length ?? 0) > 200 || /[\u0000-\u001f\u007f]/.test(options.search ?? '')) {
+        throw new CliError('arguments_invalid', 'Use ci coverage <run> [scenarios|files]. Paging/search apply to details; --status all|selected|skipped applies to scenarios.', 2);
+    }
+    const path = `/api/workspaces/${scope.workspace}/ci/runs/${run}/coverage`, auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const value = await api(path, auth);
+    if (!ciCoverageMatches(value, scope.workspace, run))
+        throw new CliError('ci_coverage_changed', 'The original scenario selection could not be confirmed. Reopen this CI run.');
+    const selection = value.selection;
+    if (!selection) {
+        output('ci_coverage', value, 'Scenario selection is unavailable. Reading does not prepare or execute a run.');
+        return;
+    }
+    const command = `firedrill ci coverage ${run}`;
+    if (!detail) {
+        output('ci_coverage', value, [`${selection.selected_count.toLocaleString()} of ${selection.baseline_count.toLocaleString()} baseline scenarios selected; ${selection.skipped_count.toLocaleString()} skipped.`,
+            `${selection.selected_drills.toLocaleString()} of ${selection.baseline_drills.toLocaleString()} baseline drills planned.`,
+            `Reviewed PR policy: ${selection.policy_mode === 'change_relevant' ? 'change-relevant scenarios' : 'all planned scenarios'}.`,
+            selection.reduced ? 'Reduced scope. Skipped scenarios are not part of this run.' : 'All baseline scenarios are included.',
+            `${ciCoverageReason(selection.reason)}.`, selection.changed_files === null ? 'Source comparison unavailable.' : `${selection.changed_files.toLocaleString()} changed paths in the supported source comparison.`,
+            `Inspect cases: ${command} scenarios --workspace ${scope.workspace}`, ...(selection.changed_files !== null ? [`Inspect source: ${command} files --workspace ${scope.workspace}`] : []),
+        ].map(terminalText).join('\n'));
+        if (options.json || !process.stdin.isTTY || !process.stderr.isTTY)
+            return;
+        detail = await selectOne('Inspect original selection', [{ value: 'done', label: 'Done' }, { value: 'scenarios', label: 'Selected and skipped scenarios' },
+            ...(selection.changed_files === null ? [] : [{ value: 'files', label: 'Changed source files' }])], options.signal);
+        if (detail === 'done')
+            return;
+    }
+    const page = Number(options.page ?? '1'), query = options.search ?? '';
+    const search = query ? ` --search ${quote(query)}` : '', json = options.json ? ' --json' : '';
+    if (detail === 'files') {
+        if (selection.changed_files === null)
+            throw new CliError('ci_comparison_unavailable', 'Source comparison is unavailable. Inspect scenario coverage for the selection reason.');
+        const rows = await api(`${path}/files?${new URLSearchParams({ page: String(page), q: query })}`, auth);
+        if (!ciCoverageFilesMatch(rows, scope.workspace, run, selection, query, page))
+            throw new CliError('ci_coverage_changed', 'This source page does not match the original retained selection.');
+        output('ci_coverage_files', rows, [...rows.results.map(row => `${row.path} · ${ciCoverageFileLabel(row.change)}`),
+            ...(!rows.count ? [query ? 'No changed source paths match this search.' : 'No changes were recorded in the supported comparison.'] : []),
+            `Page ${rows.page}; ${rows.count.toLocaleString()} source paths. File changes do not establish behavioral impact.`,
+            ...(rows.next ? [`Continue: ${command} files --workspace ${scope.workspace} --page ${rows.page + 1}${search}${json}`] : [])].map(terminalText).join('\n'));
+        return;
+    }
+    const selected = (options.status ?? 'all');
+    const rows = await api(`${path}/scenarios?${new URLSearchParams({ page: String(page), q: query, selected })}`, auth);
+    if (!ciCoverageScenariosMatch(rows, scope.workspace, run, selection, { page, query, selected }))
+        throw new CliError('ci_coverage_changed', 'This scenario page does not match the original retained selection.');
+    output('ci_coverage_scenarios', rows, [...rows.results.map(row => [row.available ? row.name : 'Scenario details unavailable',
+            `${row.selected ? 'Selected' : 'Skipped'} · ${ciCoverageReason(row.reason)} · Saved revision ${row.revision}`,
+            ...row.links.map(link => `  ${link.path}: ${ciCoverageLinkLabel(link.status)}`),
+            ...(row.detail_path ? [workspaceLink(scope.workspace, row.detail_path)] : [])].map(terminalText).join('\n')),
+        ...(!rows.count ? ['No original scenarios match these filters.'] : []), `Page ${rows.page}; ${rows.count.toLocaleString()} baseline cases.`,
+        ...(rows.next ? [`Continue: ${command} scenarios --workspace ${scope.workspace} --page ${rows.page + 1} --status ${selected}${search}${json}`] : [])].join('\n\n'));
+}

package/dist/cli/src/ci-delivery-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/ci-delivery-contracts.js';

package/dist/cli/src/ci-result-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/ci-result-contracts.js';

package/dist/cli/src/ci-run-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/ci-run-contracts.js';