@playcraft/cli 0.1.42 → 0.1.44-beta

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

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

@@ -0,0 +1,70 @@
+import { readFileSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+const memory = new WeakMap();
+/** Unattended member execution: workspace-write to the member directory and one controlled temp dir. */
+export function memberExecutionPolicy(cwd, tempDir) {
+    return {
+        cwd,
+        approvalPolicy: 'never',
+        sandboxPolicy: {
+            type: 'workspaceWrite',
+            writableRoots: [cwd, tempDir],
+            networkAccess: true,
+            excludeTmpdirEnvVar: true,
+            excludeSlashTmp: true,
+        },
+    };
+}
+function policyPath(state, sessionId) {
+    return join(state.config.stateDir, 'batch-sessions', `${sessionId.replace(/[^a-zA-Z0-9._-]/g, '_')}.json`);
+}
+function parsePolicy(raw) {
+    const value = JSON.parse(raw);
+    if (value?.approvalPolicy !== 'never' || value.sandboxPolicy?.type !== 'workspaceWrite')
+        return undefined;
+    if (!value.cwd || !Array.isArray(value.sandboxPolicy.writableRoots) || value.sandboxPolicy.writableRoots.length === 0)
+        return undefined;
+    if (!value.sandboxPolicy.excludeSlashTmp || !value.sandboxPolicy.excludeTmpdirEnvVar)
+        return undefined;
+    return value;
+}
+export async function bindMemberPolicy(state, sessionId, policy) {
+    const path = policyPath(state, sessionId);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temporary, JSON.stringify(policy), { mode: 0o600 });
+    renameSync(temporary, path);
+    const map = memory.get(state) ?? new Map();
+    map.set(sessionId, policy);
+    memory.set(state, map);
+}
+/** Synchronous: the shared session adapter reapplies this on every thread start and resume. */
+export function trustedMemberPolicy(state, sessionId) {
+    const cached = memory.get(state)?.get(sessionId);
+    if (cached)
+        return cached;
+    try {
+        const parsed = parsePolicy(readFileSync(policyPath(state, sessionId), 'utf8'));
+        if (!parsed) {
+            return {
+                cwd: state.config.workspaceRoot,
+                approvalPolicy: 'never',
+                sandboxPolicy: { type: 'readOnly', networkAccess: false },
+            };
+        }
+        const map = memory.get(state) ?? new Map();
+        map.set(sessionId, parsed);
+        memory.set(state, map);
+        return parsed;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        return {
+            cwd: state.config.workspaceRoot,
+            approvalPolicy: 'never',
+            sandboxPolicy: { type: 'readOnly', networkAccess: false },
+        };
+    }
+}

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

@@ -0,0 +1,202 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { sandboxBatchMemberPrepareSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { registerWorkspaceDirectory } from '../workspaces/directories.js';
+import { workspaceContainerRoot } from '../workspaces/registry.js';
+import { copyCredentialHelpers, gitRead, gitWrite } from './git.js';
+import { digestFiles, readSourceFiles, restoreArchive } from './source-capture.js';
+import { groupExited, runProcessGroup } from './processes.js';
+import { filesystemObjectStore, memberStatus, readMember, readSnapshot, readStopMarker, serializeRun, sourceCacheDir, writeMember, } from './records.js';
+const BRANCH = /^remix\/draft-[a-f0-9]{16}$/;
+const LOCKS = ['pnpm-lock.yaml', 'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'bun.lock', 'bun.lockb'];
+export function frozenInstallCommand() {
+    return process.env.PLAYCRAFT_BATCH_INSTALL_COMMAND
+        ?? 'pnpm install --frozen-lockfile --store-dir /var/cache/playcraft/pnpm-store --ignore-scripts';
+}
+function hashCommand(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+async function materialize(state, snapshot, destination, store, sourceRoot) {
+    const cache = sourceCacheDir(state, snapshot.batchId);
+    const cachedDigest = await readFile(`${cache}.digest`, 'utf8').catch(() => '');
+    if (cachedDigest.trim() === snapshot.digest && await lstat(join(cache, '.git')).catch(() => undefined)) {
+        await gitWrite(dirnameOf(destination), ['clone', '--local', '--no-hardlinks', '--', cache, destination]);
+        if (digestFiles(await readSourceFiles(destination)) !== snapshot.digest)
+            throw new Error('batch_snapshot_mismatch');
+        return;
+    }
+    if (snapshot.remoteRef) {
+        const binding = state.journal.getWorkspace(snapshot.sourceWorkspaceId);
+        if (!binding?.repositoryUrl)
+            throw new Error('batch_snapshot_mismatch');
+        await gitWrite(dirnameOf(destination), ['init', '--initial-branch', 'source', destination]);
+        await copyCredentialHelpers(sourceRoot, destination);
+        await gitWrite(destination, ['remote', 'add', 'origin', binding.repositoryUrl]);
+        try {
+            await gitWrite(destination, ['fetch', '--no-tags', 'origin', snapshot.remoteRef]);
+        }
+        catch {
+            throw new Error('batch_snapshot_mismatch');
+        }
+        await gitWrite(destination, ['checkout', '--detach', 'FETCH_HEAD']);
+        if ((await gitRead(destination, ['rev-parse', 'HEAD'])).trim() !== snapshot.commitHash)
+            throw new Error('batch_snapshot_mismatch');
+        if (digestFiles(await readSourceFiles(destination)) !== snapshot.digest)
+            throw new Error('batch_snapshot_mismatch');
+        return;
+    }
+    if (!snapshot.artifactKey)
+        throw new Error('batch_snapshot_mismatch');
+    const body = await store.get(snapshot.artifactKey).catch(() => { throw new Error('batch_snapshot_mismatch'); });
+    await restoreArchive(body, destination, snapshot.digest);
+}
+function dirnameOf(path) {
+    return join(path, '..');
+}
+async function checkoutBranch(root, branchName, commit, repositoryUrl) {
+    await gitWrite(root, ['checkout', '-B', branchName, commit]);
+    const origin = await gitRead(root, ['remote', 'get-url', 'origin']).catch(() => '');
+    if (!origin.trim())
+        await gitWrite(root, ['remote', 'add', 'origin', repositoryUrl]);
+    else if (origin.trim() !== repositoryUrl)
+        await gitWrite(root, ['remote', 'set-url', 'origin', repositoryUrl]);
+    await gitWrite(root, ['config', 'user.name', 'PlayCraft']);
+    await gitWrite(root, ['config', 'user.email', 'playcraft@localhost']);
+}
+async function resumeBranch(repositoryUrl, branchName, commit, destination, sourceRoot) {
+    await gitWrite(dirnameOf(destination), ['clone', '--branch', branchName, '--single-branch', '--', repositoryUrl, destination]);
+    await copyCredentialHelpers(sourceRoot, destination);
+    if ((await gitRead(destination, ['rev-parse', 'HEAD'])).trim() !== commit && !(await gitRead(destination, ['cat-file', '-e', `${commit}^{commit}`]).then(() => true, () => false))) {
+        throw new Error('batch_commit_mismatch');
+    }
+    await gitWrite(destination, ['checkout', '-B', branchName, commit]);
+}
+export async function assertMemberDependencies(root) {
+    let manifest;
+    try {
+        manifest = await readFile(join(root, 'package.json'), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return 'skip';
+        throw error;
+    }
+    let names = [];
+    try {
+        const pkg = JSON.parse(manifest);
+        names = [...Object.keys(pkg.dependencies ?? {}), ...Object.keys(pkg.devDependencies ?? {})];
+    }
+    catch {
+        throw new Error('dependency_lock_mismatch');
+    }
+    const present = [];
+    for (const lock of LOCKS)
+        if (await lstat(join(root, lock)).catch(() => undefined))
+            present.push(lock);
+    if (present.length > 1)
+        throw new Error('dependency_locks_conflict');
+    if (present.length === 0)
+        return 'skip';
+    if (present[0] !== 'pnpm-lock.yaml')
+        throw new Error('dependency_lock_mismatch');
+    const lock = await readFile(join(root, 'pnpm-lock.yaml'), 'utf8');
+    if (names.some(name => !lock.includes(`${name}:`) && !lock.includes(`/${name}@`) && !lock.includes(`'${name}'`) && !lock.includes(`"${name}"`))) {
+        throw new Error('dependency_lock_mismatch');
+    }
+    return 'install';
+}
+export async function prepareBatchMember(state, body, options) {
+    if (!body || typeof body !== 'object' || !('occupancyId' in body) || !body.occupancyId)
+        throw new Error('occupancy_required');
+    const parsed = sandboxBatchMemberPrepareSchema.safeParse(body);
+    if (!parsed.success)
+        throw new Error(parsed.error.issues.some(issue => issue.path.includes('branchName')) ? 'batch_branch_invalid' : 'invalid_batch_request');
+    const command = parsed.data;
+    if (!BRANCH.test(command.branchName))
+        throw new Error('batch_branch_invalid');
+    const hash = hashCommand(command);
+    return serializeRun(command.runId, async () => {
+        const marker = await readStopMarker(state, command.runId);
+        const existing = await readMember(state, command.runId);
+        if (existing && command.ownerFence < existing.ownerFence)
+            throw new Error('stale_owner');
+        if (marker)
+            return memberStatus(await sealStopped(state, command, existing));
+        if (existing && existing.ownerFence === command.ownerFence && existing.commandHash?.prepare === hash && existing.state !== 'running' && existing.state !== 'failed') {
+            return memberStatus(existing);
+        }
+        if (existing && existing.ownerFence === command.ownerFence && existing.commandHash?.prepare && existing.commandHash.prepare !== hash)
+            throw new Error('batch_command_conflict');
+        if (existing?.processes.some(process => process.role === 'install' && !process.stopped && !groupExited(process.pid)))
+            return memberStatus(existing);
+        const snapshot = command.snapshot;
+        if ((await readSnapshot(state, snapshot.batchId))?.digest === snapshot.digest) {
+            /* The local snapshot record is an accelerator; the command snapshot remains authoritative. */
+        }
+        let record = await writeMember(state, {
+            runId: command.runId, ownerFence: command.ownerFence, occupancyId: command.occupancyId,
+            workspaceId: command.workspaceId, directoryName: command.directoryName, phase: 'prepare', state: 'running',
+            writersStopped: false, holding: true, stopRequested: false, processes: existing?.processes ?? [],
+            commandHash: { ...existing?.commandHash, prepare: hash }, snapshotDigest: snapshot.digest, branchName: command.branchName,
+            updatedAt: new Date().toISOString(),
+        });
+        const parent = await workspaceContainerRoot(state, command.workspaceId);
+        const root = join(parent, command.directoryName);
+        const staging = join(parent, `.batch-member-${randomUUID()}`);
+        const binding = state.journal.getWorkspace(command.workspaceId);
+        if (!binding?.repositoryUrl)
+            throw new Error('workspace_not_registered');
+        const sourceRoot = join(parent, snapshot.sourceDirectoryName);
+        try {
+            if (!await lstat(root).catch(() => undefined)) {
+                await mkdir(parent, { recursive: true });
+                if (command.resumeFromCommit)
+                    await resumeBranch(binding.repositoryUrl, command.branchName, command.resumeFromCommit, staging, sourceRoot);
+                else
+                    await materialize(state, snapshot, staging, options?.objectStore ?? filesystemObjectStore(state), sourceRoot);
+                const commit = command.resumeFromCommit ?? snapshot.commitHash;
+                await checkoutBranch(staging, command.branchName, commit, binding.repositoryUrl);
+                const { rename } = await import('node:fs/promises');
+                await rename(staging, root);
+            }
+            await registerWorkspaceDirectory(state, {
+                workspaceId: command.workspaceId, directoryName: command.directoryName, remixId: command.remixId,
+                branchName: command.branchName, sourceCommit: command.resumeFromCommit ?? snapshot.commitHash,
+            }, state.acceptedLeaseFence);
+            const plan = await assertMemberDependencies(root);
+            if (plan === 'install') {
+                const installed = await runProcessGroup(root, frozenInstallCommand(), 'install', async (process) => {
+                    record = await writeMember(state, { ...record, processes: [...record.processes, process] });
+                });
+                record = await writeMember(state, { ...record, processes: record.processes.map(process => process.pid === installed.process.pid ? { ...installed.process, role: 'install' } : process) });
+                if (await readStopMarker(state, command.runId))
+                    return memberStatus(await sealStopped(state, command, record));
+                if (installed.code !== 0)
+                    throw new Error('batch_install_failed');
+            }
+            const head = (await gitRead(root, ['rev-parse', 'HEAD'])).trim();
+            record = await writeMember(state, { ...record, state: 'completed', writersStopped: true, holding: true, headCommit: head, error: undefined });
+            return memberStatus(record);
+        }
+        catch (error) {
+            const code = error instanceof Error && /^[a-z0-9_]+$/.test(error.message) ? error.message : 'batch_prepare_failed';
+            record = await writeMember(state, { ...record, state: 'failed', writersStopped: true, holding: false, error: code });
+            return memberStatus(record);
+        }
+        finally {
+            await rm(staging, { recursive: true, force: true });
+        }
+    });
+}
+async function sealStopped(state, command, existing) {
+    return writeMember(state, {
+        runId: command.runId, ownerFence: Math.max(command.ownerFence, existing?.ownerFence ?? 0), occupancyId: command.occupancyId,
+        workspaceId: command.workspaceId, directoryName: command.directoryName, phase: existing?.phase ?? 'prepare',
+        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/processes.js

@@ -0,0 +1,72 @@
+import { execFile, spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { setTimeout as delay } from 'node:timers/promises';
+export async function processBirth(pid) {
+    if (process.platform !== 'linux') {
+        return promisify(execFile)('ps', ['-p', String(pid), '-o', 'lstart='], { timeout: 2000 }).then(value => value.stdout.trim() || undefined, () => undefined);
+    }
+    try {
+        const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+        return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function groupExited(pid) {
+    try {
+        process.kill(-pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+/**
+ * Stops one run's process group. A mismatched birth means the pid was reused, which is not proof
+ * that the original writers exited, so the caller must not report writersStopped.
+ */
+export async function stopProcessGroup(record) {
+    if (record.stopped || groupExited(record.pid))
+        return true;
+    if (record.birth && await processBirth(record.pid) !== record.birth)
+        return false;
+    for (const signal of ['SIGTERM', 'SIGKILL']) {
+        try {
+            process.kill(-record.pid, signal);
+        }
+        catch { /* Recheck the group. */ }
+        const deadline = Date.now() + 2000;
+        while (Date.now() < deadline) {
+            if (groupExited(record.pid))
+                return true;
+            await delay(25);
+        }
+    }
+    return groupExited(record.pid);
+}
+export async function runProcessGroup(cwd, command, role, onStart) {
+    const child = spawn('bash', ['-lc', command], {
+        cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+        env: { PATH: process.env.PATH, HOME: cwd, GIT_TERMINAL_PROMPT: '0' },
+    });
+    const pid = child.pid;
+    if (!pid)
+        throw new Error('batch_process_not_started');
+    let output = '';
+    const collect = (chunk) => { output = (output + String(chunk)).slice(-64 * 1024); };
+    child.stdout?.on('data', collect);
+    child.stderr?.on('data', collect);
+    // Subscribe before any await. A short command can exit during processBirth or onStart,
+    // and a late listener never sees that close event.
+    const finished = new Promise((resolve) => {
+        child.once('error', () => resolve(null));
+        child.once('close', resolve);
+    });
+    const tracked = { pid, birth: await processBirth(pid), stopped: false, role };
+    await onStart(tracked);
+    const code = await finished;
+    tracked.stopped = groupExited(pid);
+    return { code, output, process: tracked };
+}