firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/source-runtime.js

@@ -0,0 +1,346 @@
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, mkdtemp, open, realpath, rename, rm } from 'node:fs/promises';
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { privateDirectory } from './credentials.js';
+import { CliError, endpoint, jsonRequest, responseError } from './http.js';
+import { selectOne } from './prompts.js';
+import { bootstrapProcessLock } from './bootstrap-process-lock.js';
+const digest = /^[a-f0-9]{64}$/;
+const inside = (parent, child) => { const value = relative(parent, child); return !isAbsolute(value) && value !== '..' && !value.startsWith('..' + sep); };
+const fail = () => new CliError('source_runtime_integrity', 'The private source helper could not be confirmed. It was not executed or overwritten.');
+const interactive = () => !!process.stdin.isTTY && !!process.stderr.isTTY;
+function host() {
+    if (!['darwin', 'linux'].includes(process.platform) || !['x64', 'arm64'].includes(process.arch)) {
+        throw new CliError('source_host_unsupported', 'Local source capture requires macOS or Linux on arm64 or x64.', 2);
+    }
+    const report = process.report.getReport();
+    if (process.platform === 'linux' && !report.header?.glibcVersionRuntime) {
+        throw new CliError('source_host_unsupported', 'The source helper currently supports GNU libc Linux. This host was not changed.', 2);
+    }
+    return { os: process.platform, arch: process.arch };
+}
+function release(value) {
+    if (!value || Object.keys(value).sort().join(',') !== 'arch,archive,notices,os,python_version,uv,uv_version'
+        || !['darwin', 'linux'].includes(value.os) || !['x64', 'arm64'].includes(value.arch) || value.uv_version !== '0.9.5'
+        || !/^3\.(12|13)\.[0-9]{1,3}$/.test(value.python_version))
+        throw fail();
+    let bucket;
+    for (const [name, filename, maximum] of [['uv', 'uv', 128 * 1024 ** 2], ['archive', 'python.tar.gz', 256 * 1024 ** 2], ['notices', 'notices.txt', 1024 ** 2]]) {
+        const part = value[name];
+        if (!part || Object.keys(part).sort().join(',') !== 'sha256,size,url' || !digest.test(part.sha256)
+            || !Number.isSafeInteger(part.size) || part.size < 1 || part.size > maximum || typeof part.url !== 'string')
+            throw fail();
+        let url;
+        try {
+            url = new URL(part.url);
+        }
+        catch {
+            throw fail();
+        }
+        const segments = url.pathname.split('/');
+        if (url.origin !== 'https://storage.googleapis.com' || url.username || url.password || url.search || url.hash
+            || segments.length !== 6 || !/^[a-z0-9][a-z0-9._-]{1,220}[a-z0-9]$/.test(segments[1])
+            || segments.slice(2).join('/') !== `firedrill-source-runtime/v1/${part.sha256}/${filename}` || bucket && bucket !== segments[1])
+            throw fail();
+        bucket = segments[1];
+    }
+    return value;
+}
+async function directory() {
+    const path = join(await privateDirectory(), 'source-runtime');
+    await mkdir(path, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+        throw error; });
+    const value = await lstat(path);
+    if (!value.isDirectory() || value.isSymbolicLink() || value.mode & 0o077 || process.getuid && value.uid !== process.getuid())
+        throw fail();
+    return path;
+}
+async function ownedFile(path, maximum) {
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > maximum || before.mode & 0o022
+        || process.getuid && before.uid !== process.getuid())
+        throw fail();
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const actual = await file.stat();
+    if (actual.ino !== before.ino || actual.dev !== before.dev || actual.size !== before.size) {
+        await file.close();
+        throw fail();
+    }
+    return file;
+}
+async function fileHash(path, maximum) {
+    const file = await ownedFile(path, maximum);
+    try {
+        const before = await file.stat(), hash = createHash('sha256');
+        let size = 0;
+        for await (const part of file.createReadStream({ autoClose: false })) {
+            size += part.length;
+            if (size > maximum)
+                throw fail();
+            hash.update(part);
+        }
+        const after = await file.stat();
+        if (before.size !== size || after.size !== size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw fail();
+        return { size, sha256: hash.digest('hex') };
+    }
+    finally {
+        await file.close();
+    }
+}
+function key(value) {
+    return `cpython-${value.python_version}-${value.os === 'darwin' ? 'macos' : 'linux'}-${value.arch === 'x64' ? 'x86_64' : 'aarch64'}-${value.os === 'darwin' ? 'none' : 'gnu'}`;
+}
+async function interpreter(root, value, project, allowVerifiedInsideProject = false) {
+    const selected = host(), config = release(value.release);
+    if (value.schema !== 'firedrill.source-runtime-install.v1' || config.os !== selected.os || config.arch !== selected.arch
+        || !/^install-[a-f0-9-]{36}$/.test(value.directory) || !digest.test(value.executable_sha256))
+        throw fail();
+    const path = join(root, value.directory, 'python', key(config), 'bin', `python${config.python_version.split('.').slice(0, 2).join('.')}`);
+    const actual = await realpath(path);
+    const tree = join(root, value.directory);
+    if (!inside(tree, actual) || !allowVerifiedInsideProject && inside(project, actual))
+        throw fail();
+    for (let at = dirname(actual); inside(root, at); at = dirname(at)) {
+        const info = await lstat(at);
+        if (!info.isDirectory() || info.isSymbolicLink() || info.mode & 0o022 || process.getuid && info.uid !== process.getuid())
+            throw fail();
+        if (at === root)
+            break;
+    }
+    if ((await fileHash(actual, 128 * 1024 ** 2)).sha256 !== value.executable_sha256)
+        throw fail();
+    return actual;
+}
+async function retained(project, allowVerifiedInsideProject = false) {
+    const root = await directory(), selected = host();
+    const file = await ownedFile(join(root, `${selected.os}-${selected.arch}.json`), 32768).catch(error => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!file)
+        return null;
+    try {
+        let value;
+        try {
+            value = JSON.parse(await file.readFile('utf8'));
+        }
+        catch {
+            throw fail();
+        }
+        return { value, executable: await interpreter(root, value, project, allowVerifiedInsideProject) };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function run(binary, args, cwd, environment, signal, milliseconds, maximum = 2048) {
+    const stop = AbortSignal.any([signal, AbortSignal.timeout(milliseconds)]);
+    return new Promise((accept, refuse) => {
+        let size = 0, overflow = false;
+        const chunks = [];
+        const child = spawn(binary, args, { shell: false, cwd, env: environment, signal: stop, stdio: ['ignore', 'pipe', 'pipe'] });
+        child.stdout.on('data', (part) => { size += part.length; if (size > maximum) {
+            overflow = true;
+            child.kill('SIGTERM');
+        }
+        else
+            chunks.push(part); });
+        child.stderr.resume();
+        child.once('error', () => refuse(new CliError('source_runtime_unavailable', 'The source helper stopped. No project code was executed.')));
+        child.once('close', code => { if (stop.aborted || overflow)
+            refuse(new CliError('source_runtime_unavailable', 'The source helper stopped. No project code was executed.'));
+        else
+            accept({ code, output: Buffer.concat(chunks).toString('utf8') }); });
+    });
+}
+async function compatible(binary, project, signal) {
+    if (inside(project, binary))
+        return false;
+    const value = await lstat(binary);
+    if (!value.isFile() || value.mode & 0o022 || !(value.mode & 0o111) || process.getuid && ![0, process.getuid()].includes(value.uid))
+        return false;
+    const result = await run(binary, ['-I', '-B', '-c', 'import sys; print(str(sys.version_info.major)+"."+str(sys.version_info.minor))'], await directory(), { PATH: '/usr/bin:/bin' }, signal, 3000).catch(error => { signal.throwIfAborted(); return null; });
+    return result?.code === 0 && ['3.12', '3.13'].includes(result.output.trim());
+}
+async function download(part, path, signal, output, stage) {
+    const file = await open(path, 'wx', 0o600);
+    try {
+        const response = await fetch(part.url, { redirect: 'error', credentials: 'omit', referrerPolicy: 'no-referrer',
+            signal: AbortSignal.any([signal, AbortSignal.timeout(300000)]) });
+        if (!response.ok || !response.body)
+            throw new CliError('source_runtime_download_failed', 'The source helper download did not finish. No runtime was activated.');
+        const reader = response.body.getReader(), hash = createHash('sha256');
+        let size = 0, reported = 0;
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                size += chunk.value.length;
+                if (size > part.size)
+                    throw fail();
+                hash.update(chunk.value);
+                let at = 0;
+                while (at < chunk.value.length) {
+                    const written = await file.write(chunk.value, at, chunk.value.length - at);
+                    if (!written.bytesWritten)
+                        throw fail();
+                    at += written.bytesWritten;
+                }
+                if (size - reported >= 4 * 1024 ** 2) {
+                    reported = size;
+                    output('source_runtime_download', { stage, bytes: size, total: part.size }, `Downloading source helper: ${size} / ${part.size} bytes`);
+                }
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+            reader.releaseLock();
+        }
+        if (size !== part.size || hash.digest('hex') !== part.sha256)
+            throw fail();
+        await file.sync();
+        output('source_runtime_download', { stage, bytes: size, total: part.size, verified: true }, `${stage} download verified.`);
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function installSourceRuntime(project, signal, approve, output, allowPrompt = false) {
+    const current = await retained(project);
+    if (current)
+        return current;
+    const selected = host();
+    const response = await jsonRequest(endpoint('/api/auth/cli/source-runtime'), { signal }, 32768);
+    if (response.status !== 200)
+        throw responseError(response.body, response.status);
+    if (response.body.schema !== 'firedrill.source-runtime-catalog.v1' || !Array.isArray(response.body.runtimes) || response.body.runtimes.length > 4)
+        throw fail();
+    const rows = response.body.runtimes.map(release).filter(row => row.os === selected.os && row.arch === selected.arch);
+    if (rows.length !== 1)
+        throw new CliError('source_runtime_configuration_required', 'The source helper for this host is not published yet. No runtime or project files were changed.', 2);
+    const config = rows[0];
+    if (!approve) {
+        if (!allowPrompt || !interactive())
+            throw new CliError('source_runtime_consent_required', 'Run firedrill source runtime install --approve-download to allow the private helper download, then repeat this command. No source is uploaded.', 2);
+        approve = await selectOne(`Download Python ${config.python_version} for source capture (${Math.ceil((config.uv.size + config.archive.size + config.notices.size) / 1024 ** 2)} MB)?`, [{ value: true, label: 'Download helper', detail: 'Private app storage only. No PATH changes, project installs or agent execution.' }, { value: false, label: 'Cancel' }], signal);
+        if (!approve)
+            throw new CliError('source_runtime_declined', 'Helper download canceled. Project files were not changed.', 2);
+    }
+    const root = await directory(), lock = await bootstrapProcessLock(join(root, 'install.lock'));
+    signal = AbortSignal.any([signal, lock.signal]);
+    const nonce = randomUUID();
+    let stage, activated = false;
+    try {
+        lock.assertHeld();
+        signal.throwIfAborted();
+        const existing = await retained(project);
+        if (existing)
+            return existing;
+        stage = join(root, 'install-' + randomUUID());
+        await mkdir(stage, { mode: 0o700 });
+        const temporary = await mkdtemp(join(stage, 'scratch-'));
+        const uv = join(stage, 'uv'), archive = join(temporary, config.archive.sha256.slice(0, 9) + '-python.tar.gz');
+        const intent = await open(join(stage, 'release.json'), 'wx', 0o600);
+        try {
+            await intent.writeFile(JSON.stringify(config));
+            await intent.sync();
+        }
+        finally {
+            await intent.close();
+        }
+        output('source_runtime_install', { stage: 'downloading', version: config.python_version }, 'Downloading the source capture helper.');
+        await download(config.uv, uv, signal, output, 'Installer');
+        await download(config.archive, archive, signal, output, 'Python');
+        await download(config.notices, join(stage, 'notices.txt'), signal, output, 'Notices');
+        await chmod(uv, 0o700);
+        const [major, minor, patch] = config.python_version.split('.').map(Number), metadata = join(stage, 'downloads.json');
+        const file = await open(metadata, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify({ [key(config)]: { name: 'cpython', arch: { family: config.arch === 'x64' ? 'x86_64' : 'aarch64', variant: null },
+                    os: config.os === 'darwin' ? 'macos' : 'linux', libc: config.os === 'darwin' ? 'none' : 'gnu', major, minor, patch,
+                    prerelease: null, variant: null, build: null, sha256: config.archive.sha256,
+                    url: pathToFileURL(archive).href } }));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        // uv only extracts the already hash-checked local archive. It has no remote
+        // index, customer config, proxy, provider credential or package command.
+        const result = await run(uv, ['python', 'install', '--offline', '--no-config', '--no-bin', '--no-progress', '--managed-python',
+            '--install-dir', join(stage, 'python'), '--python-downloads-json-url', metadata, key(config)], stage, { HOME: stage, PATH: '/usr/bin:/bin', UV_CACHE_DIR: join(stage, 'cache'), UV_PYTHON_CACHE_DIR: temporary,
+            UV_PYTHON_INSTALL_BIN: '0', UV_NO_CONFIG: '1', UV_OFFLINE: '1', TMPDIR: temporary }, signal, 120000);
+        if (result.code !== 0)
+            throw new CliError('source_runtime_install_failed', 'The private source helper could not be installed. No target or project code was executed.');
+        const executable = await realpath(join(stage, 'python', key(config), 'bin', `python${major}.${minor}`));
+        if (!inside(stage, executable) || !await compatible(executable, project, signal))
+            throw fail();
+        const value = { schema: 'firedrill.source-runtime-install.v1', release: config,
+            directory: stage.slice(root.length + 1), executable_sha256: (await fileHash(executable, 128 * 1024 ** 2)).sha256 };
+        await interpreter(root, value, project);
+        const path = join(root, `${config.os}-${config.arch}.json`), receipt = path + '.' + nonce + '.tmp';
+        const record = await open(receipt, 'wx', 0o600);
+        try {
+            await record.writeFile(JSON.stringify(value));
+            await record.sync();
+        }
+        finally {
+            await record.close();
+        }
+        lock.assertHeld();
+        signal.throwIfAborted();
+        await rename(receipt, path);
+        activated = true;
+        output('source_runtime_install', { stage: 'installed', version: config.python_version, source_uploaded: false, target_executed: false }, 'Source capture helper installed. No project code was run.');
+        return { value, executable };
+    }
+    finally {
+        // Only this invocation's freshly allocated directory is eligible. Never
+        // remove a retained install, user project, shared parent or prior lock.
+        try {
+            if (stage && !activated && inside(root, stage) && /^install-[a-f0-9-]{36}$/.test(stage.slice(root.length + 1)))
+                await rm(stage, { recursive: true }).catch(() => undefined);
+        }
+        finally {
+            await lock.close();
+        }
+    }
+}
+async function resolveSourcePython(project, signal, allowPrompt, allowVerifiedInsideProject = false) {
+    host();
+    for (const part of (process.env.PATH ?? '').split(delimiter)) {
+        if (!part || !isAbsolute(part))
+            continue;
+        const binary = await realpath(resolve(part, 'python3')).catch(() => null);
+        if (binary && await compatible(binary, project, signal))
+            return binary;
+    }
+    const cached = await retained(project, allowVerifiedInsideProject);
+    if (cached)
+        return cached.executable;
+    if (!allowPrompt || !interactive())
+        throw new CliError('source_runtime_consent_required', 'Run firedrill source runtime install --approve-download to allow the private helper download, then repeat this command. No source is uploaded.', 2);
+    return (await installSourceRuntime(project, signal, false, (_type, _value, readable) => process.stderr.write(readable + '\n'), true)).executable;
+}
+export async function sourcePython(project, signal, allowPrompt = false) {
+    return resolveSourcePython(project, signal, allowPrompt);
+}
+/** Fixed first-party offline control code only. PATH candidates retain the
+ * normal outside-project trust rule. Only the exact private receipt/path/hash-
+ * verified cached interpreter can be inside cwd, for example when cwd is home.
+ * This selector never installs, prompts, contacts a provider or imports a target.
+ */
+export async function controlPython(signal) {
+    return resolveSourcePython(await realpath(process.cwd()), signal, false, true);
+}
+export async function sourceRuntimeCommand(action, options, output) {
+    const project = await realpath(process.cwd());
+    const value = action === 'install' ? await installSourceRuntime(project, options.signal, options.approve, output, options.interactive) : await retained(project);
+    output('result', { host: host(), installed: !!value, version: value?.value.release.python_version ?? null, source_uploaded: false, target_executed: false }, value ? `Source helper: Python ${value.value.release.python_version}. No project code was run.` : 'No private source helper is installed. A compatible Python already on PATH can still be used.');
+}

package/dist/cli/src/source-selection-intents.js

@@ -0,0 +1,75 @@
+import { createHash } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+import { privateDirectory } from './credentials.js';
+import { readMetadata } from './configuration-intents.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { nativeMetadataCanonical } from '../../contracts/local-value-source-contracts.js';
+const metadataSchema = z.object({ expected_source_id: z.string().uuid(), consent_to_transfer: z.literal(true), roots: z.array(z.object({ source_id: z.string().uuid(), alias: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/) }).strict()).min(1).max(128) }).strict();
+const schema = z.object({ schema: z.literal('firedrill.source-selection-intent.v1'), owner: z.string().uuid(), workspace: z.string().uuid(),
+    agent: z.string().uuid(), key: z.string().uuid(), metadata: metadataSchema, graph_sha256: z.string().regex(/^[a-f0-9]{64}$/),
+    request_sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict();
+const hash = (value) => createHash('sha256').update(nativeMetadataCanonical(value)).digest('hex');
+export const sourceSelectionDigest = (input) => hash({ ...input, graph: input.graph ?? {} });
+const invalid = () => new CliError('source_selection_metadata_required', 'Keep the original source selection and request ID. A newer source or changed graph was not substituted.', 2);
+const pathFor = async (scope, agent, key) => join(await privateDirectory(), `source-selection-${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(agent)}-${identifier(key)}.json`);
+export async function retainedSourceSelection(scope, agent, key) {
+    let value;
+    try {
+        value = await readMetadata(await pathFor(scope, agent, key), true);
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return null;
+        throw invalid();
+    }
+    const parsed = schema.safeParse(value);
+    if (!parsed.success || parsed.data.owner !== scope.owner || parsed.data.workspace !== scope.workspace || parsed.data.agent !== agent || parsed.data.key !== key)
+        throw invalid();
+    if (parsed.data.graph_sha256 === hash({}) && sourceSelectionDigest(parsed.data.metadata) !== parsed.data.request_sha256)
+        throw invalid();
+    return parsed.data;
+}
+export function sourceSelectionBody(original, file) {
+    const body = file ?? (original.graph_sha256 === hash({}) ? { ...original.metadata, graph: {} } : null);
+    if (!body || sourceSelectionDigest(body) !== original.request_sha256 || hash(body.graph ?? {}) !== original.graph_sha256)
+        throw invalid();
+    return body;
+}
+export async function rememberSourceSelection(scope, agent, key, input) {
+    // Source IDs/aliases and digests only. Never journal graph commands or values.
+    const metadata = metadataSchema.parse({ expected_source_id: input.expected_source_id, roots: input.roots, consent_to_transfer: input.consent_to_transfer });
+    const value = { schema: 'firedrill.source-selection-intent.v1', owner: scope.owner, workspace: scope.workspace,
+        agent: identifier(agent), key: identifier(key), metadata, graph_sha256: hash(input.graph ?? {}), request_sha256: sourceSelectionDigest(input) };
+    const path = await pathFor(scope, agent, key);
+    try {
+        const file = await open(path, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        if (process.platform !== 'win32') {
+            const parent = await open(dirname(path), 'r');
+            try {
+                await parent.sync();
+            }
+            finally {
+                await parent.close();
+            }
+        }
+    }
+    catch (error) {
+        if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST')
+            throw error;
+        const prior = await retainedSourceSelection(scope, agent, key);
+        if (!prior || prior.request_sha256 !== value.request_sha256 || prior.graph_sha256 !== value.graph_sha256)
+            throw invalid();
+        return prior;
+    }
+    return value;
+}

package/dist/cli/src/source-sets.js

@@ -0,0 +1,214 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { api } from './auth.js';
+import { CliError, releaseClosed } from './http.js';
+import { identifier } from './world-contracts.js';
+import { selectedWorkspace } from './world-access.js';
+import { selectMany, selectOne } from './prompts.js';
+import { readSourceSet, readSourceSetWithdrawal, sourceSetWithdrawalSchema, sourceOptionSchema, sourceSetSchema } from '../../contracts/source-set-contracts.js';
+import { rememberSourceSelection, retainedSourceSelection, sourceSelectionBody, sourceSelectionDigest } from './source-selection-intents.js';
+import { readMetadata } from './configuration-intents.js';
+const pageSchema = z.object({ results: z.array(sourceOptionSchema).max(100), count: z.number().int().nonnegative(),
+    page: z.number().int().positive(), page_size: z.number().int().positive(), next: z.string().nullable() });
+const historySchema = z.object({ results: z.array(sourceSetSchema).max(100), count: z.number().int().nonnegative(),
+    page: z.number().int().positive(), page_size: z.number().int().positive() });
+const inputSchema = z.object({ expected_source_id: z.string().uuid(), consent_to_transfer: z.literal(true),
+    roots: z.array(z.object({ alias: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/), source_id: z.string().uuid() }).strict()).min(1).max(128),
+    graph: z.record(z.string(), z.unknown()).optional() }).strict();
+async function inputFile(path) {
+    try {
+        const value = inputSchema.parse(await readMetadata(path));
+        return { ...value, expected_source_id: identifier(value.expected_source_id),
+            roots: value.roots.map(root => ({ ...root, source_id: identifier(root.source_id) })) };
+    }
+    catch {
+        throw new CliError('source_set_input_invalid', 'Use a bounded JSON source selection with source IDs, component aliases and an optional service graph. Keep credentials in Vault.', 2);
+    }
+}
+export async function sourceSetsCommand(args, options, output) {
+    const action = args[0] ?? 'list';
+    if (!['list', 'options', 'use', 'status', 'withdraw'].includes(action) || args.length > (['status', 'withdraw'].includes(action) ? 2 : 1)
+        || options.file !== undefined && !['use', 'withdraw'].includes(action) || options.change && action !== 'withdraw'
+        || (options.page !== undefined || options.search !== undefined) && !['list', 'options'].includes(action)
+        || options.search !== undefined && action !== 'options' || options.request !== undefined && !['use', 'status', 'withdraw'].includes(action)
+        || options.approve && action !== 'use')
+        throw new CliError('arguments_invalid', 'Use sources list|options|use|status|withdraw with --agent <id> and action-specific options.', 2);
+    const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    const scope = await selectedWorkspace({ workspace: options.workspace, interactive, signal: options.signal, openBrowser: options.openBrowser });
+    let agent = options.agent ? identifier(options.agent) : undefined;
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    if (!agent && interactive) {
+        let page = 1;
+        while (!agent) {
+            const rows = await api(`/api/workspaces/${scope.workspace}/agents?page=${page}&page_size=25`, auth);
+            if (!Array.isArray(rows.results) || rows.results.length > 25)
+                throw new CliError('source_set_response_changed', 'The agent page changed. Read it again.');
+            const choices = rows.results.map(item => ({ value: identifier(item.id), label: item.name }));
+            if (page > 1)
+                choices.unshift({ value: 'previous', label: 'Previous page' });
+            if (rows.next)
+                choices.push({ value: 'next', label: 'Next page' });
+            if (!choices.length)
+                throw new CliError('agent_required', 'Connect an agent first.', 2);
+            const choice = await selectOne('Agent', choices, options.signal);
+            if (choice === 'next')
+                page++;
+            else if (choice === 'previous')
+                page--;
+            else
+                agent = choice;
+        }
+    }
+    if (!agent)
+        throw new CliError('agent_required', 'Pass --agent <id> to select the original application.', 2);
+    const base = `/api/workspaces/${scope.workspace}/agents/${agent}`;
+    const suppliedKey = args[1] ?? options.request;
+    if (args[1] && options.request && args[1] !== options.request)
+        throw new CliError('arguments_invalid', 'Keep one original source-selection request ID.', 2);
+    if (action === 'status') {
+        const key = identifier(suppliedKey ?? '');
+        const saved = await retainedSourceSelection(scope, agent, key);
+        const raw = await api(`${base}/source-sets/${key}`, auth);
+        const row = raw.state === 'not_received' ? z.object({ state: z.literal('not_received'), request_key: z.literal(key) }).strict().parse(raw)
+            : sourceSetWithdrawalSchema.safeParse(raw).success ? readSourceSetWithdrawal(raw, scope.workspace, agent, scope.owner, key, saved?.request_sha256)
+                : readSourceSet(raw, scope.workspace, agent, key);
+        if ('actor_id' in row && (row.actor_id !== scope.owner || saved && row.request_sha256 !== saved.request_sha256))
+            throw new CliError('source_set_request_changed', 'The original source selection could not be confirmed.');
+        output('source_set', row, `Source request ${key}: ${row.state}.`);
+        return;
+    }
+    if (action === 'withdraw') {
+        const key = identifier(suppliedKey ?? '');
+        let saved = await retainedSourceSelection(scope, agent, key);
+        if (!saved && options.file)
+            saved = await rememberSourceSelection(scope, agent, key, await inputFile(options.file));
+        else if (saved && options.file)
+            sourceSelectionBody(saved, await inputFile(options.file));
+        if (!saved)
+            throw new CliError('source_selection_metadata_required', 'Provide the exact original selection file or use the terminal that retained this request. No request was withdrawn.', 2);
+        const approved = options.change || interactive && await selectOne('Withdraw this source selection?', [
+            { value: false, label: 'Cancel' }, { value: true, label: 'Withdraw original selection', detail: 'A selection that is already connected stays unchanged.' }
+        ], options.signal);
+        if (!approved)
+            throw new CliError('source_change_consent_required', 'No request withdrawn. Review and use --approve-change for automation.', 2);
+        const raw = await api(`${base}/source-sets/${key}`, { ...auth, method: 'DELETE', body: { request_sha256: saved.request_sha256 } });
+        const row = sourceSetWithdrawalSchema.safeParse(raw).success ? readSourceSetWithdrawal(raw, scope.workspace, agent, scope.owner, key, saved.request_sha256)
+            : readSourceSet(raw, scope.workspace, agent, key);
+        if (row.actor_id !== scope.owner || row.request_sha256 !== saved.request_sha256)
+            throw new CliError('source_set_request_changed', 'Check the original source selection before another action.');
+        output('source_set', row, row.state === 'ready' ? 'This source selection was already connected and stays unchanged.' : `Source request ${key}: ${row.state}.`);
+        return;
+    }
+    const page = Number(options.page ?? '1'), query = (options.search ?? '').trim();
+    if (!Number.isSafeInteger(page) || page < 1 || page > 999999999 || query.length > 200)
+        throw new CliError('query_invalid', 'Use a positive page and a search of up to 200 characters.', 2);
+    if (action === 'list') {
+        const rows = historySchema.parse(await api(`${base}/source-sets?page=${page}&page_size=25`, auth));
+        if (rows.page !== page || rows.page_size !== 25 || rows.results.length > 25 || rows.results.some(row => row.workspace_id !== scope.workspace || row.agent_id !== agent))
+            throw new CliError('source_set_response_changed', 'Source history could not be confirmed. Read it again.');
+        output('source_sets', rows, rows.results.map(row => `${row.id}  ${row.state}  ${row.roots.length} components`).join('\n') || 'No combined source selections.');
+        return;
+    }
+    const fetchPage = async (page) => {
+        const value = pageSchema.parse(await api(`${base}/source-set-options?${new URLSearchParams({ page: String(page), page_size: '25', q: query })}`, auth));
+        if (value.page !== page || value.page_size !== 25 || value.results.length > 25 || new Set(value.results.map(row => row.id)).size !== value.results.length)
+            throw new CliError('source_set_response_changed', 'Available source components could not be confirmed. Read them again.');
+        return value;
+    };
+    if (action === 'options') {
+        const rows = await fetchPage(page);
+        output('source_options', rows, rows.results.map(row => `${row.id}  ${row.name}  ${row.label}`).join('\n') || 'No connected source matches.');
+        return;
+    }
+    let body;
+    const retained = options.request ? await retainedSourceSelection(scope, agent, identifier(options.request)) : null;
+    if (retained)
+        body = sourceSelectionBody(retained, options.file ? await inputFile(options.file) : undefined);
+    else if (options.file)
+        body = await inputFile(options.file);
+    else {
+        if (!interactive)
+            throw new CliError('source_selection_required', 'Pass --file <reviewed-source-selection.json> and --upload-source, or use an interactive terminal.', 2);
+        const selected = new Map();
+        let current = 1, finished = false;
+        while (!finished) {
+            const rows = await fetchPage(current);
+            const choices = rows.results.map(row => ({ value: row.id, label: row.name, detail: row.label }));
+            const picked = await selectMany('Source components (Space selects, Enter continues)', choices, options.signal, [...selected.keys()]);
+            for (const row of rows.results) {
+                if (picked.includes(row.id))
+                    selected.set(row.id, row);
+                else
+                    selected.delete(row.id);
+            }
+            if (selected.size > 128)
+                throw new CliError('source_capacity_required', 'Narrow the source selection or contact support for more composition capacity.', 2);
+            const navigation = [{ value: 'done', label: `Use ${selected.size} selected components` }, { value: 'cancel', label: 'Cancel' }];
+            if (rows.next)
+                navigation.push({ value: 'next', label: 'Next page' });
+            if (current > 1)
+                navigation.push({ value: 'previous', label: 'Previous page' });
+            const next = await selectOne('Source selection', navigation, options.signal);
+            if (next === 'cancel')
+                return;
+            if (next === 'next')
+                current++;
+            else if (next === 'previous')
+                current--;
+            else
+                finished = true;
+        }
+        if (!selected.size)
+            throw new CliError('source_selection_required', 'Select at least one connected source.', 2);
+        const detail = await api(base, auth);
+        if (!detail.source)
+            throw new CliError('source_required', 'The agent has no connected source.');
+        const used = new Set();
+        const roots = [...selected.values()].map((row, index) => {
+            const name = row.name.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48);
+            const stem = /^[a-z]/.test(name) ? name : `component-${index + 1}`;
+            let alias = stem, suffix = 2;
+            while (used.has(alias))
+                alias = `${stem}-${suffix++}`;
+            used.add(alias);
+            return { alias, source_id: row.id };
+        });
+        body = { expected_source_id: identifier(detail.source.id), roots, consent_to_transfer: true };
+    }
+    const approved = options.approve || interactive && await selectOne('Use these sources together in isolated preparation?', [
+        { value: false, label: 'Not now' }, { value: true, label: `Use ${body.roots.length} source components` }
+    ], options.signal);
+    if (!approved)
+        throw new CliError('source_transfer_consent_required', 'No sources combined. Review the selection and approve with --upload-source.', 2);
+    const key = options.request ? identifier(options.request) : randomUUID();
+    const saved = await rememberSourceSelection(scope, agent, key, body);
+    const requestDigest = sourceSelectionDigest(body);
+    if (saved.request_sha256 !== requestDigest)
+        throw new CliError('source_set_request_changed', 'Keep the original source selection before retrying.');
+    const original = (row) => {
+        if (row.actor_id !== scope.owner || row.request_sha256 !== requestDigest)
+            throw new CliError('source_set_request_changed', 'This request belongs to another source selection. Recover its original inputs before choosing a new request.');
+        return row;
+    };
+    output('source_set_request', { agent_id: agent, request_key: key }, `Source request ${key}. Recover with sources status ${key} --agent ${agent}.`);
+    const prior = await api(`${base}/source-sets/${key}`, auth);
+    if (sourceSetWithdrawalSchema.safeParse(prior).success) {
+        readSourceSetWithdrawal(prior, scope.workspace, agent, scope.owner, key, requestDigest);
+        throw new CliError('source_set_withdrawn', 'This source selection was withdrawn. Review a new selection to continue.', 2);
+    }
+    if (prior.state !== 'not_received') {
+        const row = original(readSourceSet(prior, scope.workspace, agent, key));
+        output('source_set', row, `Original source request ${key}: ${row.state}.`);
+        return;
+    }
+    z.object({ state: z.literal('not_received'), request_key: z.literal(key) }).strict().parse(prior);
+    try {
+        const row = original(readSourceSet(await api(`${base}/source-sets`, { ...auth, method: 'POST', idempotencyKey: key, body }), scope.workspace, agent, key));
+        output('source_set', row, `Source selection ${row.state}. Startup requirements are discovered from the selected components. Existing worlds keep their original source.`);
+    }
+    catch (error) {
+        if (options.signal.aborted || releaseClosed(error))
+            throw error;
+        throw new CliError('source_set_acceptance_unknown', `Check sources status ${key} --agent ${agent}. The original request was not repeated and no simulation started.`);
+    }
+}