@playcraft/cli 0.1.42 → 0.1.44-beta

package/dist/workspace/transfer-client.js

@@ -0,0 +1,233 @@
+import { randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream, existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, stat, statfs, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { RESOURCE_GRANT_ACTIONS, workspaceSessionScopeSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { PlayCraftHttpClient } from '../utils/playcraft-http-client.js';
+import { createWorkspacePushTransfer, inspectWorkspaceCommit, RAW_ATTRIBUTES, runTransferGit, transferGit } from '../workspace-runtime/workspaces/transfer.js';
+import { workspaceMessage as message } from './messages.js';
+import { normalizeWorkspaceTransferError, transferByteCount, workspaceTransferFailure } from './transfer-errors.js';
+const META_FILE = '.playcraft-workspace.json';
+export function workspaceServiceUrl(baseUrl, path) {
+    const base = new URL(baseUrl);
+    if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
+        throw new Error(message('invalidTarget'));
+    return `${base.toString().replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+async function request(client, path, init = {}) {
+    const headers = new Headers(init.headers);
+    headers.set('Authorization', `Bearer ${client.token}`);
+    headers.set('X-Request-Id', client.requestId);
+    let response;
+    try {
+        response = await fetch(workspaceServiceUrl(client.baseUrl, path), {
+            ...init, headers, redirect: 'error', signal: AbortSignal.timeout(15 * 60_000),
+        });
+    }
+    catch (error) {
+        throw normalizeWorkspaceTransferError(error);
+    }
+    if (response.ok)
+        return response;
+    const body = await response.json().catch(() => ({}));
+    const value = body && typeof body === 'object' ? body : {};
+    const nested = value.error && typeof value.error === 'object' ? value.error : {};
+    const code = String(nested.code ?? value.reason ?? value.code ?? value.message ?? value.error ?? response.status);
+    const rawDetails = nested.details ?? value.details;
+    const details = rawDetails && typeof rawDetails === 'object' ? rawDetails : undefined;
+    if (response.status === 401)
+        throw new Error(`${message('login')} ${client.baseUrl}`);
+    if (code.startsWith('workspace_transfer_') || code === 'invalid_workspace_transfer')
+        throw workspaceTransferFailure(code, details);
+    if (response.status === 413)
+        throw workspaceTransferFailure('workspace_transfer_proxy_too_large');
+    if (response.status === 408 || response.status === 504)
+        throw workspaceTransferFailure('workspace_transfer_timeout');
+    throw workspaceTransferFailure(code, details);
+}
+async function json(client, path, body) {
+    const response = await request(client, path, body === undefined ? {} : {
+        method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
+    });
+    const value = await response.json();
+    return (value?.result ?? value);
+}
+async function ensureAccess(client, workspaceId, directoryName) {
+    const workspace = await json(client, `/api/cloud-workspaces/${workspaceId}`);
+    const scope = workspace.projectId
+        ? `/api/projects/${encodeURIComponent(workspace.projectId)}/cloud-workspaces/${workspaceId}`
+        : `/api/cloud-workspaces/${workspaceId}`;
+    let grant = await json(client, `${scope}/runtime-grants`, {
+        clientRequestId: `workspace-cli-${randomUUID()}`, actions: RESOURCE_GRANT_ACTIONS,
+    });
+    for (let attempt = 0; grant.grantStatus === 'pending' && grant.grantRequestId && attempt < 60; attempt++) {
+        await new Promise(resolve => setTimeout(resolve, 500));
+        grant = await json(client, `${scope}/runtime-grants/${encodeURIComponent(grant.grantRequestId)}`);
+    }
+    if (grant.grantStatus !== 'ready')
+        throw new Error(message('notReady'));
+    let operation = await json(client, `/runtime/workspaces/${workspaceId}/ensure`, { clientRequestId: randomUUID(), directoryName: directoryName === 'root' ? 'basic' : directoryName });
+    for (let attempt = 0; operation.operationId && ['queued', 'dispatched', 'accepted'].includes(operation.status ?? '') && attempt < 60; attempt++) {
+        await new Promise(resolve => setTimeout(resolve, 500));
+        operation = await json(client, `/runtime/operations/${encodeURIComponent(operation.operationId)}`);
+    }
+    if (operation.status !== 'completed')
+        throw new Error(message('notReady'));
+}
+async function localDiskSpace(path, required) {
+    const disk = await statfs(path);
+    const available = disk.bavail * disk.bsize;
+    if (required > available)
+        throw workspaceTransferFailure('workspace_transfer_disk_full', { actual: required, limit: available });
+    return available;
+}
+async function downloadBundle(response, target, temporary) {
+    if (!response.body)
+        throw new Error(message('failed'));
+    try {
+        const available = await localDiskSpace(temporary, Number(response.headers.get('content-length') ?? 0));
+        let bytes = 0;
+        const guard = new Transform({ transform(chunk, _encoding, callback) {
+                bytes += chunk.length;
+                callback(bytes > available ? workspaceTransferFailure('workspace_transfer_disk_full', { actual: bytes, limit: available }) : null, chunk);
+            } });
+        await pipeline(Readable.fromWeb(response.body), guard, createWriteStream(target, { flags: 'wx', mode: 0o600 }));
+        const declared = response.headers.get('content-length');
+        if (declared && Number(declared) !== bytes)
+            throw workspaceTransferFailure('invalid_workspace_transfer');
+    }
+    finally {
+        await response.body.cancel().catch(() => undefined);
+    }
+}
+export async function workspaceClone(options) {
+    const workspaceId = options.workspaceId.trim(), directoryName = options.directory ?? 'basic';
+    if (!/^[a-f0-9-]{36}$/i.test(workspaceId) || !workspaceSessionScopeSchema.safeParse(directoryName).success)
+        throw new Error(message('invalidTarget'));
+    const target = resolve(options.dir?.trim() || `workspace-${workspaceId}-${directoryName}`);
+    if (existsSync(target))
+        throw new Error(message('directoryExists'));
+    const client = new PlayCraftHttpClient(options);
+    await ensureAccess(client, workspaceId, directoryName);
+    const temporary = await mkdtemp(join(tmpdir(), 'playcraft-clone-'));
+    let created = false;
+    try {
+        const response = await request(client, `/runtime/workspaces/${workspaceId}/git-bundle?directoryName=${encodeURIComponent(directoryName)}`);
+        const tree = response.headers.get('x-playcraft-workspace-tree');
+        if (!tree || !/^[a-f0-9]{40,64}$/.test(tree)) {
+            await response.body?.cancel();
+            throw new Error(message('failed'));
+        }
+        const bundlePath = join(temporary, 'workspace.bundle');
+        await downloadBundle(response, bundlePath, temporary);
+        await mkdir(target);
+        created = true;
+        const contentBytes = Number(response.headers.get('x-playcraft-workspace-content-bytes') ?? 0);
+        if (Number.isSafeInteger(contentBytes) && contentBytes > 0)
+            await localDiskSpace(target, contentBytes * 2);
+        await runTransferGit(temporary, ['clone', '--no-checkout', '--', bundlePath, target]);
+        await writeFile(join(target, '.git', 'info', 'attributes'), RAW_ATTRIBUTES);
+        await runTransferGit(target, ['checkout', '--force', 'HEAD']);
+        if (transferGit(target, ['rev-parse', 'HEAD^{tree}']) !== tree)
+            throw new Error(message('failed'));
+        transferGit(target, ['config', '--unset-all', 'remote.origin.url']);
+        const meta = { schemaVersion: 'playcraft.workspace-checkout.v1', workspaceId, directoryName,
+            baseUrl: client.baseUrl, tree };
+        await writeFile(join(target, META_FILE), `${JSON.stringify(meta, null, 2)}\n`);
+        const excludePath = join(target, '.git', 'info', 'exclude');
+        const exclude = await readFile(excludePath, 'utf8').catch(() => '');
+        await writeFile(excludePath, `${exclude}\n/${META_FILE}\n`);
+        if (options.json)
+            console.log(JSON.stringify({ ok: true, command: 'workspace.clone', data: { ...meta, dir: target } }));
+        else
+            console.log(`${message('cloned')} ${target}`);
+    }
+    catch (error) {
+        if (created)
+            await rm(target, { recursive: true, force: true });
+        throw normalizeWorkspaceTransferError(error);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+export async function workspacePush(options = {}) {
+    const root = resolve(options.dir?.trim() || process.cwd());
+    let meta;
+    try {
+        meta = JSON.parse(await readFile(join(root, META_FILE), 'utf8'));
+        if (meta.schemaVersion !== 'playcraft.workspace-checkout.v1' || !/^[a-f0-9-]{36}$/i.test(meta.workspaceId) ||
+            !workspaceSessionScopeSchema.safeParse(meta.directoryName).success || !/^[a-f0-9]{40,64}$/.test(meta.tree))
+            throw new Error();
+        workspaceServiceUrl(meta.baseUrl, '/');
+    }
+    catch {
+        throw new Error(message('metadataMissing'));
+    }
+    if (transferGit(root, ['status', '--porcelain']).length > 0)
+        throw new Error(message('cleanRequired'));
+    const client = new PlayCraftHttpClient({ url: options.url || meta.baseUrl, token: options.token });
+    if (workspaceServiceUrl(client.baseUrl, '/') !== workspaceServiceUrl(meta.baseUrl, '/'))
+        throw new Error(message('invalidTarget'));
+    await ensureAccess(client, meta.workspaceId, meta.directoryName);
+    const targetTree = transferGit(root, ['rev-parse', 'HEAD^{tree}']);
+    const stats = await inspectWorkspaceCommit(root, targetTree).catch(error => { throw normalizeWorkspaceTransferError(error); });
+    const path = `/runtime/workspaces/${meta.workspaceId}/git-bundle?directoryName=${encodeURIComponent(meta.directoryName)}`;
+    const preflightResponse = await request(client, `${path}&preflight=1&contentBytes=${stats.bytes}&fileCount=${stats.files}&expectedTree=${meta.tree}&targetTree=${targetTree}`);
+    if (!preflightResponse.headers.get('content-type')?.includes('application/json')) {
+        await preflightResponse.body?.cancel();
+        throw workspaceTransferFailure('workspace_transfer_upgrade_required');
+    }
+    const preflight = await preflightResponse.json();
+    if (preflight.protocolVersion !== 2)
+        throw workspaceTransferFailure('workspace_transfer_upgrade_required');
+    if (preflight.alreadyApplied && preflight.tree === targetTree) {
+        meta.tree = targetTree;
+        await writeFile(join(root, META_FILE), `${JSON.stringify(meta, null, 2)}\n`);
+        if (options.json)
+            console.log(JSON.stringify({ ok: true, command: 'workspace.push', data: { tree: targetTree, changedPaths: [] } }));
+        else
+            console.log(message('pushed'));
+        return;
+    }
+    if (!options.json)
+        console.error(message('preflight', { files: stats.files, bytes: transferByteCount(stats.bytes) }));
+    let snapshot;
+    try {
+        snapshot = await createWorkspacePushTransfer(root, meta.tree);
+        if (snapshot.tree !== targetTree)
+            throw workspaceTransferFailure('workspace_transfer_conflict');
+        const bundleBytes = (await stat(snapshot.bundlePath)).size;
+        if (!options.json)
+            console.error(message('upload', { bytes: transferByteCount(bundleBytes) }));
+        const stream = createReadStream(snapshot.bundlePath);
+        let response;
+        try {
+            response = await request(client, path, {
+                method: 'POST', headers: { 'content-type': 'application/octet-stream', 'content-length': String(bundleBytes),
+                    'x-playcraft-workspace-tree': meta.tree }, body: stream, duplex: 'half',
+            });
+        }
+        finally {
+            stream.destroy();
+        }
+        const result = await response.json();
+        if (!/^[a-f0-9]{40,64}$/.test(result.tree))
+            throw new Error(message('failed'));
+        meta.tree = result.tree;
+        await writeFile(join(root, META_FILE), `${JSON.stringify(meta, null, 2)}\n`);
+        if (options.json)
+            console.log(JSON.stringify({ ok: true, command: 'workspace.push', data: result }));
+        else
+            console.log(message('pushed'));
+    }
+    catch (error) {
+        throw normalizeWorkspaceTransferError(error);
+    }
+    finally {
+        await snapshot?.cleanup();
+    }
+}

package/dist/workspace/transfer-errors.js

@@ -0,0 +1,48 @@
+import { WorkspaceTransferError } from '../workspace-runtime/workspaces/transfer.js';
+import { workspaceMessage as message } from './messages.js';
+export class WorkspaceCliTransferError extends Error {
+    code;
+    details;
+    constructor(code, text, details) {
+        super(text);
+        this.code = code;
+        this.details = details;
+    }
+}
+export function transferByteCount(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? message('byteCount', { value: value.toLocaleString('en-US') }) : message('byteCount', { value: '—' });
+}
+export function workspaceTransferFailure(code, details) {
+    const key = code === 'workspace_transfer_quota_exceeded' ? 'quotaExceeded'
+        : code === 'workspace_transfer_disk_full' ? typeof details?.actual === 'number' && typeof details.limit === 'number' ? 'diskFull' : 'diskFullUnknown'
+            : code === 'workspace_transfer_storage_unavailable' ? 'diskUnavailable'
+                : code === 'workspace_transfer_proxy_too_large' ? 'proxyTooLarge'
+                    : code === 'workspace_transfer_too_large' ? 'tooLarge'
+                        : code.includes('timeout') ? 'timeout'
+                            : code === 'workspace_transfer_network' ? 'network'
+                                : code === 'workspace_transfer_conflict' ? 'conflict'
+                                    : code === 'workspace_transfer_busy' ? 'busy'
+                                        : code === 'workspace_transfer_git_missing' ? 'gitMissing'
+                                            : code === 'workspace_transfer_base_missing' ? 'baseMissing'
+                                                : code.startsWith('workspace_transfer_git_') ? 'gitFailed'
+                                                    : code === 'invalid_workspace_transfer' || code === 'workspace_transfer_symlink' ? 'invalidTransfer'
+                                                        : code === 'workspace_transfer_upgrade_required' ? 'upgradeRequired' : 'failed';
+    const text = message(key, { actual: transferByteCount(details?.actual), limit: transferByteCount(details?.limit) });
+    return new WorkspaceCliTransferError(code, key === 'failed' ? `${text}: ${code}` : text, details);
+}
+export function normalizeWorkspaceTransferError(error) {
+    if (error instanceof WorkspaceCliTransferError)
+        return error;
+    if (error instanceof WorkspaceTransferError)
+        return workspaceTransferFailure(error.code, error.details);
+    const value = (error && typeof error === 'object' ? error : {});
+    if (value.code === 'ENOSPC')
+        return workspaceTransferFailure('workspace_transfer_disk_full');
+    if (/Timeout|Abort/.test(value.name ?? '') || /TIMEOUT/.test(value.cause?.code ?? ''))
+        return workspaceTransferFailure('workspace_transfer_timeout');
+    if (/UND_ERR_SOCKET|ECONNRESET|ECONNREFUSED|ENOTFOUND|EPIPE/.test(value.cause?.code ?? value.code ?? '') ||
+        error instanceof TypeError && /fetch|network|terminated/i.test(error.message))
+        return workspaceTransferFailure('workspace_transfer_network');
+    return error instanceof Error ? error : new Error(String(error));
+}

package/dist/workspace-runtime/batch/control.js

@@ -0,0 +1,80 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { sandboxBatchMemberStopSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { groupExited, stopProcessGroup } from './processes.js';
+import { memberStatus, readMember, serializeRun, writeMember, writeStopMarker } from './records.js';
+async function prove(record) {
+    let stopped = true;
+    for (const process of record.processes) {
+        if (process.stopped || groupExited(process.pid))
+            process.stopped = true;
+        else {
+            process.stopped = await stopProcessGroup(process);
+            if (!process.stopped)
+                stopped = false;
+        }
+    }
+    return stopped;
+}
+function sessionBusy(state, record) {
+    const session = record.sessionId ? state.journal.getSession(record.sessionId) : undefined;
+    if (!session)
+        return false;
+    return session.turnBlock === 'uncertain' || session.turnStatus === 'starting' || session.turnStatus === 'running';
+}
+/** Read-only besides reconciling process proof. Does not start work or advance a phase. */
+export async function readBatchMemberStatus(state, runId) {
+    const record = await readMember(state, runId);
+    if (!record)
+        return undefined;
+    const processes = record.processes.map(process => ({ ...process, stopped: process.stopped || groupExited(process.pid) }));
+    const live = processes.some(process => !process.stopped);
+    let next = { ...record, processes };
+    if (live && (record.writersStopped || record.state === 'completed' || record.state === 'stopped' || record.state === 'needs_user' || record.state === 'failed')) {
+        next = { ...next, writersStopped: false, state: record.stopRequested ? 'stopping' : 'unknown', holding: true };
+    }
+    else if (!live && record.state === 'running') {
+        const turnLive = sessionBusy(state, record);
+        next = { ...next, writersStopped: !turnLive, state: record.stopRequested ? 'stopped' : turnLive ? 'running' : 'unknown', holding: turnLive || !record.stopRequested };
+    }
+    if (JSON.stringify(next) !== JSON.stringify(record))
+        next = await writeMember(state, next);
+    return memberStatus(next);
+}
+export async function stopBatchMember(state, runId, body) {
+    const parsed = sandboxBatchMemberStopSchema.safeParse({ ...(body && typeof body === 'object' ? body : {}), runId });
+    if (!parsed.success)
+        throw new Error('invalid_batch_request');
+    const command = parsed.data;
+    return serializeRun(runId, async () => {
+        const existing = await readMember(state, runId);
+        if (existing && command.ownerFence < existing.ownerFence)
+            throw new Error('stale_owner');
+        if (existing?.state === 'completed' && existing.phase === 'deliver' && existing.evidence && existing.writersStopped)
+            return memberStatus(existing);
+        await writeStopMarker(state, runId, command.ownerFence);
+        const session = existing?.sessionId ? state.journal.getSession(existing.sessionId) : undefined;
+        if (session?.threadId && existing?.sessionId) {
+            await state.native?.interrupt?.({ sessionId: existing.sessionId, threadId: session.threadId }).catch(() => undefined);
+            const deadline = Date.now() + 2_000;
+            while (sessionBusy(state, existing) && Date.now() < deadline)
+                await delay(15);
+        }
+        const record = existing ?? {
+            runId, ownerFence: command.ownerFence, occupancyId: '00000000-0000-0000-0000-000000000000', workspaceId: '00000000-0000-0000-0000-000000000000',
+            directoryName: 'basic', phase: 'prepare', state: 'stopping', writersStopped: false, holding: true, stopRequested: true, processes: [],
+            updatedAt: new Date().toISOString(),
+        };
+        const writersStopped = await prove(record) && !sessionBusy(state, record);
+        const saved = await writeMember(state, {
+            ...record, ownerFence: command.ownerFence, stopRequested: true, state: writersStopped ? 'stopped' : 'stopping',
+            writersStopped, holding: !writersStopped,
+        });
+        return memberStatus(saved);
+    });
+}
+export async function rememberProcess(state, runId, process) {
+    const record = await readMember(state, runId);
+    if (!record)
+        return;
+    await writeMember(state, { ...record, processes: [...record.processes.filter(item => item.pid !== process.pid), process] });
+}

package/dist/workspace-runtime/batch/deliver.js

@@ -0,0 +1,150 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hashOperationPayload, sandboxBatchMemberDeliverSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { findExternalLocalReferences } from '../previews/single-file.js';
+import { workspaceRoot } from '../workspaces/registry.js';
+import { gitRead, gitWrite } from './git.js';
+import { groupExited, runProcessGroup, stopProcessGroup } from './processes.js';
+import { filesystemObjectStore, memberStatus, readMember, readStopMarker, serializeRun, writeMember, } from './records.js';
+function buildCommand() {
+    return process.env.PLAYCRAFT_BATCH_BUILD_COMMAND
+        ?? 'playcraft build --mode full --platform playcraft --format html --output dist/index.html .';
+}
+async function saveExact(root) {
+    await gitWrite(root, ['add', '-A', '.']);
+    const privatePaths = await gitRead(root, ['ls-files', '--', '.playcraft.json', 'playcraft.config.json', ':(glob)**/.playcraft.json', ':(glob)**/playcraft.config.json']);
+    if (privatePaths.trim())
+        throw new Error('batch_private_path');
+    const clean = await gitWrite(root, ['diff', '--cached', '--quiet']).then(() => true, () => false);
+    if (!clean)
+        await gitWrite(root, ['commit', '-m', 'Save batch member']);
+    return (await gitRead(root, ['rev-parse', 'HEAD'])).trim();
+}
+async function prove(record) {
+    let stopped = true;
+    for (const process of record.processes) {
+        if (!(process.stopped || groupExited(process.pid))) {
+            process.stopped = await stopProcessGroup(process);
+            if (!process.stopped)
+                stopped = false;
+        }
+        else
+            process.stopped = true;
+    }
+    return stopped;
+}
+export async function deliverBatchMember(state, body, options) {
+    if (!body || typeof body !== 'object' || !('occupancyId' in body) || !body.occupancyId)
+        throw new Error('occupancy_required');
+    const parsed = sandboxBatchMemberDeliverSchema.safeParse(body);
+    if (!parsed.success)
+        throw new Error('invalid_batch_request');
+    const command = parsed.data;
+    const hash = hashOperationPayload(command);
+    return serializeRun(command.runId, async () => {
+        const existing = await readMember(state, command.runId);
+        if (existing && command.ownerFence < existing.ownerFence)
+            throw new Error('stale_owner');
+        if (existing?.state === 'completed' && existing.phase === 'deliver' && existing.evidence && existing.commandHash?.deliver === hash && existing.ownerFence === command.ownerFence) {
+            return memberStatus(existing);
+        }
+        if (await readStopMarker(state, command.runId) && existing?.state === 'completed' && existing.evidence)
+            return memberStatus(existing);
+        if (await readStopMarker(state, command.runId))
+            return memberStatus(await markStopped(state, command, existing));
+        if (existing && existing.ownerFence === command.ownerFence && existing.commandHash?.deliver && existing.commandHash.deliver !== hash && existing.state === 'completed') {
+            throw new Error('batch_command_conflict');
+        }
+        const root = await workspaceRoot(state, command.workspaceId, command.directoryName);
+        let record = await writeMember(state, {
+            runId: command.runId, ownerFence: command.ownerFence, occupancyId: command.occupancyId, workspaceId: command.workspaceId,
+            directoryName: command.directoryName, phase: 'deliver', state: 'running', writersStopped: false, holding: true, stopRequested: false,
+            processes: existing?.processes ?? [], sessionId: existing?.sessionId, operationId: existing?.operationId, commandHash: { ...existing?.commandHash, deliver: hash },
+            snapshotDigest: existing?.snapshotDigest, branchName: existing?.branchName, updatedAt: new Date().toISOString(),
+        });
+        const buildRoot = join(state.config.stateDir, 'batch-builds', `${command.runId}-${randomUUID()}`);
+        try {
+            const savedCommit = command.fromCommit ?? await saveExact(root);
+            if (command.fromCommit)
+                await gitRead(root, ['cat-file', '-e', `${command.fromCommit}^{commit}`]);
+            if (await readStopMarker(state, command.runId))
+                return memberStatus(await markStopped(state, command, record));
+            let pushedCommit;
+            if (command.pushRemote) {
+                const branch = existing?.branchName ?? (await gitRead(root, ['symbolic-ref', '--short', 'HEAD'])).trim();
+                try {
+                    await gitWrite(root, ['push', '--porcelain', 'origin', `${savedCommit}:refs/heads/${branch}`]);
+                }
+                catch {
+                    throw new Error('batch_push_failed');
+                }
+                const remote = (await gitRead(root, ['ls-remote', 'origin', `refs/heads/${branch}`])).slice(0, savedCommit.length);
+                if (remote !== savedCommit)
+                    throw new Error('batch_push_failed');
+                pushedCommit = savedCommit;
+            }
+            await mkdir(join(buildRoot, '..'), { recursive: true });
+            await gitWrite(join(buildRoot, '..'), ['clone', '--local', '--no-hardlinks', '--no-checkout', '--', root, buildRoot]);
+            await gitWrite(buildRoot, ['checkout', '--detach', savedCommit]);
+            const built = await runProcessGroup(buildRoot, buildCommand(), 'build', async (process) => {
+                record = await writeMember(state, { ...record, processes: [...record.processes, process] });
+            });
+            record = await writeMember(state, { ...record, processes: record.processes.map(process => process.pid === built.process.pid ? built.process : process) });
+            if (await readStopMarker(state, command.runId))
+                return memberStatus(await markStopped(state, command, record));
+            if (built.code !== 0)
+                throw new Error('batch_build_failed');
+            const htmlPath = join(buildRoot, 'dist', 'index.html');
+            if (!(await lstat(htmlPath).catch(() => undefined))?.isFile())
+                throw new Error('batch_build_failed');
+            const entries = await readdir(join(buildRoot, 'dist'));
+            if (!entries.includes('index.html'))
+                throw new Error('batch_build_failed');
+            const bodyBytes = await readFile(htmlPath);
+            if (findExternalLocalReferences(bodyBytes.toString()).length)
+                throw new Error('batch_verify_failed');
+            const buildDigest = createHash('sha256').update(bodyBytes).digest('hex');
+            const previewRef = `workspaces/${command.workspaceId}/batches/members/${command.runId}/${buildDigest}.html`;
+            const store = options?.objectStore ?? filesystemObjectStore(state);
+            await store.put(previewRef, bodyBytes);
+            const published = await store.get(previewRef);
+            if (createHash('sha256').update(published).digest('hex') !== buildDigest)
+                throw new Error('batch_verify_failed');
+            await mkdir(join(root, 'dist'), { recursive: true });
+            await writeFile(join(root, 'dist', 'index.html'), published);
+            if (createHash('sha256').update(await readFile(join(root, 'dist', 'index.html'))).digest('hex') !== buildDigest)
+                throw new Error('batch_verify_failed');
+            const writersStopped = await prove(record);
+            if (!writersStopped)
+                return memberStatus(await writeMember(state, { ...record, state: 'stopping', writersStopped: false, holding: true, headCommit: savedCommit }));
+            if (await readStopMarker(state, command.runId))
+                return memberStatus(await markStopped(state, command, { ...record, headCommit: savedCommit }));
+            record = await writeMember(state, {
+                ...record, state: 'completed', writersStopped: true, holding: false, headCommit: savedCommit, error: undefined,
+                evidence: { savedCommit, ...(pushedCommit ? { pushedCommit } : {}), buildDigest, verified: true, previewRef },
+            });
+            return memberStatus(record);
+        }
+        catch (error) {
+            const code = error instanceof Error && /^[a-z0-9_]+$/.test(error.message) ? error.message : 'batch_deliver_failed';
+            const writersStopped = await prove(record);
+            record = await writeMember(state, { ...record, state: writersStopped ? 'failed' : 'stopping', writersStopped, holding: !writersStopped, error: code });
+            return memberStatus(record);
+        }
+        finally {
+            await rm(buildRoot, { recursive: true, force: true });
+        }
+    });
+}
+async function markStopped(state, command, existing) {
+    if (existing)
+        await prove(existing);
+    return writeMember(state, {
+        runId: command.runId, ownerFence: command.ownerFence, occupancyId: existing?.occupancyId ?? command.occupancyId,
+        workspaceId: command.workspaceId, directoryName: command.directoryName, phase: 'deliver', state: 'stopped', writersStopped: true,
+        holding: false, stopRequested: true, processes: existing?.processes ?? [], sessionId: existing?.sessionId, operationId: existing?.operationId,
+        headCommit: existing?.headCommit, evidence: existing?.evidence, commandHash: existing?.commandHash, snapshotDigest: existing?.snapshotDigest,
+        branchName: existing?.branchName, updatedAt: new Date().toISOString(),
+    });
+}

package/dist/workspace-runtime/batch/freeze.js

@@ -0,0 +1,102 @@
+import { lstat, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { statfs } from 'node:fs/promises';
+import { batchSourceFreezeResultSchema, batchSourceRemoteRef, sandboxBatchSourceFreezeRequestSchema, workspaceDiskAdmission, } from '@playcraft/common/cloud-workspace/runtime';
+import { stopBackgroundWriter } from '../processes/managed-writes.js';
+import { workspaceRoot } from '../workspaces/registry.js';
+import { copyCredentialHelpers, gitRead, gitWrite } from './git.js';
+import { archiveSource, captureIndependentSource } from './source-capture.js';
+import { filesystemObjectStore, readSnapshot, serializeFreeze, sourceCacheDir, writeSnapshot, } from './records.js';
+async function usagePercent(path) {
+    const disk = await statfs(path);
+    if (disk.blocks <= 0)
+        throw new Error('disk_usage_unavailable');
+    return ((disk.blocks - disk.bfree) / disk.blocks) * 100;
+}
+/** Dependency installs are keyed `workspaceId:directoryName`. A bare workspace id is not this directory. */
+async function stopManagedWriters(state, workspaceId, directoryName) {
+    const scope = `${workspaceId}:${directoryName}`;
+    for (const write of state.journal.listManagedWrites()) {
+        if (write.stoppedAt || write.workspaceId !== scope)
+            continue;
+        if (write.pid !== undefined) {
+            const stopped = await stopBackgroundWriter(write.pid);
+            if (!stopped)
+                continue;
+        }
+        await state.journal.putManagedWrite({ ...write, stoppedAt: new Date().toISOString() });
+    }
+}
+async function pushHiddenRef(cache, sourceRoot, remote, commit, ref) {
+    await copyCredentialHelpers(sourceRoot, cache);
+    try {
+        await gitWrite(cache, ['push', remote, `${commit}:${ref}`]);
+    }
+    catch {
+        throw new Error('batch_source_push_failed');
+    }
+    const remoteHash = (await gitRead(cache, ['ls-remote', remote, ref]).catch(() => '')).slice(0, commit.length);
+    if (remoteHash !== commit)
+        throw new Error('batch_source_push_failed');
+}
+export async function freezeBatchSource(state, body, options) {
+    const parsed = sandboxBatchSourceFreezeRequestSchema.safeParse(body);
+    if (!parsed.success)
+        throw new Error('invalid_batch_request');
+    const request = parsed.data;
+    return serializeFreeze(async () => {
+        const existing = await readSnapshot(state, request.batchId);
+        if (existing)
+            return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot: existing });
+        const source = await workspaceRoot(state, request.workspaceId, request.sourceDirectoryName);
+        const percent = Math.min(100, Math.max(0, options?.usagePercent ?? await usagePercent(source)));
+        if (workspaceDiskAdmission(percent) === 'paused')
+            throw new Error('disk_admission_paused');
+        await stopManagedWriters(state, request.workspaceId, request.sourceDirectoryName);
+        const cache = sourceCacheDir(state, request.batchId);
+        await rm(cache, { recursive: true, force: true });
+        const captured = await captureIndependentSource(source, cache);
+        await writeFile(`${cache}.digest`, captured.digest, { mode: 0o600 });
+        const binding = state.journal.getWorkspace(request.workspaceId);
+        const frozenAt = new Date((await gitRead(cache, ['show', '-s', '--format=%cI', 'HEAD'])).trim()).toISOString();
+        const snapshot = {
+            batchId: request.batchId,
+            commitHash: captured.commitHash,
+            digest: captured.digest,
+            sourceWorkspaceId: request.workspaceId,
+            sourceDirectoryName: request.sourceDirectoryName,
+            frozenAt,
+        };
+        try {
+            if (request.persist === 'remote_ref') {
+                if (!binding?.repositoryUrl)
+                    throw new Error('batch_source_push_failed');
+                const ref = batchSourceRemoteRef(request.batchId);
+                await pushHiddenRef(cache, source, binding.repositoryUrl, captured.commitHash, ref);
+                snapshot.remoteRef = ref;
+            }
+            else {
+                const key = `workspaces/${request.workspaceId}/batches/${request.batchId}/source/${captured.digest}.json.gz`;
+                const store = options?.objectStore ?? filesystemObjectStore(state);
+                try {
+                    await store.put(key, await archiveSource(cache, captured));
+                }
+                catch (error) {
+                    if (error instanceof Error && error.message === 'batch_object_key_invalid')
+                        throw error;
+                    throw new Error('batch_source_upload_failed');
+                }
+                snapshot.artifactKey = key;
+            }
+        }
+        catch (error) {
+            await rm(cache, { recursive: true, force: true });
+            await rm(`${cache}.digest`, { force: true });
+            throw error;
+        }
+        if (!await lstat(join(cache, '.git')).catch(() => undefined))
+            throw new Error('batch_source_capture_failed');
+        await writeSnapshot(state, snapshot);
+        return batchSourceFreezeResultSchema.parse({ status: 'frozen', snapshot });
+    });
+}