firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/simple/plan-apply.js

@@ -0,0 +1,506 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { CliError } from '../http.js';
+import { selectOne, terminalText } from '../prompts.js';
+import { approveCredits } from './credit-approval.js';
+import { requestInput } from '../request-input.js';
+import { selectedWorkspace } from '../world-access.js';
+import { applyNativePlan, cancelPreparedApply, cancelUnstartedApply, createApplyPlan, createNativeCampaign, estimatePlanFunding, findNativeApplyOperation, getApplyPlan, getNativeApplyOperation, getWorldRevision, latestWorldRevision, } from '../native/cloud-resources.js';
+import { jitteredInterval, retryTransient, sleep } from '../native/control-plane.js';
+import { activeTime } from '../native/contracts.js';
+const MAX_INPUT_BYTES = 1024 * 1024;
+/** Read one bounded JSON object from a file path, or from stdin when the path is "-". */
+export async function readJsonInput(path, label, signal, maximumBytes = MAX_INPUT_BYTES) {
+    if (!path)
+        throw new CliError('input_required', `Provide ${label} as a file path, or - to read it from standard input.`, 2);
+    if (path !== '-')
+        return requestInput(path, signal, maximumBytes);
+    if (process.stdin.isTTY)
+        throw new CliError('input_required', `Pipe ${label} on standard input when using -. Typed input is not read.`, 2);
+    const chunks = [];
+    let size = 0;
+    const onAbort = () => process.stdin.destroy();
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        for await (const chunk of process.stdin) {
+            signal.throwIfAborted();
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            size += bytes.length;
+            if (size > maximumBytes)
+                throw new CliError('request_file_invalid', `${label} exceeds ${maximumBytes} bytes. Nothing was submitted.`, 2);
+            chunks.push(bytes);
+        }
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+    signal.throwIfAborted();
+    try {
+        const raw = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+        const value = JSON.parse(raw);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error();
+        return raw;
+    }
+    catch {
+        throw new CliError('request_file_invalid', `${label} on standard input is not a JSON object. Nothing was submitted.`, 2);
+    }
+}
+/** Parse bounded JSON input into an object, with a stable error when it is not one. */
+export async function readJsonObject(path, label, signal, maximumBytes = MAX_INPUT_BYTES) {
+    const raw = await readJsonInput(path, label, signal, maximumBytes);
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        value = null;
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new CliError('request_file_invalid', `${label} is not a JSON object. Nothing was submitted.`, 2);
+    return value;
+}
+const scopeOf = (options) => selectedWorkspace({ workspace: options.workspace, signal: options.signal,
+    interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY, openBrowser: options.openBrowser && !options.json });
+/** Plain words for the review's requirement codes; the code and resource stay exactly as the service returned them. */
+const GAP_TEXT = {
+    resource_adapter_required: 'a saved resource needs a compatible execution adapter',
+    scenario_evaluation_required: 'select an evaluation for this scenario',
+    scenario_dependency_missing: 'an event refers to a dependency missing from this world',
+    real_dependency_event_unsupported: 'a simulated availability event cannot change a real account',
+    scenario_required: 'add at least one scenario',
+    parallel_state_boundary_required: 'use isolated state for each drill or choose serial execution',
+    local_state_reset_required: 'configure a reset for the local state before running independent drills',
+    configuration_mapping_required: 'declare the required build or runtime configuration',
+    dependency_mapping_incomplete: 'map each required dependency to a hosted tool or an explicitly authorized real connection',
+    dependency_contract_mismatch: 'the selected tool contract does not match the agent dependency',
+    tool_operation_unavailable: 'the selected tool is missing a required operation',
+    tool_protocol_mismatch: 'the tool connection protocol does not match the agent dependency',
+    library_parameters_require_binding: 'this library version declares parameters: bind it with firedrill library bind <version-id> --file <values.json> '
+        + 'and reference the bound version instead',
+};
+/** Characters of one bound parameter value shown in the review; the full value is in the bound version. */
+const BOUND_PREVIEW = 80;
+/** How each hosted tool runs, from the review's `tool_execution` (root lanes; an unlisted lane is shown by its code). */
+const LANE_TEXT = {
+    pooled: 'shared tool worker (reviewed catalog version)',
+    isolated: 'isolated runtime (own run time, cleanup and cost ceiling per drill)',
+};
+function laneLines(review) {
+    const lanes = Array.isArray(review.tool_execution) ? review.tool_execution : [];
+    const real = new Set(review.real_dependency_grants);
+    const dependencies = Array.isArray(review.dependencies) ? review.dependencies : [];
+    const lines = lanes.filter(item => typeof item.alias === 'string').map(item => `  ${terminalText(item.alias)}: hosted tool, `
+        + (typeof item.lane === 'string' && Object.hasOwn(LANE_TEXT, item.lane) ? LANE_TEXT[item.lane] : terminalText(String(item.lane))));
+    for (const dependency of dependencies) {
+        if (typeof dependency.alias === 'string' && dependency.mode === 'real') {
+            lines.push(`  ${terminalText(dependency.alias)}: real account${real.has(dependency.alias) ? ' (grant still needed)' : ''}`);
+        }
+    }
+    return lines.length ? ['Dependencies:', ...lines] : [];
+}
+/**
+ * The exact parameter values fixed in bound library versions this plan uses
+ * (root's `parameter_bindings`), shown before approval because they decide
+ * what the drills say and check. Values are service data, terminal-escaped.
+ */
+function bindingLines(review) {
+    const items = Array.isArray(review.parameter_bindings) ? review.parameter_bindings : [];
+    const lines = [];
+    for (const item of items) {
+        const binding = item.binding && typeof item.binding === 'object' ? item.binding : null;
+        if (typeof item.revision_id !== 'string' || !binding || !binding.values || typeof binding.values !== 'object')
+            continue;
+        const values = Object.entries(binding.values).map(([name, value]) => {
+            const text = typeof value === 'string' ? JSON.stringify(value.length > BOUND_PREVIEW ? `${value.slice(0, BOUND_PREVIEW)}...` : value) : String(value);
+            return `${terminalText(name)}=${terminalText(text)}`;
+        });
+        lines.push(`  ${terminalText(item.revision_id)}${typeof binding.source_revision_id === 'string' ? ` (bound from ${terminalText(binding.source_revision_id)})` : ''}: `
+            + (values.length ? values.join(', ') : 'all parameters at their defaults'));
+    }
+    return lines.length ? ['Parameter values fixed in bound library versions:', ...lines] : [];
+}
+/**
+ * Root's evolution review for v3 scenarios (absent for earlier ones): how each
+ * scenario's schedule behaves without the agent. A world-only continuation is
+ * approved together with the plan, so it is spelled out before the approval.
+ */
+function evolutionLines(review) {
+    const items = Array.isArray(review.evolution) ? review.evolution : [];
+    const lines = items.filter(item => typeof item.scenario_id === 'string').map(item => {
+        const timed = typeof item.timed_occurrences === 'number' && item.timed_occurrences > 0
+            ? `${item.timed_occurrences} timed event(s)${typeof item.max_after_active_ms === 'number' ? `, the last at ${activeTime(item.max_after_active_ms)} of active time` : ''}`
+            : 'no timed events';
+        const mode = item.mode === 'world_only' && typeof item.continuation_seconds === 'number'
+            ? `the world keeps evolving for up to ${activeTime(item.continuation_seconds * 1000)} without the agent`
+            : item.mode === 'pause_with_agent' ? 'the schedule pauses while the agent is disconnected' : terminalText(String(item.mode));
+        return `  ${terminalText(item.scenario_id)}: ${timed}; ${mode}`;
+    });
+    if (!lines.length)
+        return [];
+    return ['Scenario timing (real active time, never accelerated):', ...lines,
+        ...items.some(item => item.mode === 'world_only')
+            ? ['  Approving this plan approves that world-only continuation. It never extends a deadline, funding or capacity, and never starts or resumes the agent.']
+            : []];
+}
+/** Human summary of an effect-free plan review. Values are service data, so every field is terminal-escaped. */
+function reviewText(plan, requestKey) {
+    const review = plan.review;
+    const nested = review.changes && typeof review.changes === 'object' ? review.changes.changes : undefined;
+    const changes = Array.isArray(nested) ? nested : [];
+    const gaps = review.gaps;
+    const text = (value) => terminalText(typeof value === 'string' ? value : value === null || value === undefined ? '-' : JSON.stringify(value));
+    return [
+        `Plan ${plan.id}${plan.expired ? ' (expired)' : ''}`,
+        `World revision: ${plan.world_revision_id}`,
+        `Review digest: ${plan.review_digest}`,
+        `Expires: ${terminalText(plan.expires_at)}`,
+        typeof review.requested_drills === 'number' ? `Requested drills: ${review.requested_drills}` : null,
+        typeof review.requires_serial === 'boolean' ? `Serial execution: ${review.requires_serial ? 'yes' : 'no'}` : null,
+        changes.length ? 'Changes:' : 'Changes: none since the previous declaration',
+        ...changes.map(change => `  ${text(change.change)} ${text(change.field)} ${text(change.identity)}`),
+        ...laneLines(review),
+        ...bindingLines(review),
+        ...evolutionLines(review),
+        gaps.length ? 'Unresolved requirements (apply is refused until these are fixed):' : 'Unresolved requirements: none',
+        ...gaps.map(gap => `  ${text(gap.code)}${gap.resource_id ? ` (${text(gap.resource_id)})` : ''}`
+            + (typeof gap.code === 'string' && Object.hasOwn(GAP_TEXT, gap.code) ? `: ${GAP_TEXT[gap.code]}` : '')),
+        review.real_dependency_grants.length ? `Real-access grants still needed: ${review.real_dependency_grants.map(terminalText).join(', ')}` : null,
+        `Gates checked at apply: ${review.required_gates.map(terminalText).join(', ')}`,
+        'This review allocates nothing, starts nothing and spends no credits.',
+        requestKey ? `Request key: ${requestKey} (replay with --world-revision ${plan.world_revision_id} --request ${requestKey})` : null,
+    ].filter((line) => line !== null).join('\n');
+}
+/** Service units as an exact decimal amount when the scale is a power of ten. */
+export function amount(units, scale, denomination) {
+    const name = terminalText(denomination);
+    if (!/^10*$/.test(String(scale)))
+        return `${units} units (${scale} per ${name})`;
+    const digits = String(scale).length - 1;
+    const fraction = digits ? String(units % scale).padStart(digits, '0').replace(/0+$/, '') : '';
+    return `${Math.floor(units / scale)}${fraction ? `.${fraction}` : ''} ${name}`;
+}
+/** Plain words for root's quote components; a component not listed here is shown by its code. */
+const COMPONENT_TEXT = {
+    participants: 'synthetic participants', evaluation: 'evaluation', tool_state: 'catalog tool state',
+    baseline: 'tool preparation', isolated_runtime: 'isolated custom tools',
+};
+/** A whole-second ceiling in the largest exact unit. */
+function span(seconds) {
+    return seconds % 3600 === 0 ? `${seconds / 3600} h` : seconds % 60 === 0 ? `${seconds / 60} min` : `${seconds} s`;
+}
+/** The ceilings a quote freezes, in words. */
+function quoteLimits(quote) {
+    if (quote.participant_limits)
+        return ` (${terminalText(quote.participant_limits.model)}, up to ${quote.participant_limits.max_steps} steps)`;
+    const limits = quote.isolated_limits;
+    if (!limits)
+        return '';
+    const memory = limits.memory_mb % 1024 === 0 ? `${limits.memory_mb / 1024} GiB` : `${limits.memory_mb} MiB`;
+    return ` (each tool per drill: up to ${span(limits.duration_seconds)} running plus up to ${span(limits.cleanup_seconds)} cleanup;`
+        + ` ${limits.cpu_units} CPU, ${memory} memory, ${limits.disk_gb} GB disk)`;
+}
+/** Human summary of a cloud-work estimate. It reserves nothing and never charges local target compute. */
+function estimateText(estimate) {
+    const money = (units) => amount(units, estimate.credit_scale, estimate.denomination);
+    return [
+        `Cloud-work estimate (maximum, nothing reserved): ${money(estimate.maximum_units)}`,
+        ...estimate.quotes.map(quote => `  ${COMPONENT_TEXT[quote.component] ?? terminalText(quote.component)}: up to ${money(quote.maximum_units)}`
+            + quoteLimits(quote)),
+        estimate.reservation_policy === 'baseline_then_admitted_drills' && estimate.initial_reservation_units !== null
+            ? `Apply first reserves ${money(estimate.initial_reservation_units)} for tool preparation (the baseline); each drill reserves its share only when it is`
+                + ' admitted, so the whole maximum is never held up front.'
+            : null,
+        `Local target compute is not charged. Estimate expires: ${terminalText(estimate.expires_at)}`,
+    ].filter((line) => line !== null).join('\n');
+}
+/**
+ * `plan --world <world-id> [--world-revision <id>] [--request <key>]` creates an
+ * effect-free review of the world's newest (or pinned) declaration;
+ * `plan show <plan-id>` reads a saved review.
+ */
+export async function planCommand(args, options, emit) {
+    if (args[0] === 'show') {
+        if (args.length !== 2 || options.world !== undefined || options.worldRevision !== undefined || options.request !== undefined)
+            throw new CliError('arguments_invalid', 'Use firedrill plan show <plan-id>.', 2);
+        const scope = await scopeOf(options);
+        const plan = await getApplyPlan(scope, { planId: args[1], signal: options.signal });
+        emit('plan', plan, reviewText(plan));
+        return;
+    }
+    if (args.length || !options.world)
+        throw new CliError('arguments_invalid', 'Use firedrill plan --world <world-id> [--world-revision <revision-id>], or firedrill plan show <plan-id>.', 2);
+    // A replay reviews the revision the original did; resolving the newest again could review a different declaration.
+    if (options.request !== undefined && options.worldRevision === undefined)
+        throw new CliError('arguments_invalid', 'A plan replay needs the world revision the original reviewed. Rerun with --world-revision <id> '
+            + '(the plan\'s world_revision_id, printed with its request key) and the same --request. Nothing was submitted.', 2);
+    const scope = await scopeOf(options);
+    const revision = options.worldRevision !== undefined
+        ? await getWorldRevision(scope, { worldId: options.world, revisionId: options.worldRevision, signal: options.signal })
+        : await latestWorldRevision(scope, { worldId: options.world, signal: options.signal });
+    const plan = await createApplyPlan(scope, { worldRevisionId: revision.id, worldDigest: revision.definition_digest,
+        requestKey: options.request, signal: options.signal });
+    // The estimate is informational here; apply requires it again before approval.
+    let estimate = null, estimateProblem = null;
+    if (!plan.review.gaps.length && !plan.expired) {
+        try {
+            estimate = await estimatePlanFunding(scope, { planId: plan.id, reviewDigest: plan.review_digest, signal: options.signal });
+        }
+        catch (error) {
+            if (options.signal.aborted)
+                throw error;
+            estimateProblem = error instanceof CliError ? error.code : 'estimate_unavailable';
+        }
+    }
+    emit('plan', { ...plan, estimate, estimate_error: estimateProblem }, reviewText(plan, plan.request_key)
+        + (estimate ? `\n${estimateText(estimate)}` : estimateProblem ? `\nCloud-work estimate unavailable (${estimateProblem}).` : '')
+        + (plan.review.gaps.length ? '' : `\nAfter the human approves it: firedrill apply ${plan.id} --approve --follow`));
+}
+const APPLY_FOLLOW_MS = 5_000;
+const PREPARING = new Set(['accepted', 'queued', 'provisioning', 'reconciling']);
+/** Plain words for a preparation state; none of them means a target may start. */
+function preparationText(operation) {
+    const capacity = operation.capacity;
+    const words = {
+        accepted: 'approved; preparation credits reserved', queued: 'queued for preparation', provisioning: 'preparing cloud capacity',
+        reconciling: 'reconciling an uncertain preparation step', ready: 'ready', failed: 'failed', cancelled: 'cancelled',
+    };
+    return `Preparation ${operation.id}: ${words[operation.state]}`
+        + (operation.failure_code ? ` (${terminalText(operation.failure_code)})` : '')
+        + (capacity && capacity.reason ? `; capacity ${terminalText(capacity.state)}: ${terminalText(capacity.reason)}` : '');
+}
+/**
+ * A stable request key per preparation and purpose (for `funding`, per apply
+ * request key), so a rerun replays instead of asking twice.
+ */
+function operationKey(purpose, operationId) {
+    const hex = createHash('sha256').update(`firedrill.native-${purpose}.v1\0${operationId}`).digest('hex');
+    const variant = ((parseInt(hex.slice(16, 17), 16) & 0x3) | 0x8).toString(16);
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-${variant}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+const preparedCancelled = (operation) => operation.state === 'cancelled' && operation.failure_code === 'prepared_unused_cancelled';
+const unstartedCancelled = (operation) => operation.state === 'cancelled' && operation.failure_code === 'cancelled_before_creation';
+/** The service alone proves no effects. A lost response never triggers an automatic second POST. */
+async function cancelUnstarted(scope, plan, operation, requestKey, options, emit) {
+    const recovery = `firedrill apply ${plan.id} --request ${requestKey} --cancel`;
+    const effect = 'Cancels this queued preparation only if no preparation effect has started. Its unused credit hold is released. Saved records are retained; this does not stop a running agent or delete data.';
+    const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    let approved = options.approve === true;
+    if (!approved && interactive) {
+        approved = await selectOne(`Cancel queued preparation ${operation.id}?`, [
+            { value: false, label: 'Keep it', detail: 'Nothing is cancelled.' },
+            { value: true, label: 'Cancel preparation', detail: effect },
+        ], options.signal);
+    }
+    if (!approved)
+        throw new CliError('apply_cancel_approval_required', `${effect} Review it, then rerun: ${recovery} --approve. Nothing was cancelled.`, 2);
+    const cancelKey = operationKey('unstarted-cancel', operation.id);
+    emit('apply_cancel_request', { operation_id: operation.id, request_key: cancelKey, recovery_command: `${recovery} --approve` }, `Cancelling queued preparation ${operation.id}. If the response is interrupted, inspect the original and use the same recovery command: ${recovery} --approve.`);
+    let receipt;
+    try {
+        receipt = await cancelUnstartedApply(scope, { operationId: operation.id, requestKey: cancelKey, reviewDigest: plan.review_digest, signal: options.signal });
+    }
+    catch (error) {
+        if (options.signal.aborted)
+            throw error;
+        const current = await getNativeApplyOperation(scope, { operationId: operation.id, signal: AbortSignal.timeout(15_000) }).catch(() => null);
+        if (current)
+            emit('apply_operation', current, unstartedCancelled(current)
+                ? `${preparationText(current)}. The preparation is cancelled, but this read does not verify the cancellation receipt.`
+                : `${preparationText(current)}. The cancellation receipt was not confirmed.`);
+        // Even a cancelled readback cannot prove this request's receipt. A later
+        // explicit same-key invocation may recover it; never automatically retry.
+        if (error instanceof CliError && error.httpStatus !== null && error.httpStatus >= 400 && error.httpStatus < 500)
+            throw error;
+        throw new CliError('native_apply_cancel_unconfirmed', `The cancellation receipt was not confirmed. Read the original preparation; to recover the same cancellation receipt, use: ${recovery} --approve. No second cancellation was sent.`, 1);
+    }
+    emit('apply_cancelled', { ...receipt, plan_id: plan.id }, `Queued preparation ${receipt.operation_id} cancelled before effects started. Its unused credit hold was released. Saved records are retained. Receipt ${receipt.receipt_digest}.`);
+}
+/**
+ * `apply <plan-id> --request <key> --cancel` cancels an explicitly eligible
+ * unstarted queue entry or a ready preparation without a campaign, after approval.
+ * Root releases the unused reserved
+ * run credits; the prepared data is retained for normal retention, not purged
+ * by this request. The cancellation key is derived from the preparation, so a
+ * rerun replays the original receipt instead of sending a second cancellation.
+ */
+async function cancelPrepared(scope, plan, operation, requestKey, options, emit) {
+    const recovery = `firedrill apply ${plan.id} --request ${requestKey} --cancel`;
+    if (operation.can_request_unstarted_cancellation || unstartedCancelled(operation)) {
+        return cancelUnstarted(scope, plan, operation, requestKey, options, emit);
+    }
+    if (preparedCancelled(operation)) {
+        emit('apply_operation', operation, `${preparationText(operation)}. It was already cancelled; nothing else was sent.`);
+        return;
+    }
+    if (!operation.can_request_prepared_cancellation) {
+        const why = operation.state === 'ready'
+            ? 'It already has a campaign. Cancel that instead: firedrill simulation cancel <campaign-id>.'
+            : PREPARING.has(operation.state) ? `It is not ready yet. Wait with firedrill apply ${plan.id} --request ${requestKey} --follow, then cancel.`
+                : `It is already ${operation.state}.`;
+        throw new CliError('native_apply_cancel_unavailable', `${preparationText(operation)}. Only a ready preparation with no campaign can be cancelled here. ${why} Nothing was cancelled.`, 2);
+    }
+    const effect = 'Releases the unused reserved run credits for this prepared world (preparation usage is already settled). No campaign can be created from it afterwards. The prepared data is kept until normal retention removes it; this does not purge it.';
+    const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    let approved = options.approve === true;
+    if (!approved && interactive) {
+        approved = await selectOne(`Cancel prepared world ${operation.id}?`, [
+            { value: false, label: 'Keep it', detail: 'Nothing is cancelled.' },
+            { value: true, label: 'Cancel it', detail: effect },
+        ], options.signal);
+    }
+    if (!approved)
+        throw new CliError('apply_cancel_approval_required', `${effect} Review it, then rerun with --approve. Nothing was cancelled.`, 2);
+    const cancelKey = operationKey('prepared-cancel', operation.id);
+    emit('apply_cancel_request', { operation_id: operation.id, request_key: cancelKey, recovery_command: `${recovery} --approve` }, `Cancelling prepared world ${operation.id}. If this is interrupted, rerun: ${recovery} --approve (it replays the same request).`);
+    let receipt;
+    try {
+        receipt = await cancelPreparedApply(scope, { operationId: operation.id, requestKey: cancelKey, reviewDigest: plan.review_digest, signal: options.signal });
+    }
+    catch (error) {
+        if (options.signal.aborted)
+            throw error;
+        // A rejected or unanswered request is resolved from the preparation itself, never by a second cancellation key.
+        const current = await getNativeApplyOperation(scope, { operationId: operation.id, signal: AbortSignal.timeout(15_000) }).catch(() => null);
+        if (current && preparedCancelled(current)) {
+            emit('apply_operation', current, `${preparationText(current)}. The cancellation is recorded${error instanceof CliError && error.code === 'idempotency_conflict' ? ' under an earlier request' : ''}; its receipt was not received here.`);
+            return;
+        }
+        if (error instanceof CliError && error.httpStatus !== null && error.httpStatus >= 400 && error.httpStatus < 500)
+            throw error;
+        throw new CliError('native_apply_cancel_unconfirmed', `The cancellation may or may not have reached Firedrill. Rerun: ${recovery} --approve (the same request is replayed, never sent twice).`, 1);
+    }
+    emit('apply_cancelled', { ...receipt, plan_id: plan.id }, `Prepared world ${receipt.operation_id} cancelled. Unused reserved run credits were released. Its prepared data is kept until normal retention removes it. Receipt ${receipt.receipt_digest}.`);
+}
+/**
+ * `apply <plan-id> [--approve] [--request <key>] [--follow]` re-reads the
+ * review, refuses expired or incomplete plans and asks for explicit approval
+ * with the maximum cloud-work cost in view. Approval reserves the preparation
+ * first (drill work is reserved in bounded waves as drills are admitted, within
+ * the approved maximum) and queues preparation; the command shows the real preparation state and,
+ * once the service reports it ready, creates the campaign (drill slots only).
+ * Nothing here starts a target: `firedrill run --campaign` does, on this machine.
+ * `--request` with the printed key reads the original preparation (no second
+ * approval or charge). When none is recorded yet, it reviews the same quotes
+ * again and, once approved, sends the same request under the same key, which
+ * the service applies at most once. `--follow` waits until it is ready, failed
+ * or cancelled.
+ */
+export async function applyCommand(args, options, emit) {
+    if (args.length !== 1 || options.world !== undefined || options.worldRevision !== undefined)
+        throw new CliError('arguments_invalid', 'Use firedrill apply <plan-id> with the plan ID returned by firedrill plan.', 2);
+    if (options.request !== undefined && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(options.request))
+        throw new CliError('arguments_invalid', 'Use --request with the apply request key Firedrill printed. Nothing was applied.', 2);
+    if (options.cancel && (options.request === undefined || options.follow))
+        throw new CliError('arguments_invalid', 'Use firedrill apply <plan-id> --request <key> --cancel with the apply request key Firedrill printed. Nothing was cancelled.', 2);
+    if (options.cancel && options.approveCredits !== undefined)
+        throw new CliError('arguments_invalid', '--approve-credits does not apply to cancellation. Nothing was cancelled.', 2);
+    const scope = await scopeOf(options);
+    const retry = { signal: options.signal, attempts: 4 };
+    const plan = await retryTransient(() => getApplyPlan(scope, { planId: args[0], signal: options.signal }), retry);
+    const requestKey = (options.request ?? randomUUID()).toLowerCase();
+    const recovery = `firedrill apply ${plan.id} --request ${requestKey}${options.follow ? ' --follow' : ''}`;
+    // A retained preparation under this key is read, never approved or charged again.
+    let operation = options.request ? await retryTransient(() => findNativeApplyOperation(scope, { requestKey, signal: options.signal }), retry) : null;
+    let landedFirst = false;
+    if (operation && operation.plan_id !== plan.id) {
+        throw new CliError('idempotency_conflict', 'That request key belongs to a different plan. Use the key printed for this plan. Nothing was applied.', 2);
+    }
+    if (options.cancel) {
+        if (!operation)
+            throw new CliError('native_apply_not_found', 'No preparation was found under that request key. Nothing was cancelled.', 2);
+        return cancelPrepared(scope, plan, operation, requestKey, options, emit);
+    }
+    if (!operation) {
+        if (plan.expired)
+            throw new CliError('native_plan_expired', 'This review expired. Run firedrill plan again. Nothing was applied.', 2);
+        if (plan.review.gaps.length) {
+            emit('plan', plan, reviewText(plan));
+            throw new CliError('native_plan_requirements_unmet', 'Resolve the listed requirements and create a new plan. Nothing was applied.', 2);
+        }
+        // A human approves with the maximum cloud-work cost in view; without an estimate nothing is applied.
+        // The estimate's key follows the apply key, so a rerun under it gets the original quotes back and sends the
+        // same request, which the service replays instead of refusing as a different budget under the same key.
+        const estimateKey = operationKey('funding', requestKey);
+        let estimate = await retryTransient(() => estimatePlanFunding(scope, { planId: plan.id, reviewDigest: plan.review_digest,
+            requestKey: estimateKey, signal: options.signal }), retry);
+        // Expired quotes can never be reserved, so a rerun reviews fresh ones instead of failing the same way every time.
+        if (options.request && !(Date.parse(estimate.expires_at) > Date.now())) {
+            const renewalKey = randomUUID();
+            estimate = await retryTransient(() => estimatePlanFunding(scope, { planId: plan.id, reviewDigest: plan.review_digest,
+                requestKey: renewalKey, signal: options.signal }), retry);
+        }
+        const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+        let approved = options.approve === true;
+        if (!approved && interactive)
+            process.stderr.write(reviewText(plan) + '\n');
+        emit('plan_estimate', estimate, estimateText(estimate));
+        if (!approved && interactive) {
+            approved = await selectOne(`Apply plan ${plan.id} to the selected workspace?`, [
+                { value: false, label: 'Not now', detail: 'Nothing is applied and no credits are reserved.' },
+                { value: true, label: 'Apply plan', detail: 'Reserves preparation now and drill work as drills are admitted, within the approved maximum above. Prepares this exact plan; no target starts.' },
+            ], options.signal);
+        }
+        if (!approved) {
+            throw new CliError('apply_approval_required', options.request
+                ? `No preparation is recorded under request ${requestKey} yet, so the original may not have arrived. After the human approves the estimate above, `
+                    + `rerun: ${recovery} --approve. It is sent under the same key, so it is never applied or charged twice. Nothing was applied.`
+                : 'Review the plan, then rerun with --approve. Nothing was applied.', 2);
+        }
+        const creditApproval = await approveCredits(estimate.quotes, options, interactive, `${recovery} --approve`);
+        // Printed before sending, so an interrupted or unanswered request can be recovered without a second charge.
+        emit('apply_request', { plan_id: plan.id, request_key: requestKey, recovery_command: recovery }, `Applying plan ${plan.id}. If this is interrupted, check it with: ${recovery}`);
+        try {
+            operation = await applyNativePlan(scope, { planId: plan.id, reviewDigest: plan.review_digest,
+                quoteIds: estimate.quotes.map(quote => quote.id), budgetDigest: estimate.digest, requestKey, signal: options.signal, creditApproval });
+        }
+        catch (error) {
+            if (options.signal.aborted)
+                throw error;
+            if (error instanceof CliError && error.code === 'idempotency_conflict') {
+                // The key already holds a request with another budget: the original landed after the lookup above
+                // (or was sent with other quotes). Read and continue with it; nothing is applied or charged again.
+                const original = await findNativeApplyOperation(scope, { requestKey, signal: options.signal }).catch(() => undefined);
+                options.signal.throwIfAborted();
+                if (original === undefined) {
+                    throw new CliError('native_apply_unconfirmed', `A preparation is already recorded under this request key, but it could not be read. Nothing else was applied. Check it with: ${recovery}`, 1);
+                }
+                if (original === null || original.plan_id !== plan.id)
+                    throw error;
+                operation = original;
+                landedFirst = true;
+            }
+            else if (error instanceof CliError && error.httpStatus !== null && error.httpStatus >= 400 && error.httpStatus < 500) {
+                throw error;
+            }
+            else {
+                throw new CliError('native_apply_unconfirmed', `The apply request may or may not have reached Firedrill. Check it with: ${recovery}`, 1);
+            }
+        }
+    }
+    if (!operation)
+        throw new CliError('native_apply_unconfirmed', `The apply result could not be read. Check it with: ${recovery}`, 1);
+    emit('apply_operation', operation, preparationText(operation)
+        + (landedFirst ? '\nThe original request under this key landed first, so this is that preparation with its own approved budget; nothing was applied or charged again.' : ''));
+    while (options.follow && PREPARING.has(operation.state)) {
+        if (!await sleep(jitteredInterval(APPLY_FOLLOW_MS), options.signal))
+            break;
+        const operationId = operation.id;
+        const next = await retryTransient(() => getNativeApplyOperation(scope, { operationId, signal: options.signal }), { signal: options.signal, attempts: 4 });
+        if (next.state !== operation.state || next.state_revision !== operation.state_revision)
+            emit('apply_operation', next, preparationText(next));
+        operation = next;
+    }
+    options.signal.throwIfAborted();
+    if (operation.state === 'failed' || operation.state === 'cancelled') {
+        throw new CliError(operation.failure_code && /^[a-z0-9_]{1,64}$/.test(operation.failure_code) ? operation.failure_code : `native_preparation_${operation.state}`, `Preparation ${operation.state}. Reserved credits are released by the service. Create a new plan to try again.`, 1);
+    }
+    if (operation.state !== 'ready') {
+        emit('apply_pending', { operation_id: operation.id, state: operation.state, recovery_command: `firedrill apply ${plan.id} --request ${requestKey} --follow` }, `Not ready yet; no target has started. Check again with: firedrill apply ${plan.id} --request ${requestKey} --follow\n`
+            + `Rerunning that creates its campaign once ready. If it is no longer wanted, once ready release its unused credits instead: firedrill apply ${plan.id} --request ${requestKey} --cancel`);
+        return;
+    }
+    // Ready: allocate the campaign's drill slots. Still nothing starts until a runner on this machine takes them.
+    const campaign = await createNativeCampaign(scope, { operationId: operation.id, requestKey: operationKey('campaign', operation.id), signal: options.signal });
+    const runCommand = `firedrill run --plan <path> --descriptor <path> --campaign ${campaign.campaign_id}`;
+    emit('campaign_created', { ...campaign, operation_id: operation.id, next_command: runCommand }, `Campaign ${campaign.campaign_id}: ${campaign.planned_drills} drill(s) allocated; none started.\nRun them on this machine: ${runCommand}\nWatch: firedrill watch ${campaign.campaign_id} --follow`);
+}