firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/runner-world-commands.js

@@ -0,0 +1,268 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { signRunnerRequest } from './runner-identity.js';
+import { localWorldClaimPath, localWorldClaimTime } from './runner-world-claim.js';
+import { retainLocalWorldObservation } from './runner-world-observations.js';
+import { LocalWorldCommandEvidence } from './runner-world-command-evidence.js';
+import { localWorldIdentityMatches, LOCAL_WORLD_IDENTITY_KEYS } from '../../contracts/local-world-native-contracts.js';
+const HASH = /^[a-f0-9]{64}$/, CHUNK = 65536, MAX_BODY = 8 * 1024 ** 2;
+const KINDS = ['http', 'mcp', 'stop', 'surface_open', 'surface_action', 'state_capture', 'world_reset', 'checkpoint_save', 'checkpoint_load',
+    'voice_start', 'voice_audio', 'voice_listen', 'voice_stop', 'app_save', 'paired_save'];
+const FINISHED = ['observed', 'not_dispatched', 'unknown', 'stop_requested'];
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const exact = (value, fields) => Object.keys(value).sort().join(',') === [...fields].sort().join(',');
+const sha = (body) => createHash('sha256').update(body).digest('hex');
+const invalid = () => new CliError('local_world_command_changed', 'The saved command does not match this exact local world. No action was repeated.');
+function command(value) {
+    if (value === null)
+        return;
+    if (!record(value) || !exact(value, ['id', 'sequence', 'kind', 'state', 'sha256', 'not_after', 'publication_key', 'publication_started_at'])
+        || typeof value.id !== 'string' || identifier(value.id) !== value.id
+        || typeof value.sequence !== 'string' || !/^[1-9][0-9]{0,15}$/.test(value.sequence)
+        || !Number.isSafeInteger(Number(value.sequence)) || typeof value.kind !== 'string' || !KINDS.includes(value.kind)
+        || typeof value.state !== 'string' || !['queued', 'publishing', 'accepted', ...FINISHED].includes(value.state)
+        || typeof value.sha256 !== 'string' || !HASH.test(value.sha256) || typeof value.not_after !== 'string'
+        || !Number.isFinite(Date.parse(value.not_after))
+        || (value.publication_key === null) !== (value.publication_started_at === null)
+        || value.publication_key !== null && (typeof value.publication_key !== 'string' || identifier(value.publication_key) !== value.publication_key
+            || typeof value.publication_started_at !== 'string' || !Number.isFinite(Date.parse(value.publication_started_at))))
+        throw invalid();
+}
+function same(left, right) {
+    return ['id', 'sequence', 'kind', 'sha256', 'not_after'].every(key => left[key] === right[key]);
+}
+function bytes(value, size, maximum, digest) {
+    if (typeof value !== 'string' || !Number.isSafeInteger(size) || size < 0 || size > maximum
+        || value.length !== 4 * Math.ceil(size / 3) || typeof digest !== 'string' || !HASH.test(digest))
+        throw invalid();
+    const body = Buffer.from(value, 'base64');
+    if (body.length !== size || body.toString('base64') !== value || sha(body) !== digest) {
+        body.fill(0);
+        throw invalid();
+    }
+    return body;
+}
+/** Private outbound command transport, not local-session admission. The cloud
+ * publication intent is committed before the sole native write. An existing or
+ * uncertain publication is read back by ORIGINAL id/hash, never sent again.
+ * Evidence collection, observation retention and lifecycle settlement are owned
+ * by the enclosing collector, not fabricated by returning from this transport. */
+export class LocalWorldCommandDelivery {
+    busy = false;
+    retainedObservation = null;
+    retainedObservationShape = null;
+    lastObservationRetention = -Infinity;
+    evidence = null;
+    owner;
+    configuration;
+    channel;
+    signal;
+    constructor(owner, configuration, channel, signal) {
+        this.owner = owner;
+        this.configuration = configuration;
+        this.channel = channel;
+        this.signal = signal;
+        if (configuration.control.schema !== 'firedrill.world-session.v1' || !owner.evidenceUpload
+            || !HASH.test(configuration.manifest_sha256))
+            throw invalid();
+    }
+    evidenceStore() {
+        return this.evidence ??= LocalWorldCommandEvidence.open(this.owner, this.configuration, this.channel, this.signal);
+    }
+    async close() {
+        if (this.busy)
+            throw invalid();
+        if (this.evidence)
+            await (await this.evidence).close();
+    }
+    async request(input) {
+        const owner = this.owner, sent = await localWorldClaimTime(owner, this.signal);
+        const action = input.action, selected = input.action === 'next' ? undefined : input.selected;
+        const selection = selected ? { command_id: selected.id, command_sha256: selected.sha256 } : null;
+        const fields = input.action === 'next' ? { action: 'next' }
+            : input.action === 'packet' ? { action: 'packet', command_id: selection.command_id, command_sha256: selection.command_sha256 }
+                : input.action === 'publish' ? { action: 'publish', command_id: selection.command_id, command_sha256: selection.command_sha256, publication_key: input.publication_key }
+                    : input.action === 'body' ? { action: 'body', command_id: selection.command_id, command_sha256: selection.command_sha256, offset: input.offset, length: input.length }
+                        : { action: 'checkpoint', command_id: selection.command_id, command_sha256: selection.command_sha256, offset: input.offset, length: input.length };
+        const payload = { schema: 'firedrill.local-world-command-read.v1',
+            job_id: owner.job, attempt_id: owner.attempt, lease_id: owner.lease, request_key: owner.request,
+            device_key: owner.device, native_session_id: owner.nativeSession, manifest_sha256: this.configuration.manifest_sha256,
+            session_id: owner.session.session_id, input_sha256: owner.session.input_sha256, read_key: randomUUID(), sent_at_ms: sent, ...fields };
+        const proof = await signRunnerRequest(owner, owner.device, payload, this.signal);
+        // Neither this API client nor the private native channel retries a write.
+        const result = await api(localWorldClaimPath(owner) + '/world-commands', { actor: owner.owner,
+            workspace: owner.workspace, signal: this.signal, method: 'POST', body: proof });
+        const extra = action === 'packet' ? ['packet_base64', 'body'] : ['body', 'checkpoint'].includes(action) ? ['offset', 'length', 'sha256', 'content_base64'] : [];
+        if (!record(result) || !localWorldIdentityMatches(result, owner, this.configuration.manifest_sha256)
+            || !exact(result, [...LOCAL_WORLD_IDENTITY_KEYS.filter(key => key !== 'manifest_sha256'), 'schema', 'session_id', 'lease_id', 'manifest_sha256', 'input_sha256',
+                'action', 'command', 'server_time', 'provenance', ...extra])
+            || result.schema !== 'firedrill.local-world-command-delivery.v1' || result.session_id !== owner.session.session_id
+            || result.lease_id !== owner.lease || result.manifest_sha256 !== this.configuration.manifest_sha256
+            || result.input_sha256 !== owner.session.input_sha256 || result.action !== action || result.provenance !== 'customer_device'
+            || typeof result.server_time !== 'string' || !Number.isFinite(Date.parse(result.server_time)))
+            throw invalid();
+        command(result.command);
+        if (selected && (!result.command || !same(selected, result.command)))
+            throw invalid();
+        if (result.command && Date.parse(result.command.not_after) > Date.parse(owner.session.expires_at))
+            throw invalid();
+        return result;
+    }
+    async next() {
+        if (this.busy)
+            throw invalid();
+        this.busy = true;
+        try {
+            await this.readObservation();
+            const result = await this.request({ action: 'next' });
+            if (result.command && FINISHED.includes(result.command.state))
+                throw invalid();
+            return result.command;
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    async observe() {
+        if (this.busy)
+            throw invalid();
+        this.busy = true;
+        try {
+            return await this.readObservation();
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    async readObservation() {
+        const observation = await this.channel.observe(), body = Buffer.from(JSON.stringify(observation));
+        // This is upload cadence only, not a simulation clock, invented delay or
+        // altered evidence. Keep changes promptly; coalesce unchanged heartbeats.
+        const comparable = Buffer.from(JSON.stringify({ ...observation, status: observation.status === null ? null
+                : Object.fromEntries(Object.entries(observation.status).filter(([key]) => !['observed_at', 'elapsed_ms'].includes(key))) }));
+        let digest, shape;
+        try {
+            digest = sha(body);
+            shape = sha(comparable);
+        }
+        finally {
+            body.fill(0);
+            comparable.fill(0);
+        }
+        if (this.retainedObservation !== digest && (this.retainedObservationShape !== shape || performance.now() - this.lastObservationRetention >= 15000)) {
+            await retainLocalWorldObservation(this.owner, this.configuration, observation, this.signal);
+            this.retainedObservation = digest;
+            this.retainedObservationShape = shape;
+            this.lastObservationRetention = performance.now();
+        }
+        return observation;
+    }
+    inspectNative(value, selected) {
+        if (value.session_id !== this.owner.session.session_id || value.operation_id !== this.owner.lease
+            || value.command_id !== selected.id || value.command_sha256 !== selected.sha256 || value.sequence !== Number(selected.sequence))
+            throw invalid();
+        return value;
+    }
+    /** Recovery is observation only. A missing native receipt stays unknown. */
+    async recover(selected) {
+        command(selected);
+        if (this.busy)
+            throw invalid();
+        this.busy = true;
+        try {
+            return await this.readResult(selected);
+        }
+        finally {
+            this.busy = false;
+        }
+    }
+    async readResult(selected) {
+        const evidence = await this.evidenceStore();
+        const saved = await evidence.saved(selected);
+        const value = this.inspectNative(saved ?? await this.channel.result(selected.id), selected);
+        return evidence.retain(selected, value);
+    }
+    async deliver(selected) {
+        command(selected);
+        if (this.busy || FINISHED.includes(selected.state))
+            throw invalid();
+        this.busy = true;
+        let packet = null, body = null;
+        try {
+            const evidence = await this.evidenceStore();
+            await evidence.remember(selected); // Durable encrypted identity before publication authority.
+            const saved = await this.request({ action: 'packet', selected }), current = saved.command;
+            if (current.publication_key !== null)
+                return await this.readResult(current);
+            if (current.state !== 'queued' || !record(saved.body) || !exact(saved.body, ['size', 'sha256'])
+                || !Number.isSafeInteger(saved.body.size) || Number(saved.body.size) < 0 || Number(saved.body.size) > MAX_BODY
+                || typeof saved.body.sha256 !== 'string' || !HASH.test(saved.body.sha256) || typeof saved.packet_base64 !== 'string')
+                throw invalid();
+            // Base64 length alone cannot determine the decoded size; bounded decoding
+            // is checked against the original retained command hash before use.
+            if (saved.packet_base64.length > 4 * Math.ceil(65536 / 3))
+                throw invalid();
+            packet = Buffer.from(saved.packet_base64, 'base64');
+            if (!packet.length || packet.length > 65536 || packet.toString('base64') !== saved.packet_base64 || sha(packet) !== selected.sha256)
+                throw invalid();
+            let document;
+            try {
+                document = JSON.parse(packet.toString('utf8'));
+            }
+            catch {
+                throw invalid();
+            }
+            if (!record(document) || !exact(document, ['schema', 'session_id', 'operation_id', 'command_id', 'sequence', 'kind', 'not_after', 'request'])
+                || document.schema !== 'firedrill.world-session-command.v1' || document.session_id !== this.owner.session.session_id
+                || document.operation_id !== this.owner.lease || document.command_id !== selected.id || document.sequence !== Number(selected.sequence)
+                || document.kind !== selected.kind || document.not_after !== selected.not_after || !record(document.request))
+                throw invalid();
+            body = Buffer.alloc(Number(saved.body.size));
+            for (let offset = 0; offset < body.length; offset += CHUNK) {
+                const length = Math.min(CHUNK, body.length - offset), part = await this.request({ action: 'body', selected, offset, length });
+                if (part.command.publication_key !== null)
+                    return await this.readResult(part.command);
+                if (part.offset !== offset || part.length !== length)
+                    throw invalid();
+                const chunk = bytes(part.content_base64, length, CHUNK, part.sha256);
+                try {
+                    chunk.copy(body, offset);
+                }
+                finally {
+                    chunk.fill(0);
+                }
+            }
+            if (sha(body) !== saved.body.sha256 || ['http', 'mcp'].includes(selected.kind)
+                && (document.request.body_size !== body.length || document.request.body_sha256 !== saved.body.sha256))
+                throw invalid();
+            if (selected.kind === 'checkpoint_load') {
+                if (body.length)
+                    throw invalid();
+                await this.channel.checkpointInput(packet, async (offset, length) => {
+                    const part = await this.request({ action: 'checkpoint', selected, offset, length });
+                    if (part.command.publication_key !== null || part.command.state !== 'queued'
+                        || part.offset !== offset || part.length !== length)
+                        throw invalid();
+                    return bytes(part.content_base64, length, CHUNK, part.sha256);
+                });
+            }
+            const publication = randomUUID(), admitted = await this.request({ action: 'publish', selected, publication_key: publication });
+            if (admitted.command?.publication_key !== publication || admitted.command.state !== 'publishing'
+                || !admitted.command.publication_started_at)
+                throw invalid();
+            // The cloud has already committed a durable intent. Loss from here can
+            // only trigger original result() readback, not another native publish().
+            this.signal.throwIfAborted();
+            const value = this.inspectNative(await this.channel.publish(packet, body), selected);
+            return await evidence.retain(selected, value);
+        }
+        finally {
+            packet?.fill(0);
+            body?.fill(0);
+            this.busy = false;
+        }
+    }
+}

package/dist/cli/src/runner-world-completion.js

@@ -0,0 +1,76 @@
+import { CliError } from './http.js';
+import { localContainerCompletion } from './runner-container.js';
+import { syncClosingReceipt } from './runner-completion.js';
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const fail = () => new CliError('local_world_closing_changed', 'The original local world cleanup record could not be confirmed. No world or command was restarted.');
+function status(value, session, operation) {
+    if (value === null)
+        return null;
+    if (!record(value) || value.schema !== 'firedrill.world-session-status.v7' || value.session_id !== session || value.operation_id !== operation
+        || value.target_invocation_observed !== false || value.behavior_assessed !== false || typeof value.state !== 'string'
+        || !['starting', 'active', 'resetting', 'checkpointing', 'stopping', 'stopped', 'failed'].includes(value.state)
+        || typeof value.code !== 'string' || value.code !== '' && !/^[a-z_]{1,64}$/.test(value.code))
+        throw fail();
+    const failed = value.state === 'failed';
+    // Cleanup carries lifecycle facts only. The original native status may also
+    // contain an applied dataset, fork, topology or private-filter reference;
+    // those stay in the separately gated evidence journal. Do not require their
+    // absence or open that journal to report this exact container's cleanup.
+    if (!failed && (typeof value.observed_at !== 'string' || !Number.isFinite(Date.parse(value.observed_at))
+        || ['elapsed_ms', 'completed_command_sequence', 'reset_count'].some(key => !Number.isSafeInteger(value[key]) || Number(value[key]) < 0)
+        || typeof value.native_cleanup_finished !== 'boolean' || value.native_cleanup_finished !== (value.state === 'stopped')))
+        throw fail();
+    return { schema: 'firedrill.local-world-closing-observation.v1', session_id: session, operation_id: operation,
+        target_invocation_observed: false, behavior_assessed: false, state: value.state, code: value.code,
+        observed_at: failed ? null : value.observed_at, elapsed_ms: failed ? null : value.elapsed_ms,
+        completed_command_sequence: failed ? null : value.completed_command_sequence,
+        reset_count: failed ? null : value.reset_count, native_cleanup_finished: failed ? null : value.native_cleanup_finished };
+}
+/** Reads existing private journals only. No Docker/provider lookup, execution
+ * claim/pulse, target/model/Vault activity, native publication or replacement key.
+ * The current authenticated member signs cleanup facts with the original device.
+ */
+export async function syncLocalWorldCompletion(scope, operation, signal, options = {}) {
+    const saved = await localContainerCompletion(scope, operation, 'world_session');
+    const identity = saved.worldEvidenceOwner, session = saved.document.world_session;
+    if (!identity || !session || identity.session.session_id !== session.session_id)
+        throw fail();
+    // This reference was journaled from the actual channel's validated final
+    // bytes before native release. It is NOT proof the bytes were saved locally
+    // or retained in GCS. Reporting cleanup must not depend on decrypting files.
+    const reference = saved.worldFinalStatus;
+    const native = reference ? { size: reference.size, sha256: reference.sha256 } : null;
+    const document = { ...saved.document, status: status(saved.document.status, session.session_id, saved.lease),
+        evidence: { schema: 'firedrill.local-world-closing-evidence.v1', native_status: native } };
+    return syncClosingReceipt(scope, { ...saved, document }, signal, options);
+}
+/** Report cleanup before saved-file transfer, then wait for settlement only
+ * after retention actually completed. This avoids waiting for the evidence
+ * worker while the same command has not yet supplied its original bytes.
+ */
+export async function syncLocalWorldClosing(scope, operation, signal, options = {}) {
+    let receipt = await syncLocalWorldCompletion(scope, operation, signal);
+    if (!receipt.received || receipt.settled)
+        return receipt;
+    const { syncLocalWorldEvidence } = await import('./runner-world-evidence-sync.js');
+    try {
+        const evidence = await syncLocalWorldEvidence(scope, operation, signal, options);
+        try {
+            receipt = await syncLocalWorldCompletion(scope, operation, signal, { wait: ['synced', 'access_removed', 'closed'].includes(evidence.state) });
+            return { ...receipt, evidence };
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            return { ...receipt, evidence, settlement_observation: 'unconfirmed',
+                settlement_code: error instanceof CliError ? error.code : 'local_world_closing_unconfirmed' };
+        }
+    }
+    catch (error) {
+        signal.throwIfAborted();
+        // Cleanup acceptance is an already observed fact. Failure to open/decrypt
+        // an optional evidence journal must not erase that separate original receipt.
+        return { ...receipt, evidence: { schema: 'firedrill.local-world-evidence-sync.v2', state: 'unconfirmed',
+                operation_id: operation, cleanup_receipt_received: receipt.received, cloud_settlement_observed: receipt.settled,
+                command_scan_complete: false, code: error instanceof CliError ? error.code : 'local_world_evidence_unconfirmed' } };
+    }
+}

package/dist/cli/src/runner-world-erasure.js

@@ -0,0 +1,95 @@
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { selectOne } from './prompts.js';
+import { localContainerCompletion, localWorldEvidenceContexts } from './runner-container.js';
+import { LocalWorldJournal } from './runner-world-journal.js';
+/** Offline removal of evidence only. The ORIGINAL owned container must already
+ * have an exact no-dispatch/cleanup receipt. No cloud login, model, Docker exec,
+ * credential rotation or deletion of source folders/cloud reports occurs.
+ */
+export async function forgetWorldEvidence(operation, options, output) {
+    const id = identifier(operation);
+    let context;
+    for await (const one of localWorldEvidenceContexts(id, options.workspace, undefined, options.signal)) {
+        if (context)
+            throw new CliError('local_world_erasure_identity', 'Choose one original saved world operation. No files or keys were removed.', 2);
+        context = one;
+    }
+    if (!context)
+        throw new CliError('local_world_erasure_identity', 'Choose one original saved world operation. No files or keys were removed.', 2);
+    const saved = await localContainerCompletion(context, id, 'world_session');
+    if (!saved.worldEvidenceOwner)
+        throw new CliError('local_world_erasure_identity', 'The original local world identity is unavailable.');
+    if (!options.approve) {
+        if (options.json || !process.stdin.isTTY || !process.stderr.isTTY)
+            throw new CliError('local_world_erasure_consent', 'Pass --discard-evidence to remove this operation’s private local evidence key and files. Cloud reports are unchanged.', 2);
+        const approved = await selectOne('Remove private local evidence for ' + id + '?', [
+            { value: false, label: 'Keep evidence' },
+            { value: true, label: 'Remove key and files', detail: 'Unsynchronized evidence cannot be recovered. Cloud reports and the cleanup receipt remain.' },
+        ], options.signal);
+        if (!approved)
+            return output({ state: 'kept', operation_id: id }, 'Local evidence kept.');
+    }
+    options.signal.throwIfAborted();
+    const journal = await LocalWorldJournal.acquire(saved.worldEvidenceOwner, saved.manifestSha256, { existingOnly: true, erasureOnly: true });
+    try {
+        const receipt = await journal.erase(options.signal);
+        output({ ...receipt, operation_id: id, workspace_id: context.workspace }, receipt.already_removed
+            ? 'This operation’s private local evidence was already removed. Cloud reports are unchanged.'
+            : receipt.continuation_required ? 'The private evidence key is removed. A bounded file-removal pass finished; repeat this exact forget command to continue. Cloud reports are unchanged.'
+                : 'Private local evidence files and their OS-held key removed. Cloud reports are unchanged. Filesystem backups are not covered.');
+    }
+    finally {
+        await journal.close();
+    }
+}
+export async function pruneWorldEvidence(options, output) {
+    let removed = 0, alreadyRemoved = 0, kept = 0, deferredCount = 0, inspected = 0;
+    const deferred = [];
+    const problem = (operation, code) => {
+        deferredCount++;
+        const item = { operation_id: operation, code };
+        if (deferred.length < 25)
+            deferred.push(item);
+        output({ schema: 'firedrill.local-world-prune-item.v1', ...item, state: 'deferred' }, `${operation}: ${code}. Evidence was not removed.`);
+    };
+    for await (const context of localWorldEvidenceContexts(undefined, options.workspace, problem, options.signal)) {
+        options.signal.throwIfAborted();
+        let journal;
+        try {
+            const saved = await localContainerCompletion(context, context.operation, 'world_session');
+            if (!saved.worldEvidenceOwner)
+                throw new CliError('local_world_erasure_identity', 'Original local world identity unavailable.');
+            journal = await LocalWorldJournal.acquire(saved.worldEvidenceOwner, saved.manifestSha256, { existingOnly: true, erasureOnly: true });
+            if (!journal.removalStarted && !Number.isFinite(journal.expiresAt))
+                throw new CliError('local_world_retention_unavailable', 'Use the exact forget command to remove a partially initialized private journal. No expiry was invented.');
+            if (!journal.removalStarted && journal.expiresAt > Date.now()) {
+                kept++;
+                continue;
+            }
+            const receipt = await journal.erase(options.signal);
+            if (receipt.continuation_required)
+                problem(context.operation, 'local_world_erasure_pending');
+            else if (receipt.already_removed)
+                alreadyRemoved++;
+            else
+                removed++;
+        }
+        catch (error) {
+            if (!(error instanceof CliError))
+                throw error;
+            problem(context.operation, error.code);
+        }
+        finally {
+            if (journal)
+                await journal.close();
+            inspected++;
+            if (inspected % 250 === 0)
+                output({ schema: 'firedrill.local-world-prune-progress.v1', inspected, removed,
+                    already_removed: alreadyRemoved, kept, deferred_count: deferredCount }, `Checked ${inspected} local world receipts.`);
+        }
+    }
+    output({ schema: 'firedrill.local-world-prune.v1', removed, already_removed: alreadyRemoved, kept, deferred,
+        inspected, deferred_count: deferredCount, deferred_truncated: deferredCount > deferred.length,
+        cloud_data_changed: false, filesystem_backup_erasure_attested: false }, `Local evidence: ${removed} removed, ${alreadyRemoved} previously removed, ${kept} within retention, ${deferredCount} need attention. Cloud reports are unchanged.`);
+}

package/dist/cli/src/runner-world-evidence-sync.js

@@ -0,0 +1,91 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { localContainerCompletion } from './runner-container.js';
+import { localWorldClaimPath } from './runner-world-claim.js';
+import { LocalWorldCommandEvidence } from './runner-world-command-evidence.js';
+import { historicalRunnerSigner } from './runner-identity.js';
+import { localClosingReceiptMatches } from '../../contracts/local-evidence-contracts.js';
+/** Existing encrypted bytes only, with a finite distinct historical server
+ * authority. No container/native channel, lease pulse, runtime configuration,
+ * model request or target replay exists in this recovery path.
+ */
+export async function syncLocalWorldEvidence(scope, operation, signal, options = {}) {
+    const saved = await localContainerCompletion(scope, operation, 'world_session'), owner = saved.worldEvidenceOwner;
+    if (!owner)
+        throw new CliError('local_world_evidence_changed', 'The original local world identity is unavailable. No world was replaced.');
+    const receipt = await api(localWorldClaimPath(owner) + '/completion', { actor: scope.owner, workspace: scope.workspace, signal });
+    if (!localClosingReceiptMatches(receipt, { ...owner, manifestSha256: saved.manifestSha256 })
+        || receipt.schema !== 'firedrill.local-completion-receipt.v1' || receipt.job_id !== owner.job || receipt.attempt_id !== owner.attempt
+        || receipt.lease_id !== owner.lease || receipt.request_key !== owner.request || receipt.manifest_sha256 !== saved.manifestSha256
+        || receipt.received !== true || receipt.cleanup_recorded !== true
+        || receipt.document?.schema !== 'firedrill.local-world-container-receipt.v1'
+        || receipt.document.world_session.session_id !== owner.session.session_id) {
+        throw new CliError('local_world_closing_required', 'Synchronize the original cleanup receipt with firedrill runner completion sync before transferring saved world files.');
+    }
+    const common = { schema: 'firedrill.local-world-evidence-sync.v2', operation_id: owner.lease, session_id: owner.session.session_id,
+        cleanup_receipt_received: receipt.received, cloud_settlement_observed: receipt.settled,
+        provenance: 'customer_device', command_details: options.onCommand ? 'streamed' : 'summary_only' };
+    if (receipt.settled === true)
+        return { ...common, state: 'closed', synchronized_commands: null, unavailable_commands: null, command_scan_complete: null };
+    if (receipt.settled !== false)
+        throw new CliError('local_world_evidence_changed', 'The closing status could not be confirmed. No files were discarded.');
+    const signer = await historicalRunnerSigner(scope, saved.device, signal);
+    // Cleanup survives revocation, but private evidence does not. Do not even
+    // decrypt the retained evidence journal on this cleanup-only recovery path.
+    if (signer.cleanupOnly)
+        return { ...common, state: 'access_removed', synchronized_commands: null,
+            unavailable_commands: null, command_scan_complete: false, native_status: { state: 'unavailable', code: 'runner_cleanup_only' } };
+    const evidence = await LocalWorldCommandEvidence.recover(owner, saved.manifestSha256, signal);
+    let synchronized = 0, unavailable = 0, commandScanComplete = true;
+    let nativeStatus = null;
+    const report = async (command, code) => {
+        if (code === null)
+            synchronized++;
+        else
+            unavailable++;
+        await options.onCommand?.({ schema: 'firedrill.local-world-evidence-command.v1', operation_id: owner.lease,
+            session_id: owner.session.session_id, command_id: command.id, sequence: command.sequence,
+            state: code === null ? 'synchronized' : 'unavailable', code });
+    };
+    try {
+        for await (const command of evidence.commands()) {
+            signal.throwIfAborted();
+            const original = await evidence.saved(command);
+            if (!original) {
+                await report(command, 'native_result_not_retained');
+                continue;
+            }
+            try {
+                await evidence.retain(command, original);
+                await report(command, null);
+            }
+            catch (error) {
+                if (!(error instanceof CliError) || !['local_world_file_unavailable', 'local_world_evidence_unavailable',
+                    'local_world_closing_access_removed', 'runner_cleanup_only'].includes(error.code))
+                    throw error;
+                await report(command, error.code);
+                if (['local_world_closing_access_removed', 'runner_cleanup_only'].includes(error.code)) {
+                    commandScanComplete = false;
+                    break;
+                }
+            }
+        }
+        if (saved.worldFinalStatus && commandScanComplete) {
+            try {
+                nativeStatus = await evidence.retainFinalNative({ size: saved.worldFinalStatus.size, sha256: saved.worldFinalStatus.sha256 });
+            }
+            catch (error) {
+                if (!(error instanceof CliError) || !['local_world_final_unavailable', 'local_world_closing_access_removed', 'runner_cleanup_only'].includes(error.code))
+                    throw error;
+                nativeStatus = { state: 'unavailable', code: error.code };
+            }
+        }
+        const partial = !commandScanComplete || unavailable > 0 || !!nativeStatus && typeof nativeStatus === 'object' && 'state' in nativeStatus
+            && nativeStatus.state !== 'retained';
+        return { ...common, state: partial ? 'partial' : 'synced', synchronized_commands: synchronized,
+            unavailable_commands: unavailable, command_scan_complete: commandScanComplete, native_status: nativeStatus };
+    }
+    finally {
+        await evidence.close();
+    }
+}