@playcraft/cli 0.1.43-beta → 0.1.45-beta

package/dist/commands/tools-batch.js

@@ -16,6 +16,8 @@ const messages = {
         help: '\nUse --prompt with --workspace-id and a stable --client-request-id. The platform plans and generates independent Remix directories while preserving the source. An omitted count defaults to 3; maximum 10. --input also accepts existing structured drafts.\n',
         confirmation: 'Generation is queued. Read the batch status to track its results.',
         review: 'This existing draft requires baseline approval in the browser.',
+        sync: 'Apply the latest source snapshot to an existing batch',
+        syncDone: 'Batch sync requested',
     },
     zh: {
         create: '用一个 prompt 创建并自动生成独立 Remix 变体',
@@ -30,6 +32,8 @@ const messages = {
         help: '\n使用 --prompt、--workspace-id 和稳定的 --client-request-id。平台自动规划，在副本中生成独立 Remix，保持来源不变。未指定数量默认 3 个，最多 10 个。--input 也兼容现有结构化草案。\n',
         confirmation: '生成已排队，可查询批次状态追踪各项成果。',
         review: '此历史草案需要在浏览器确认基准。',
+        sync: '将来源最新快照同步到已有批次',
+        syncDone: '已请求同步到批次',
     },
 };
 const language = () => /^zh/i.test(process.env.PLAYCRAFT_LANG ?? process.env.LANG ?? '') ? messages.zh : messages.en;
@@ -71,6 +75,20 @@ export function registerBatchCommands(tools) {
             handleError(error);
         }
     });
+    tools.command('sync-batch')
+        .description(t.sync)
+        .requiredOption('--batch-id <id>', t.id)
+        .option('--json', 'JSON (JavaScript Object Notation, 数据交换格式)')
+        .action(async (opts) => {
+        try {
+            const client = new AgentApiClient();
+            const result = await client.post('/sync-batch', { batchId: opts.batchId });
+            console.log(opts.json ? JSON.stringify(result, null, 2) : t.syncDone);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
     tools.command('get-batch')
         .description(t.status)
         .requiredOption('--batch-id <id>', t.id)

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 gitWrite(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 gitWrite(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 });
+    });
+}

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

@@ -0,0 +1,205 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { hashOperationPayload, operationScopeKey, sandboxBatchMemberGenerateSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { attachNativeCollector, executeOperation } from '../server/dispatch.js';
+import { workspaceRoot } from '../workspaces/registry.js';
+import { bindMemberPolicy, memberExecutionPolicy } from './policy.js';
+import { groupExited, stopProcessGroup } from './processes.js';
+import { memberStatus, readMember, readStopMarker, serializeRun, writeMember } from './records.js';
+function hashCommand(value) {
+    return hashOperationPayload(value);
+}
+function operation(state, input) {
+    const now = new Date().toISOString();
+    const record = {
+        operationId: randomUUID(), environment: state.config.environment, userId: state.config.userId,
+        clientRequestId: input.clientRequestId, kind: input.kind, status: 'queued', payloadHash: hashOperationPayload(input.payload),
+        workspaceId: input.workspaceId, directoryName: input.directoryName, sessionId: input.sessionId,
+        generation: state.config.generation, runtimeEpoch: state.runtimeEpoch, leaseFence: state.acceptedLeaseFence,
+        createdAt: now, updatedAt: now,
+    };
+    return { scopeKey: operationScopeKey(record), record };
+}
+function turnTerminal(event) {
+    if (event.kind === 'approval_request')
+        return 'needs_user';
+    if (event.method !== 'turn/completed' && event.method !== 'turn.completed' && event.method !== 'turn.failed' && event.method !== 'turn.interrupted')
+        return undefined;
+    const turn = event.params && typeof event.params === 'object' ? event.params.turn : undefined;
+    if (event.method === 'turn.failed' || turn?.status === 'failed')
+        return 'failed';
+    if (event.method === 'turn.interrupted' || turn?.status === 'interrupted')
+        return 'interrupted';
+    return 'completed';
+}
+function threadIdOf(event) {
+    const params = event.params && typeof event.params === 'object' ? event.params : undefined;
+    return typeof params?.threadId === 'string' ? params.threadId : undefined;
+}
+async function proveStopped(record) {
+    let stopped = true;
+    for (const process of record.processes) {
+        if (process.stopped || groupExited(process.pid))
+            process.stopped = true;
+        else {
+            const did = await stopProcessGroup(process);
+            process.stopped = did;
+            if (!did)
+                stopped = false;
+        }
+    }
+    return stopped;
+}
+export async function generateBatchMember(state, body) {
+    if (!body || typeof body !== 'object' || !('occupancyId' in body) || !body.occupancyId)
+        throw new Error('occupancy_required');
+    const parsed = sandboxBatchMemberGenerateSchema.safeParse(body);
+    if (!parsed.success)
+        throw new Error('invalid_batch_request');
+    const command = parsed.data;
+    const hash = hashCommand(command);
+    return serializeRun(command.runId, async () => {
+        attachNativeCollector(state);
+        const existing = await readMember(state, command.runId);
+        if (existing && command.ownerFence < existing.ownerFence)
+            throw new Error('stale_owner');
+        if (await readStopMarker(state, command.runId))
+            return memberStatus(await stoppedRecord(state, command, existing));
+        if (existing && existing.ownerFence === command.ownerFence && existing.commandHash?.generate === hash && existing.phase === 'generate' && existing.state !== 'running') {
+            return memberStatus(await reconcileGenerate(state, existing));
+        }
+        if (existing && existing.ownerFence === command.ownerFence && existing.commandHash?.generate && existing.commandHash.generate !== hash)
+            throw new Error('batch_command_conflict');
+        const root = await workspaceRoot(state, command.workspaceId, command.directoryName);
+        const sessionId = command.sessionId ?? existing?.sessionId ?? `member-${command.runId}`;
+        const tempDir = join(state.config.stateDir, 'batch-temp', command.runId);
+        await mkdir(tempDir, { recursive: true, mode: 0o700 });
+        const policy = memberExecutionPolicy(root, tempDir);
+        await bindMemberPolicy(state, sessionId, policy);
+        const turnPayload = { text: command.prompt, permissionMode: 'auto', ...(command.model && /^[0-9a-f-]{36}$/i.test(command.model) ? { modelConfigId: command.model } : {}) };
+        const turnKey = operation(state, { kind: 'session.turn', clientRequestId: `batch-turn:${command.runId}`, sessionId, workspaceId: command.workspaceId, directoryName: command.directoryName, payload: turnPayload });
+        const prior = state.journal.getOperation(turnKey.scopeKey);
+        if (prior && prior.payloadHash !== turnKey.record.payloadHash)
+            throw new Error('batch_command_conflict');
+        let record = await writeMember(state, {
+            runId: command.runId, ownerFence: command.ownerFence, occupancyId: command.occupancyId, workspaceId: command.workspaceId,
+            directoryName: command.directoryName, phase: 'generate', state: prior ? (prior.status === 'uncertain' ? 'unknown' : prior.status === 'completed' ? 'completed' : 'running') : 'running',
+            writersStopped: false, holding: true, stopRequested: false, processes: existing?.processes ?? [], sessionId,
+            operationId: prior?.operationId, commandHash: { ...existing?.commandHash, generate: hash },
+            snapshotDigest: existing?.snapshotDigest, branchName: existing?.branchName, headCommit: existing?.headCommit,
+            updatedAt: new Date().toISOString(),
+        });
+        if (prior)
+            return memberStatus(await finishGenerate(state, record, prior, root));
+        if (!state.native?.ready()) {
+            record = await writeMember(state, { ...record, state: 'failed', writersStopped: true, holding: false, error: 'capability_unavailable' });
+            return memberStatus(record);
+        }
+        const terminals = new Map();
+        const unsubscribe = state.native.onCollected?.((event) => {
+            const threadId = threadIdOf(event);
+            const terminal = turnTerminal(event);
+            if (!threadId || !terminal)
+                return;
+            if (terminals.get(threadId) === 'needs_user')
+                return;
+            terminals.set(threadId, terminal);
+        });
+        try {
+            if (!state.journal.getSession(sessionId)) {
+                const created = operation(state, { kind: 'session.create', clientRequestId: `batch-create:${command.runId}`, sessionId, workspaceId: command.workspaceId, directoryName: command.directoryName, payload: { permissionMode: 'auto' } });
+                if (!state.journal.getOperation(created.scopeKey))
+                    await executeOperation(state, created.scopeKey, created.record, { permissionMode: 'auto' });
+            }
+            if (await readStopMarker(state, command.runId))
+                return memberStatus(await stoppedRecord(state, command, record));
+            const started = await executeOperation(state, turnKey.scopeKey, turnKey.record, turnPayload);
+            record = await writeMember(state, { ...record, operationId: started.operationId, sessionId });
+            return memberStatus(await finishGenerate(state, record, started, root, () => {
+                const threadId = state.journal.getSession(sessionId)?.threadId;
+                return threadId ? terminals.get(threadId) : undefined;
+            }));
+        }
+        finally {
+            unsubscribe?.();
+        }
+    });
+}
+async function finishGenerate(state, record, started, root, early) {
+    if (await readStopMarker(state, record.runId))
+        return stoppedRecord(state, { ...record, occupancyId: record.occupancyId }, record);
+    const sessionId = record.sessionId;
+    let terminal = early?.();
+    if (!terminal && (started.status === 'uncertain' || started.error === 'native_receipt_lost')) {
+        return writeMember(state, { ...record, state: 'unknown', writersStopped: false, holding: true, operationId: started.operationId, error: 'native_receipt_lost' });
+    }
+    if (!terminal && started.status === 'failed') {
+        const writersStopped = await proveStopped(record);
+        return writeMember(state, { ...record, state: writersStopped ? 'failed' : 'stopping', writersStopped, holding: !writersStopped, operationId: started.operationId, error: started.error ?? 'batch_turn_failed' });
+    }
+    const deadline = Date.now() + 5_000;
+    while (!terminal && Date.now() < deadline) {
+        terminal = early?.();
+        const session = state.journal.getSession(sessionId);
+        if (session?.turnStatus === 'waiting_for_user')
+            terminal = 'needs_user';
+        else if (session?.turnStatus === 'completed')
+            terminal = 'completed';
+        else if (session?.turnStatus === 'failed')
+            terminal = 'failed';
+        else if (session?.turnStatus === 'interrupted')
+            terminal = 'interrupted';
+        if (!terminal)
+            await delay(15);
+    }
+    if (terminal === 'needs_user') {
+        const session = state.journal.getSession(sessionId);
+        if (session?.threadId)
+            await state.native?.interrupt?.({ sessionId, threadId: session.threadId }).catch(() => undefined);
+        const writersStopped = await proveStopped(record);
+        if (await readStopMarker(state, record.runId))
+            return stoppedRecord(state, record, record);
+        return writeMember(state, {
+            ...record, state: writersStopped ? 'needs_user' : 'stopping', writersStopped, holding: writersStopped ? false : true,
+            operationId: started.operationId, error: writersStopped ? 'needs_user' : undefined,
+        });
+    }
+    if (terminal === 'completed') {
+        const writersStopped = await proveStopped(record);
+        if (!writersStopped)
+            return writeMember(state, { ...record, state: 'stopping', writersStopped: false, holding: true, operationId: started.operationId });
+        if (await readStopMarker(state, record.runId))
+            return stoppedRecord(state, record, record);
+        const head = await import('./git.js').then(git => git.gitRead(root, ['rev-parse', 'HEAD'])).then(value => value.trim()).catch(() => record.headCommit);
+        return writeMember(state, { ...record, state: 'completed', writersStopped: true, holding: true, operationId: started.operationId, headCommit: head, error: undefined });
+    }
+    const writersStopped = await proveStopped(record);
+    return writeMember(state, {
+        ...record, state: writersStopped ? (terminal === 'interrupted' ? 'stopped' : 'failed') : 'unknown',
+        writersStopped, holding: !writersStopped, operationId: started.operationId,
+        error: writersStopped ? (terminal === 'interrupted' ? undefined : 'batch_turn_failed') : 'native_receipt_lost',
+    });
+}
+async function reconcileGenerate(state, record) {
+    const session = record.sessionId ? state.journal.getSession(record.sessionId) : undefined;
+    if (record.state === 'unknown' && session?.turnStatus === 'completed') {
+        const writersStopped = await proveStopped(record);
+        if (writersStopped && !await readStopMarker(state, record.runId)) {
+            return writeMember(state, { ...record, state: 'completed', writersStopped: true, holding: true, error: undefined });
+        }
+    }
+    return record;
+}
+async function stoppedRecord(state, command, existing) {
+    if (existing)
+        await proveStopped(existing);
+    return writeMember(state, {
+        runId: command.runId, ownerFence: command.ownerFence, occupancyId: command.occupancyId, workspaceId: command.workspaceId,
+        directoryName: command.directoryName, phase: existing?.phase ?? 'generate', 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/git.js

@@ -0,0 +1,40 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { dirname } from 'node:path';
+const execute = promisify(execFile);
+/** Read-only git. An empty credential helper keeps the source checkout from authenticating or writing. */
+export async function gitRead(root, args) {
+    return runGit(root, ['-c', 'credential.helper=', ...args]);
+}
+/** Push and fetch. Local credential helpers copied onto this repo stay in effect. */
+export async function gitWrite(root, args) {
+    return runGit(root, args);
+}
+async function runGit(root, args) {
+    const { stdout } = await execute('git', [
+        '-c', 'core.hooksPath=/dev/null', '-c', 'init.templateDir=', '-c', 'core.fsmonitor=false', '-C', root, ...args,
+    ], {
+        timeout: 90_000, maxBuffer: 64 * 1024 * 1024,
+        env: {
+            PATH: process.env.PATH, HOME: dirname(root), GIT_OPTIONAL_LOCKS: '0',
+            GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0',
+        },
+    });
+    return stdout;
+}
+/** Copies URL credential helpers onto a snapshot repo without reading or writing the source config. */
+export async function copyCredentialHelpers(sourceRoot, destinationRoot) {
+    const listed = await gitRead(sourceRoot, ['config', '--local', '--get-regexp', '^(credential\\.|http\\.|url\\.)']).catch(() => '');
+    for (const line of listed.split('\n')) {
+        if (!line)
+            continue;
+        const space = line.indexOf(' ');
+        if (space < 1)
+            continue;
+        const key = line.slice(0, space);
+        const value = line.slice(space + 1);
+        if (!/^(credential\.|http\.|url\.)/.test(key) || /[\r\n]/.test(value))
+            continue;
+        await gitWrite(destinationRoot, ['config', '--local', key, value]);
+    }
+}

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

@@ -0,0 +1,8 @@
+import { listMembers } from './records.js';
+/** True while a member Run still holds the directory. Other sandbox write entries must refuse it. */
+export async function batchDirectoryHeld(state, workspaceId, directoryName) {
+    if (!workspaceId)
+        return false;
+    const members = await listMembers(state);
+    return members.some(record => record.holding && record.workspaceId === workspaceId && record.directoryName === directoryName);
+}