@playcraft/cli 0.1.54 → 0.1.56-beta

package/dist/workspace/transfer-client.js

@@ -0,0 +1,237 @@
+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 });
+    // Ensure may return a queued receipt before the workspace is prepared; a cold container can
+    // take minutes, so follow the operation instead of relying on the HTTP response to be final.
+    const ensureDeadline = Date.now() + 180_000;
+    while (operation.operationId && ['queued', 'dispatched', 'accepted'].includes(operation.status ?? '')
+        && Date.now() < ensureDeadline) {
+        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/content-changes.js

@@ -0,0 +1,30 @@
+import { gitRead } from './git.js';
+const reference = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const excludedDirectories = new Set(['node_modules', 'dist', 'build', 'coverage', 'docs', 'test', 'tests', '__tests__']);
+const contentExtension = /\.(?:[cm]?[jt]sx?|vue|svelte|html?|css|s[ac]ss|less|json5?|ya?ml|xml|glsl|wgsl|vert|frag|lua|py|svg|png|jpe?g|webp|avif|gif|bmp|mp[34]|wav|ogg|m4a|webm|glb|gltf|fbx|obj|bin|atlas|woff2?|ttf|otf)$/i;
+function contentPath(path) {
+    const parts = path.split('/');
+    if (parts.some(part => part.startsWith('.') || excludedDirectories.has(part)))
+        return false;
+    const name = parts.at(-1);
+    if (/^(?:package(?:-lock)?\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|tsconfig(?:\.[^.]+)?\.json|(?:vite|vitest|webpack|eslint|prettier)\.config\..+)$/i.test(name))
+        return false;
+    return contentExtension.test(name);
+}
+/** A completed batch member must change code, runtime configuration, or assets. */
+export async function requireBatchContentChanges(root, before, after) {
+    if (!reference.test(before) || !reference.test(after))
+        throw new Error('batch_change_reference_invalid');
+    const stdout = await gitRead(root, ['diff', '--raw', '--no-abbrev', '--no-renames', '-z', before, after, '--']);
+    const records = stdout.split('\0'), paths = [];
+    for (let index = 0; index + 1 < records.length; index += 2) {
+        const [oldMode, newMode, oldBlob, newBlob] = records[index].slice(1).split(' ');
+        const path = records[index + 1];
+        if ((oldMode === '100644' || oldMode === '100755' || newMode === '100644' || newMode === '100755')
+            && oldBlob !== newBlob && contentPath(path))
+            paths.push(path);
+    }
+    if (!paths.length)
+        throw new Error('batch_generation_no_content_change');
+    return paths;
+}

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

@@ -0,0 +1,86 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { sandboxBatchMemberStopSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { groupExited, stopProcessGroup } from './processes.js';
+import { settleObservedGenerate } from './generate.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;
+    if (record.phase === 'generate' && record.state === 'running') {
+        const settled = await settleObservedGenerate(state, record);
+        if (settled.state !== 'running')
+            return memberStatus(settled);
+    }
+    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,173 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { hashOperationPayload, sandboxBatchMemberDeliverSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRoot } from '../workspaces/registry.js';
+import { groupExited, runProcessGroup, stopProcessGroup } from './processes.js';
+import { memberStatus, readMember, readStopMarker, serializeRun, writeMember, } from './records.js';
+/** Base build writes dist/index.html. Channel packaging stays on export playable (`--mode full`). */
+function buildCommand() {
+    return (process.env.PLAYCRAFT_BATCH_BUILD_COMMAND ?? 'CI=1 playcraft build --mode base --output dist .');
+}
+async function readBuiltHtml(root) {
+    const htmlPath = join(root, 'dist', 'index.html');
+    const info = await lstat(htmlPath).catch(() => undefined);
+    if (!info?.isFile() || info.isSymbolicLink())
+        throw new Error('batch_build_failed');
+    const handle = await open(htmlPath, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => {
+        throw new Error('batch_build_failed');
+    });
+    await handle.close();
+}
+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) {
+    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(),
+            sourceCommit: existing?.sourceCommit ??
+                state.journal
+                    .getWorkspace(command.workspaceId)
+                    ?.directories?.find((directory) => directory.directoryName === command.directoryName)
+                    ?.sourceCommit,
+            beforeTree: existing?.beforeTree,
+        });
+        try {
+            if (await readStopMarker(state, command.runId))
+                return memberStatus(await markStopped(state, command, record));
+            const built = await runProcessGroup(root, 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');
+            await readBuiltHtml(root);
+            const writersStopped = await prove(record);
+            if (!writersStopped)
+                return memberStatus(await writeMember(state, {
+                    ...record,
+                    state: 'stopping',
+                    writersStopped: false,
+                    holding: true,
+                }));
+            if (await readStopMarker(state, command.runId))
+                return memberStatus(await markStopped(state, command, record));
+            record = await writeMember(state, {
+                ...record,
+                state: 'completed',
+                writersStopped: true,
+                holding: false,
+                error: undefined,
+                evidence: { verified: true },
+            });
+            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);
+        }
+    });
+}
+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(),
+        sourceCommit: existing?.sourceCommit,
+        beforeTree: existing?.beforeTree,
+    });
+}