firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/simple/watch.js

@@ -0,0 +1,28 @@
+import { CliError } from '../http.js';
+import { terminalText } from '../prompts.js';
+import { reportCommand } from '../campaign-reports.js';
+import { identifier } from '../world-contracts.js';
+import { nativeWatch } from './native-report.js';
+/**
+ * Campaign progress. A native campaign shows its drill slots and execution
+ * states from the native read routes, and --follow keeps polling until the
+ * campaign settles, for a bounded time. A retained campaign from the older world commands (retired
+ * for new work in this release) is read once from its retained report reads
+ * (execution slots and latest activity); there is nothing to follow.
+ */
+export async function watchCommand(args, options, emit) {
+    // firedrill simulations lists only retained campaigns, never ones created by firedrill apply.
+    if (args.length !== 1)
+        throw new CliError('arguments_invalid', 'Use firedrill watch <campaign> [--follow] with one campaign id. '
+            + 'A campaign from firedrill apply is named in its campaign_created output; firedrill apply <plan-id> --request <apply-request-key> '
+            + 'prints the same campaign again, with no second approval or charge. firedrill simulations lists only campaigns from the older world commands.', 2);
+    const campaign = identifier(args[0]);
+    if (await nativeWatch(campaign, options, emit))
+        return;
+    const report = (type) => (value, readable) => emit(type, value, readable.split('\n').map(terminalText).join('\n'));
+    const common = { json: options.json, workspace: options.workspace, openBrowser: options.openBrowser && !options.json, signal: options.signal };
+    await reportCommand([campaign, 'assignments'], common, report('campaign_assignments'));
+    await reportCommand([campaign, 'activity'], common, report('campaign_activity'));
+    emit('watch_snapshot', { campaign_id: campaign, retained: true, follow: { state: 'not_applicable', reason: 'retained_campaign' } }, (options.follow ? 'Retained campaign: one snapshot. --follow applies to campaigns created by firedrill apply.'
+        : 'Retained campaign: one snapshot.') + ' Run firedrill watch again to refresh.');
+}

package/dist/cli/src/simple/world-reuse.js

@@ -0,0 +1,586 @@
+// `firedrill world versions | version | recipients | grants | share |
+// share-request | withdraw-share-request | revoke | fork | fork-request |
+// withdraw-fork | dependents`:
+// reusing a world definition across workspaces of one organization.
+//
+// - Sharing grants one exact world revision to another workspace, read only or
+//   read and fork. Only an administrator of the owner workspace shares, lists
+//   grants or revokes, and only after the human approves. It shares the closed
+//   declaration only: never the owner's descriptor, sources, configuration
+//   values, credentials, spending or execution, and never the tools or library
+//   versions the declaration references (each needs its own access).
+// - Forking copies one usable revision into a new private world of this
+//   workspace, bound to this workspace's agent and descriptor revision, after
+//   the human approves. The declaration is the source as read, or the caller's
+//   remapped copy; the source is pinned by its exact digest. The fork is this
+//   workspace's own afterwards. Tool archive and state forks are different.
+// - Request keys are printed before anything is sent. The same key returns the
+//   original; a lost answer is read back or withdrawn, never sent under a new key.
+// Nothing here provisions, runs or spends anything.
+import { randomUUID } from 'node:crypto';
+import { CliError } from '../http.js';
+import { selectOne, terminalText } from '../prompts.js';
+import { selectedWorkspace } from '../world-access.js';
+import { errorCode, retryTransient } from '../native/control-plane.js';
+import { listLibraryRecipients } from '../native/library-sharing.js';
+import { answerLost } from '../native/metadata-requests.js';
+import { getNativeDescriptor, listNativeDescriptors } from '../native/registration.js';
+import { answeredRefusal, checkFork, declarationNeeds, forkWorld, getReusableWorld, listReusableWorlds, listWorldDependents, listWorldGrants, recoverWorldFork, recoverWorldGrant, revokeWorldGrant, shareWorldVersion, withdrawWorldFork, withdrawWorldGrantRequest, WORLD_DEPENDENT_KINDS, worldReuseId, } from '../native/world-reuse.js';
+import { readJsonObject } from './plan-apply.js';
+/** The verbs this module owns under `firedrill world`. */
+export const WORLD_REUSE_VERBS = new Set(['versions', 'version', 'recipients', 'grants', 'share', 'share-request', 'withdraw-share-request', 'revoke',
+    'fork', 'fork-request', 'withdraw-fork', 'dependents']);
+const RECOVER_MS = 15_000;
+const DEFINITION_BYTES = 2 * 1024 * 1024;
+const tty = (options) => !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+const scopeOf = (options) => selectedWorkspace({ workspace: options.workspace, signal: options.signal,
+    interactive: tty(options), openBrowser: options.openBrowser && !options.json });
+const sharedHere = (scope, row) => row.owner_workspace_id !== scope.workspace.toLowerCase();
+function pageNumber(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^[1-9][0-9]{0,6}$/.test(value))
+        throw new CliError('arguments_invalid', 'Use --page with a number of 1 or more.', 2);
+    return Number(value);
+}
+/** Who owns a world version and what this workspace may do with it. */
+export function worldAccess(scope, row) {
+    if (sharedHere(scope, row)) {
+        return `shared from workspace ${row.owner_workspace_id}: `
+            + `${row.can_use ? 'read and fork' : 'read only here (shared read only, or its world or agent is archived)'}; never editable here`;
+    }
+    return row.can_use ? 'owned by this workspace' : 'owned by this workspace; its world or agent is archived, so it cannot be forked until restored';
+}
+/** Why a world version cannot be forked here, with the one step that changes that. */
+function unusableText(scope, row) {
+    if (sharedHere(scope, row)) {
+        return `Workspace ${row.owner_workspace_id} shared this world version read only, or its world or agent is archived, so it cannot be forked here. `
+            + 'Ask its owner for read-and-fork access.';
+    }
+    return 'Its world or agent is archived. Restore it before forking this version.';
+}
+function versionLine(scope, row) {
+    return `  ${row.id}  ${terminalText(row.name)} v${row.revision}  ${worldAccess(scope, row)}  ${terminalText(row.created_at)}`;
+}
+function grantLine(grant) {
+    return `  ${grant.id}  workspace ${grant.recipient_workspace_id}  ${grant.allow_use ? 'read and fork' : 'read only'}  `
+        + `shared ${terminalText(grant.created_at)}${grant.revoked_at ? `  revoked ${terminalText(grant.revoked_at)}` : ''}`;
+}
+/** A fork's lines. The agent is named only when this run sent it; a fork read back by key does not record it. */
+function forkText(fork, lead, agentId) {
+    return [
+        `${lead} into a new private world ${fork.world_id}, revision ${fork.target_revision_id} (digest ${fork.target_digest}).`,
+        `Copied from world version ${fork.source_revision_id} at digest ${fork.source_digest}. Later changes to the source never reach it, `
+            + 'and revoking the share does not remove it.',
+        `Review it with: firedrill plan --world ${fork.world_id}`,
+        `Change it with firedrill world save --agent ${agentId ?? '<the agent it was forked for>'} --world ${fork.world_id} --expected-revision <n> `
+            + `--file <declaration.json|->, where <n> is its newest revision in firedrill world history ${fork.world_id}. `
+            + `The forked declaration is the definition in firedrill world show ${fork.world_id} ${fork.target_revision_id} --json`,
+        `Request key (rerun with --request to replay): ${fork.request_key}`,
+    ].join('\n');
+}
+/** Root answers 404 for a page past the last one; that is not a missing version. */
+const pastEnd = (page, otherwise) => (error) => {
+    if ((page ?? 1) > 1 && error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('page_not_found', `There is no page ${page}. Start again from --page 1.`, 2);
+    }
+    return otherwise(error);
+};
+const rethrow = (error) => { throw error; };
+/** Only an organization administrator shares, lists grants, revokes or lists recipients; root says so with admin_required. */
+const adminOnly = (error) => {
+    if (errorCode(error) === 'admin_required') {
+        throw new CliError('native_world_admin_required', 'Only an administrator of this organization can share world versions, list or revoke their '
+            + 'sharing, or list recipient workspaces. Nothing was shared or changed.', 3, error instanceof CliError ? error.httpStatus : null);
+    }
+    throw error;
+};
+const notReadable = (error) => {
+    if (error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('native_world_version_not_found', 'That is not a world version this workspace can read. Find them with firedrill world versions.', 2);
+    }
+    throw error;
+};
+/** Grants are listed and revoked by an administrator of the owner workspace only; any other workspace gets 404. */
+const ownerAdminOnly = (error) => {
+    if (errorCode(error) === 'admin_required')
+        return adminOnly(error);
+    if (error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('native_world_version_not_found', 'That is not a world version this workspace owns. Only the owner workspace lists or revokes '
+            + 'its sharing grants; find this workspace\'s versions with firedrill world versions.', 2);
+    }
+    throw error;
+};
+/** Each verb's arguments and flags, checked before anything is read or sent. */
+export function checkWorldReuseArguments(args, options) {
+    const [verb, first, second, third] = args;
+    const takes = {
+        versions: ['search', 'page'], version: [], recipients: ['search', 'page'], grants: ['page'], share: ['request', 'approve'], 'share-request': [],
+        'withdraw-share-request': ['approve'], revoke: ['approve'], fork: ['agent', 'descriptorRevision', 'file', 'request', 'approve'], 'fork-request': [], 'withdraw-fork': ['approve'],
+        dependents: ['kind', 'page'],
+    };
+    const flags = { kind: '--kind', file: '--file', search: '--search', archived: '--archived',
+        page: '--page', expectedRevision: '--expected-revision', request: '--request', agent: '--agent', world: '--world',
+        descriptorRevision: '--descriptor-revision', approve: '--approve-change', parameters: '--parameters', removeParameters: '--remove-parameters' };
+    const extra = Object.keys(flags)
+        .filter((flag) => options[flag] !== undefined && options[flag] !== false && !takes[verb]?.includes(flag));
+    if (extra.length)
+        throw new CliError('arguments_invalid', `firedrill world ${verb} does not take ${extra.map((flag) => flags[flag]).join(', ')}.`, 2);
+    const counts = { versions: 1, version: 2, recipients: 1, grants: 2, share: 4, 'share-request': 3, 'withdraw-share-request': 3,
+        revoke: 3, fork: 2,
+        'fork-request': 2, 'withdraw-fork': 2, dependents: 2 };
+    if (args.length !== counts[verb] || (verb === 'share' && third !== 'read' && third !== 'use') || (verb === 'fork' && options.agent === undefined)) {
+        throw new CliError('arguments_invalid', 'Use firedrill world versions [--search <prefix>], world version <version-id>, world recipients, '
+            + 'world grants <version-id>, world share <version-id> <workspace-id> read|use, world share-request|withdraw-share-request <version-id> <request-key>, '
+            + 'world revoke <version-id> <grant-id>, world fork <version-id> --agent <agent-id> [--descriptor-revision <id>] [--file <declaration.json|->], '
+            + 'world fork-request <request-key>, world withdraw-fork <request-key> or world dependents <version-id> [--kind fork|campaign].', 2);
+    }
+    const keyed = verb === 'fork-request' || verb === 'withdraw-fork';
+    if (first !== undefined)
+        worldReuseId(first, keyed ? 'request key' : 'world version id');
+    if (second !== undefined)
+        worldReuseId(second, verb === 'share' ? 'workspace id' : verb === 'revoke' ? 'grant id' : 'request key');
+    if (options.request !== undefined)
+        worldReuseId(options.request, 'request key');
+    if (options.agent !== undefined)
+        worldReuseId(options.agent, 'agent id');
+    if (options.descriptorRevision !== undefined)
+        worldReuseId(options.descriptorRevision, 'descriptor revision id');
+    if (verb === 'dependents' && options.kind !== undefined && !WORLD_DEPENDENT_KINDS.includes(options.kind)) {
+        throw new CliError('arguments_invalid', `Use --kind ${WORLD_DEPENDENT_KINDS.join('|')} with world dependents.`, 2);
+    }
+    if (options.search !== undefined && [...options.search].length > 120) {
+        throw new CliError('arguments_invalid', 'Use a name prefix of up to 120 characters.', 2);
+    }
+    pageNumber(options.page);
+}
+/** `share <version-id> <workspace-id> read|use [--request <key>] [--approve-change]`. */
+async function share(scope, args, options, emit) {
+    const [, version, recipientArg, mode] = args;
+    const signal = options.signal;
+    const recipient = worldReuseId(recipientArg, 'workspace id');
+    if (recipient === scope.workspace.toLowerCase()) {
+        throw new CliError('arguments_invalid', 'Share with another workspace of this organization; this one already owns the world. Nothing was sent.', 2);
+    }
+    const allowUse = mode === 'use';
+    const access = allowUse ? 'read and fork' : 'read only';
+    const requestKey = options.request === undefined ? randomUUID() : worldReuseId(options.request, 'request key');
+    const rerun = `firedrill world share ${version.toLowerCase()} ${recipient} ${mode} --request ${requestKey}`;
+    const read = `firedrill world share-request ${version.toLowerCase()} ${requestKey}`;
+    const row = await getReusableWorld(scope, { revisionId: version, signal }).catch(notReadable);
+    if (sharedHere(scope, row)) {
+        throw new CliError('native_world_share_owner_only', `Only workspace ${row.owner_workspace_id}, which owns this world, can share it. Nothing was sent.`, 2);
+    }
+    // A grant already made under this key is shown, never made again. The read
+    // is administrator-only, so a fresh key also confirms that before the human is asked.
+    const original = await recoverWorldGrant(scope, { revisionId: row.id, requestKey, signal }).catch(adminOnly);
+    if (original) {
+        if (original.recipient_workspace_id !== recipient || original.allow_use !== allowUse) {
+            throw new CliError('idempotency_conflict', `Request ${requestKey} shared this world version with workspace ${original.recipient_workspace_id} `
+                + `(${original.allow_use ? 'read and fork' : 'read only'}). Nothing was changed; share differently under a new request.`, 2);
+        }
+        emit('world_grant', original, `Already shared under request ${requestKey}:\n${grantLine(original)}`
+            + (original.revoked_at ? '\nThis grant was revoked. A request key is never renewed: to share again, start without --request.' : ''));
+        return;
+    }
+    emit('world_share_review', { version: row, recipient_workspace_id: recipient, allow_use: allowUse, request_key: requestKey }, [
+        `Share world ${terminalText(row.name)} v${row.revision} (version ${row.id}) with workspace ${recipient}: ${access}.`,
+        allowUse ? 'It can read this exact declaration and fork it into its own private worlds.'
+            : 'It can read this exact declaration, but not fork it.',
+        'The declaration holds references and configuration names only. That workspace never gets this workspace\'s descriptor, sources, configuration '
+            + 'values or credentials, and no access to the tools or library versions it references: those need their own sharing.',
+        'It can never edit this world. Revoking later stops new reads and forks; forks it already made stay its own.',
+        row.can_use ? null : 'Its world or agent is archived now, so it cannot be forked until restored (an archived world cannot be shared at all).',
+    ].filter((line) => line !== null).join('\n'));
+    let approved = options.approve === true;
+    if (!approved && tty(options)) {
+        approved = await selectOne(`Share this world version with workspace ${recipient} (${access})?`, [
+            { value: false, label: 'Not now', detail: 'Nothing is shared.' },
+            { value: true, label: 'Share it', detail: `Grants ${access} access to this exact declaration only.` },
+        ], signal);
+    }
+    if (!approved)
+        throw new CliError('world_share_consent_required', `Nothing was shared. After the human approves: ${rerun} --approve-change`, 2);
+    if (options.json)
+        emit('request_prepared', { request_key: requestKey }, '');
+    else
+        process.stderr.write(`Request key: ${requestKey} (if interrupted, rerun ${rerun} --approve-change; ${read} reads it back)\n`);
+    let grant;
+    try {
+        // The same key and body replay the original grant, so a retry never shares twice.
+        grant = await retryTransient(() => shareWorldVersion(scope, { revisionId: row.id, recipientWorkspaceId: recipient, allowUse, requestKey, signal }), { signal, attempts: 3 });
+    }
+    catch (error) {
+        if (errorCode(error) === 'admin_required')
+            adminOnly(error);
+        if (errorCode(error) === 'native_world_grant_withdrawn') {
+            throw new CliError('native_world_grant_withdrawn', `Sharing request ${requestKey} was withdrawn, so it will never land. Share again without --request `
+                + 'only if the human still wants it.', 2);
+        }
+        // A refusal with the service's own code wrote nothing; only an answer that never arrived is recovered by its key.
+        if (signal.aborted || !answerLost(error) || answeredRefusal(error)) {
+            if (error instanceof CliError && error.httpStatus === 404) {
+                throw new CliError('native_world_recipient_unavailable', 'That workspace is not another active workspace of this organization, or this world '
+                    + 'is archived. Find recipients with firedrill world recipients. Nothing was shared.', 2);
+            }
+            throw error;
+        }
+        const recovered = await recoverWorldGrant(scope, { revisionId: row.id, requestKey, signal: AbortSignal.timeout(RECOVER_MS) }).catch(() => null);
+        if (!recovered) {
+            throw new CliError('native_world_share_unconfirmed', `The share was not confirmed and may still land. Read it with ${read}, or rerun ${rerun} `
+                + '--approve-change, which returns the original instead of sharing twice. Before sharing differently, withdraw it: '
+                + `firedrill world withdraw-share-request ${row.id} ${requestKey} --approve-change. Never share it again under a new key.`);
+        }
+        if (recovered.recipient_workspace_id !== recipient || recovered.allow_use !== allowUse) {
+            throw new CliError('native_response_unconfirmed', `Request ${requestKey} recorded a different grant, not this share. Nothing else was sent. `
+                + `Read it with ${read}.`, 2);
+        }
+        grant = recovered;
+    }
+    emit('world_grant', grant, `Shared world ${terminalText(row.name)} v${row.revision} with workspace ${grant.recipient_workspace_id}: `
+        + `${grant.allow_use ? 'read and fork' : 'read only'}.\n${grantLine(grant)}\nRevoke it with firedrill world revoke ${row.id} ${grant.id}`);
+}
+/** `revoke <version-id> <grant-id> [--approve-change]`. */
+async function revoke(scope, args, options, emit) {
+    const [, version, grantArg] = args;
+    const signal = options.signal;
+    const revisionId = worldReuseId(version, 'world version id');
+    const grantId = worldReuseId(grantArg, 'grant id');
+    // Revoked by its exact id: root's revoke needs no listing, and grant history
+    // is never searched (an old grant may sit beyond any page bound). The
+    // original-request read is administrator-only, so reading a fresh key
+    // confirms that before the human is asked. It changes nothing.
+    await recoverWorldGrant(scope, { revisionId, requestKey: randomUUID(), signal }).catch(ownerAdminOnly);
+    const command = `firedrill world revoke ${revisionId} ${grantId}`;
+    let approved = options.approve === true;
+    if (!approved && tty(options)) {
+        approved = await selectOne(`Revoke sharing grant ${grantId} of world version ${revisionId}?`, [
+            { value: false, label: 'Not now', detail: 'Nothing is changed.' },
+            { value: true, label: 'Revoke', detail: 'Stops that workspace\'s new reads and forks. Forks it already made are its own and are not removed.' },
+        ], signal);
+    }
+    if (!approved)
+        throw new CliError('world_share_consent_required', `Nothing was changed. After the human approves: ${command} --approve-change`, 2);
+    // Idempotent: a grant revoked earlier is returned as it is, with its original revocation time.
+    const revoked = await retryTransient(() => revokeWorldGrant(scope, { revisionId, grantId, signal }), { signal, attempts: 3 })
+        .catch((error) => {
+        if (errorCode(error) !== 'admin_required' && error instanceof CliError && error.httpStatus === 404) {
+            throw new CliError('native_world_grant_not_found', 'That is not a sharing grant of a world version this workspace owns. Nothing was changed. '
+                + `List them with firedrill world grants ${revisionId}.`, 2);
+        }
+        return ownerAdminOnly(error);
+    });
+    emit('world_grant', revoked, `Grant ${revoked.id} is revoked (since ${terminalText(revoked.revoked_at)}).\n${grantLine(revoked)}\n`
+        + `Workspace ${revoked.recipient_workspace_id} can no longer read or fork this world version. Forks it already made stay its own.`);
+}
+/** `fork <version-id> --agent <agent-id> [--descriptor-revision <id>] [--file <declaration.json|->] [--request <key>] [--approve-change]`. */
+async function fork(scope, args, options, emit) {
+    const [, version] = args;
+    const signal = options.signal;
+    const sourceId = worldReuseId(version, 'world version id');
+    const agentId = worldReuseId(options.agent, 'agent id');
+    const remapped = options.file === undefined ? undefined
+        : await readJsonObject(options.file, 'the remapped world declaration', signal, DEFINITION_BYTES);
+    const requestKey = options.request === undefined ? randomUUID() : worldReuseId(options.request, 'request key');
+    // A fork already made under this key is shown, never made again. Root
+    // returns it before checking current access, so this works after a revoke.
+    if (options.request !== undefined) {
+        const original = await recoverWorldFork(scope, { requestKey, signal });
+        if (original.state === 'withdrawn') {
+            throw new CliError('native_world_fork_withdrawn', `Fork request ${requestKey} was withdrawn, so it will never land. Fork again without --request `
+                + 'only if the human still wants it.', 2);
+        }
+        if (original.state === 'committed') {
+            if (original.fork.source_revision_id !== sourceId) {
+                throw new CliError('idempotency_conflict', `Request ${requestKey} forked world version ${original.fork.source_revision_id}, not ${sourceId}. `
+                    + 'Nothing was sent; fork this version without --request.', 2);
+            }
+            return recoveredOnly(original.fork, requestKey, emit);
+        }
+    }
+    const source = await getReusableWorld(scope, { revisionId: sourceId, signal }).catch(notReadable);
+    if (!source.can_use)
+        throw new CliError('native_world_use_not_granted', `${unusableText(scope, source)} Nothing was sent.`, 2);
+    const definition = remapped ?? source.definition;
+    const descriptorRevision = options.descriptorRevision !== undefined
+        ? await agentDescriptor(scope, agentId, worldReuseId(options.descriptorRevision, 'descriptor revision id'), signal)
+        : await newestDescriptor(scope, agentId, signal);
+    const needs = declarationNeeds(definition);
+    const references = [
+        needs.simulatedTools ? `${needs.simulatedTools} simulated tool version${needs.simulatedTools === 1 ? '' : 's'}` : null,
+        needs.realTools ? `${needs.realTools} real tool${needs.realTools === 1 ? '' : 's'}` : null,
+        needs.libraryVersions ? `${needs.libraryVersions} library version${needs.libraryVersions === 1 ? '' : 's'}` : null,
+        needs.worldItems ? `${needs.worldItems} world item${needs.worldItems === 1 ? '' : 's'}` : null,
+    ].filter((part) => part !== null);
+    const rerun = `firedrill world fork ${sourceId} --agent ${agentId} --descriptor-revision ${descriptorRevision}`
+        + `${options.file === undefined ? '' : ' --file <the same declaration>'} --request ${requestKey}`;
+    emit('world_fork_review', { source, agent_id: agentId, native_descriptor_id: descriptorRevision, remapped: remapped !== undefined, needs,
+        request_key: requestKey }, [
+        `Fork world ${terminalText(source.name)} v${source.revision} (version ${source.id}`
+            + `${sharedHere(scope, source) ? `, shared from workspace ${source.owner_workspace_id}` : ''}) into a new private world of this workspace,`,
+        `for agent ${agentId} with descriptor revision ${descriptorRevision}${options.descriptorRevision === undefined ? ' (its newest)' : ''}.`,
+        remapped ? `The declaration is your remapped file; the source is pinned by its digest ${source.definition_digest}.`
+            : `The declaration is copied as read (digest ${source.definition_digest}). To point it at other versions this workspace uses, `
+                + `export its definition with firedrill world version ${source.id} --json, edit it and pass it with --file.`,
+        references.length ? `It references ${references.join(', ')}.` : null,
+        'Forking grants no access to anything it references: each must already be usable by this workspace, or the fork is refused.',
+        needs.configurationNames.length ? `Configuration names (values are never copied; this workspace sets its own): ${needs.configurationNames.map(terminalText).join(', ')}.` : null,
+        'The new world is this workspace\'s own. Nothing is provisioned, run or spent.',
+    ].filter((line) => line !== null).join('\n'));
+    let approved = options.approve === true;
+    if (!approved && tty(options)) {
+        approved = await selectOne('Fork this world version into a new private world?', [
+            { value: false, label: 'Not now', detail: 'Nothing is forked.' },
+            { value: true, label: 'Fork it', detail: 'Creates a new world of this workspace from this exact declaration.' },
+        ], signal);
+    }
+    if (!approved)
+        throw new CliError('world_fork_consent_required', `Nothing was forked. After the human approves: ${rerun} --approve-change`, 2);
+    if (options.json)
+        emit('request_prepared', { request_key: requestKey }, '');
+    else
+        process.stderr.write(`Request key: ${requestKey} (if interrupted, rerun ${rerun} --approve-change; firedrill world fork-request ${requestKey} reads it back)\n`);
+    let result;
+    try {
+        // The same key and body return the original fork, so a retry never forks twice.
+        result = await retryTransient(() => forkWorld(scope, { source, agentId, descriptorRevisionId: descriptorRevision, definition, requestKey, signal }), { signal, attempts: 3 });
+    }
+    catch (error) {
+        // A refusal with the service's own code wrote nothing; only an answer that never arrived is recovered by its key.
+        if (signal.aborted || !answerLost(error) || answeredRefusal(error)) {
+            // The source was just read as usable, so a 404 most often means the
+            // destination: root also answers 404 for an archived or non-local agent.
+            if (error instanceof CliError && error.httpStatus === 404) {
+                throw new CliError('native_world_fork_not_found', `Nothing was forked. Agent ${agentId} may be archived or not a locally registered agent, `
+                    + `or descriptor revision ${descriptorRevision} may no longer be one of its revisions (firedrill descriptors --agent ${agentId}). `
+                    + `If both are right, the share was revoked or the source world was archived just now: check with firedrill world version ${sourceId}.`, 2);
+            }
+            throw error;
+        }
+        // No answer: read the original back by its key. Never sent again here, never under a new key.
+        const recovered = await recoverWorldFork(scope, { requestKey, signal: AbortSignal.timeout(RECOVER_MS) }).catch(() => null);
+        if (recovered?.state === 'withdrawn') {
+            throw new CliError('native_world_fork_withdrawn', `Fork request ${requestKey} was withdrawn, so it will never land.`, 2);
+        }
+        if (recovered?.state !== 'committed') {
+            throw new CliError('native_world_fork_unconfirmed', `The fork was not confirmed and may still land (request ${requestKey}). Read it with `
+                + `firedrill world fork-request ${requestKey}, or rerun ${rerun} --approve-change, which returns the original instead of forking twice. `
+                + `Before forking differently, withdraw it: firedrill world withdraw-fork ${requestKey}. Never fork it again under a new key.`);
+        }
+        result = checkFork(recovered.fork, { sourceId, sourceDigest: source.definition_digest, requestKey });
+        // A key this run created was never used before, so the recovered fork is
+        // this request. A key the caller supplied may hold an earlier original.
+        if (options.request !== undefined)
+            return recoveredOnly(result, requestKey, emit);
+    }
+    emit('world_fork', result, forkText(result, 'Forked', agentId));
+}
+/**
+ * An original fork read back by a caller-supplied key. Root identifies it by
+ * the key, not by this invocation's flags, so it is shown as recorded: the
+ * agent, descriptor revision and declaration given now are never claimed.
+ */
+function recoveredOnly(fork, requestKey, emit) {
+    emit('native_request', { kind: 'world_fork', request_key: requestKey, state: 'committed', receipt: fork, submitted_change_confirmed: false }, [
+        forkText(fork, 'Recovered the original fork under this request key'),
+        'It keeps the agent, descriptor revision and declaration it was created with. The --agent, --descriptor-revision and --file given now are '
+            + 'not applied and not confirmed to match.',
+        `Inspect it with firedrill world show ${fork.world_id} ${fork.target_revision_id} before continuing. To fork differently, run without --request.`,
+    ].join('\n'));
+}
+/** Root answers a fork for a missing destination with a bare 404, so the destination is read before the human is asked. */
+const destinationMissing = (agentId, descriptorId) => (error) => {
+    if (error instanceof CliError && error.httpStatus === 404) {
+        throw new CliError('native_world_fork_destination_not_found', descriptorId === undefined
+            ? `Agent ${agentId} is not an agent of this workspace. Use the agent id from firedrill status. Nothing was sent.`
+            : `Agent ${agentId} has no descriptor revision ${descriptorId} in this workspace. List its revisions with `
+                + `firedrill descriptors --agent ${agentId}. Nothing was sent.`, 2);
+    }
+    throw error;
+};
+/** This agent's newest registered descriptor revision: the default a fork binds to, which the review names. */
+async function newestDescriptor(scope, agentId, signal) {
+    const newest = (await listNativeDescriptors(scope, { agentId, page: 1, signal }).catch(destinationMissing(agentId))).results[0];
+    if (!newest)
+        throw new CliError('native_descriptor_required', 'Register a descriptor for this agent first with firedrill register. Nothing was sent.', 2);
+    return newest.id.toLowerCase();
+}
+/** An explicit descriptor revision must be one of this agent's own. */
+async function agentDescriptor(scope, agentId, descriptorId, signal) {
+    await getNativeDescriptor(scope, { agentId, descriptorId, signal }).catch(destinationMissing(agentId, descriptorId));
+    return descriptorId;
+}
+/** `withdraw-share-request <version-id> <request-key> [--approve-change]`. */
+async function withdrawShareRequest(scope, revisionId, requestKey, options, emit) {
+    const signal = options.signal;
+    // Administrator-only, like the share itself; a grant that already landed is shown, not withdrawn.
+    const original = await recoverWorldGrant(scope, { revisionId, requestKey, signal }).catch((error) => ownerAdminOnly(error));
+    if (original) {
+        emit('world_grant', original, `This sharing request already landed, so nothing was withdrawn:\n${grantLine(original)}\n`
+            + (original.revoked_at ? 'It is already revoked.' : `Revoke it instead: firedrill world revoke ${revisionId} ${original.id} --approve-change`));
+        return;
+    }
+    const command = `firedrill world withdraw-share-request ${revisionId} ${requestKey}`;
+    let approved = options.approve === true;
+    if (!approved && tty(options)) {
+        approved = await selectOne(`Withdraw sharing request ${requestKey} so it can never land?`, [
+            { value: false, label: 'Not now', detail: 'Nothing is changed.' },
+            { value: true, label: 'Withdraw', detail: 'If it already landed, the grant is shown instead and kept.' },
+        ], signal);
+    }
+    if (!approved)
+        throw new CliError('world_share_consent_required', `Nothing was withdrawn. After the human approves: ${command} --approve-change`, 2);
+    const outcome = await retryTransient(() => withdrawWorldGrantRequest(scope, { revisionId, requestKey, signal }), { signal, attempts: 3 })
+        .catch(ownerAdminOnly);
+    if (outcome.state === 'committed') {
+        emit('world_grant', outcome.grant, `This sharing request had already landed, so nothing was withdrawn:\n${grantLine(outcome.grant)}\n`
+            + `Revoke it instead: firedrill world revoke ${revisionId} ${outcome.grant.id} --approve-change`);
+        return;
+    }
+    emit('world_share_withdrawal', { state: 'withdrawn', revision_id: revisionId, request_key: requestKey }, `Withdrawn. Sharing request ${requestKey} will never land. Share again without --request only if the human still wants it.`);
+}
+/** `withdraw-fork <request-key> [--approve-change]`. */
+async function withdrawFork(scope, requestKey, options, emit) {
+    const signal = options.signal;
+    const original = await recoverWorldFork(scope, { requestKey, signal });
+    if (original.state === 'committed') {
+        emit('world_fork', original.fork, forkText(original.fork, 'This request already landed, so nothing was withdrawn. It forked'));
+        return;
+    }
+    if (original.state === 'withdrawn') {
+        emit('world_fork_withdrawal', { state: 'withdrawn', request_key: requestKey }, `Fork request ${requestKey} is already withdrawn; it will never land.`);
+        return;
+    }
+    const command = `firedrill world withdraw-fork ${requestKey}`;
+    let approved = options.approve === true;
+    if (!approved && tty(options)) {
+        approved = await selectOne(`Withdraw fork request ${requestKey} so it can never land?`, [
+            { value: false, label: 'Not now', detail: 'Nothing is changed.' },
+            { value: true, label: 'Withdraw', detail: 'If it already landed, the fork is shown instead and kept.' },
+        ], signal);
+    }
+    if (!approved)
+        throw new CliError('world_fork_consent_required', `Nothing was withdrawn. After the human approves: ${command} --approve-change`, 2);
+    const outcome = await retryTransient(() => withdrawWorldFork(scope, { requestKey, signal }), { signal, attempts: 3 });
+    if (outcome.state === 'committed') {
+        emit('world_fork', outcome.fork, forkText(outcome.fork, 'This request had already landed, so nothing was withdrawn. It forked'));
+        return;
+    }
+    emit('world_fork_withdrawal', { state: 'withdrawn', request_key: requestKey }, `Withdrawn. Fork request ${requestKey} will never land. Fork again without --request only if the human still wants it.`);
+}
+/**
+ * `world versions [--search <prefix>] [--page <n>] | version <version-id> | recipients [--search <prefix>] [--page <n>]
+ *  | grants <version-id> [--page <n>] | share <version-id> <workspace-id> read|use [--request <key>] [--approve-change]
+ *  | share-request <version-id> <key> | withdraw-share-request <version-id> <key> [--approve-change]
+ *  | revoke <version-id> <grant-id> [--approve-change]
+ *  | fork <version-id> --agent <id> [--descriptor-revision <id>] [--file <declaration.json|->] [--request <key>] [--approve-change]
+ *  | fork-request <key> | withdraw-fork <key> [--approve-change] | dependents <version-id> [--kind fork|campaign] [--page <n>]`.
+ */
+export async function worldReuseCommand(args, options, emit) {
+    checkWorldReuseArguments(args, options);
+    const [verb, first, second] = args;
+    const signal = options.signal;
+    const scope = await scopeOf(options);
+    if (verb === 'share')
+        return share(scope, args, options, emit);
+    if (verb === 'revoke')
+        return revoke(scope, args, options, emit);
+    if (verb === 'fork')
+        return fork(scope, args, options, emit);
+    if (verb === 'withdraw-fork')
+        return withdrawFork(scope, worldReuseId(first, 'request key'), options, emit);
+    if (verb === 'withdraw-share-request') {
+        return withdrawShareRequest(scope, worldReuseId(first, 'world version id'), worldReuseId(second, 'request key'), options, emit);
+    }
+    if (verb === 'versions') {
+        const number = pageNumber(options.page);
+        const page = await listReusableWorlds(scope, { search: options.search, page: number, signal }).catch(pastEnd(number, rethrow));
+        emit('world_versions', page, [
+            `World versions this workspace can read, newest first, page ${page.page} (${page.count} in all):`,
+            ...page.results.map((row) => versionLine(scope, row)),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            'Read one: firedrill world version <version-id>. Fork one: firedrill world fork <version-id> --agent <agent-id>',
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'version') {
+        const row = await getReusableWorld(scope, { revisionId: worldReuseId(first, 'world version id'), signal }).catch(notReadable);
+        const needs = declarationNeeds(row.definition);
+        emit('world_version', row, [
+            `World ${terminalText(row.name)} v${row.revision}: version ${row.id}  digest ${row.definition_digest}  ${terminalText(row.created_at)}`,
+            `Access: ${worldAccess(scope, row)}`,
+            `References: ${needs.simulatedTools} simulated tool version(s), ${needs.realTools} real tool(s), ${needs.libraryVersions} library version(s), `
+                + `${needs.worldItems} world item(s). Configuration names: ${needs.configurationNames.length ? needs.configurationNames.map(terminalText).join(', ') : 'none'}.`,
+            terminalText(JSON.stringify(row.definition, null, 2)),
+            row.can_use ? `Fork it: firedrill world fork ${row.id} --agent <agent-id>` : null,
+            sharedHere(scope, row) ? null : `Share it: firedrill world share ${row.id} <workspace-id> read|use`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'recipients') {
+        // The organization's recipient chooser is shared with library sharing.
+        const number = pageNumber(options.page);
+        const page = await listLibraryRecipients(scope, { search: options.search, page: number, signal }).catch(pastEnd(number, adminOnly));
+        emit('world_recipients', page, [
+            `Workspaces of this organization a world version can be shared with, page ${page.page} (${page.count} in all):`,
+            ...page.results.map((one) => `  ${one.id}  ${terminalText(one.name)}`),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            'Share a version: firedrill world share <version-id> <workspace-id> read|use',
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'grants') {
+        const revisionId = worldReuseId(first, 'world version id');
+        const number = pageNumber(options.page);
+        const page = await listWorldGrants(scope, { revisionId, page: number, signal }).catch(pastEnd(number, ownerAdminOnly));
+        emit('world_grants', { revision_id: revisionId, ...page }, [
+            `Sharing grants of world version ${revisionId}, page ${page.page} (${page.count} in all, revoked ones included):`,
+            ...page.results.map(grantLine),
+            page.results.length ? null : '  none',
+            page.next ? `More: --page ${page.page + 1}` : null,
+            `Share it: firedrill world share ${revisionId} <workspace-id> read|use`,
+        ].filter((line) => line !== null).join('\n'));
+        return;
+    }
+    if (verb === 'share-request') {
+        const revisionId = worldReuseId(first, 'world version id');
+        const requestKey = worldReuseId(second, 'request key');
+        const grant = await recoverWorldGrant(scope, { revisionId, requestKey, signal }).catch(adminOnly);
+        emit('world_grant', grant ?? { revision_id: revisionId, request_key: requestKey, state: 'not_found' }, grant ? grantLine(grant).trim()
+            : `None of your sharing requests for this world version is recorded under ${requestKey}. An unanswered request may still arrive. `
+                + 'Rerun the original share with the same --request key (it returns the original instead of sharing twice), or withdraw it first: '
+                + `firedrill world withdraw-share-request ${revisionId} ${requestKey}. Never share it under a new key.`);
+        return;
+    }
+    if (verb === 'fork-request') {
+        const requestKey = worldReuseId(first, 'request key');
+        const original = await recoverWorldFork(scope, { requestKey, signal });
+        if (original.state === 'committed') {
+            emit('world_fork', original.fork, forkText(original.fork, 'Forked'));
+        }
+        else {
+            emit('world_fork_request', { request_key: requestKey, state: original.state }, original.state === 'withdrawn'
+                ? `Fork request ${requestKey} was withdrawn; it will never land.`
+                : `None of your fork requests is recorded under ${requestKey}. An unanswered request may still land. Rerun the original fork with `
+                    + `--request ${requestKey} (it returns the original instead of forking twice), or withdraw it first: firedrill world withdraw-fork ${requestKey}. `
+                    + 'Never fork it again under a new key.');
+        }
+        return;
+    }
+    const revisionId = worldReuseId(first, 'world version id');
+    const kind = (options.kind ?? 'fork');
+    const number = pageNumber(options.page);
+    const page = await listWorldDependents(scope, { revisionId, kind, page: number, signal }).catch(pastEnd(number, notReadable));
+    emit('world_dependents', { revision_id: revisionId, kind, ...page }, [
+        `${kind === 'fork' ? 'Forks' : 'Campaigns'} in this workspace from world version ${revisionId}, page ${page.page} (${page.count} in all):`,
+        ...page.results.map((one) => 'world_id' in one
+            ? `  fork ${one.id}  world ${one.world_id} revision ${one.target_revision_id}  ${terminalText(one.created_at)}`
+            : `  campaign ${one.id}  ${terminalText(one.state)}  ${terminalText(one.created_at)}`),
+        page.results.length ? null : '  none',
+        page.next ? `More: --page ${page.page + 1}` : null,
+        'Other workspaces\' forks and campaigns are never shown here.',
+        kind === 'fork' ? `Campaigns planned from it: firedrill world dependents ${revisionId} --kind campaign` : null,
+    ].filter((line) => line !== null).join('\n'));
+}