@playcraft/cli 0.1.54 → 0.1.56-beta

package/dist/workspace-runtime/server/terminal-host.js

@@ -0,0 +1,366 @@
+import { batchDirectoryHeld } from '../batch/occupancy.js';
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import { lstat } from 'node:fs/promises';
+import { StringDecoder } from 'node:string_decoder';
+import { WebSocketServer } from 'ws';
+import { appendTerminalOutput, createTerminalOutputLog, decodeTerminalBytes, runtimeError, terminalClientFrameSchema, terminalOutputSince, } from '@playcraft/common/cloud-workspace/runtime';
+import { resolveWorkspaceFile } from '../workspaces/files.js';
+import { sessionWorkspaceRoot } from '../workspaces/registry.js';
+import { startLauncherProcess } from '../codex/launcher-client.js';
+import { controlTokenMatches, extractControlToken } from './auth.js';
+const require = createRequire(import.meta.url);
+const commands = new WeakMap();
+const hosts = new WeakMap();
+export function setTerminalCommand(state, command) {
+    commands.set(state, command);
+}
+export function terminalHost(state) {
+    let host = hosts.get(state);
+    if (!host) {
+        host = new TerminalHost(state);
+        hosts.set(state, host);
+    }
+    return host;
+}
+export function disposeTerminalHost(state) {
+    hosts.get(state)?.dispose();
+    hosts.delete(state);
+}
+export class TerminalHost {
+    state;
+    disposed = false;
+    sessions = new Map();
+    spawning = new Map();
+    restored;
+    attempted = new Set();
+    closing = new Set();
+    stops = new Map();
+    confirmed = new Set();
+    sockets = new WebSocketServer({ noServer: true });
+    constructor(state) {
+        this.state = state;
+        // An absent in-memory session cannot prove a restored terminal's old process group stopped.
+        this.restored = new Set((state.journal?.listTerminals?.() ?? []).map(terminal => terminal.terminalId));
+    }
+    async handleUpgrade(request, socket, head) {
+        const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+        const match = /^\/runtime\/terminals\/([^/]+)\/connect$/.exec(url.pathname);
+        if (!match || !controlTokenMatches(this.state.config.controlToken, extractControlToken(request.headers))) {
+            rejectUpgrade(socket, 401, runtimeError('unauthenticated', 'control_token_required'));
+            return;
+        }
+        if (this.disposed || this.state.journal.destroyed()) {
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'runtime_destroyed'));
+            return;
+        }
+        let terminalId;
+        try {
+            terminalId = decodeURIComponent(match[1]);
+        }
+        catch {
+            rejectUpgrade(socket, 404, { error: 'terminal_not_found' });
+            return;
+        }
+        const terminal = this.state.journal.getTerminal(terminalId);
+        if (!terminal) {
+            rejectUpgrade(socket, 404, { error: 'terminal_not_found' });
+            return;
+        }
+        if (await batchDirectoryHeld(this.state, terminal.workspaceId, terminal.directoryName)) {
+            rejectUpgrade(socket, 409, { error: 'batch_workspace_readonly' });
+            return;
+        }
+        if (terminal.status === 'destroyed') {
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'terminal_destroyed'));
+            return;
+        }
+        if (this.closing.has(terminalId) || this.restored.has(terminalId) && !this.sessions.has(terminalId)) {
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'terminal_stop_unconfirmed'));
+            return;
+        }
+        let session = this.sessions.get(terminal.terminalId);
+        if (!session) {
+            try {
+                let pending = this.spawning.get(terminal.terminalId);
+                if (!pending) {
+                    pending = terminalDirectory(this.state, terminal).then((cwd) => this.spawn(terminal, cwd))
+                        .finally(() => this.spawning.delete(terminal.terminalId));
+                    this.spawning.set(terminal.terminalId, pending);
+                }
+                session = await pending;
+            }
+            catch {
+                rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'pty_unavailable'));
+                return;
+            }
+        }
+        if (this.disposed || this.state.journal.destroyed() || this.closing.has(terminalId) || this.state.journal.getTerminal(terminalId)?.status === 'destroyed') {
+            if (!this.closing.has(terminalId))
+                this.revoke(terminalId, 'terminal_destroyed');
+            rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'terminal_destroyed'));
+            return;
+        }
+        const active = session;
+        this.sockets.handleUpgrade(request, socket, head, (ws) => this.attach(active, ws));
+    }
+    destroy(terminalId) {
+        const pending = this.stops.get(terminalId);
+        if (pending)
+            return pending;
+        this.closing.add(terminalId);
+        const stopped = (async () => {
+            await this.spawning.get(terminalId);
+            const session = this.sessions.get(terminalId);
+            if (session)
+                await session.stop();
+            else if (!this.confirmed.has(terminalId) && (this.restored.has(terminalId) || this.attempted.has(terminalId)))
+                throw new Error('terminal_stop_unconfirmed');
+            const terminal = this.state.journal.getTerminal(terminalId);
+            if (!terminal)
+                throw new Error('terminal_not_found');
+            const destroyed = terminal.status === 'destroyed' ? terminal : await this.state.journal.putTerminal({
+                ...terminal, status: 'destroyed', destroyedAt: new Date().toISOString(),
+            });
+            this.confirmed.add(terminalId);
+            this.revoke(terminalId, 'terminal_destroyed');
+            this.closing.delete(terminalId);
+            return destroyed;
+        })().finally(() => this.stops.delete(terminalId));
+        this.stops.set(terminalId, stopped);
+        return stopped;
+    }
+    revoke(terminalId, reason) {
+        const session = this.sessions.get(terminalId);
+        if (!session)
+            return;
+        this.sessions.delete(terminalId);
+        const frame = { type: 'revoked', reason };
+        for (const listener of session.listeners)
+            listener(frame);
+        session.listeners.clear();
+        try {
+            session.pty.kill();
+        }
+        catch {
+            /* the process may already have exited */
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        for (const terminalId of [...this.sessions.keys()])
+            this.revoke(terminalId, 'runtime_destroyed');
+        this.sockets.close();
+    }
+    async spawn(terminal, cwd) {
+        if (this.disposed)
+            throw new Error('pty_unavailable');
+        if (this.state.config.workspaceMode === 'multi' || process.env.PLAYCRAFT_LAUNCHER_SOCKET
+            || process.getuid?.() === 1500) {
+            // User shells require the root launcher's fixed development account, even when an
+            // alternative command is installed for local tests. Never fall back to the control user.
+            const socketPath = process.env.PLAYCRAFT_LAUNCHER_SOCKET;
+            if (!socketPath)
+                throw new Error('pty_unavailable');
+            this.attempted.add(terminal.terminalId);
+            const child = await startLauncherProcess({ socketPath, processId: `terminal-${randomUUID()}`,
+                runtimeEpoch: this.state.runtimeEpoch, cwd, argv: [], env: {}, terminal: { cols: 80, rows: 24 } });
+            if (this.disposed) {
+                await child.stop();
+                throw new Error('pty_unavailable');
+            }
+            const session = { terminalId: terminal.terminalId, streamId: randomUUID(), log: createTerminalOutputLog(), listeners: new Set(),
+                stop: () => child.stop(),
+                pty: { write: (data) => { child.stdin?.write(data); }, resize: child.resize,
+                    kill: () => { void child.stop().catch(() => undefined); } } };
+            const decoder = new StringDecoder('utf8');
+            child.stdout?.on('data', (data) => { const text = decoder.write(data); if (text)
+                publish(session, text); });
+            child.onExit((code) => {
+                const tail = decoder.end();
+                if (tail)
+                    publish(session, tail);
+                const stopped = code === undefined ? Promise.resolve(false) : child.stop().then(() => true, () => false);
+                void stopped.then(confirmed => this.exited(terminal.terminalId, session, confirmed ? code : undefined)).catch(() => undefined);
+            });
+            this.sessions.set(terminal.terminalId, session);
+            return session;
+        }
+        const pty = require('node-pty');
+        const command = commands.get(this.state) ?? defaultShell();
+        let finishExit;
+        let didExit = false;
+        const knownExit = new Promise(resolve => { finishExit = () => { didExit = true; resolve(); }; });
+        this.attempted.add(terminal.terminalId);
+        const session = {
+            terminalId: terminal.terminalId,
+            streamId: randomUUID(),
+            log: createTerminalOutputLog(),
+            listeners: new Set(),
+            pty: pty.spawn(command.file, command.args, {
+                name: 'xterm-256color',
+                cols: 80,
+                rows: 24,
+                cwd,
+                env: shellEnv(command.file, cwd),
+            }),
+            stop: async () => {
+                if (!didExit)
+                    session.pty.kill();
+                let timer;
+                try {
+                    await Promise.race([knownExit, new Promise((_resolve, reject) => {
+                            timer = setTimeout(() => reject(new Error('terminal_stop_unconfirmed')), 3000);
+                        })]);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            },
+        };
+        const local = session.pty;
+        local.onData((data) => publish(session, data));
+        local.onExit(({ exitCode, signal }) => { finishExit(); void this.exited(terminal.terminalId, session, exitCode, signal).catch(() => undefined); });
+        this.sessions.set(terminal.terminalId, session);
+        return session;
+    }
+    async exited(terminalId, session, code, signal) {
+        session.exited = { code: code ?? null, ...(signal === undefined ? {} : { signal: String(signal) }) };
+        try {
+            if (code !== undefined) {
+                const terminal = this.state.journal.getTerminal(terminalId);
+                if (terminal && terminal.status !== 'destroyed')
+                    await this.state.journal.putTerminal({
+                        ...terminal, status: 'destroyed', destroyedAt: new Date().toISOString(),
+                    });
+                if (terminal)
+                    this.confirmed.add(terminalId);
+            }
+        }
+        finally {
+            for (const listener of session.listeners)
+                listener(exitFrame(session));
+        }
+    }
+    attach(session, ws) {
+        let open = true;
+        let resumed = false;
+        let cursor = 0;
+        const send = (frame) => {
+            if (open && ws.readyState === ws.OPEN)
+                ws.send(JSON.stringify(frame));
+        };
+        const listener = (frame) => {
+            if (!resumed)
+                return;
+            if (frame.type === 'output') {
+                const end = frame.offset + decodeTerminalBytes(frame.data).length;
+                if (end <= cursor)
+                    return;
+                cursor = Math.max(cursor, end);
+            }
+            send(frame);
+        };
+        session.listeners.add(listener);
+        ws.on('message', (raw) => {
+            let body;
+            try {
+                body = JSON.parse(String(raw));
+            }
+            catch {
+                return;
+            }
+            const parsed = terminalClientFrameSchema.safeParse(body);
+            if (!parsed.success || (session.exited || this.closing.has(session.terminalId)) && parsed.data.type !== 'resume')
+                return;
+            const frame = parsed.data;
+            if (frame.type === 'resume') {
+                if (frame.streamId && frame.streamId !== session.streamId) {
+                    send({ type: 'reset', streamId: session.streamId, offset: session.log.end });
+                    cursor = session.log.end;
+                    resumed = true;
+                    if (session.exited)
+                        send(exitFrame(session));
+                    return;
+                }
+                const since = terminalOutputSince(session.log, frame.offset);
+                if (since.gap)
+                    send({ type: 'gap', streamId: session.streamId, offset: since.offset });
+                for (const item of since.frames) {
+                    send({ type: 'output', streamId: session.streamId, offset: item.offset, data: item.data });
+                }
+                cursor = session.log.end;
+                resumed = true;
+                if (session.exited)
+                    send(exitFrame(session));
+                return;
+            }
+            if (!resumed)
+                return;
+            if (frame.type === 'resize') {
+                session.pty.resize(frame.cols, frame.rows);
+                return;
+            }
+            session.pty.write(Buffer.from(decodeTerminalBytes(frame.data)).toString('utf8'));
+        });
+        const detach = () => {
+            open = false;
+            session.listeners.delete(listener);
+        };
+        ws.on('close', detach);
+        ws.on('error', detach);
+    }
+}
+function publish(session, text) {
+    const before = session.log.end;
+    session.log = appendTerminalOutput(session.log, text);
+    const since = terminalOutputSince(session.log, before);
+    for (const item of since.frames) {
+        const frame = {
+            type: 'output',
+            streamId: session.streamId,
+            offset: item.offset,
+            data: item.data,
+        };
+        for (const listener of session.listeners)
+            listener(frame);
+    }
+}
+function exitFrame(session) {
+    return {
+        type: 'exit',
+        streamId: session.streamId,
+        code: session.exited?.code ?? null,
+        ...(session.exited?.signal ? { signal: session.exited.signal } : {}),
+    };
+}
+async function terminalDirectory(state, terminal) {
+    const root = await sessionWorkspaceRoot(state, terminal.workspaceId, terminal.directoryName);
+    if (!terminal.cwd)
+        return root;
+    const resolved = await resolveWorkspaceFile(root, terminal.cwd);
+    const stat = await lstat(resolved);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('pty_unavailable');
+    return resolved;
+}
+function defaultShell() {
+    const shell = process.env.SHELL;
+    const file = shell && shell.startsWith('/') ? shell : '/bin/sh';
+    return { file, args: ['-i'] };
+}
+function shellEnv(file, cwd) {
+    return {
+        PATH: process.env.PATH ?? '/usr/bin:/bin',
+        HOME: process.env.HOME ?? cwd,
+        TERM: 'xterm-256color',
+        LANG: process.env.LANG ?? 'C.UTF-8',
+        SHELL: file,
+    };
+}
+function rejectUpgrade(socket, status, body) {
+    const payload = JSON.stringify(body);
+    const title = status === 401 ? 'Unauthorized' : status === 404 ? 'Not Found' : 'Conflict';
+    socket.write(`HTTP/1.1 ${status} ${title}\r\ncontent-type: application/json; charset=utf-8\r\ncontent-length: ${Buffer.byteLength(payload)}\r\nconnection: close\r\n\r\n${payload}`);
+    socket.destroy();
+}

package/dist/workspace-runtime/server/types.js

@@ -0,0 +1 @@
+export {};

package/dist/workspace-runtime/server/workspace-transfer.js

@@ -0,0 +1,168 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { applyWorkspaceTransfer, createWorkspaceTransfer, inspectWorkspaceTransfer, inspectWorkspaceTree, WorkspaceTransferError } from '../workspaces/transfer.js';
+import { assertTransferDiskSpace, checkWorkspaceTransferQuota, transferDiskBudget } from '../workspaces/transfer-quota.js';
+import { revisionScope, sessionWorkspaceRoot, workspaceContainerRoot } from '../workspaces/registry.js';
+import { workspaceDirectoryOccupied } from '../workspaces/directory-maintenance.js';
+import { publishSourceEvents } from './dispatch.js';
+export async function handleWorkspaceTransfer(state, request, response, url) {
+    const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
+    const directoryName = url.searchParams.get('directoryName') ?? 'basic';
+    const root = await sessionWorkspaceRoot(state, workspaceId, directoryName);
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    const close = () => { if (!response.writableEnded)
+        abort(); };
+    request.once('aborted', abort);
+    response.once('close', close);
+    let temporary;
+    try {
+        const directories = directoryName === 'root'
+            ? [...new Set(['root', 'basic', ...(state.journal.getWorkspace(workspaceId ?? '')?.directories ?? []).map(item => item.directoryName)])].sort()
+            : [...new Set(['root', directoryName])].sort();
+        const assertAvailable = async () => {
+            controller.signal.throwIfAborted();
+            if (state.journal.destroyed())
+                throw new WorkspaceTransferError('runtime_destroyed');
+            for (const directory of directories) {
+                if (await workspaceDirectoryOccupied(state, workspaceId ?? 'workspace', directory))
+                    throw new WorkspaceTransferError('workspace_transfer_busy');
+            }
+        };
+        const quotaRoot = await workspaceContainerRoot(state, workspaceId);
+        if (request.method === 'GET' && url.searchParams.get('preflight') === '1') {
+            const integer = (key) => {
+                const value = url.searchParams.get(key) ?? '';
+                if (!/^\d+$/.test(value) || !Number.isSafeInteger(Number(value)))
+                    throw new WorkspaceTransferError('invalid_workspace_transfer');
+                return Number(value);
+            };
+            const expectedTree = url.searchParams.get('expectedTree') ?? '';
+            if (!/^[a-f0-9]{40,64}$/.test(expectedTree))
+                throw new WorkspaceTransferError('invalid_workspace_transfer');
+            const incoming = { bytes: integer('contentBytes'), files: integer('fileCount') };
+            await assertAvailable();
+            const targetTree = url.searchParams.get('targetTree');
+            if (targetTree !== null && !/^[a-f0-9]{40,64}$/.test(targetTree))
+                throw new WorkspaceTransferError('invalid_workspace_transfer');
+            const current = await inspectWorkspaceTree(root, { signal: controller.signal });
+            if (current.tree === targetTree) {
+                writeJson(response, 200, { protocolVersion: 2, alreadyApplied: true, tree: current.tree });
+                return;
+            }
+            if (current.tree !== expectedTree)
+                throw new WorkspaceTransferError('workspace_transfer_conflict');
+            const quota = await checkWorkspaceTransferQuota(quotaRoot, current, incoming, state.config.workspaceStorageQuotaBytes);
+            await assertTransferDiskSpace(tmpdir(), current.bytes * 2 + incoming.bytes * 2);
+            writeJson(response, 200, { protocolVersion: 2, quota, contentBytes: incoming.bytes, fileCount: incoming.files });
+            return;
+        }
+        if (request.method === 'GET') {
+            const current = await inspectWorkspaceTransfer(root, { signal: controller.signal });
+            await assertTransferDiskSpace(tmpdir(), current.bytes * 3);
+            const snapshot = await createWorkspaceTransfer(root, { signal: controller.signal });
+            try {
+                controller.signal.throwIfAborted();
+                response.writeHead(200, { 'content-type': 'application/octet-stream', 'cache-control': 'private, no-store',
+                    'content-length': (await stat(snapshot.bundlePath)).size, 'x-content-type-options': 'nosniff',
+                    'x-playcraft-workspace-tree': snapshot.tree, 'x-playcraft-workspace-head': snapshot.head,
+                    'x-playcraft-workspace-content-bytes': snapshot.stats.bytes, 'x-playcraft-workspace-file-count': snapshot.stats.files });
+                await pipeline(createReadStream(snapshot.bundlePath), response, { signal: controller.signal });
+            }
+            finally {
+                await snapshot.cleanup();
+            }
+            return;
+        }
+        const expectedTree = request.headers['x-playcraft-workspace-tree'];
+        if (typeof expectedTree !== 'string' || !/^[a-f0-9]{40,64}$/.test(expectedTree))
+            throw new WorkspaceTransferError('invalid_workspace_transfer');
+        const rawLength = request.headers['content-length'];
+        const declaredLength = rawLength === undefined ? undefined : Number(rawLength);
+        if (rawLength !== undefined && (typeof rawLength !== 'string' || !/^\d+$/.test(rawLength) || !Number.isSafeInteger(declaredLength)))
+            throw new WorkspaceTransferError('invalid_workspace_transfer');
+        await assertAvailable();
+        const disk = await transferDiskBudget(tmpdir());
+        if (declaredLength !== undefined)
+            await assertTransferDiskSpace(tmpdir(), declaredLength);
+        temporary = await mkdtemp(join(tmpdir(), 'playcraft-upload-'));
+        const bundlePath = join(temporary, 'incoming.bundle');
+        let size = 0, lastProbe = 0;
+        const guard = new Transform({ transform(chunk, _encoding, callback) {
+                size += chunk.length;
+                if (size > disk.budget) {
+                    callback(new WorkspaceTransferError('workspace_transfer_disk_full', { metric: 'transferBytes', actual: size, limit: disk.budget }));
+                    return;
+                }
+                if (size - lastProbe < 16 * 1024 * 1024) {
+                    callback(null, chunk);
+                    return;
+                }
+                lastProbe = size;
+                assertTransferDiskSpace(temporary, chunk.length).then(() => callback(null, chunk), error => callback(error));
+            } });
+        await pipeline(Readable.from(request.iterator({ destroyOnReturn: false })), guard, createWriteStream(bundlePath, { flags: 'wx', mode: 0o600 }), { signal: controller.signal });
+        if (!size || (declaredLength !== undefined && size !== declaredLength))
+            throw new WorkspaceTransferError('invalid_workspace_transfer');
+        const lockKeys = [...new Set([...directories.map(name => `directory:${workspaceId}:${name}`),
+                ...directories.map(name => `workspace:${revisionScope(state, workspaceId, name) ?? 'single'}`)])];
+        const locked = async (index) => index < lockKeys.length
+            ? state.journal.exclusive(lockKeys[index], () => locked(index + 1))
+            : apply();
+        const apply = async () => {
+            await assertAvailable();
+            const current = await inspectWorkspaceTransfer(root, { signal: controller.signal });
+            await assertTransferDiskSpace(tmpdir(), current.bytes * 2);
+            return applyWorkspaceTransfer(root, bundlePath, expectedTree, {
+                signal: controller.signal,
+                validateSnapshot: async (incoming, actualCurrent) => {
+                    await checkWorkspaceTransferQuota(quotaRoot, actualCurrent, incoming, state.config.workspaceStorageQuotaBytes);
+                    await assertTransferDiskSpace(tmpdir(), incoming.bytes);
+                },
+            });
+        };
+        const result = await locked(0);
+        if (result.changedPaths.length > 0) {
+            const groups = new Map([[directoryName, result.changedPaths]]);
+            if (directoryName === 'root')
+                for (const path of result.changedPaths) {
+                    const [directory, ...parts] = path.split('/');
+                    if (directory && directories.includes(directory) && parts.length)
+                        groups.set(directory, [...(groups.get(directory) ?? []), parts.join('/')]);
+                }
+            const events = [];
+            for (const [directory, paths] of groups)
+                events.push(await state.journal.allocateSourceEvent({
+                    runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,
+                    workspaceId, type: 'files.changed', occurredAt: new Date().toISOString(), payload: { workspaceId, directoryName: directory, paths },
+                }));
+            await publishSourceEvents(state, events);
+        }
+        writeJson(response, 200, result);
+    }
+    catch (error) {
+        if (response.headersSent)
+            response.destroy(error instanceof Error ? error : undefined);
+        else if (!controller.signal.aborted) {
+            const code = error instanceof WorkspaceTransferError ? error.code
+                : error.code === 'ENOSPC' ? 'workspace_transfer_disk_full' : 'workspace_transfer_failed';
+            const status = code === 'workspace_transfer_quota_exceeded' ? 413 : code === 'workspace_transfer_disk_full' ? 507
+                : code === 'invalid_workspace_transfer' ? 400 : code.includes('timeout') ? 504 : code === 'workspace_transfer_storage_unavailable' ? 503 : 409;
+            writeJson(response, status, { error: code, ...(error instanceof WorkspaceTransferError && error.details ? { details: error.details } : {}) });
+        }
+    }
+    finally {
+        request.off('aborted', abort);
+        response.off('close', close);
+        if (temporary)
+            await rm(temporary, { recursive: true, force: true });
+    }
+}
+function writeJson(response, status, body) {
+    response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'private, no-store' });
+    response.end(JSON.stringify(body));
+}

package/dist/workspace-runtime/verify-artifact.js

@@ -0,0 +1,59 @@
+import assert from 'node:assert/strict';
+import { randomUUID } from 'node:crypto';
+import { readFile, mkdtemp, rm } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { batchSourceRemoteRef, parseSandboxRuntimeConfig } from '@playcraft/common/cloud-workspace/runtime';
+import { createLoopbackNativeAdapter } from './codex/loopback.js';
+import { startWorkspaceRuntime } from './serve.js';
+async function dependencyVersion(name, entry) {
+    let directory = dirname(createRequire(import.meta.url).resolve(entry));
+    for (;;) {
+        const metadata = await readFile(join(directory, 'package.json'), 'utf8').then(JSON.parse).catch(() => undefined);
+        if (metadata?.name === name)
+            return metadata.version;
+        const parent = dirname(directory);
+        if (parent === directory)
+            throw new Error(`package_metadata_missing:${name}`);
+        directory = parent;
+    }
+}
+/** Starts only an isolated temporary runtime; never reads or changes an existing workspace. */
+export async function verifyRuntimeArtifact(expectedVersion) {
+    assert.match(expectedVersion, /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/);
+    const metadata = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8'));
+    assert.equal(metadata.version, expectedVersion, 'command package version differs from the release target');
+    assert.equal(await dependencyVersion('@playcraft/common', '@playcraft/common/cloud-workspace/runtime'), expectedVersion);
+    assert.equal(await dependencyVersion('@playcraft/build', '@playcraft/build'), expectedVersion);
+    const batchId = randomUUID();
+    assert.equal(batchSourceRemoteRef(batchId), `refs/tags/playcraft/batch/${batchId}/source`, 'installed shared library lacks standard tag references for source snapshots');
+    const directory = await mkdtemp(join(tmpdir(), 'playcraft-artifact-verify-'));
+    let runtime;
+    try {
+        const config = parseSandboxRuntimeConfig({
+            protocolMajor: 1, protocolMinor: 0, environment: 'artifact-verification',
+            runtimeId: randomUUID(), userId: 'artifact-verification', generation: 1, runtimeEpoch: 0,
+            workspaceMode: 'multi', workspaceRoot: join(directory, 'workspaces'), stateDir: join(directory, 'state'),
+            publicBaseUrl: 'http://127.0.0.1:9', controlToken: randomUUID(), cliVersion: expectedVersion,
+            listen: { host: '127.0.0.1', port: 0 },
+        });
+        runtime = await startWorkspaceRuntime(config, { nativeAdapter: createLoopbackNativeAdapter() });
+        const response = await fetch(`${runtime.url}/runtime/identity`, {
+            headers: { authorization: `Bearer ${config.controlToken}` }, signal: AbortSignal.timeout(10_000),
+        });
+        assert.equal(response.status, 200, 'built runtime identity is unavailable');
+        const identity = await response.json();
+        assert.equal(identity.runtimeId, config.runtimeId);
+        assert.equal(identity.batchSourceFreezeRevision, 2, 'built runtime lacks the required batch source freeze implementation');
+    }
+    finally {
+        await runtime?.close();
+        await rm(directory, { recursive: true, force: true });
+    }
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    await verifyRuntimeArtifact(process.argv[2] ?? '');
+    console.log('Runtime artifact verified: batchSourceFreezeRevision=2');
+}

package/dist/workspace-runtime/workspaces/append-only-log.js

@@ -0,0 +1,62 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/**
+ * One append-only log file with a hard byte cap. When the cap is crossed the file is atomically
+ * replaced with a truncation notice plus the newest bytes, so readers never see a half write.
+ */
+export class AppendOnlyLog {
+    path;
+    maxBytes;
+    truncatedNotice;
+    constructor(path, maxBytes, truncatedNotice = '[playcraft] log truncated; showing the tail\n') {
+        this.path = path;
+        this.maxBytes = maxBytes;
+        this.truncatedNotice = truncatedNotice;
+    }
+    async append(chunk) {
+        if (!chunk)
+            return;
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const handle = await open(this.path, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW, 0o600);
+        try {
+            await handle.write(Buffer.from(chunk));
+        }
+        finally {
+            await handle.close();
+        }
+        const info = await stat(this.path);
+        if (info.size <= this.maxBytes)
+            return;
+        const content = await readFile(this.path);
+        const notice = Buffer.from(this.truncatedNotice);
+        const tail = content.subarray(Math.max(0, content.length - (this.maxBytes - notice.length)));
+        const temporary = `${this.path}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, Buffer.concat([notice, tail]), { mode: 0o600 });
+            await rename(temporary, this.path);
+        }
+        catch (error) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async read(offset = 0) {
+        let content;
+        try {
+            content = await readFile(this.path);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return { text: '', size: 0, offset: 0 };
+            throw error;
+        }
+        const start = Math.min(Math.max(0, offset), content.length);
+        return { text: content.subarray(start).toString('utf8'), size: content.length, offset: start };
+    }
+    async size() {
+        const info = await stat(this.path).catch(() => undefined);
+        return info?.isFile() ? info.size : 0;
+    }
+}