firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/runner-container.js

@@ -0,0 +1,794 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, opendir, rename } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { docker, command, dockerProcess, hostArch, imagePresent } from './runner-runtime.js';
+import { containerPolicy } from './local-container-policy.js';
+import { boundaryArguments, requireContainerBoundary } from './local-container-boundary.js';
+import { LocalModelRelay, modelFrameWriter, readModelFrames } from './runner-model-transport.js';
+import { withLocalJobInputs } from './runner-ownership.js';
+import { liveEventReader, trialReader, trialStatus } from './runner-trial-protocol.js';
+import { LocalSessionChannel, SESSION_FRAME_SCHEMA } from './runner-session-channel.js';
+import { localWorldObservation, localWorldStatus } from './runner-world-session-protocol.js';
+import { protectLocalWorldSession } from './runner-world-native-filters.js';
+import { LocalWorldJournal } from './runner-world-journal.js';
+import { processLifetimeLock } from './runner-process-lock.js';
+import { localExecutionTimeout } from './runner-execution-deadline.js';
+import { startCampaignWorldControls } from './runner-campaign-controls.js';
+const SCHEMA = 'firedrill.local-execution-frame.v1', CHUNK = 16384;
+const HASH = /^[a-f0-9]{64}$/, IMAGE = /^[a-z][a-z0-9-]{0,62}-docker\.pkg\.dev\/[a-z][a-z0-9-]{4,62}\/[a-z][a-z0-9-]{0,62}\/[a-z][a-z0-9-]{0,62}@sha256:[a-f0-9]{64}$/;
+const invalid = () => new CliError('local_container_identity_changed', 'The container does not match the exact saved execution. It was not started or replaced.');
+const failed = () => new CliError('local_container_unconfirmed', 'Local execution did not finish with a confirmed receipt. Its exact container journal was retained. No start was repeated.');
+const sha = (value) => createHash('sha256').update(value).digest('hex');
+const journalWrites = new Map();
+async function directory() {
+    const path = join(await privateDirectory(), 'containers');
+    await mkdir(path, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+        throw error; });
+    const row = await lstat(path);
+    if (!row.isDirectory() || row.isSymbolicLink() || row.mode & 0o077 || process.getuid && row.uid !== process.getuid())
+        throw invalid();
+    return path;
+}
+const journalPath = async (scope, lease) => join(await directory(), `${identifier(scope.owner)}-${identifier(scope.workspace)}-${identifier(lease)}.json`);
+export async function hasLocalContainerJournal(scope, lease) {
+    return lstat(await journalPath(scope, lease)).then(() => true, error => {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    });
+}
+async function retain(value, initial = false) {
+    // Native release acknowledgement and error teardown can overlap. Preserve
+    // invocation order and immutable stage bytes so an older write cannot replace
+    // the later exact-resource cleanup receipt.
+    const key = [value.owner, value.workspace, value.lease].join(':'), body = JSON.stringify(value);
+    const writing = (journalWrites.get(key) ?? Promise.resolve()).then(async () => {
+        const path = await journalPath(value, value.lease), temporary = path + '.' + randomUUID() + '.tmp';
+        const file = await open(initial ? path : temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(body);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        if (!initial)
+            await rename(temporary, path);
+        const parent = await open(await directory(), constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+        try {
+            await parent.sync();
+        }
+        finally {
+            await parent.close();
+        }
+    });
+    journalWrites.set(key, writing);
+    try {
+        await writing;
+    }
+    finally {
+        if (journalWrites.get(key) === writing)
+            journalWrites.delete(key);
+    }
+}
+async function load(scope, lease) {
+    const path = await journalPath(scope, lease), before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.mode & 0o077 || before.size > 8 * 1024 ** 2 + 16384
+        || process.getuid && before.uid !== process.getuid())
+        throw invalid();
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const actual = await file.stat();
+        if (actual.ino !== before.ino || actual.dev !== before.dev || actual.size !== before.size)
+            throw invalid();
+        const value = JSON.parse(await file.readFile('utf8'));
+        if (value.schema !== 'firedrill.local-container.v1' || !['validation', 'trial', 'world_session'].includes(value.purpose)
+            || value.owner !== scope.owner || value.workspace !== scope.workspace
+            || value.lease !== lease || value.name !== 'fd-job-' + lease || !IMAGE.test(value.image)
+            || !/^[a-f0-9]{40}$/.test(value.source_revision) || !HASH.test(value.manifest_sha256) || !HASH.test(value.configuration_digest)
+            || value.container_id !== null && !HASH.test(value.container_id)
+            || !['preflight', 'no_resource_dispatched', 'create_dispatched', 'created', 'start_dispatched', 'bootstrapped', 'guest_exited', 'container_exited', 'cleanup_confirmed'].includes(value.stage))
+            throw invalid();
+        for (const id of [value.world, value.device, value.job, value.attempt, value.request])
+            identifier(id);
+        if (value.purpose === 'world_session') {
+            const session = value.world_session;
+            if (!session || Object.keys(session).sort().join(',') !== 'configuration_id,expires_at,input_sha256,session_id'
+                || identifier(session.session_id) !== session.session_id || identifier(session.configuration_id) !== session.configuration_id
+                || !HASH.test(session.input_sha256) || !Number.isFinite(Date.parse(session.expires_at))
+                || typeof value.session_released !== 'boolean')
+                throw invalid();
+            const identity = value.world_journal;
+            if (!identity || Object.keys(identity).sort().join(',') !== 'attempt,device,evidenceUpload,grant,job,lease,nativeSession,owner,payloadDigest,request,session,workspace'
+                || identity.owner !== value.owner || identity.workspace !== value.workspace || identity.device !== value.device || identity.lease !== value.lease
+                || identity.job !== value.job || identity.request !== value.request || identity.attempt !== value.attempt || identity.evidenceUpload !== true
+                || JSON.stringify(identity.session) !== JSON.stringify(session) || !HASH.test(identity.payloadDigest))
+                throw invalid();
+            identifier(identity.grant);
+            identifier(identity.nativeSession);
+            const reference = value.world_final_status;
+            if (reference !== null && (!reference || Object.keys(reference).sort().join(',') !== 'schema,sha256,size'
+                || reference.schema !== 'firedrill.local-world-final-reference.v1' || !Number.isSafeInteger(reference.size)
+                || reference.size < 1 || reference.size > 8 * 1024 ** 2 || !HASH.test(reference.sha256)))
+                throw invalid();
+        }
+        else if (value.world_session !== undefined || value.session_released !== undefined || value.world_journal !== undefined
+            || value.world_final_status !== undefined || before.size > 16384)
+            throw invalid();
+        return value;
+    }
+    catch {
+        throw invalid();
+    }
+    finally {
+        await file.close();
+    }
+}
+async function locked(scope, lease, work) {
+    const path = (await journalPath(scope, lease)) + '.lock';
+    const lock = await processLifetimeLock(path);
+    try {
+        lock.assertHeld();
+        const value = await work(lock);
+        lock.assertHeld();
+        return value;
+    }
+    finally {
+        await lock.close();
+    }
+}
+function labels(value) {
+    return { 'io.firedrill.local-execution': value.lease, 'io.firedrill.actor': value.owner, 'io.firedrill.workspace': value.workspace,
+        'io.firedrill.job': value.job, 'io.firedrill.attempt': value.attempt, 'io.firedrill.device': value.device,
+        'io.firedrill.manifest': value.manifest_sha256 };
+}
+async function inspected(context, value, signal) {
+    const reply = await command(context, ['container', 'inspect', value.container_id ?? value.name], { signal });
+    if (reply.code !== 0)
+        return null; // Never absence proof for a delayed create.
+    let rows;
+    try {
+        rows = JSON.parse(reply.output);
+    }
+    catch {
+        throw invalid();
+    }
+    const row = Array.isArray(rows) && rows.length === 1 ? rows[0] : null;
+    if (!row || !HASH.test(row.Id) || value.container_id && row.Id !== value.container_id || row.Name !== '/' + value.name
+        || row.Config?.Image !== value.image || Object.entries(labels(value)).some(([key, expected]) => row.Config?.Labels?.[key] !== expected))
+        throw invalid();
+    return row;
+}
+async function cleanup(context, value, signal) {
+    if (value.stage === 'cleanup_confirmed' || value.stage === 'no_resource_dispatched')
+        return true;
+    if (value.stage === 'preflight') {
+        // This persisted stage precedes create intent. It is not a failed inspect
+        // being mistaken for deletion of an uncertain resource.
+        value.stage = 'no_resource_dispatched';
+        await retain(value);
+        return true;
+    }
+    if (!context)
+        return false;
+    const row = await inspected(context, value, signal);
+    if (!row)
+        return false;
+    value.container_id = row.Id;
+    await retain(value);
+    const result = await command(context, ['container', 'rm', '--force', row.Id], { signal });
+    if (result.code !== 0)
+        return false;
+    // Successful deletion is exact-resource proof. A failed/not-found command or
+    // an absent pending create is deliberately NOT promoted to cleanup proof.
+    value.stage = 'cleanup_confirmed';
+    await retain(value);
+    return true;
+}
+/** Exact local cleanup only. Does not replay bootstrap/start or settle cloud state. */
+export async function recoverLocalContainer(scope, lease, signal) {
+    lease = identifier(lease);
+    return locked(scope, lease, async (lock) => {
+        signal = AbortSignal.any([signal, lock.signal]);
+        const value = await load(scope, lease);
+        const confirmed = value.stage === 'cleanup_confirmed' || value.stage === 'no_resource_dispatched'
+            || await cleanup(value.stage === 'preflight' ? undefined : await docker(), value, signal);
+        return { schema: 'firedrill.local-container-recovery.v1', operation_id: lease,
+            cleanup_confirmed: confirmed, resource_state: value.stage === 'no_resource_dispatched' ? 'not_dispatched' : confirmed ? 'removed' : 'unconfirmed',
+            cloud_completion_recorded: false };
+    });
+}
+/** Read the exact private journal only. No Docker lookup, start or deletion. */
+export async function localContainerPurpose(scope, operation) {
+    return (await load(scope, identifier(operation))).purpose;
+}
+/** OS-owned metadata discovery for OFFLINE evidence erasure only. This neither
+ * authenticates cloud access nor opens evidence, starts or removes a container.
+ */
+export async function* localWorldEvidenceContexts(operation, workspace, onProblem, signal) {
+    for await (const row of localEvidenceContexts(operation, workspace, onProblem, signal)) {
+        if (row.purpose === 'world_session')
+            yield row;
+    }
+}
+export async function* localEvidenceContexts(operation, workspace, onProblem, signal) {
+    if (operation)
+        identifier(operation);
+    if (workspace)
+        identifier(workspace);
+    const uuid = '[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}';
+    const format = new RegExp('^(' + uuid + ')-(' + uuid + ')-(' + uuid + ')\\.json$');
+    // OS directory iteration is bounded and closes on exhaustion, cancellation or
+    // an early consumer return. No sort/whole-history array is needed for erasure.
+    for await (const item of await opendir(await directory(), { bufferSize: 32 })) {
+        signal?.throwIfAborted();
+        const found = format.exec(item.name);
+        if (!found || operation && found[3] !== operation || workspace && found[2] !== workspace)
+            continue;
+        const scope = { owner: identifier(found[1]), workspace: identifier(found[2]) }, id = identifier(found[3]);
+        try {
+            const record = await load(scope, id);
+            yield { ...scope, operation: id, purpose: record.purpose };
+        }
+        catch (error) {
+            if (!onProblem)
+                throw error;
+            onProblem(id, error instanceof CliError ? error.code : 'local_container_identity_changed');
+        }
+    }
+}
+/** Offline evidence removal holds the ORIGINAL execution lock and requires its
+ * saved no-dispatch or exact cleanup receipt. No Docker/provider call occurs. */
+export async function withLocalContainerCompletion(scope, operation, purpose, work) {
+    operation = identifier(operation);
+    return locked(scope, operation, async (lock) => work(await localContainerCompletion(scope, operation, purpose), lock.signal));
+}
+export async function localContainerCompletion(scope, operation, purpose = 'validation') {
+    const value = await load(scope, identifier(operation));
+    if (value.purpose !== purpose)
+        throw new CliError('local_completion_purpose_changed', 'Use the closing receipt for this exact saved execution purpose.');
+    const absent = value.stage === 'no_resource_dispatched';
+    if (!absent && (value.stage !== 'cleanup_confirmed' || !value.container_id)) {
+        throw new CliError('local_container_cleanup_pending', 'Confirm cleanup of the exact saved container before synchronizing its closing receipt.');
+    }
+    return { owner: value.owner, workspace: value.workspace, device: value.device, job: value.job, request: value.request,
+        lease: value.lease, attempt: value.attempt, manifestSha256: value.manifest_sha256,
+        worldEvidenceOwner: purpose === 'world_session' ? value.world_journal : undefined,
+        worldFinalStatus: purpose === 'world_session' ? value.world_final_status : undefined,
+        document: { schema: purpose === 'world_session' ? 'firedrill.local-world-container-receipt.v1'
+                : purpose === 'trial' ? 'firedrill.local-trial-container-receipt.v1' : 'firedrill.local-container-receipt.v1',
+            ...(purpose === 'world_session' ? { world_session: value.world_session, session_released: value.session_released } : {}),
+            operation_id: value.lease, container_id: value.container_id,
+            name: value.name, image: value.image, resource_state: absent ? 'not_dispatched' : 'removed', removed: !absent,
+            launch: value.launch, exit_code: value.exit_code, status: value.status ?? null } };
+}
+function boundary(owner, policy, inputs) {
+    const memory = owner.limits.memory_mb * 1024 ** 2, cpus = owner.limits.cpu_units * 10 ** 9;
+    if (!Number.isSafeInteger(memory) || memory < 1024 ** 3 || !Number.isSafeInteger(cpus) || cpus < 10 ** 9)
+        throw invalid();
+    const workBytes = Math.floor(memory * 0.6), privateBytes = Math.floor(memory * 0.05);
+    const workInput = inputs.manifest.entries.filter(item => !['scenarios', 'dataset', 'checkpoint', 'application_checkpoint'].includes(item.part)).reduce((sum, item) => sum + item.size, 0);
+    const scenarioSize = owner.purpose === 'world_session' ? 0 : inputs.manifest.entries.find(item => item.part === 'scenarios')?.size ?? Infinity;
+    const datasetSize = inputs.manifest.entries.find(item => item.part === 'dataset')?.size ?? 0;
+    // The fixed guest bootstrap places initial checkpoints in /run/simulation,
+    // beside scenarios and datasets, not in the separate /work archive store.
+    const checkpointSize = inputs.manifest.entries.find(item => item.part === 'checkpoint')?.size ?? 0;
+    const applicationSize = inputs.manifest.entries.find(item => item.part === 'application_checkpoint')?.size ?? 0;
+    if (workInput * 2 > workBytes || scenarioSize + datasetSize + checkpointSize + applicationSize + 4 * 1024 ** 2 > privateBytes) {
+        throw new CliError('local_storage_capacity_required', 'The approved memory-backed execution storage cannot hold these inputs safely. No image, memory limit or execution location was changed.', 2);
+    }
+    return { image: owner.runtime.image, arguments: ['-m', 'runtime_support.guest_local_execution', '--operation-id', owner.lease,
+            ...(policy.requiredApparmor ? ['--apparmor-profile', policy.apparmor.name] : [])], memoryBytes: memory, nanoCpus: cpus,
+        interactive: true, tmpfs: {
+            '/work': `rw,nosuid,nodev,size=${workBytes},uid=2000,gid=2000,mode=0755`,
+            '/run/simulation': `rw,nosuid,nodev,noexec,size=${privateBytes},uid=2000,gid=2000,mode=0700`,
+            '/tmp': `rw,nosuid,nodev,noexec,size=${privateBytes},uid=2000,gid=2000,mode=1777`
+        } };
+}
+async function bootstrap(owner, inputs, configuration, write, signal) {
+    const packet = Buffer.from(JSON.stringify(configuration));
+    if (packet.length > 2 * 1024 ** 2)
+        throw invalid();
+    const parts = [...(owner.purpose === 'world_session' ? ['source', 'compiled', 'packages']
+            : ['source', owner.purpose === 'trial' ? 'compiled' : 'candidate', 'packages', 'scenarios']),
+        ...(['trial', 'world_session'].includes(owner.purpose) && inputs.manifest.entries.some(one => one.part === 'dataset') ? ['dataset'] : []),
+        ...(['world_session', 'trial'].includes(owner.purpose) && inputs.manifest.entries.some(one => one.part === 'checkpoint') ? ['checkpoint'] : []),
+        ...(['world_session', 'trial'].includes(owner.purpose) && inputs.manifest.entries.some(one => one.part === 'application_checkpoint') ? ['application_checkpoint'] : [])];
+    const entries = parts.map(part => {
+        const entry = inputs.manifest.entries.find(item => item.part === part);
+        if (!entry)
+            throw invalid();
+        return entry;
+    });
+    const configurationEntry = { part: 'configuration', size: packet.length, sha256: sha(packet) };
+    const emit = (kind, fields = {}) => write({ schema: SCHEMA, kind, id: owner.lease, ...fields });
+    try {
+        await emit('bootstrap', { job_id: owner.job, attempt_id: owner.attempt, manifest_sha256: inputs.manifestSha256,
+            purpose: owner.purpose, entries: [...entries, configurationEntry] });
+        for (const entry of [...entries, configurationEntry]) {
+            signal.throwIfAborted();
+            let size = 0, sequence = 0;
+            const hash = createHash('sha256');
+            const chunk = async (body) => {
+                signal.throwIfAborted();
+                hash.update(body);
+                size += body.length;
+                await emit('input_chunk', { part: entry.part, sequence: sequence++, data: body.toString('base64') });
+            };
+            if (entry.part === 'configuration') {
+                for (let offset = 0; offset < packet.length; offset += CHUNK)
+                    await chunk(packet.subarray(offset, offset + CHUNK));
+            }
+            else {
+                const path = inputs.files[entry.part];
+                if (typeof path !== 'string')
+                    throw invalid();
+                const before = await lstat(path);
+                if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.mode & 0o077 || before.size !== entry.size
+                    || process.getuid && before.uid !== process.getuid())
+                    throw invalid();
+                const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+                try {
+                    const actual = await file.stat();
+                    if (actual.ino !== before.ino || actual.dev !== before.dev || actual.size !== before.size)
+                        throw invalid();
+                    const bytes = Buffer.alloc(CHUNK);
+                    while (size < entry.size) {
+                        const result = await file.read(bytes, 0, Math.min(CHUNK, entry.size - size), size);
+                        if (!result.bytesRead)
+                            throw invalid();
+                        await chunk(bytes.subarray(0, result.bytesRead));
+                    }
+                    const after = await file.stat();
+                    if (after.size !== actual.size || after.mtimeMs !== actual.mtimeMs || after.ctimeMs !== actual.ctimeMs)
+                        throw invalid();
+                }
+                finally {
+                    await file.close();
+                }
+            }
+            if (size !== entry.size || hash.digest('hex') !== entry.sha256)
+                throw invalid();
+            await emit('input_end', { part: entry.part, sequence });
+        }
+        await emit('commit');
+    }
+    finally {
+        packet.fill(0);
+    } // Best-effort buffer erasure, not JS-string zeroization.
+}
+async function connected(context, value, owner, inputs, configuration, policy, collector, signal) {
+    const selected = value.boundary;
+    if (!selected || !value.security)
+        throw invalid();
+    value.stage = 'start_dispatched';
+    await retain(value);
+    const child = dockerProcess(context, ['container', 'start', '--attach', '--interactive', value.container_id], signal);
+    child.stderr.resume(); // No daemon/target output or frame body goes to a terminal.
+    const closed = new Promise((resolve, reject) => {
+        child.once('error', () => reject(failed()));
+        child.once('close', code => resolve(code));
+    });
+    void closed.catch(() => undefined);
+    const stopping = new AbortController(), combined = AbortSignal.any([signal, stopping.signal]);
+    const write = modelFrameWriter(child.stdin, combined);
+    let relay;
+    let session, sessionWork;
+    let campaignControls;
+    let finalSession;
+    let installed = false, finished = false, result;
+    const live = collector.purpose === 'trial' && configuration.control.schema === 'firedrill.trial.v1'
+        ? liveEventReader(owner.lease, configuration.control.execution_id, configuration.control.scenario_key, collector.live, collector.liveArtifact) : null;
+    const incoming = readModelFrames(child.stdout, combined);
+    const reading = (async () => {
+        for await (const frame of incoming) {
+            if (!frame || typeof frame !== 'object' || Array.isArray(frame))
+                throw failed();
+            const item = frame;
+            if (item.schema === 'firedrill.local-runtime-frame.v2') {
+                if (!installed || finished || !relay)
+                    throw failed();
+                await relay.accept(item);
+                continue;
+            }
+            if (item.schema === SESSION_FRAME_SCHEMA) {
+                if (!installed || finished || collector.purpose !== 'world_session' || !session)
+                    throw failed();
+                await session.accept(item);
+                continue;
+            }
+            if (item.schema !== SCHEMA || item.id !== owner.lease)
+                throw failed();
+            if (typeof item.kind === 'string' && ['live_event', 'live_event_chunk', 'live_event_end',
+                'live_artifact', 'live_artifact_chunk', 'live_artifact_end'].includes(item.kind)) {
+                if (!installed || finished || !live)
+                    throw failed();
+                await live.accept(item);
+                continue;
+            }
+            if (item.kind === 'bootstrapped' && !installed && !finished
+                && Object.keys(item).sort().join(',') === 'id,kind,manifest_sha256,schema' && item.manifest_sha256 === inputs.manifestSha256) {
+                const row = await inspected(context, value, combined);
+                if (!row || row.State?.Running !== true || row.State?.Restarting)
+                    throw failed();
+                requireContainerBoundary(row, policy, selected);
+                value.stage = 'bootstrapped';
+                await retain(value);
+                installed = true;
+                if (collector.purpose === 'world_session') {
+                    if (owner.purpose !== 'world_session' || configuration.control.schema !== 'firedrill.world-session.v1')
+                        throw failed();
+                    const sessionOwner = owner, control = configuration.control;
+                    session = new LocalSessionChannel(owner.lease, owner.session.session_id, write, combined, observation => localWorldObservation(observation, sessionOwner, control));
+                }
+                // Bootstrap may outlive the window checked before container start.
+                // Refuse the target handoff now; closing grace never authorizes work.
+                localExecutionTimeout(configuration);
+                await write({ schema: SCHEMA, kind: 'execute', id: owner.lease });
+                if (collector.purpose === 'trial' && owner.purpose === 'trial' && owner.evidenceUpload
+                    && configuration.control.schema === 'firedrill.trial.v1' && configuration.control.world_continuity === 'continuous') {
+                    // This is a separate bounded control poll, not another model reader
+                    // or local runner. Every native call rechecks the ORIGINAL container
+                    // identity and unchanged isolation before its fixed image entry.
+                    const current = async (active) => {
+                        const row = await inspected(context, value, active);
+                        if (!row || row.State?.Running !== true || row.State?.Restarting || value.stage !== 'bootstrapped')
+                            throw failed();
+                        requireContainerBoundary(row, policy, selected);
+                    };
+                    campaignControls = startCampaignWorldControls(owner, configuration, {
+                        stage: async (id, packet, digest, active) => {
+                            await current(active);
+                            const bounded = AbortSignal.any([active, AbortSignal.timeout(20000)]);
+                            const staging = dockerProcess(context, ['container', 'exec', '--interactive', '--user', '2000:2000', value.container_id,
+                                '/opt/firedrill/bin/python', '-P', '-B', '-m', 'runtime_support.guest_campaign_input',
+                                '--operation-id', owner.lease, '--command-id', identifier(id)], bounded);
+                            staging.stderr.resume();
+                            const chunks = [];
+                            let length = 0, overflow = false;
+                            const done = new Promise((resolve, reject) => {
+                                staging.stdout.on('data', (chunk) => {
+                                    length += chunk.length;
+                                    if (length > 8192) {
+                                        overflow = true;
+                                        staging.kill('SIGTERM');
+                                    }
+                                    else
+                                        chunks.push(chunk);
+                                });
+                                staging.once('error', () => reject(failed()));
+                                staging.once('close', code => overflow || bounded.aborted ? reject(failed()) : resolve({ code, body: Buffer.concat(chunks) }));
+                            });
+                            staging.stdin.on('error', () => undefined);
+                            staging.stdin.end(packet);
+                            const result = await done;
+                            try {
+                                const row = JSON.parse(result.body.toString('utf8'));
+                                if (result.code !== 0 && row && typeof row === 'object' && !Array.isArray(row)
+                                    && Object.keys(row).sort().join(',') === 'code,schema'
+                                    && row.schema === 'firedrill.campaign-world-control-error.v1'
+                                    && row.code === 'campaign_world_control_capacity')
+                                    throw new CliError('campaign_world_control_capacity', 'This runtime has no room to retain another world control. No command was published.');
+                                if (result.code !== 0 || !row || typeof row !== 'object' || Array.isArray(row)
+                                    || Object.keys(row).sort().join(',') !== 'command_id,operation_id,schema,sha256,staged'
+                                    || row.schema !== 'firedrill.campaign-world-control-input.v1'
+                                    || row.command_id !== id || row.operation_id !== owner.lease
+                                    || row.sha256 !== digest || row.staged !== true)
+                                    throw failed();
+                            }
+                            finally {
+                                result.body.fill(0);
+                                for (const bytes of chunks)
+                                    bytes.fill(0);
+                            }
+                        },
+                        read: async (id, mode, active) => {
+                            await current(active);
+                            const result = await command(context, ['container', 'exec', '--user', '2000:2000', value.container_id,
+                                '/opt/firedrill/bin/python', '-P', '-B', '-m', 'runtime_support.guest_campaign_bridge',
+                                '--operation-id', owner.lease, '--command-id', identifier(id), '--mode', mode], { signal: active, seconds: 15, maximum: 32768 });
+                            let resultValue;
+                            try {
+                                resultValue = JSON.parse(result.output);
+                            }
+                            catch {
+                                throw failed();
+                            }
+                            if (result.code !== 0) {
+                                if (resultValue && typeof resultValue === 'object' && !Array.isArray(resultValue)
+                                    && Object.keys(resultValue).sort().join(',') === 'code,schema'
+                                    && resultValue.schema === 'firedrill.campaign-world-control-error.v1'
+                                    && resultValue.code === 'campaign_world_control_capacity')
+                                    throw new CliError('campaign_world_control_capacity', 'This runtime has no room to retain another world control. No command was published.');
+                                throw failed();
+                            }
+                            return resultValue;
+                        },
+                    }, combined);
+                }
+                if (collector.purpose === 'world_session') {
+                    if (owner.purpose !== 'world_session' || !session)
+                        throw failed();
+                    const channel = session, sessionOwner = owner;
+                    // Never await this loop inside the sole pipe reader. Model replies,
+                    // command acknowledgements and evidence chunks all need that reader.
+                    sessionWork = Promise.resolve().then(async () => {
+                        if (await protectLocalWorldSession(sessionOwner, configuration, channel, combined)) {
+                            await collector.run(sessionOwner, configuration, channel, combined);
+                        }
+                        if (!channel.isClosing || channel.isReleased)
+                            throw failed();
+                        finalSession = await channel.finalObservation();
+                        value.world_final_status = finalSession.reference;
+                        await retain(value);
+                        await channel.release();
+                        value.session_released = true;
+                        await retain(value);
+                    }).catch(error => { stopping.abort(); throw error; });
+                    void sessionWork.catch(() => undefined);
+                }
+                continue;
+            }
+            if (item.kind !== 'finished' || !installed || finished || live?.pending || Object.keys(item).sort().join(',') !== 'id,kind,launch,schema,status'
+                || !item.launch || typeof item.launch !== 'object' || Array.isArray(item.launch)
+                || item.status !== null && (!item.status || typeof item.status !== 'object' || Array.isArray(item.status)))
+                throw failed();
+            const launch = item.launch;
+            if (launch.launch_id !== owner.lease || !['exited', 'launch_failed'].includes(launch.state)
+                || Object.keys(launch).sort().join(',') !== (launch.state === 'exited' ? 'exit_code,launch_id,state' : 'launch_id,state')
+                || launch.state === 'exited' && (!Number.isSafeInteger(launch.exit_code) || launch.exit_code < -128 || launch.exit_code > 255))
+                throw failed();
+            if (collector.purpose === 'trial')
+                trialStatus(item.status);
+            if (collector.purpose === 'world_session') {
+                if (owner.purpose !== 'world_session' || configuration.control.schema !== 'firedrill.world-session.v1'
+                    || !session?.isClosing || !session.isReleased || !sessionWork || !finalSession)
+                    throw failed();
+                await sessionWork;
+                const reference = finalSession.reference, received = item.status;
+                if (reference === null ? received !== null : received === null
+                    || Object.keys(received).sort().join(',') !== 'schema,sha256,size'
+                    || received.schema !== reference.schema || received.sha256 !== reference.sha256 || received.size !== reference.size)
+                    throw failed();
+                const originalLaunch = finalSession.observation.launch;
+                if (!originalLaunch || originalLaunch.launch_id !== launch.launch_id || originalLaunch.state !== launch.state
+                    || originalLaunch.exit_code !== launch.exit_code)
+                    throw failed();
+                item.status = finalSession.observation.status;
+                localWorldStatus(item.status, owner, configuration.control);
+            }
+            finished = true;
+            await campaignControls?.stop();
+            campaignControls = undefined;
+            relay?.close();
+            value.launch = launch;
+            value.status = item.status;
+            value.stage = 'guest_exited';
+            await retain(value);
+            const row = await inspected(context, value, combined);
+            if (!row || row.State?.Running !== true || row.State?.Restarting)
+                throw failed();
+            requireContainerBoundary(row, policy, selected);
+            let exported = false;
+            const reply = async (kind) => {
+                const response = await incoming.next();
+                const frame = response.value;
+                if (response.done || !frame || frame.schema !== SCHEMA || frame.kind !== kind || frame.id !== owner.lease)
+                    throw failed();
+                return frame;
+            };
+            const exportNative = async (kind) => {
+                const status = item.status;
+                if (exported || launch.state !== 'exited' || !['native_validation', 'native_operation_attempt'].includes(kind)
+                    || (kind === 'native_validation' ? launch.exit_code !== 0 || status?.state !== 'native_validated'
+                        : launch.exit_code === 0 || status?.state !== 'failed' || status.operation_attempt_available !== true))
+                    throw failed();
+                exported = true;
+                await write({ schema: SCHEMA, kind: 'export', id: owner.lease, artifact: kind });
+                const response = await reply('exported'), receipt = response.receipt;
+                if (Object.keys(response).sort().join(',') !== 'artifact,id,kind,receipt,schema' || response.artifact !== kind || !receipt
+                    || !Number.isSafeInteger(receipt.size) || receipt.size < 1 || !HASH.test(receipt.sha256)
+                    || (kind === 'native_validation' ? Object.keys(receipt).sort().join(',') !== 'runtime_validated,scope,sha256,size'
+                        || receipt.size > 128 * 1024 ** 2 || !('runtime_validated' in receipt) || receipt.runtime_validated !== false
+                        || !('scope' in receipt) || receipt.scope !== (configuration.control.validation_scope === 'target_startup_only'
+                        ? 'target_startup_only' : 'native_runtime_and_scenario_preconditions')
+                        : Object.keys(receipt).sort().join(',') !== 'complete,sha256,size' || receipt.size > 8 * 1024 ** 2
+                            || !('complete' in receipt) || receipt.complete !== false))
+                    throw failed();
+                return { kind, receipt, read: async (offset, length) => {
+                        if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 1 || length > CHUNK || offset + length > receipt.size)
+                            throw failed();
+                        await write({ schema: SCHEMA, kind: 'export_chunk', id: owner.lease, offset, length });
+                        const response = await reply('export_chunk');
+                        if (Object.keys(response).sort().join(',') !== 'data,id,kind,length,offset,schema,sha256'
+                            || response.offset !== offset || response.length !== length || typeof response.data !== 'string'
+                            || response.data.length > 4 * Math.ceil(CHUNK / 3))
+                            throw failed();
+                        const body = Buffer.from(response.data, 'base64');
+                        if (body.length !== length || body.toString('base64') !== response.data || sha(body) !== response.sha256)
+                            throw failed();
+                        return body;
+                    } };
+            };
+            const observation = { operation_id: owner.lease, container_id: value.container_id, launch,
+                status: item.status, provenance: 'customer_device' };
+            if (collector.purpose === 'trial') {
+                const control = configuration.control;
+                if (control.schema !== 'firedrill.trial.v1')
+                    throw failed();
+                result = await collector.collect(owner, observation, trialReader(owner.lease, control.execution_id, control.scenario_key, launch, (kind, fields = {}) => write({ schema: SCHEMA, kind, id: owner.lease, ...fields }), reply), combined);
+            }
+            else if (collector.purpose === 'world_session') {
+                if (owner.purpose !== 'world_session' || !finalSession)
+                    throw failed();
+                result = await collector.collect(owner, observation, finalSession, combined);
+            }
+            else
+                result = await collector.collect(owner, observation, exportNative, combined);
+            await write({ schema: SCHEMA, kind: 'release', id: owner.lease });
+            child.stdin.end();
+        }
+        if (!finished)
+            throw failed();
+    })();
+    // Start both handlers in this turn, before any awaited operation. Even a
+    // constructor failure goes through descriptor and child teardown below.
+    let sending = Promise.resolve();
+    try {
+        relay = new LocalModelRelay(configuration, write, combined);
+        sending = bootstrap(owner, inputs, configuration, write, combined);
+        // Both operations have handlers immediately. A malformed/closed channel
+        // aborts input writes, and no start/bootstrap call is retried.
+        await Promise.all([sending, reading]);
+        const exit = await closed, row = await inspected(context, value, combined);
+        if (!row || row.State?.Running || row.State?.Restarting || row.State?.Status !== 'exited'
+            || !Number.isSafeInteger(row.State?.ExitCode) || exit === null || exit !== row.State.ExitCode)
+            throw failed();
+        requireContainerBoundary(row, policy, selected);
+        value.stage = 'container_exited';
+        value.exit_code = row.State.ExitCode;
+        await retain(value);
+        return result;
+    }
+    finally {
+        finalSession?.statusBytes?.fill(0);
+        relay?.close();
+        session?.close();
+        stopping.abort();
+        await campaignControls?.stop();
+        child.stdin.destroy();
+        child.stdout.destroy();
+        child.kill('SIGTERM');
+        // Killing the CLI is not container cleanup. The caller always resolves the
+        // owned container separately, under a fresh bounded cleanup signal.
+        let timer;
+        try {
+            await Promise.race([Promise.allSettled([sending, reading, closed, sessionWork]), new Promise(resolve => {
+                    timer = setTimeout(() => { child.kill('SIGKILL'); resolve(); }, 2000);
+                })]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            await live?.close();
+        }
+    }
+}
+/** Internal executor; public run controls wait for completion/evidence wiring. */
+async function executeLocalContainer(owner, inputs, configuration, collector, signal) {
+    if (!owner.resourceJournalRetained)
+        throw invalid();
+    if (owner.purpose !== collector.purpose || (collector.purpose === 'world_session'
+        ? owner.purpose !== 'world_session' || configuration.control.schema !== 'firedrill.world-session.v1'
+            || configuration.control.purpose !== 'world_inspection_session'
+            || configuration.world_session?.session_id !== owner.session.session_id
+            || configuration.world_session?.input_sha256 !== owner.session.input_sha256
+        : collector.purpose === 'trial'
+            ? configuration.control.schema !== 'firedrill.trial.v1' || configuration.control.purpose !== 'simulation_trial'
+            : configuration.control.schema !== 'firedrill.validation.v1' || configuration.control.purpose !== 'world_validation')
+        || configuration.operation_id !== owner.lease || configuration.job_id !== owner.job
+        || configuration.attempt_id !== owner.attempt || configuration.manifest_sha256 !== inputs.manifestSha256)
+        throw invalid();
+    return locked(owner, owner.lease, async (lock) => {
+        signal = AbortSignal.any([signal, lock.signal]);
+        const value = { schema: 'firedrill.local-container.v1', owner: owner.owner, workspace: owner.workspace, world: owner.world,
+            purpose: collector.purpose, device: owner.device, job: owner.job, attempt: owner.attempt, lease: owner.lease, request: owner.request,
+            manifest_sha256: inputs.manifestSha256, configuration_digest: owner.configurationDigest, image: owner.runtime.image,
+            source_revision: owner.runtime.source_revision, name: 'fd-job-' + owner.lease, container_id: null, stage: 'preflight',
+            boundary: null, security: null,
+            launch: null, exit_code: null, status: null };
+        if (owner.purpose === 'world_session') {
+            value.world_session = owner.session;
+            value.session_released = false;
+            value.world_final_status = null;
+            value.world_journal = { owner: owner.owner, workspace: owner.workspace, device: owner.device, lease: owner.lease, attempt: owner.attempt,
+                nativeSession: owner.nativeSession, job: owner.job, request: owner.request, grant: owner.grant, payloadDigest: owner.payloadDigest,
+                session: owner.session, evidenceUpload: owner.evidenceUpload };
+        }
+        await retain(value, true); // Existing/uncertain request refuses replacement.
+        // The owner fence follows durable resource intent and precedes all Docker
+        // interaction. A crash cannot leave dispatched work with no cleanup journal.
+        await owner.resourceJournalRetained();
+        let result, executionError, cleaned = false, context;
+        try {
+            if (owner.purpose === 'world_session') {
+                const journal = await LocalWorldJournal.acquire(owner, inputs.manifestSha256, { retainUntil: inputs.manifest.evidence_recovery_until });
+                await journal.close(); // Real frozen manifest policy before native work.
+            }
+            context = await docker();
+            const arch = hostArch(), response = await command(context, ['info', '--format', '{{json .}}'], { signal, maximum: 128 * 1024 });
+            let host;
+            try {
+                host = JSON.parse(response.output);
+            }
+            catch {
+                throw failed();
+            }
+            const daemonArch = host.Architecture === 'x86_64' ? 'amd64' : host.Architecture === 'aarch64' ? 'arm64' : host.Architecture;
+            if (response.code !== 0 || host.OSType !== 'linux' || arch !== owner.runtime.arch || daemonArch !== arch
+                || !Number.isSafeInteger(host.NCPU) || host.NCPU < owner.limits.cpu_units || !Number.isSafeInteger(host.MemTotal)
+                || host.MemTotal < owner.limits.memory_mb * 1024 ** 2) {
+                throw new CliError('local_container_capacity_required', 'The approved local image and CPU/memory resources are not available on this device. No emulation or cloud fallback was selected.', 2);
+            }
+            const policy = await containerPolicy(arch, host.SecurityOptions), selected = boundary(owner, policy, inputs);
+            if (!await imagePresent(context, owner.runtime, signal))
+                throw new CliError('runtime_image_required', 'Install the exact approved execution image first. Nothing was downloaded or started.', 2);
+            value.boundary = selected;
+            value.security = { seccomp_sha256: policy.seccomp.sha256,
+                apparmor_profile: policy.requiredApparmor ? policy.apparmor.name : null };
+            value.stage = 'create_dispatched';
+            await retain(value);
+            const created = await command(context, ['container', 'create', '--name', value.name, '--pull', 'never', '--platform', `linux/${arch}`,
+                ...Object.entries(labels(value)).flatMap(([key, item]) => ['--label', key + '=' + item]), ...boundaryArguments(selected, policy)], { signal });
+            if (created.code !== 0 || !HASH.test(created.output.trim()))
+                throw failed();
+            value.container_id = created.output.trim();
+            value.stage = 'created';
+            await retain(value);
+            const row = await inspected(context, value, signal);
+            if (!row || row.State?.Status !== 'created' || row.State?.Running || row.State?.Restarting)
+                throw failed();
+            requireContainerBoundary(row, policy, selected);
+            const deadline = AbortSignal.any([signal, AbortSignal.timeout(localExecutionTimeout(configuration, 600000))]);
+            result = await connected(context, value, owner, inputs, configuration, policy, collector, deadline);
+        }
+        catch (error) {
+            executionError = error;
+        }
+        finally {
+            try {
+                cleaned = await cleanup(context, value, AbortSignal.timeout(15000));
+            }
+            catch {
+                cleaned = false;
+            }
+        }
+        if (!cleaned)
+            throw new CliError('local_container_cleanup_pending', 'Exact container cleanup is not confirmed. Its journal remains for recovery. Cloud completion was not implied.');
+        if (executionError)
+            throw executionError;
+        return result;
+    });
+}
+export async function executeLocalValidation(owner, inputs, configuration, collect, signal) {
+    return executeLocalContainer(owner, inputs, configuration, { purpose: 'validation', collect }, signal);
+}
+export async function executeLocalTrial(owner, inputs, configuration, collect, signal, live, liveArtifact) {
+    return executeLocalContainer(owner, inputs, configuration, { purpose: 'trial', collect, live, liveArtifact }, signal);
+}
+/** Existing source approval, one claim and keeper own the entire execution. */
+export async function withOwnedLocalValidation(context, device, job, grantRequest, signal, collect) {
+    return withLocalJobInputs(context, device, job, grantRequest, 'validation', signal, (owner, inputs, configuration, active) => executeLocalValidation(owner, inputs, configuration, collect, active));
+}
+/** Internal manual-world lane. Public creation/claim waits for cloud lifecycle,
+ * signed command/evidence consumers and browser/native handoff to be complete. */
+export async function executeLocalWorldSession(owner, inputs, configuration, collector, signal) {
+    return executeLocalContainer(owner, inputs, configuration, { purpose: 'world_session', ...collector }, signal);
+}
+export async function withOwnedLocalWorldSession(context, device, job, grantRequest, signal, collector) {
+    return withLocalJobInputs(context, device, job, grantRequest, 'world_session', signal, (owner, inputs, configuration, active) => executeLocalWorldSession(owner, inputs, configuration, collector, active));
+}