firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/local-execution-setup.js

@@ -0,0 +1,81 @@
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { currentLocalRunner, enrollLocalRunner, localRunnerSelectionPage } from './runner-identity.js';
+import { scopedRuntimeCommand } from './runner-runtime.js';
+import { authorizeLocalExecution } from './runner-grants.js';
+import { identifier } from './world-contracts.js';
+export function localSetupRequired(context, purpose, output) {
+    const scope = `--workspace ${context.workspace} --world ${context.world}`;
+    output('local_execution_setup_required', { world_id: context.world, purpose, required_input: ['runner_identity', 'runtime_readiness', 'local_permission'],
+        commands: [`firedrill runner enroll --workspace ${context.workspace} --enroll-device`,
+            `firedrill runner runtime install --workspace ${context.workspace} --install-runtime`,
+            `firedrill runner runtime check --workspace ${context.workspace}`,
+            `firedrill runner authorize <device-key> ${scope} --operations ${purpose} --approve-local`],
+        execution_started: false }, 'Local execution needs a registered runner, the pinned runtime and permission for this world. Use the explicit runner commands to review setup. No execution was started.');
+    throw new CliError('local_execution_setup_required', 'Review local setup in an interactive terminal, or provide the original --grant <permission-request-id>. No setup was approved automatically.', 2);
+}
+/** Orchestration only: the existing enrollment, runtime and permission handlers
+ * retain their own original requests, current authority checks and consent.
+ * This is never called to replace a saved campaign's execution identity.
+ */
+export async function setupLocalExecution(context, purpose, options, output) {
+    if (options.json || !process.stdin.isTTY || !process.stderr.isTTY)
+        localSetupRequired(context, purpose, output);
+    let device = options.device;
+    if (!device) {
+        let page = 1;
+        while (!device) {
+            const { directory, candidates } = await localRunnerSelectionPage(context, page, options.signal);
+            const choices = candidates.map(row => ({ value: row.device_key, label: row.label, detail: 'Registered in this terminal session. Local ownership is checked before use.' }));
+            choices.push({ value: 'register', label: 'Register this device', detail: 'Create a new runner identity after approval. This does not grant execution.' });
+            if (page > 1)
+                choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+            if (directory.next)
+                choices.push({ value: 'next', label: 'Next page', detail: '' });
+            choices.push({ value: 'cancel', label: 'Cancel local setup', detail: 'Keep this world. Do not start local or cloud execution.' });
+            const selected = await selectOne('Local runner', choices, options.signal);
+            if (selected === 'previous') {
+                page--;
+                continue;
+            }
+            if (selected === 'next') {
+                page++;
+                continue;
+            }
+            if (selected === 'cancel')
+                throw new CliError('canceled', 'Local setup canceled. No execution was started.', 130);
+            if (selected === 'register') {
+                const receipt = await enrollLocalRunner(context, options, output);
+                if (receipt.state === 'not_retained')
+                    throw new CliError('runner_enrollment_unconfirmed', 'The original runner enrollment is not confirmed. Inspect its exact device key before continuing; no replacement was enrolled.');
+                device = receipt.device_key;
+            }
+            else
+                device = identifier(selected);
+        }
+    }
+    const runner = await currentLocalRunner(context, identifier(device), options.signal);
+    const runtimeOptions = { ...options, workspace: context.workspace, install: false };
+    const image = await scopedRuntimeCommand(context, 'install', undefined, runtimeOptions, output);
+    if (!image?.installed)
+        throw new CliError('local_runtime_required', 'The pinned local execution image is not available. No permission or execution was created.', 2);
+    if (!await selectOne('Check local execution isolation?', [
+        { value: true, label: 'Check isolation', detail: 'Start and remove a source-free readiness container. No project, model or simulation runs.' },
+        { value: false, label: 'Cancel' }
+    ], options.signal))
+        throw new CliError('canceled', 'Local setup canceled. No project or simulation was started.', 130);
+    const observed = await scopedRuntimeCommand(context, 'check', undefined, runtimeOptions, output);
+    if (!observed?.isolation_observed || !observed.cleanup_confirmed)
+        throw new CliError('local_runtime_cleanup_pending', 'The readiness container has not finished cleanup. Recover the exact runtime request shown above before continuing. No project or simulation was started.', 2);
+    // Enrollment does not outlive its original native session. The current grant
+    // offer is read again by authorizeLocalExecution after this host review.
+    const current = await currentLocalRunner(context, runner.device_key, options.signal);
+    if (current.native_session_id !== runner.native_session_id)
+        throw new CliError('runner_scope_changed', 'The runner session changed during setup. No permission was created.');
+    const permission = await authorizeLocalExecution(context, current.device_key, { ...options, world: context.world, workspace: context.workspace,
+        operations: purpose, expectedRuntime: observed.runtime }, output);
+    if (permission.state !== 'active' || permission.device_key !== current.device_key || !permission.operations.includes(purpose)) {
+        throw new CliError('local_permission_changed', 'The original local permission is not currently active. Inspect its exact request; no replacement or execution was started.');
+    }
+    return { request: permission.request_key, device: permission.device_key };
+}

package/dist/cli/src/local-source-basis.js

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { localSource } from './local-source.js';
+import { originalLocalSourceBatch } from './source-batch.js';
+import { savedProject } from './source-connection.js';
+import { localGrantSourceRootsMatch } from '../../contracts/local-grant-contracts.js';
+import { nativeMetadataCanonical } from '../../contracts/local-value-source-contracts.js';
+const digest = (value) => createHash('sha256').update(nativeMetadataCanonical(value)).digest('hex');
+const unavailable = () => new CliError('local_source_basis_changed', 'The local folders do not match the original connected source selection. No folder was substituted, uploaded or executed.', 2);
+/** One source verifier shared by new permission review and every local claim.
+ * Actual execution still consumes the retained immutable composed snapshot.
+ */
+export async function verifyLocalSourceBasis(context, device, session, basis, signal, allowPrompt = false) {
+    const root = await realpath(process.cwd());
+    if (!basis.source_set) {
+        const capture = await localSource('inspect', root, signal, allowPrompt);
+        if (capture.content_digest !== basis.source_content_digest)
+            throw unavailable();
+        return { project_digest: createHash('sha256').update(root).digest('hex'), file_count: capture.files.length, component_count: 1 };
+    }
+    const binding = await savedProject(context, root);
+    if (binding?.world !== context.world || binding.source !== basis.source_id || !binding.batch_key) {
+        throw new CliError('local_source_batch_required', 'Open an original selected source folder with its private multi-folder selection journal. If that original connection is pending, use connect multi-resume <original-key>. No source was reconnected or uploaded.', 2);
+    }
+    const batch = await originalLocalSourceBatch(context, binding.batch_key, context.world, basis.source_id, basis.source_set, signal);
+    const basisDigest = digest(basis), rows = [];
+    let page = 1, pageSize = null;
+    while (true) {
+        const value = await api(`${context.prefix}/local-runners/${device}/grant-offer/source-roots?basis_sha256=${basisDigest}&page=${page}`, { actor: context.owner, workspace: context.workspace, signal });
+        if (!localGrantSourceRootsMatch(value, context.owner, context.workspace, context.world, device, session, basisDigest, basis.source_set, page)
+            || pageSize !== null && pageSize !== value.page_size || rows.length + value.results.length > basis.source_set.root_count)
+            throw unavailable();
+        pageSize = value.page_size;
+        rows.push(...value.results);
+        if (!value.next)
+            break;
+        if (page >= 128)
+            throw unavailable();
+        page++;
+    }
+    if (rows.length !== basis.source_set.root_count || new Set(rows.map(row => row.alias)).size !== rows.length
+        || new Set(rows.map(row => row.source_id)).size !== rows.length
+        || digest({ schema: 'firedrill.local-source-roots.v1', roots: rows }) !== basis.source_set.roots_sha256
+        || digest({ schema: 'firedrill.source-set.v1', roots: rows.map(({ content_digest: _capture, ...row }) => row) }) !== basis.source_set.source_set_sha256)
+        throw unavailable();
+    let fileCount = 0;
+    const mapping = [];
+    for (let index = 0; index < rows.length; index++) {
+        const declared = rows[index], selected = batch.roots[index];
+        if (declared.content_digest === null)
+            throw new CliError('local_source_binding_unavailable', 'This component has no original local capture to compare. Use a reviewed local source connection; no local path or digest was guessed.', 2);
+        if (!selected || declared.alias !== selected.alias || declared.source_id !== selected.source_id
+            || declared.content_digest !== selected.content_digest || declared.directory !== `components/${selected.alias}`
+            || !batch.composition.roots.some(row => row.alias === declared.alias && row.source_id === declared.source_id
+                && row.revision === declared.revision && row.directory === declared.directory && row.label === declared.label))
+            throw unavailable();
+        const physical = await realpath(selected.path);
+        if (physical !== selected.path)
+            throw unavailable();
+        const capture = await localSource('inspect', physical, signal, allowPrompt);
+        if (capture.content_digest !== declared.content_digest)
+            throw unavailable();
+        fileCount += capture.files.length;
+        if (!Number.isSafeInteger(fileCount))
+            throw unavailable();
+        mapping.push({ alias: declared.alias, path: physical });
+    }
+    if (!mapping.some(row => row.path === root))
+        throw unavailable();
+    return { project_digest: digest({ schema: 'firedrill.local-project-roots.v1', roots: mapping }), file_count: fileCount, component_count: mapping.length };
+}

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

@@ -0,0 +1,66 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { CliError } from './http.js';
+import { privateDirectory } from './credentials.js';
+import { sourcePython } from './source-runtime.js';
+// Only our bundled helper is invoked. Customer source is data, not a script,
+// package hook or Python import. Capture itself is offline. If there is no
+// compatible interpreter, acquisition requires separate explicit consent.
+export const trustedPython = sourcePython;
+export async function localSource(action, root, signal, allowPrompt = false) {
+    const script = fileURLToPath(new URL('../runtime/source_snapshot.py', import.meta.url));
+    const project = await realpath(resolve(root));
+    const runtime = await trustedPython(project, signal, allowPrompt);
+    const args = ['-I', '-B', script, action, '--root', project];
+    if (action === 'snapshot')
+        args.push('--storage', await privateDirectory());
+    signal.throwIfAborted();
+    return new Promise((accept, refuse) => {
+        let bytes = 0, overflow = false;
+        const chunks = [];
+        const environment = Object.fromEntries(['PATH', 'SYSTEMROOT'].flatMap(key => process.env[key] === undefined ? [] : [[key, process.env[key]]]));
+        const child = spawn(runtime, args, { shell: false, windowsHide: true, env: environment,
+            stdio: ['ignore', 'pipe', 'pipe'], signal });
+        child.stdout.on('data', (chunk) => {
+            bytes += chunk.length;
+            if (bytes > 32 * 1024 * 1024) {
+                overflow = true;
+                child.kill('SIGTERM');
+                return;
+            }
+            if (!overflow)
+                chunks.push(chunk);
+        });
+        child.stderr.resume(); // Never echo source paths/provider/configuration text.
+        child.once('error', () => refuse(new CliError(signal.aborted ? 'canceled' : 'python_runtime_required', signal.aborted ? 'Source capture stopped. No upload occurred.' : 'The source helper could not start. Inspect firedrill source runtime inspect. No upload occurred.', signal.aborted ? 130 : 2)));
+        child.once('close', code => {
+            if (signal.aborted) {
+                refuse(new CliError('canceled', 'Source capture stopped. No upload occurred.', 130));
+                return;
+            }
+            if (overflow) {
+                refuse(new CliError('source_capacity_required', 'The source manifest exceeds local intake capacity. Choose a smaller root.'));
+                return;
+            }
+            try {
+                const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                if (!result.ok) {
+                    if (!/^[a-z_]{1,64}$/.test(result.error?.code) || typeof result.error?.message !== 'string')
+                        throw new Error();
+                    refuse(new CliError(result.error.code, result.error.message, 2));
+                    return;
+                }
+                const value = result.data;
+                if (code !== 0 || value.schema !== 'firedrill.local-source.v1' || value.uploaded !== false
+                    || value.provenance !== 'customer_device' || !/^[a-f0-9]{64}$/.test(value.content_digest) || !Array.isArray(value.files))
+                    throw new Error();
+                accept(value);
+            }
+            catch {
+                refuse(new CliError('source_capture_failed', 'Local source capture did not return a complete manifest. No upload or execution occurred.'));
+            }
+        });
+    });
+}

package/dist/cli/src/local-value-store.js

@@ -0,0 +1,91 @@
+import { CliError, API_ORIGIN } from './http.js';
+import { identifier } from './world-contracts.js';
+const invalid = () => new CliError('local_value_unavailable', 'The exact private value is unavailable in this OS credential store. No replacement or file fallback was used.');
+async function entry(scope, id) {
+    try {
+        const { Entry } = await import('@napi-rs/keyring');
+        return new Entry('run.firedrill.simulation.device-value.v1', [API_ORIGIN, identifier(scope.workspace), identifier(scope.world), identifier(id)].join(':'), process.platform === 'linux' ? { linux: { store: 'secret-service' } } : undefined);
+    }
+    catch {
+        throw invalid();
+    }
+}
+export async function saveLocalValue(scope, id, metadata, value) {
+    if (!value || value.includes('\0') || Buffer.byteLength(value) > 65536)
+        throw new CliError('local_value_input_invalid', 'Enter a nonempty value of at most 64 KiB without NUL bytes. It was not saved.', 2);
+    const store = await entry(scope, id);
+    const body = JSON.stringify({ schema: 'firedrill.device-value.v1', ...scope, id, metadata, value });
+    try {
+        if (store.getPassword() !== null)
+            throw invalid();
+        store.setPassword(body);
+        if (store.getPassword() !== body)
+            throw invalid();
+    }
+    catch {
+        throw invalid();
+    }
+}
+export async function savedLocalValue(scope, id) {
+    try {
+        const raw = (await entry(scope, id)).getPassword();
+        if (raw === null || raw.length > 420000)
+            throw invalid();
+        const value = JSON.parse(raw), metadata = value.metadata;
+        if (value.schema !== 'firedrill.device-value.v1' || value.id !== identifier(id)
+            || value.owner !== scope.owner || value.workspace !== scope.workspace || value.world !== scope.world
+            || !metadata || identifier(metadata.device_key) !== metadata.device_key || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(metadata.name)
+            || !['build', 'runtime', 'both'].includes(metadata.phase) || !Number.isSafeInteger(metadata.configuration_revision)
+            || metadata.configuration_revision < 1 || metadata.value_stored_locally !== true
+            || typeof value.value !== 'string' || !value.value || value.value.includes('\0') || Buffer.byteLength(value.value) > 65536)
+            throw invalid();
+        return value;
+    }
+    catch {
+        throw invalid();
+    }
+}
+export async function forgetLocalValue(scope, id) {
+    const store = await entry(scope, id);
+    try {
+        if (store.getPassword() !== null)
+            store.deleteCredential();
+        if (store.getPassword() !== null)
+            throw invalid();
+    }
+    catch {
+        throw invalid();
+    }
+}
+/** Called after the signed packet passes its normal checks. No value is sent
+ * back to the cloud or persisted in a job journal. JS strings are not zeroized. */
+export async function resolveLocalValues(owner, references, phases, secretNames) {
+    if (!Array.isArray(references) || references.length > 10000 || !Array.isArray(secretNames))
+        throw invalid();
+    const seen = new Set();
+    let bytes = Buffer.byteLength(JSON.stringify(phases));
+    for (const reference of references) {
+        if (!reference || reference.schema !== 'firedrill.local-value-reference.v1' || identifier(reference.id) !== reference.id
+            || reference.world_id !== owner.world || reference.actor_id !== owner.owner || reference.device_key !== owner.device
+            || reference.state !== 'available' || reference.value_uploaded !== false || reference.revoked_at !== null
+            || !secretNames.includes(reference.name) || seen.has(reference.id))
+            throw invalid();
+        seen.add(reference.id);
+        const saved = await savedLocalValue(owner, reference.id);
+        try {
+            if (saved.metadata.name !== reference.name || saved.metadata.phase !== reference.phase || saved.metadata.device_key !== owner.device)
+                throw invalid();
+            for (const phase of reference.phase === 'both' ? ['build', 'runtime'] : [reference.phase]) {
+                if (!['build', 'runtime'].includes(phase) || Object.hasOwn(phases[phase], reference.name))
+                    throw invalid();
+                bytes += Buffer.byteLength(saved.value) + Buffer.byteLength(reference.name) + 16;
+                if (bytes > 1536 * 1024)
+                    throw new CliError('local_value_capacity', 'Local values exceed this runtime packet capacity. No target was started.');
+                Object.defineProperty(phases[phase], reference.name, { value: saved.value, writable: true, configurable: true, enumerable: true });
+            }
+        }
+        finally {
+            saved.value = '';
+        }
+    }
+}

package/dist/cli/src/local-values.js

@@ -0,0 +1,163 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { auth, choosePaged, interactive, line, query } from './configuration.js';
+import { readMetadata, record } from './configuration-intents.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { signRunnerRequest } from './runner-identity.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { readPrivateValue } from './vault.js';
+import { forgetLocalValue, savedLocalValue, saveLocalValue } from './local-value-store.js';
+import { localValueLookupMatches, localValueOriginalMatches, localValuePageMatches, localValueRegistrationMatches, nativeMetadataCanonical } from '../../contracts/local-value-source-contracts.js';
+import { localRunnersMatch } from '../../contracts/local-runner-contracts.js';
+const invalid = () => new CliError('local_value_input_invalid', 'Use name, phase and enrolled device_key metadata only. Values belong in hidden input or --value-stdin, never a JSON file or command arguments.', 2);
+const responseInvalid = () => new CliError('local_value_receipt_invalid', 'The saved metadata did not match this account, world, device or original request. No private value was uploaded. Inspect the original reference before continuing.');
+const digest = (body) => createHash('sha256').update(nativeMetadataCanonical(body)).digest('hex');
+const describe = (row) => `${terminalText(row.name)} · ${row.phase} · ${terminalText(row.device_label)} · ${row.state}\n${row.id}`;
+async function approved(options, question) {
+    if (options.approve)
+        return;
+    if (!interactive(options) || !await selectOne(question, [{ value: false, label: 'Cancel' }, { value: true, label: 'Confirm' }], options.signal))
+        throw new CliError('approval_required', 'Nothing was changed. Review the action and use --approve-change for automation.', 2);
+}
+async function lookup(context, options, id) {
+    const result = await api(`${context.prefix}/local-values/${id}`, auth(context, options));
+    if (!localValueLookupMatches(result, context, id))
+        throw responseInvalid();
+    return result;
+}
+async function original(context, options, id, metadata) {
+    const result = await api(`${context.prefix}/local-values/${id}`, { ...auth(context, options), method: 'PUT', body: metadata });
+    const retained = await lookup(context, options, id);
+    if (retained.state === 'not_retained' || !localValueOriginalMatches(result, context, id, metadata, digest(metadata))
+        || !localValueOriginalMatches(retained, context, id, metadata, digest(metadata))
+        || nativeMetadataCanonical(result) !== nativeMetadataCanonical(retained))
+        throw responseInvalid();
+    return retained;
+}
+async function page(context, options, selectedPage, search) {
+    const result = await api(`${context.prefix}/local-values?${query({ ...options, page: String(selectedPage), search })}`, auth(context, options));
+    if (!localValuePageMatches(result, context, search, selectedPage))
+        throw responseInvalid();
+    return result;
+}
+export async function localValuesCommand(args, options, output) {
+    let action = args[0] ?? (interactive(options) ? '' : 'list');
+    if (args.length > 2 || options.request || options.status || options.page !== undefined && !/^[1-9][0-9]{0,8}$/.test(options.page)
+        || (options.search?.length ?? 0) > 200)
+        throw invalid();
+    // Exact OS-owned removal does not need cloud authentication or current access.
+    if (action === 'forget') {
+        if (!args[1] || !options.world || !options.workspace || options.file || options.valueStdin || options.page || options.search)
+            throw invalid();
+        await approved(options, 'Remove this private OS credential only? Cloud references, running processes and previous effects will not be erased.');
+        await forgetLocalValue({ workspace: identifier(options.workspace), world: identifier(options.world) }, identifier(args[1]));
+        output({ id: args[1], local_value_removed: true, cloud_reference_revoked: false }, 'Local value removed. Cloud reference and already issued runtime values are unchanged.');
+        return;
+    }
+    if (!action)
+        action = await selectOne('Values kept on this device', [{ value: 'list', label: 'View local value references' },
+            { value: 'save', label: 'Save a private local value' }], options.signal);
+    if (!['list', 'show', 'save', 'recover', 'remove'].includes(action) || action !== 'save' && (options.file || options.valueStdin)
+        || !['list', 'show', 'remove'].includes(action) && (options.page || options.search)
+        || ['list', 'save'].includes(action) && args[1])
+        throw invalid();
+    const context = await selectedWorld({ ...options, interactive: interactive(options) }), access = auth(context, options);
+    const path = `${context.prefix}/local-values`;
+    if (action === 'list') {
+        const result = await page(context, options, Number(options.page ?? 1), options.search ?? '');
+        output(result, [...result.results.map(describe), `${result.count} references · Page ${result.page}`,
+            ...(result.next ? [`Continue with --page ${result.page + 1}.`] : [])].join('\n\n'));
+        return;
+    }
+    let id = args[1];
+    if (action === 'save') {
+        let input;
+        if (options.file)
+            input = await readMetadata(options.file);
+        else {
+            if (!interactive(options))
+                throw invalid();
+            let page = 1, device;
+            while (!device) {
+                const rows = await api(`/api/workspaces/${context.workspace}/local-runners?page=${page}`, access);
+                if (!localRunnersMatch(rows, context.owner, context.workspace, '', page))
+                    throw responseInvalid();
+                const choices = rows.results.filter(row => !['revoked', 'expired', 'access_removed'].includes(row.state))
+                    .map(row => ({ value: identifier(row.device_key), label: terminalText(row.label), detail: row.state }));
+                if (page > 1)
+                    choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+                if (rows.next)
+                    choices.push({ value: 'next', label: 'Next page', detail: '' });
+                choices.push({ value: 'cancel', label: 'Cancel', detail: '' });
+                const value = await selectOne('Enrolled device', choices, options.signal);
+                if (value === 'cancel')
+                    throw new CliError('canceled', 'No value was saved.', 130);
+                if (value === 'next' || value === 'previous')
+                    page += value === 'next' ? 1 : -1;
+                else
+                    device = value;
+            }
+            input = { device_key: device, name: await line('Variable name', 128, options.signal), phase: await selectOne('Used during', [{ value: 'runtime', label: 'Runtime' }, { value: 'build', label: 'Build' }, { value: 'both', label: 'Build and Runtime' }], options.signal) };
+        }
+        if (!record(input) || Object.keys(input).sort().join(',') !== 'device_key,name,phase' || typeof input.name !== 'string'
+            || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(input.name) || typeof input.device_key !== 'string'
+            || typeof input.phase !== 'string' || !['build', 'runtime', 'both'].includes(input.phase))
+            throw invalid();
+        const device = identifier(input.device_key);
+        // Prove this OS installation has the selected device identity, without
+        // submitting a pulse, authorizing a job or sending a value to the cloud.
+        await signRunnerRequest(context, device, { schema: 'firedrill.local-value-owner.v1', world_id: context.world }, options.signal);
+        const revision = await api(`${context.prefix}/configuration?page_size=1`, access);
+        if (!Number.isSafeInteger(revision.configuration_revision) || revision.configuration_revision < 1)
+            throw invalid();
+        const metadata = { name: input.name, phase: input.phase, device_key: device,
+            configuration_revision: revision.configuration_revision, value_stored_locally: true };
+        await approved(options, `Keep ${input.name} in this OS credential store and map it to ${input.phase} on this device only? Managed execution will require a different mapping.`);
+        id = randomUUID();
+        output({ id, world_id: context.world, workspace_id: context.workspace, value_uploaded: false }, `Local request ${id}\nRecover: firedrill values recover ${id} --workspace ${context.workspace} --world ${context.world}`);
+        let value = await readPrivateValue(options);
+        try {
+            await saveLocalValue(context, id, metadata, value);
+        }
+        finally {
+            value = '';
+        }
+        const result = await original(context, options, id, metadata);
+        output(result, describe(result));
+        return;
+    }
+    if (!id && interactive(options) && action !== 'recover')
+        id = (await choosePaged('Local value', path, context, options, row => ({ label: row.name, detail: `${row.phase} · ${row.device_label} · ${row.state}` }), false, (selectedPage, search) => page(context, options, selectedPage, search)))?.id;
+    if (!id)
+        throw new CliError('local_value_required', 'Choose a saved reference ID or use its original recovery ID.', 2);
+    id = identifier(id);
+    if (action === 'recover') {
+        const saved = await savedLocalValue(context, id);
+        try {
+            await approved(options, 'Continue the original local-value reference request without uploading its value?');
+            const prior = await lookup(context, options, id);
+            const result = prior.state === 'not_retained' ? await original(context, options, id, saved.metadata) : prior;
+            if (!localValueOriginalMatches(result, context, id, saved.metadata, digest(saved.metadata)))
+                throw responseInvalid();
+            output(result, describe(result));
+        }
+        finally {
+            saved.value = '';
+        }
+        return;
+    }
+    if (action === 'remove') {
+        await approved(options, 'Revoke this cloud reference? Its private value remains on this OS until explicitly forgotten.');
+        const result = await api(`${path}/${id}`, { ...access, method: 'DELETE' });
+        const retained = await lookup(context, options, id);
+        if (!localValueRegistrationMatches(result, context, id) || result.state !== 'revoked' || retained.state === 'not_retained'
+            || retained.state !== 'revoked' || nativeMetadataCanonical(result) !== nativeMetadataCanonical(retained))
+            throw responseInvalid();
+        output(retained, `${describe(retained)}\nRemove the private copy separately with firedrill values forget ${id} --workspace ${context.workspace} --world ${context.world}.`);
+        return;
+    }
+    const result = await lookup(context, options, id);
+    output(result, result.state === 'not_retained' ? 'No matching reference is retained. No value was read.' : describe(result));
+}

package/dist/cli/src/login-organizations.js

@@ -0,0 +1,70 @@
+import { createInterface } from 'node:readline/promises';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+export function loginOrganizationIdentifier(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^org_[A-Za-z0-9]{1,120}$/.test(value) && !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(value))
+        throw new CliError('organization_invalid', 'Use an organization ID from firedrill workspace organizations.', 2);
+    return value;
+}
+export async function chooseLoginOrganization(read, options) {
+    if (options.organization) {
+        const page = await read('', 1, options.organization);
+        if (page.results.length !== 1 || page.count !== 1)
+            throw new CliError('organization_not_available', page.membership_sync.state === 'running'
+                ? 'Organization access is still being checked. Finish workspace discovery, then authorize the selected organization again.'
+                : 'This organization is not available to the signed-in account. No workspace access was granted.', 2);
+        return page.results[0].workos_organization_id;
+    }
+    // Scripts keep the provider's original grant unless they explicitly request
+    // another organization. No hidden prompt, all-page fetch or scope expansion.
+    if (options.json || !process.stdin.isTTY || !process.stderr.isTTY)
+        return undefined;
+    let number = 1, query = '';
+    while (true) {
+        const page = await read(query, number);
+        if (page.count === 1 && !query && page.membership_sync.state !== 'running')
+            return page.results[0].workos_organization_id;
+        if (!page.count && !query && page.membership_sync.state !== 'running')
+            return undefined;
+        const choices = page.results.map(row => ({ value: row.workos_organization_id, label: row.name,
+            detail: row.workos_organization_id === page.grant_organization_id ? 'Current sign-in' : '' }));
+        if (number > 1)
+            choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+        if (page.next)
+            choices.push({ value: 'next', label: 'Next page', detail: '' });
+        if (page.membership_sync.state === 'running')
+            choices.push({ value: 'refresh', label: 'Check organization access again', detail: 'Access discovery is running.' });
+        choices.push({ value: 'search', label: query ? 'Change search' : 'Search organizations', detail: query }, { value: 'cancel', label: 'Cancel', detail: '' });
+        const choice = await selectOne('Organization', choices, options.signal);
+        if (choice === 'cancel')
+            throw new CliError('canceled', 'Organization selection canceled. No workspace access was granted.', 130);
+        if (choice === 'previous') {
+            number--;
+            continue;
+        }
+        if (choice === 'next') {
+            number++;
+            continue;
+        }
+        if (choice === 'refresh')
+            continue;
+        if (choice === 'search') {
+            const prompt = createInterface({ input: process.stdin, output: process.stderr, terminal: false });
+            try {
+                query = (await prompt.question('Find organizations (blank for all): ', { signal: options.signal })).trim();
+                if (query.length > 200 || /[\u0000-\u001f\u007f-\u009f]/.test(query))
+                    throw new CliError('search_invalid', 'Use search text up to 200 characters without terminal controls.', 2);
+                number = 1;
+            }
+            finally {
+                prompt.close();
+            }
+            continue;
+        }
+        if (!page.results.some(row => row.workos_organization_id === choice))
+            throw new CliError('organization_unconfirmed', 'The organization selection could not be confirmed.', 2);
+        return choice;
+    }
+}