firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/world-session-state.js

@@ -0,0 +1,145 @@
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { worldSessionMatches, worldSessionsPageMatches } from '../../contracts/session-contracts.js';
+import { sessionStateActionMatches, sessionStateRequestMatches, sessionCapturesPageMatches, sessionResetsPageMatches, sessionStateCounter } from '../../contracts/session-state-contracts.js';
+export const SESSION_STATE_ACTIONS = ['captures', 'capture', 'capture-show', 'capture-request', 'resets', 'reset', 'reset-request'];
+const captureText = (row) => `${row.id}  ${row.state}`
+    + (row.reset_count === null ? '' : ` · state version ${row.reset_count}`)
+    + (row.observation ? `\n${row.observation.collection_count.toLocaleString()} collections · ${row.observation.record_count.toLocaleString()} records`
+        + (row.observation.captured_at ? ` · ${row.observation.captured_at}` : '') + `\nCapture: ${row.observation.id}` : '')
+    + (row.problem ? '\n' + row.problem : '');
+const resetText = (row) => `${row.id}  ${row.state}`
+    + (row.reset_at ? `\nStarting data restored ${row.reset_at} · state version ${row.reset_count}` : '\nA reset is not confirmed until its runtime receipt is retained.')
+    + (row.problem ? '\n' + row.problem : '');
+/** Shares the browser's original session journal. No ambiguous write is repeated. */
+export async function worldSessionState(args, options, output) {
+    const action = args[0], writing = action === 'capture' || action === 'reset';
+    const kind = action.startsWith('capture') ? 'capture' : 'reset';
+    const exact = ['capture-show', 'capture-request', 'reset-request'].includes(action);
+    if (!SESSION_STATE_ACTIONS.includes(action) || (exact ? args.length !== 3 : args.length > 2)
+        || options.search !== undefined || options.name !== undefined || options.checkpoint !== undefined
+        || options.shareCheckpointWithDevice !== undefined || options.approveRealSession !== undefined
+        || options.local !== undefined || options.managed !== undefined || options.device !== undefined || options.grant !== undefined
+        || options.seconds !== undefined || options.dataset !== undefined || options.shareDatasetWithDevice !== undefined
+        || options.acknowledgeSharedState !== undefined || options.run !== undefined && !writing
+        || options.page !== undefined && (!['captures', 'resets'].includes(action) || !/^[1-9][0-9]{0,8}$/.test(options.page))) {
+        throw new CliError('arguments_invalid', 'Use sessions captures, capture, capture-show, capture-request, resets, reset or reset-request with the matching session and optional history page. --run approves only a new capture or reset.', 2);
+    }
+    const tty = !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    const world = await selectedWorld({ ...options, interactive: tty });
+    const auth = { actor: world.owner, workspace: world.workspace, signal: options.signal };
+    const worldScope = { actor: world.owner, workspace: world.workspace, world: world.world };
+    let sessionId = args[1];
+    if (!sessionId) {
+        if (!tty)
+            throw new CliError('arguments_invalid', 'Provide a session ID from firedrill sessions.', 2);
+        let page = 1;
+        while (!sessionId) {
+            const result = await api(`${world.prefix}/runtime-sessions?page=${page}`, auth);
+            if (!worldSessionsPageMatches(result, worldScope))
+                throw new CliError('world_session_receipt_invalid', 'Session history could not be confirmed in this world.');
+            const choices = result.results.map(row => ({ value: row.id, label: row.id, detail: `${row.execution_location} · ${row.state}` }));
+            if (page > 1)
+                choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+            if (result.next)
+                choices.push({ value: 'next', label: 'Next page', detail: '' });
+            choices.push({ value: 'cancel', label: 'Cancel', detail: '' });
+            const choice = await selectOne('World session', choices, options.signal);
+            if (choice === 'cancel')
+                throw new CliError('canceled', 'No state action was submitted.', 130);
+            if (choice === 'previous')
+                page--;
+            else if (choice === 'next')
+                page++;
+            else
+                sessionId = identifier(choice);
+        }
+    }
+    sessionId = identifier(sessionId);
+    const scope = { ...worldScope, session: sessionId }, base = `${world.prefix}/runtime-sessions/${sessionId}`;
+    const unconfirmed = () => new CliError('world_session_acceptance_unconfirmed', 'The original state request could not be confirmed. Inspect its key; no replacement was submitted.', 2);
+    function describe(row) { return 'observation' in row ? captureText(row) : resetText(row); }
+    async function lookup(key, present = true) {
+        const receipt = kind === 'capture'
+            ? await api(`${base}/capture-intent?request_key=${identifier(key)}`, auth)
+            : await api(`${base}/reset-intent?request_key=${identifier(key)}`, auth);
+        if (!sessionStateRequestMatches(receipt, scope, key, kind))
+            throw unconfirmed();
+        if (present)
+            output(`world_session_${kind}_request`, receipt, receipt.request ? describe(receipt.request)
+                : `Request ${key} is not recorded yet. A delayed original request may still arrive. Inspect it again or close the session; do not submit a replacement.`);
+        return receipt;
+    }
+    if (action.endsWith('-request')) {
+        await lookup(identifier(args[2]));
+        return;
+    }
+    if (action === 'capture-show') {
+        const id = identifier(args[2]), row = await api(`${base}/captures/${id}`, auth);
+        if (!sessionStateActionMatches(row, scope, 'capture', { id }))
+            throw unconfirmed();
+        output('world_session_capture', row, captureText(row));
+        return;
+    }
+    if (action === 'captures' || action === 'resets') {
+        const page = action === 'captures'
+            ? await api(`${base}/captures?page=${options.page ?? '1'}`, auth)
+            : await api(`${base}/resets?page=${options.page ?? '1'}`, auth);
+        if ('uncertain_reset' in page ? !sessionResetsPageMatches(page, scope) : !sessionCapturesPageMatches(page, scope))
+            throw unconfirmed();
+        const continuation = `firedrill sessions ${action} ${sessionId} --world ${world.world} --workspace ${world.workspace} --page ${page.page + 1}${options.json ? ' --json' : ''}`;
+        output(`world_session_${action}`, page, (page.results.map(describe).join('\n\n') || `No ${action} recorded for this session.`)
+            + `\nPage ${page.page}; ${page.count.toLocaleString()} matching entries.${page.next ? '\nContinue: ' + continuation : ''}`);
+        return;
+    }
+    const session = await api(base, auth);
+    if (!worldSessionMatches(session, worldScope, { id: sessionId }))
+        throw unconfirmed();
+    if (!session.can_control || session.terminal_at || session.state !== 'active' || !session.observation_current
+        || sessionStateCounter(session.reset_count) === null || kind === 'reset' && (session.reset_pending || session.voice_call_open
+        || sessionStateCounter(session.reset_count) >= 9223372036854775807n)) {
+        throw new CliError('world_session_state_unavailable', 'Use a current, controllable active session. End a voice call or inspect pending reset activity before resetting.', 2);
+    }
+    if (!options.run) {
+        if (!tty)
+            throw new CliError('world_session_consent_required', 'Use --run to approve this exact capture or reset in automation.', 2);
+        const detail = kind === 'capture' ? 'Captures supported current database records. This does not reset data or resolve an earlier uncertain write.'
+            : 'Restores the session’s sealed starting databases and restarts the agent and services. Other files and real-account changes are not restored. Tool views close.'
+                + (session.external_effects ? ' Restarting the agent may make new real requests using its approved access.' : '');
+        if (!await selectOne(kind === 'capture' ? 'Capture current database records?' : 'Reset to starting data?', [
+            { value: false, label: 'Cancel' }, { value: true, label: kind === 'capture' ? 'Capture data' : 'Reset to starting data', detail }
+        ], options.signal)) {
+            throw new CliError('canceled', 'No state action was submitted.', 130);
+        }
+    }
+    const key = randomUUID();
+    output('world_session_state_request_key', { session_id: sessionId, request_key: key, kind }, `Request: ${key}\nRecover: firedrill sessions ${kind}-request ${sessionId} ${key} --world ${world.world} --workspace ${world.workspace}. Do not repeat an uncertain action.`);
+    let result;
+    try {
+        if (kind === 'capture')
+            result = await api(`${base}/captures`, { ...auth, method: 'POST', idempotencyKey: key, body: {} });
+        else {
+            const body = { expected_reset_count: session.reset_count };
+            result = await api(`${base}/resets`, { ...auth, method: 'POST', idempotencyKey: key, body });
+        }
+    }
+    catch (error) {
+        if (options.signal.aborted)
+            throw error;
+        const receipt = await lookup(key, false);
+        if (!receipt.request)
+            throw unconfirmed();
+        result = receipt.request;
+    }
+    const selected = { key, ...(kind === 'reset' ? { counter: session.reset_count } : {}) };
+    if (!sessionStateActionMatches(result, scope, kind, selected))
+        throw unconfirmed();
+    const original = await lookup(key, false);
+    if (!sessionStateRequestMatches(original, scope, key, kind, selected) || original.request?.id !== result.id)
+        throw unconfirmed();
+    output(`world_session_${kind}`, original.request, describe(original.request));
+}

package/dist/cli/src/world-session-voice.js

@@ -0,0 +1,66 @@
+import { workspaceLink } from './browser-links.js';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne } from './prompts.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { worldSessionsPageMatches } from '../../contracts/session-contracts.js';
+import { manualVoicePageMatches, manualVoiceRequestMatches } from '../../contracts/session-voice-contracts.js';
+export const SESSION_VOICE_ACTIONS = ['voice', 'voice-request'];
+const describe = (row) => `${row.id}  ${row.kind} · ${row.state}\nCall ${row.call_id} · ${row.created_at}`
+    + (row.audio_available && row.audio ? `\n${row.audio.duration_ms} ms response audio currently available.`
+        : row.audio_recorded ? '\nAudio was recorded; playback is no longer available.' : '')
+    + (row.omitted_samples ? '\nSome received audio was omitted; this is not a complete call recording.' : '')
+    + (row.problem ? '\n' + row.problem : '');
+export async function worldSessionVoice(args, options, output) {
+    const action = args[0];
+    if (!SESSION_VOICE_ACTIONS.includes(action) || (action === 'voice-request' ? args.length !== 3 : args.length > 2)
+        || options.page !== undefined && (action !== 'voice' || !/^[1-9][0-9]{0,8}$/.test(options.page)))
+        throw new CliError('arguments_invalid', 'Use sessions voice [session] [--page N] or sessions voice-request <session> <key>.', 2);
+    const tty = !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    const world = await selectedWorld({ ...options, interactive: tty });
+    const auth = { actor: world.owner, workspace: world.workspace, signal: options.signal };
+    const identity = { actor: world.owner, workspace: world.workspace, world: world.world };
+    let id = args[1], page = 1;
+    if (!id && !tty)
+        throw new CliError('arguments_invalid', 'Provide a session from firedrill sessions.', 2);
+    while (!id) {
+        const value = await api(`${world.prefix}/runtime-sessions?page=${page}`, auth);
+        if (!worldSessionsPageMatches(value, identity))
+            throw new CliError('world_session_receipt_invalid', 'Session history could not be confirmed.');
+        const choices = value.results.map(row => ({ value: row.id, label: row.id, detail: row.state }));
+        if (page > 1)
+            choices.push({ value: 'previous', label: 'Previous page', detail: '' });
+        if (value.next)
+            choices.push({ value: 'next', label: 'Next page', detail: '' });
+        choices.push({ value: 'cancel', label: 'Cancel', detail: '' });
+        const selected = await selectOne('World session', choices, options.signal);
+        if (selected === 'cancel')
+            throw new CliError('canceled', 'Voice inspection canceled. No call was changed.', 130);
+        if (selected === 'previous')
+            page--;
+        else if (selected === 'next')
+            page++;
+        else
+            id = identifier(selected);
+    }
+    id = identifier(id);
+    const scope = { ...identity, session: id }, base = `${world.prefix}/runtime-sessions/${id}`;
+    const unconfirmed = () => new CliError('manual_voice_acceptance_unconfirmed', 'The selected voice records could not be confirmed. No audio request was submitted.', 2);
+    if (action === 'voice-request') {
+        const key = identifier(args[2]), value = await api(`${base}/voice-intent?request_key=${key}`, auth);
+        if (!manualVoiceRequestMatches(value, scope, key))
+            throw unconfirmed();
+        output('world_voice_request', value, value.request ? describe(value.request)
+            : 'The original request is not recorded yet. It may still arrive. Inspect this key or close the session; do not start a replacement call.');
+        return;
+    }
+    const value = await api(`${base}/voice?page=${options.page ?? '1'}`, auth);
+    if (!manualVoicePageMatches(value, scope))
+        throw unconfirmed();
+    const link = workspaceLink(world.workspace, `/worlds/${world.world}?world_tab=sessions&session=${id}`);
+    output('world_voice_history', value, (value.results.map(describe).join('\n\n') || 'No voice actions recorded for this session.')
+        + `\nPage ${value.page}; ${value.count.toLocaleString()} matching actions.${value.next
+            ? `\nContinue: firedrill sessions voice ${id} --world ${world.world} --workspace ${world.workspace} --page ${value.page + 1}${options.json ? ' --json' : ''}` : ''}`
+        + (value.supported || value.call ? `\nVoice controls: ${link}\nUse workspace ${world.workspace} in the browser.` : ''));
+}

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

@@ -0,0 +1,288 @@
+import { randomUUID } from 'node:crypto';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { selectOne, terminalText } from './prompts.js';
+import { execution, startingData } from './simulation-run.js';
+import { executeAssignment } from './runner-execute.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { CHECKPOINT_ACTIONS, worldSessionCheckpoints } from './world-session-checkpoints.js';
+import { SESSION_REQUEST_ACTIONS, worldSessionRequests } from './world-session-requests.js';
+import { SESSION_STATE_ACTIONS, worldSessionState } from './world-session-state.js';
+import { SESSION_VOICE_ACTIONS, worldSessionVoice } from './world-session-voice.js';
+import { WORLD_LIFECYCLE_ACTIONS, worldLifecycleCommand, worldAllocationApproval } from './world-session-lifecycle.js';
+import { COORDINATED_ACTIONS, coordinatedCheckpointsCommand } from './coordinated-checkpoints.js';
+import { worldSessionMatches, worldSessionRequestMatches, worldSessionsPageMatches, worldSessionOpeningScopeMatches } from '../../contracts/session-contracts.js';
+const description = (row) => `${row.id}  ${row.state}  ${row.execution_location === 'local' ? 'Local device' : 'Cloud'}\n`
+    + (row.terminal_at ? `Closed ${row.terminal_at}` : `Expires ${row.expires_at}`)
+    + (row.dataset_id ? row.starting_data ? `\n${row.starting_data.edit_count} saved edits applied ${row.starting_data.applied_at}; ${row.starting_data.rows_affected} rows directly affected.`
+        : '\nSaved starting-data application has not been confirmed.' : '')
+    + (row.fork ? `\nCheckpoint ${row.fork.checkpoint_id}: ${row.fork.observed_at ? 'applied ' + row.fork.observed_at : 'application not yet confirmed'}.` : '')
+    + (row.external_effects ? `\n${row.external_effects.real_connections_count} shared real-account connections. External changes are not reset or undone.` : '')
+    + (row.problem ? '\n' + row.problem : '');
+/** One shared manual-world API. Opening is not a trial or an evaluation.
+ * Lost replies are recovered by reading the ORIGINAL request, never retrying
+ * a newly generated intent or changing execution location.
+ */
+export async function worldSessionsCommand(args, options, output) {
+    const requestedAction = args[0] ?? 'list', action = requestedAction === 'resume' ? 'open' : requestedAction;
+    if (options.acknowledgePartialState && requestedAction !== 'resume')
+        throw new CliError('arguments_invalid', 'Use --acknowledge-partial-state only for sessions resume.', 2);
+    if (COORDINATED_ACTIONS.includes(action)) {
+        const allowed = new Set(['json', 'workspace', 'world', 'expectedOwner', 'openBrowser', 'signal', 'page', 'search', 'request', 'name', 'run']);
+        if (Object.entries(options).some(([key, value]) => value !== undefined && !allowed.has(key)))
+            throw new CliError('arguments_invalid', 'Use checkpoint scope, name, original request and explicit capture approval only.', 2);
+        return coordinatedCheckpointsCommand(args, options, output);
+    }
+    if (WORLD_LIFECYCLE_ACTIONS.includes(action)) {
+        const allowed = new Set(['json', 'workspace', 'world', 'expectedOwner', 'openBrowser', 'signal', 'page', 'search', 'request', 'file', 'run', 'seconds', 'usageQuote', 'name']);
+        if (Object.entries(options).some(([key, value]) => value !== undefined && !allowed.has(key)))
+            throw new CliError('arguments_invalid', 'Use the selected session, its original request and only the lifecycle action’s supported options.', 2);
+        return worldLifecycleCommand(args, options, output);
+    }
+    if (SESSION_VOICE_ACTIONS.includes(action)) {
+        const allowed = new Set(['json', 'workspace', 'world', 'expectedOwner', 'openBrowser', 'signal', 'page']);
+        if (Object.entries(options).some(([key, value]) => value !== undefined && !allowed.has(key)))
+            throw new CliError('arguments_invalid', 'Use session scope and history page only. Voice input controls open in the browser.', 2);
+        return worldSessionVoice(args, options, output);
+    }
+    if (SESSION_REQUEST_ACTIONS.includes(action)) {
+        if (options.name !== undefined || options.local !== undefined || options.managed !== undefined || options.device !== undefined
+            || options.grant !== undefined || options.seconds !== undefined || options.dataset !== undefined || options.shareDatasetWithDevice !== undefined
+            || options.checkpoint !== undefined || options.shareCheckpointWithDevice !== undefined || options.approveRealSession !== undefined || options.acknowledgeSharedState !== undefined) {
+            throw new CliError('arguments_invalid', 'Use the existing session, optional request file, paging and --run consent only.', 2);
+        }
+        return worldSessionRequests(args, options, output);
+    }
+    if (options.file !== undefined)
+        throw new CliError('arguments_invalid', 'Use --file only with sessions call.', 2);
+    if (SESSION_STATE_ACTIONS.includes(action))
+        return worldSessionState(args, options, output);
+    if (CHECKPOINT_ACTIONS.includes(action))
+        return worldSessionCheckpoints(args, options, output);
+    if (!['list', 'show', 'open', 'close', 'request', 'withdraw'].includes(action)
+        || (requestedAction === 'resume' ? args.length !== 2 : ['show', 'close', 'request', 'withdraw'].includes(action) ? args.length !== 2 : args.length > 1)
+        || options.search !== undefined || options.name !== undefined
+        || action !== 'list' && options.page !== undefined
+        || options.page !== undefined && (!/^[1-9][0-9]{0,8}$/.test(options.page) || !Number.isSafeInteger(Number(options.page)))
+        || action !== 'open' && (options.local !== undefined || options.managed !== undefined || options.device !== undefined
+            || options.grant !== undefined || options.seconds !== undefined || options.dataset !== undefined || options.shareDatasetWithDevice !== undefined
+            || options.checkpoint !== undefined || options.shareCheckpointWithDevice !== undefined
+            || options.approveRealSession !== undefined || options.acknowledgeSharedState !== undefined)) {
+        throw new CliError('arguments_invalid', 'Use sessions [list], show <session>, open, close <session>, request <key> or withdraw <key>.', 2);
+    }
+    const tty = !options.json && Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    const scope = await selectedWorld({ ...options, interactive: tty });
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal: options.signal };
+    const identity = { actor: scope.owner, workspace: scope.workspace, world: scope.world };
+    const prefix = `${scope.prefix}/runtime-sessions`;
+    function session(row) {
+        if (!worldSessionMatches(row, identity))
+            throw new CliError('world_session_receipt_invalid', 'The session reference could not be confirmed. No replacement was started.');
+        output('world_session', row, description(row));
+    }
+    async function lookup(key) {
+        const receipt = await api(`${scope.prefix}/runtime-session-request?request_key=${identifier(key)}`, auth);
+        if (!worldSessionRequestMatches(receipt, identity, key)) {
+            throw new CliError('world_session_receipt_invalid', 'The original session request could not be confirmed. It was not resubmitted.');
+        }
+        output('world_session_request', receipt, `Request: ${key}\n${receipt.state}`
+            + (receipt.state === 'not_observed' ? '\nA delayed original request may still arrive. Inspect or withdraw this exact key; do not submit another opening.' : ''));
+        if (receipt.session)
+            session(receipt.session);
+        return receipt;
+    }
+    async function approve(label, detail) {
+        if (options.run)
+            return;
+        if (!tty)
+            throw new CliError('world_session_consent_required', 'Use --run to approve this exact world-session action in automation.', 2);
+        if (!await selectOne(label, [{ value: false, label: 'Cancel' }, { value: true, label: 'Continue', detail }], options.signal)) {
+            throw new CliError('canceled', 'No world-session action was submitted.', 130);
+        }
+    }
+    if (action === 'list') {
+        const result = await api(`${prefix}?page=${options.page ?? '1'}`, auth);
+        if (!worldSessionsPageMatches(result, identity))
+            throw new CliError('world_session_receipt_invalid', 'Session history could not be confirmed in this world.');
+        const continuation = `firedrill sessions list --world ${scope.world} --workspace ${scope.workspace} --page ${result.page + 1}${options.json ? ' --json' : ''}`;
+        output('world_sessions', result, (result.results.map(description).join('\n\n') || 'No world sessions have been opened.')
+            + `\nPage ${result.page}, ${result.count} matching sessions.${result.next ? '\nContinue: ' + continuation : ''}`);
+        return;
+    }
+    if (action === 'show') {
+        const id = identifier(args[1]), row = await api(`${prefix}/${id}`, auth);
+        if (!worldSessionMatches(row, identity, { id }))
+            throw new CliError('world_session_receipt_invalid', 'The selected session could not be confirmed.');
+        session(row);
+        return;
+    }
+    if (action === 'request') {
+        await lookup(identifier(args[1]));
+        return;
+    }
+    if (action === 'withdraw') {
+        const key = identifier(args[1]);
+        await approve('Withdraw this original opening?', 'A queued opening is fenced. An accepted session is requested to close; cleanup is separate.');
+        const saved = await api(`${scope.prefix}/runtime-session-request`, { ...auth, method: 'POST', body: { request_key: key } });
+        if (!worldSessionRequestMatches(saved, identity, key) || !saved.withdrawn)
+            throw new CliError('world_session_receipt_invalid', 'The original withdrawal could not be confirmed. Inspect that request before another action.');
+        const original = await lookup(key);
+        if (!original.withdrawn)
+            throw new CliError('world_session_receipt_invalid', 'Withdrawal is not confirmed. No replacement was submitted.');
+        return;
+    }
+    if (action === 'close') {
+        const key = identifier(args[1]), row = await api(`${prefix}/${key}`, auth);
+        if (!worldSessionMatches(row, identity, { id: key }))
+            throw new CliError('world_session_receipt_invalid', 'Choose a session in this world.');
+        if (row.terminal_at) {
+            session(row);
+            return;
+        }
+        await approve('Close this world session?', 'Stops controlled running state. Retained evidence remains; this cannot undo external effects.');
+        const closing = await api(`${prefix}/${key}`, { ...auth, method: 'DELETE' });
+        if (!worldSessionMatches(closing, identity, { id: key }) || !closing.cancel_requested && !closing.terminal_at)
+            throw new CliError('world_session_receipt_invalid', 'Closing is not confirmed. Inspect this same session before another action.');
+        session(closing);
+        return;
+    }
+    const current = await api(`${prefix}?state=active&page_size=1`, auth);
+    if (!worldSessionsPageMatches(current, identity, 'active'))
+        throw new CliError('world_session_scope_invalid', 'The current opening scope could not be confirmed. No session was queued.', 2);
+    if (current.opening_restriction) {
+        throw new CliError('world_session_opening_restricted', terminalText(current.opening_restriction), 2);
+    }
+    const opening = current.opening_scope;
+    if (!worldSessionOpeningScopeMatches(opening)) {
+        throw new CliError('world_session_scope_invalid', 'The current source and configuration could not be confirmed. No session was queued.', 2);
+    }
+    const checkpoint = options.checkpoint === undefined ? null : identifier(options.checkpoint);
+    const application = requestedAction === 'resume' ? await api(`${scope.prefix}/application-checkpoints/${identifier(args[1])}`, auth) : null;
+    if (application && (!application.available || checkpoint))
+        throw new CliError('application_checkpoint_incompatible', 'Choose available source-owned state without another checkpoint.', 2);
+    if (checkpoint && (options.dataset !== undefined || options.shareDatasetWithDevice !== undefined)) {
+        throw new CliError('arguments_invalid', 'Choose a checkpoint or saved starting-data version, not both.', 2);
+    }
+    if (!checkpoint && current.primary_active)
+        throw new CliError('world_session_exists', 'Inspect or close the original session before opening another. No replacement was started.', 2);
+    const selected = await execution(scope, 'world_session', options, output);
+    if (application) {
+        output('application_resume_review', application, `Application state: ${application.components.map(one => one.name).join(', ')}\nNot included: ${application.excluded.join(', ')}. Controlled services use the separately selected starting data.`);
+        if (!options.acknowledgePartialState && !(tty && await selectOne('Continue with this declared state coverage in a new process?', [{ value: false, label: 'Cancel' }, { value: true, label: 'Continue from saved application state' }], options.signal)))
+            throw new CliError('application_checkpoint_consent_required', 'Approve the exact coverage with --acknowledge-partial-state. This is not heap or socket recovery.', 2);
+    }
+    const dataset = checkpoint ? null : await startingData(scope, { ...opening, agent_comparison: null }, options);
+    let shareDataset = options.shareDatasetWithDevice === true;
+    if (selected.location === 'local' && dataset) {
+        if (!shareDataset && tty)
+            shareDataset = await selectOne('Download this starting data to the selected device?', [
+                { value: false, label: 'Cancel' }, { value: true, label: 'Download the selected data',
+                    detail: 'Use a private runner cache outside the project. Firedrill cannot remotely erase device copies or backups.' }
+            ], options.signal);
+        if (!shareDataset)
+            throw new CliError('local_dataset_consent_required', 'Approve this download interactively or use --share-dataset-with-device. No session was admitted.', 2);
+    }
+    else if (shareDataset)
+        throw new CliError('local_dataset_consent_invalid', 'Use --share-dataset-with-device only with saved data and local execution.', 2);
+    let shareCheckpoint = options.shareCheckpointWithDevice === true;
+    if (selected.location === 'local' && (checkpoint || application)) {
+        if (!shareCheckpoint && tty)
+            shareCheckpoint = await selectOne('Download this checkpoint for a separate local session?', [
+                { value: false, label: 'Cancel' }, { value: true, label: 'Download the selected checkpoint',
+                    detail: 'The original session stays unchanged. Private runner cache is outside the project; device copies and backups cannot be erased remotely.' }
+            ], options.signal);
+        if (!shareCheckpoint)
+            throw new CliError('local_checkpoint_consent_required', 'Approve the download interactively or use --share-checkpoint-with-device. No session was admitted.', 2);
+    }
+    else if (shareCheckpoint)
+        throw new CliError('local_checkpoint_consent_invalid', 'Use --share-checkpoint-with-device only with a selected checkpoint and local execution.', 2);
+    const seconds = options.seconds ?? String(opening.duration_seconds);
+    if (!/^[1-9][0-9]*$/.test(seconds) || !Number.isSafeInteger(Number(seconds)) || Number(seconds) > opening.max_duration_seconds) {
+        throw new CliError('world_session_duration_invalid', 'Use a positive whole number of seconds within runtime capacity.', 2);
+    }
+    if (selected.location === 'local' && !selected.grant.document.consent.evidence_upload) {
+        throw new CliError('local_world_session_permission_required', 'Authorize world_session with evidence upload before opening locally.', 2);
+    }
+    let realConsent;
+    if (opening.real_connections_count > 0) {
+        if (selected.location === 'local' && selected.grant.document.consent.real_account_access !== true) {
+            throw new CliError('local_grant_consent_required', 'Authorize the reviewed real accounts for this device first. No session was admitted.', 2);
+        }
+        let effects = options.approveRealSession === true, shared = options.acknowledgeSharedState === true;
+        if (!effects && tty) {
+            effects = await selectOne('Allow real-account requests in this session?', [
+                { value: false, label: 'Cancel' }, { value: true, label: 'Allow reviewed operations',
+                    detail: `${opening.real_connections_count} connections, configuration ${opening.configuration_revision}, ${seconds} seconds. Includes startup, background work and explicit commands.` }
+            ], options.signal);
+            if (!effects)
+                throw new CliError('canceled', 'No world session was submitted.', 130);
+        }
+        if (!shared && tty) {
+            shared = await selectOne('Accept shared external state?', [
+                { value: false, label: 'Cancel' }, { value: true, label: 'Accept shared state',
+                    detail: 'Reset, restore, closing and forks cannot undo or isolate real-account changes. Restarting the agent can make real requests.' }
+            ], options.signal);
+            if (!shared)
+                throw new CliError('canceled', 'No world session was submitted.', 130);
+        }
+        if (!effects || !shared)
+            throw new CliError('world_session_real_consent_required', 'Approve session operations and shared state interactively, or use --approve-real-session --acknowledge-shared-state. Startup, simulation and --run approvals do not authorize this session.', 2);
+        realConsent = { actor_id: scope.owner, acknowledge_effects: true, acknowledge_shared_state: true };
+    }
+    else if (options.approveRealSession !== undefined || options.acknowledgeSharedState !== undefined) {
+        throw new CliError('world_session_real_consent_invalid', 'This world has no real-account connection. Remove the real-session approval options.', 2);
+    }
+    output('world_session_review', { world_id: scope.world, execution_location: selected.location, duration_seconds: Number(seconds),
+        checkpoint_id: checkpoint, real_connections_count: opening.real_connections_count }, `${selected.location === 'local' ? 'This device' : 'Cloud'} · ${seconds} seconds · ${checkpoint ? 'checkpoint ' + checkpoint : dataset ? ('name' in dataset && typeof dataset.name === 'string' ? terminalText(dataset.name) : 'Saved starting data') : 'prepared data'}\n`
+        + (selected.location === 'local' ? 'Keep this terminal open. Saved evidence is uploaded with customer-device provenance.' : 'The prepared agent starts in isolated compute.')
+        + (realConsent ? '\nReviewed real-account operations remain brokered. External state is shared and cannot be reset.' : ''));
+    await approve('Open this world session?', selected.location === 'local' ? 'Open the original local assignment and keep this terminal running.' : 'Queue one managed world session.');
+    if (selected.location === 'managed' && options.usageQuote && !options.request)
+        throw new CliError('billing_quote_required', 'Use the original quote launch key with --request.', 2);
+    const key = identifier(options.request ?? randomUUID());
+    const quote = selected.location === 'managed' ? await worldAllocationApproval(scope, options, {
+        world_revision: opening.world_revision, configuration_revision: opening.configuration_revision, duration_seconds: Number(seconds),
+        dataset_id: dataset?.id ?? null, checkpoint_id: checkpoint, launch_request_key: key,
+        ...(application ? { application_checkpoint_id: application.id } : {})
+    }, output) : null;
+    const body = { world_revision: opening.world_revision, configuration_revision: opening.configuration_revision,
+        source_id: identifier(opening.source_id), source_revision: opening.source_revision, duration_seconds: Number(seconds),
+        ...(quote ? { usage_quote_id: quote } : {}),
+        ...(application ? { application_checkpoint_id: application.id, acknowledge_partial_state: true } : {}),
+        ...(dataset ? { dataset_id: dataset.id } : {}), ...(shareDataset ? { share_dataset_with_device: true } : {}),
+        ...(checkpoint ? { checkpoint_id: checkpoint } : {}), ...(shareCheckpoint ? { share_checkpoint_with_device: true } : {}),
+        ...(realConsent ? { real_account_consent: realConsent } : {}),
+        execution: selected.location === 'local' ? { location: 'local', grant_id: selected.grant.id } : { location: 'managed' } };
+    output('world_session_opening', { request_key: key, world_id: scope.world }, `Request: ${key}\nIf interrupted, use sessions request ${key}. Withdraw this same key instead of submitting a replacement.`);
+    let row;
+    try {
+        row = await api(prefix, { ...auth, method: 'POST', idempotencyKey: key, body });
+    }
+    catch (error) {
+        if (options.signal.aborted)
+            throw error;
+        const receipt = await lookup(key);
+        if (!receipt.session || receipt.withdrawn)
+            throw new CliError('world_session_acceptance_unconfirmed', `Inspect sessions request ${key}. The original opening was not resubmitted.`, 2);
+        row = receipt.session;
+    }
+    if (!worldSessionMatches(row, identity, { key, body }) || row.world_revision !== opening.world_revision || row.configuration_revision !== opening.configuration_revision
+        || row.dataset_id !== (dataset?.id ?? null) || (row.fork?.checkpoint_id ?? null) !== checkpoint
+        || (row.external_effects?.real_connections_count ?? 0) !== opening.real_connections_count
+        || row.execution_location !== selected.location || selected.location === 'local'
+        && (row.local_execution?.grant_id !== selected.grant.id || row.local_execution?.device_key !== selected.device)) {
+        throw new CliError('world_session_acceptance_unconfirmed', `Inspect sessions request ${key}. The returned identity does not match the reviewed opening.`, 2);
+    }
+    const acceptance = await lookup(key);
+    if (acceptance.withdrawn || !acceptance.session || acceptance.session.id !== row.id
+        || !worldSessionMatches(acceptance.session, identity, { key, body })) {
+        throw new CliError('world_session_acceptance_unconfirmed', `Inspect sessions request ${key}. The original acceptance could not be confirmed. No replacement was started.`, 2);
+    }
+    row = acceptance.session;
+    session(row);
+    if (selected.location === 'local' && row.local_execution?.awaiting_runner && !row.cancel_requested) {
+        await executeAssignment(selected.device, identifier(row.local_execution.job_id), { ...options, world: scope.world,
+            workspace: scope.workspace, grant: selected.request, approve: true }, output);
+    }
+}

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

@@ -0,0 +1,99 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { access } from './auth.js';
+import { CliError, endpoint, responseError } from './http.js';
+import { notificationCursor, readWorldNotification, worldStreamPath } from '../../contracts/world-stream-contracts.js';
+function position(value) {
+    const parsed = notificationCursor(value);
+    if (parsed === null) {
+        throw new CliError('stream_position_invalid', 'Reopen this world to reconnect its updates.');
+    }
+    return parsed;
+}
+// A cursor is acknowledged only after the authorized snapshot was read. A
+// reconnect reads retained notifications, never replays a user command.
+export async function watchWorld(context, initial, signal, changed, disconnected) {
+    let cursor = initial, failures = 0;
+    position(cursor);
+    while (!signal.aborted) {
+        let reader;
+        try {
+            // Serialize refresh, not the 55-second stream. Tokens stay in memory
+            // and headers; no cookies, redirects, query credentials or transcript log.
+            const token = await access(async (value) => value);
+            signal.throwIfAborted();
+            const response = await fetch(endpoint(worldStreamPath(context.workspace, context.world)), { redirect: 'error', credentials: 'omit',
+                headers: { Authorization: `Bearer ${token}`, Accept: 'text/event-stream',
+                    'X-Firedrill-Actor': context.owner, 'X-Firedrill-Workspace': context.workspace, 'Last-Event-ID': cursor },
+                signal: AbortSignal.any([signal, AbortSignal.timeout(65000)]) });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw responseError(null, response.status);
+            }
+            if (!response.headers.get('Content-Type')?.startsWith('text/event-stream') || !response.body) {
+                await response.body?.cancel();
+                throw new CliError('stream_unavailable', 'Live updates are unavailable. Reopen this world to reconnect.');
+            }
+            reader = response.body.getReader();
+            const decoder = new TextDecoder('utf-8', { fatal: true });
+            let buffer = '', received = false;
+            while (!signal.aborted) {
+                const part = await reader.read();
+                if (part.done)
+                    break;
+                buffer += decoder.decode(part.value, { stream: true }).replace(/\r\n/g, '\n');
+                if (buffer.length > 65536)
+                    throw new CliError('stream_invalid', 'Live updates could not be read safely.');
+                let boundary;
+                while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+                    const frame = buffer.slice(0, boundary);
+                    buffer = buffer.slice(boundary + 2);
+                    if (frame.length > 16384)
+                        throw new CliError('stream_invalid', 'Live updates could not be read safely.');
+                    let event = '', id = '', body = '';
+                    for (const line of frame.split('\n')) {
+                        if (line.startsWith('event:'))
+                            event = line.slice(6).trim();
+                        else if (line.startsWith('id:'))
+                            id = line.slice(3).trim();
+                        else if (line.startsWith('data:'))
+                            body += (body ? '\n' : '') + line.slice(5).trimStart();
+                    }
+                    if (event === 'access_changed') {
+                        // The API can close at JWT expiry. A fresh authorized read either
+                        // refreshes that same identity or refuses revoked access.
+                        await changed();
+                        received = true;
+                        break;
+                    }
+                    if (event === 'changed' || event === 'snapshot') {
+                        const value = readWorldNotification(body, context.workspace, context.world, event, id);
+                        if (!value)
+                            throw new CliError('stream_invalid', 'Live update identity could not be confirmed. No user action was repeated.');
+                        if (position(value.sequence) > position(cursor) || event === 'snapshot' && position(value.sequence) === position(cursor)) {
+                            await changed();
+                            cursor = value.sequence;
+                            received = true;
+                        }
+                    }
+                }
+            }
+            if (received)
+                failures = 0;
+        }
+        catch (error) {
+            if (signal.aborted)
+                return;
+            const problem = error instanceof CliError ? error : new CliError('stream_disconnected', 'Live updates disconnected. Saved work has not been canceled.');
+            if (problem.exitCode === 2 || problem.exitCode === 3 || ++failures >= 3) {
+                disconnected(problem);
+                return;
+            }
+        }
+        finally {
+            await reader?.cancel().catch(() => undefined);
+            reader?.releaseLock();
+        }
+        if (!signal.aborted)
+            await sleep(Math.min(8000, 1000 * 2 ** failures), undefined, { signal }).catch(() => undefined);
+    }
+}