@playcraft/cli 0.1.21 → 0.1.23

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

@@ -1,7 +1,7 @@
 import { readObservedFile, withObservedFile } from '../workspaces/revisions.js';
-import { registerWorkspace, revisionScope, workspaceRoot, WorkspaceContextError } from '../workspaces/registry.js';
+import { registerWorkspace, revisionScope, sessionWorkspaceRoot, workspaceRoot, WorkspaceContextError } from '../workspaces/registry.js';
 import { randomUUID } from 'node:crypto';
-import { workspaceRegistrationRequestSchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, hashOperationPayload, isLostThreadError, sourceAckSchema, operationAcceptRequestSchema, operationKindSchema, operationScopeKey, resolveIdempotentAccept, nativeHistoryReadSchema, runtimeError, runtimeConnectivityDocumentSchema, unavailableRuntimeCapabilities, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRegistrationRequestSchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, hashOperationPayload, isLostThreadError, sourceAckSchema, operationAcceptRequestSchema, operationKindSchema, operationScopeKey, isWorkspaceMutation, resolveIdempotentAccept, nativeHistoryReadSchema, runtimeError, runtimeConnectivityDocumentSchema, unavailableRuntimeCapabilities, } from '@playcraft/common/cloud-workspace/runtime';
 import { controlTokenMatches, extractControlToken } from './auth.js';
 import { applyRuntimeEndpointPatch } from './endpoints.js';
 import { canExecuteKind, executeOperation } from './dispatch.js';
@@ -16,9 +16,14 @@ import { readWorkspaceSkills } from '../workspaces/skills.js';
 import { loadWorkspaceSkillArtifact } from '../workspaces/skill-artifact-loader.js';
 import { join } from 'node:path';
 import { terminalHost } from './terminal-host.js';
+import { productionCapability, productionDirectoryBusy, executeSandboxProduction, sandboxProductionReceipt } from '../production/controller.js';
+import { cleanupWorkspaceDirectories, syncWorkspaceDirectories } from '../workspaces/directory-maintenance.js';
+import { registerWorkspaceDirectory, restoreWorkspaceDirectory } from '../workspaces/directories.js';
+import { readWorkspaceDirectoryStats } from '../workspaces/directory-stats.js';
 import { probeRuntimeConnectivity } from './connectivity.js';
 export async function handleRuntimeRequest(state, request, response) {
     const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    const directoryName = url.searchParams.get('directoryName') ?? 'basic';
     const access = authorizeRuntime(state, request);
     if (!access) {
         writeError(response, runtimeError('unauthenticated', 'control_token_required'));
@@ -29,6 +34,21 @@ export async function handleRuntimeRequest(state, request, response) {
         return;
     }
     try {
+        if (request.method === 'GET' && url.pathname === '/runtime/production/capability') {
+            writeJson(response, 200, await productionCapability(state));
+            return;
+        }
+        if (request.method === 'POST' && ['/runtime/production/stages', '/runtime/production/stop', '/runtime/production/reconcile'].includes(url.pathname)) {
+            writeJson(response, 200, await executeSandboxProduction(state, await readJson(request)));
+            return;
+        }
+        if (request.method === 'GET' && url.pathname.startsWith('/runtime/production/stages/')) {
+            writeJson(response, 200, await sandboxProductionReceipt(state, decodeURIComponent(url.pathname.slice('/runtime/production/stages/'.length)), {
+                workspaceId: url.searchParams.get('workspaceId') ?? '', directoryName, taskId: url.searchParams.get('taskId') ?? '',
+                attemptId: url.searchParams.get('attemptId') ?? '', owner: url.searchParams.get('owner') ?? '', fence: Number(url.searchParams.get('fence')),
+            }));
+            return;
+        }
         if (request.method === 'GET' && url.pathname === '/runtime/health') {
             writeJson(response, 200, { status: 'ok', handshake: handshake(state) });
             return;
@@ -42,7 +62,7 @@ export async function handleRuntimeRequest(state, request, response) {
                 return;
             }
             const workspaceId = parsed.data;
-            await workspaceRoot(state, workspaceId);
+            await sessionWorkspaceRoot(state, workspaceId, directoryName);
             writeJson(response, 200, await probeRuntimeConnectivity(state, workspaceId));
             return;
         }
@@ -82,6 +102,34 @@ export async function handleRuntimeRequest(state, request, response) {
             writeJson(response, 200, { workspaceId: binding.workspaceId, status: 'registered' });
             return;
         }
+        if (request.method === 'POST' && url.pathname === '/runtime/workspaces/directories/register') {
+            if (writeDestroyed(state, response))
+                return;
+            const body = asRecord(await readJson(request));
+            if (body.generation !== state.config.generation || body.runtimeEpoch !== state.runtimeEpoch || !Number.isSafeInteger(body.leaseFence)) {
+                writeJson(response, 409, { error: 'invalid_workspace_registration' });
+                return;
+            }
+            writeJson(response, 200, await registerWorkspaceDirectory(state, body.directory, Number(body.leaseFence)));
+            return;
+        }
+        const maintenance = /^\/runtime\/workspaces\/([a-f0-9-]{36})\/directories\/(cleanup|sync|stats)$/.exec(url.pathname);
+        if ((request.method === 'GET' || request.method === 'POST') && maintenance?.[2] === 'stats') {
+            if (writeDestroyed(state, response))
+                return;
+            writeJson(response, 200, await readWorkspaceDirectoryStats(state, maintenance[1]));
+            return;
+        }
+        if (request.method === 'POST' && maintenance) {
+            if (writeDestroyed(state, response))
+                return;
+            const body = asRecord(await readJson(request));
+            const workspaceId = maintenance[1];
+            writeJson(response, 200, maintenance[2] === 'cleanup'
+                ? await cleanupWorkspaceDirectories(state, workspaceId, body.directoryNames)
+                : await syncWorkspaceDirectories(state, workspaceId, body.commitHash, body.targetDirectoryNames));
+            return;
+        }
         if (request.method === 'POST' && url.pathname === '/runtime/endpoints') {
             try {
                 writeJson(response, 200, await applyRuntimeEndpointPatch(state, await readJson(request)));
@@ -114,7 +162,11 @@ export async function handleRuntimeRequest(state, request, response) {
             if (writeDestroyed(state, response))
                 return;
             const workspaceId = url.searchParams.get('workspaceId') ?? '';
-            const root = await workspaceRoot(state, workspaceId);
+            if (await productionDirectoryBusy(state, workspaceId, directoryName)) {
+                writeJson(response, 409, { error: 'batch_workspace_readonly' });
+                return;
+            }
+            const root = await workspaceRoot(state, workspaceId, directoryName);
             try {
                 writeJson(response, 200, await uploadWorkspaceAttachment(root, await readAttachmentUpload(request)));
             }
@@ -127,8 +179,8 @@ export async function handleRuntimeRequest(state, request, response) {
             if (writeDestroyed(state, response))
                 return;
             const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
-            const root = await workspaceRoot(state, workspaceId);
-            const listed = await listWorkspaceFiles(root, state.journal.fileRevisions(revisionScope(state, workspaceId)));
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            const listed = await listWorkspaceFiles(root, state.journal.fileRevisions(revisionScope(state, workspaceId, directoryName)));
             console.log(`[workspace-files] GET /runtime/files workspaceId=${workspaceId ?? '-'} root=${root} files=${listed.files.length}`);
             writeJson(response, 200, listed);
             return;
@@ -138,7 +190,7 @@ export async function handleRuntimeRequest(state, request, response) {
                 return;
             const relativePath = url.searchParams.get('path') ?? '';
             try {
-                writeJson(response, 200, await readObservedFile(state, url.searchParams.get('workspaceId') ?? undefined, relativePath));
+                writeJson(response, 200, await readObservedFile(state, url.searchParams.get('workspaceId') ?? undefined, relativePath, directoryName));
             }
             catch (error) {
                 if (error instanceof InvalidWorkspacePathError) {
@@ -154,11 +206,11 @@ export async function handleRuntimeRequest(state, request, response) {
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/git/status') {
-            await writeGitRead(state, response, async () => readWorkspaceGitStatus(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined)));
+            await writeGitRead(state, response, async () => readWorkspaceGitStatus(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName)));
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/git/diff') {
-            await writeGitRead(state, response, async () => readWorkspaceGitDiff(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined)));
+            await writeGitRead(state, response, async () => readWorkspaceGitDiff(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName)));
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/git/file') {
@@ -167,15 +219,15 @@ export async function handleRuntimeRequest(state, request, response) {
                 writeJson(response, 400, { error: 'invalid_git_ref' });
                 return;
             }
-            await writeGitRead(state, response, async () => readWorkspaceGitFile(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined), url.searchParams.get('path') ?? '', ref.data));
+            await writeGitRead(state, response, async () => readWorkspaceGitFile(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName), url.searchParams.get('path') ?? '', ref.data));
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/dependencies') {
             if (writeDestroyed(state, response))
                 return;
             const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
-            await workspaceRoot(state, workspaceId);
-            writeJson(response, 200, readDependencies(state, workspaceId ?? 'workspace'));
+            await workspaceRoot(state, workspaceId, directoryName);
+            writeJson(response, 200, readDependencies(state, revisionScope(state, workspaceId, directoryName) ?? 'workspace'));
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/skills') {
@@ -183,7 +235,7 @@ export async function handleRuntimeRequest(state, request, response) {
                 return;
             const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
             try {
-                const view = await state.journal.exclusive(`workspace:${revisionScope(state, workspaceId) ?? 'single'}`, async () => readWorkspaceSkills(await workspaceRoot(state, workspaceId), join(state.config.stateDir, 'skill-artifacts'), entry => loadWorkspaceSkillArtifact(state, workspaceId ?? 'workspace', entry)));
+                const view = await state.journal.exclusive(`workspace:${revisionScope(state, workspaceId, directoryName) ?? 'single'}`, async () => readWorkspaceSkills(await workspaceRoot(state, workspaceId, directoryName), join(state.config.stateDir, 'skill-artifacts'), entry => loadWorkspaceSkillArtifact(state, workspaceId ?? 'workspace', entry, directoryName)));
                 writeJson(response, 200, view);
             }
             catch (error) {
@@ -194,20 +246,20 @@ export async function handleRuntimeRequest(state, request, response) {
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/git/graph') {
-            await writeGitRead(state, response, async () => readWorkspaceGitGraph(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined)));
+            await writeGitRead(state, response, async () => readWorkspaceGitGraph(await workspaceRoot(state, url.searchParams.get('workspaceId') ?? undefined, directoryName)));
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/parameters') {
             if (writeDestroyed(state, response))
                 return;
-            writeJson(response, 200, await readObservedParameters(state, url.searchParams.get('workspaceId') ?? undefined));
+            writeJson(response, 200, await readObservedParameters(state, url.searchParams.get('workspaceId') ?? undefined, directoryName));
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/terminals') {
             if (writeDestroyed(state, response))
                 return;
             writeJson(response, 200, {
-                terminals: state.journal.listTerminals(url.searchParams.get('workspaceId') ?? undefined),
+                terminals: state.journal.listTerminals(url.searchParams.get('workspaceId') ?? undefined).filter(terminal => (terminal.directoryName ?? 'basic') === directoryName),
             });
             return;
         }
@@ -358,8 +410,19 @@ async function acceptOperation(state, request, response) {
         writeJson(response, 400, { error: 'invalid_operation', reason: 'sessionId_required' });
         return;
     }
+    if (parsed.data.directoryName === 'root' && !parsed.data.kind.startsWith('session.') && parsed.data.kind !== 'runtime.ensure') {
+        writeJson(response, 400, { error: 'invalid_workspace_directory' });
+        return;
+    }
+    if (state.config.workspaceMode === 'multi' && parsed.data.kind === 'runtime.ensure' && parsed.data.workspaceId)
+        await restoreWorkspaceDirectory(state, parsed.data.workspaceId, parsed.data.directoryName);
     if (state.config.workspaceMode === 'multi')
-        await workspaceRoot(state, parsed.data.workspaceId);
+        await sessionWorkspaceRoot(state, parsed.data.workspaceId, parsed.data.directoryName);
+    const mutation = isWorkspaceMutation(parsed.data.kind);
+    if (mutation && await productionDirectoryBusy(state, parsed.data.workspaceId, parsed.data.directoryName)) {
+        writeJson(response, 409, { error: 'batch_workspace_readonly' });
+        return;
+    }
     const payloadHash = hashOperationPayload(parsed.data.payload);
     const scopeKey = operationScopeKey({
         environment: state.config.environment,
@@ -367,6 +430,7 @@ async function acceptOperation(state, request, response) {
         kind: parsed.data.kind,
         clientRequestId: parsed.data.clientRequestId,
         workspaceId: parsed.data.workspaceId,
+        directoryName: parsed.data.directoryName,
         sessionId: parsed.data.sessionId,
     });
     const accept = () => state.journal.exclusive(scopeKey, async () => {
@@ -428,7 +492,8 @@ async function acceptOperation(state, request, response) {
             const session = state.journal.getSession(parsed.data.sessionId);
             // A replaced sandbox has no binding yet; the recovering turn creates it.
             const rebinding = !session && parsed.data.kind === 'session.turn' && parsed.data.sessionRecovery;
-            if (!rebinding && (!session || session.workspaceId !== parsed.data.workspaceId)) {
+            if (!rebinding && (!session || session.workspaceId !== parsed.data.workspaceId
+                || (session.directoryName ?? 'basic') !== (parsed.data.directoryName ?? 'basic'))) {
                 writeJson(response, 409, { error: 'session_workspace_mismatch' });
                 return;
             }
@@ -445,6 +510,7 @@ async function acceptOperation(state, request, response) {
             status: executable ? 'queued' : 'failed',
             payloadHash,
             workspaceId: parsed.data.workspaceId,
+            directoryName: parsed.data.directoryName,
             sessionId: parsed.data.sessionId,
             expectedRevision: parsed.data.expectedRevision,
             generation: state.config.generation,
@@ -479,19 +545,32 @@ async function acceptOperation(state, request, response) {
         }
         writeJson(response, executed.status === 'failed' ? 409 : 202, executed);
     });
-    if (parsed.data.kind === 'session.create')
-        await state.journal.exclusive(`session:${parsed.data.sessionId}`, accept);
-    else if (parsed.data.kind === 'terminal.create') {
-        const terminalId = typeof asRecord(parsed.data.payload).terminalId === 'string'
-            ? String(asRecord(parsed.data.payload).terminalId).trim()
-            : '';
-        if (terminalId)
-            await state.journal.exclusive(`terminal:${terminalId}`, accept);
+    const acceptBound = async () => {
+        if (mutation && await productionDirectoryBusy(state, parsed.data.workspaceId, parsed.data.directoryName)) {
+            writeJson(response, 409, { error: 'batch_workspace_readonly' });
+            return;
+        }
+        if (state.config.workspaceMode === 'multi')
+            await sessionWorkspaceRoot(state, parsed.data.workspaceId, parsed.data.directoryName);
+        if (parsed.data.kind === 'session.create')
+            await state.journal.exclusive(`session:${parsed.data.sessionId}`, accept);
+        else if (parsed.data.kind === 'terminal.create') {
+            const terminalId = typeof asRecord(parsed.data.payload).terminalId === 'string'
+                ? String(asRecord(parsed.data.payload).terminalId).trim()
+                : '';
+            if (terminalId)
+                await state.journal.exclusive(`terminal:${terminalId}`, accept);
+            else
+                await accept();
+        }
         else
             await accept();
-    }
+    };
+    // Production admission and maintenance use this same lock before checking durable occupancy.
+    if (mutation && state.config.workspaceMode === 'multi')
+        await state.journal.exclusive(`directory:${parsed.data.workspaceId}:${parsed.data.directoryName ?? 'basic'}`, acceptBound);
     else
-        await accept();
+        await acceptBound();
 }
 async function writeGitRead(state, response, read) {
     if (writeDestroyed(state, response))
@@ -638,13 +717,13 @@ async function handleSessionHistory(state, response, workspaceId, sessionId) {
     }
     writeJson(response, 200, body.data);
 }
-async function readObservedParameters(state, workspaceId) {
-    const root = await workspaceRoot(state, workspaceId);
-    const scope = revisionScope(state, workspaceId);
+async function readObservedParameters(state, workspaceId, directoryName = 'basic') {
+    const root = await workspaceRoot(state, workspaceId, directoryName);
+    const scope = revisionScope(state, workspaceId, directoryName);
     const first = await readWorkspaceParameters(root, state.journal.fileRevisions(scope));
     for (const path of [first.schemaPath, first.dataPath]) {
         if (path)
-            await withObservedFile(state, workspaceId, path, async () => undefined);
+            await withObservedFile(state, workspaceId, path, async () => undefined, directoryName);
     }
     return readWorkspaceParameters(root, state.journal.fileRevisions(scope));
 }

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

@@ -1,3 +1,4 @@
+import { productionDirectoryBusy } from '../production/controller.js';
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import { lstat } from 'node:fs/promises';
@@ -59,6 +60,10 @@ export class TerminalHost {
             rejectUpgrade(socket, 404, { error: 'terminal_not_found' });
             return;
         }
+        if (await productionDirectoryBusy(this.state, terminal.workspaceId, terminal.directoryName)) {
+            rejectUpgrade(socket, 409, { error: 'batch_workspace_readonly' });
+            return;
+        }
         if (terminal.status === 'destroyed') {
             rejectUpgrade(socket, 409, runtimeError('capability_unavailable', 'terminal_destroyed'));
             return;
@@ -258,7 +263,7 @@ function exitFrame(session) {
     };
 }
 async function terminalDirectory(state, terminal) {
-    const root = await workspaceRoot(state, terminal.workspaceId);
+    const root = await workspaceRoot(state, terminal.workspaceId, terminal.directoryName);
     if (!terminal.cwd)
         return root;
     const resolved = await resolveWorkspaceFile(root, terminal.cwd);

package/dist/workspace-runtime/workspaces/batch-commit.js

@@ -0,0 +1,142 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, open, realpath, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, sep } from 'node:path';
+import { promisify } from 'node:util';
+import { batchCommitSourceVersion } from '@playcraft/common/cloud-workspace/runtime';
+import { validateProjectSkillsSnapshot } from '@playcraft/common/project-skills';
+const execute = promisify(execFile);
+const ID = /^[A-Za-z0-9_-]{1,128}$/;
+const COMMIT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const PRIVATE_NAMES = new Set([
+    '.ssh', '.aws', '.azure', '.gnupg', '.codex', '.npm', '.pnpm-store', '.config',
+    '.npmrc', '.yarnrc', '.yarnrc.yml', '.netrc', '.git-credentials', 'credentials.json',
+    'credentials', 'secrets', 'id_rsa', 'id_ed25519', 'settings.local.json',
+]);
+const DEPENDENCY_LOCKS = ['pnpm-lock.yaml', 'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'bun.lock', 'bun.lockb'];
+const SKILLS_DECLARATION = '.playcraft/skills.json';
+const SKILLS_LOCK = '.playcraft/skills.lock.json';
+const sha256 = (body) => createHash('sha256').update(body).digest('hex');
+async function git(root, args, encoding = 'utf8') {
+    const { stdout } = await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root, ...args], {
+        timeout: 90_000, maxBuffer: 64 * 1024 * 1024, encoding: 'buffer',
+        env: { PATH: process.env.PATH, HOME: root, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
+    });
+    return encoding === 'utf8' ? Buffer.from(stdout.toString('utf8').trim()) : stdout;
+}
+function assertSource(source) {
+    if (!ID.test(source.workspaceId) || !isAbsolute(source.root))
+        throw new Error('batch_snapshot_scope_invalid');
+}
+function engineeringPath(path) {
+    return !path.split('/').some((name) => PRIVATE_NAMES.has(name) || /^\.env(?:$|\.)/.test(name) || /\.(?:pem|key|p12|pfx)$/.test(name));
+}
+function lockedArtifacts(declaration, lock) {
+    const snapshot = validateProjectSkillsSnapshot(JSON.parse(declaration.toString('utf8')), JSON.parse(lock.toString('utf8')));
+    return snapshot.lock.entries.map((entry) => `.playcraft/skill-artifacts/${entry.revision.artifactHash}.tar.gz`);
+}
+function inside(root, path) {
+    const rel = relative(root, path);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+/** Locked skill archives are kept out of Git; each one is named by the hash of its exact bytes. */
+async function readArtifact(root, path) {
+    const full = join(root, ...path.split('/'));
+    if (!inside(root, await realpath(dirname(full)).catch(() => '')))
+        throw new Error('batch_snapshot_skill_artifact_missing');
+    const handle = await open(full, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => undefined);
+    if (!handle)
+        throw new Error('batch_snapshot_skill_artifact_missing');
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new Error('batch_snapshot_skill_artifact_missing');
+        const body = await handle.readFile();
+        if (sha256(body) !== path.slice(path.lastIndexOf('/') + 1, -'.tar.gz'.length))
+            throw new Error('batch_snapshot_skill_artifact_missing');
+        return body;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function treeChecksum(root, commitHash) {
+    const listing = await git(root, ['ls-tree', '-r', '--full-tree', '-z', commitHash], 'buffer');
+    const paths = listing.toString('utf8').split('\0').filter(Boolean).map((line) => line.slice(line.indexOf('\t') + 1));
+    return { checksum: sha256(listing), paths };
+}
+/**
+ * Freezes a commit of `basic` as batch input. The commit is already saved by Git, so later edits to
+ * `basic` never reach the batch; nothing is copied to separate storage. A commit is accepted only
+ * when it carries the dependency lock and skill lock its build needs and no credential files.
+ */
+export async function freezeBatchCommit(input) {
+    assertSource(input.source);
+    if (!COMMIT.test(input.commitHash) || !ID.test(input.snapshotId))
+        throw new Error('batch_snapshot_commit_required');
+    const root = await realpath(input.source.root);
+    const resolved = (await git(root, ['rev-parse', '--verify', '--quiet', `${input.commitHash}^{commit}`]).catch(() => Buffer.from(''))).toString();
+    if (resolved !== input.commitHash)
+        throw new Error('batch_snapshot_commit_required');
+    const { checksum, paths } = await treeChecksum(root, input.commitHash);
+    if (paths.some((path) => !engineeringPath(path)))
+        throw new Error('batch_snapshot_path_invalid');
+    const tracked = new Set(paths);
+    if (!tracked.has('package.json') || !DEPENDENCY_LOCKS.some((path) => tracked.has(path)))
+        throw new Error('batch_snapshot_dependency_lock_required');
+    if (!tracked.has(SKILLS_DECLARATION) || !tracked.has(SKILLS_LOCK))
+        throw new Error('batch_snapshot_skills_lock_required');
+    const declaration = await git(root, ['show', `${input.commitHash}:${SKILLS_DECLARATION}`], 'buffer');
+    const lock = await git(root, ['show', `${input.commitHash}:${SKILLS_LOCK}`], 'buffer');
+    for (const path of lockedArtifacts(declaration, lock))
+        if (!tracked.has(path))
+            await readArtifact(root, path);
+    const committedAt = (await git(root, ['show', '-s', '--format=%cI', input.commitHash])).toString();
+    return {
+        snapshotId: input.snapshotId, sourceWorkspaceId: input.source.workspaceId, commitHash: input.commitHash, checksum,
+        sourceVersion: batchCommitSourceVersion(input.commitHash), skillLockDigest: sha256(lock),
+        frozenAt: new Date(committedAt).toISOString(),
+    };
+}
+/**
+ * Checks the frozen commit out into a new private directory and adds the locked skill archives. A
+ * pre-existing destination is never reused, and the checkout must still match the frozen checksum.
+ */
+export async function checkoutBatchCommit(input) {
+    assertSource(input.source);
+    if (!isAbsolute(input.destination) || !COMMIT.test(input.frozen.commitHash))
+        throw new Error('batch_snapshot_scope_invalid');
+    if (input.frozen.sourceWorkspaceId !== input.source.workspaceId)
+        throw new Error('batch_snapshot_identity_mismatch');
+    if (await lstat(input.destination).catch(() => undefined))
+        throw new Error('batch_snapshot_destination_exists');
+    const root = await realpath(input.source.root);
+    const { checksum } = await treeChecksum(root, input.frozen.commitHash);
+    if (checksum !== input.frozen.checksum)
+        throw new Error('batch_snapshot_identity_mismatch');
+    await mkdir(dirname(input.destination), { recursive: true });
+    try {
+        await execute('git', ['-c', 'core.hooksPath=/dev/null', 'clone', '--local', '--no-hardlinks', '--no-checkout', '--', root, input.destination], {
+            timeout: 90_000, maxBuffer: 1024 * 1024,
+            env: { PATH: process.env.PATH, HOME: dirname(input.destination), GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
+        });
+        await git(input.destination, ['checkout', '--detach', input.frozen.commitHash]);
+        const lock = await git(input.destination, ['show', `${input.frozen.commitHash}:${SKILLS_LOCK}`], 'buffer');
+        if (sha256(lock) !== input.frozen.skillLockDigest)
+            throw new Error('batch_snapshot_identity_mismatch');
+        const declaration = await git(input.destination, ['show', `${input.frozen.commitHash}:${SKILLS_DECLARATION}`], 'buffer');
+        for (const path of lockedArtifacts(declaration, lock)) {
+            const target = join(input.destination, ...path.split('/'));
+            if (await lstat(target).catch(() => undefined))
+                continue;
+            const body = await readArtifact(root, path);
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, body, { flag: 'wx', mode: 0o600 });
+        }
+    }
+    catch (cause) {
+        await rm(input.destination, { recursive: true, force: true });
+        throw cause;
+    }
+}

package/dist/workspace-runtime/workspaces/dependencies.js

@@ -11,11 +11,11 @@ const LOG_TAIL_MAX_CHARS = 8_000;
 const WRITE_PREFIX = 'dependencies-';
 const SHARE_WAIT_MS = 60_000;
 /**
- * Projects are managed with pnpm. It follows pnpm-lock.yaml when the lockfile matches, never
+ * Projects are managed with pnpm. Frozen installation preserves pnpm-lock.yaml, never
  * prompts, and writes plain lines to the log. Package scripts run: the workspace is the user's own
  * sandbox and the install runs as the development user.
  */
-const INSTALL_COMMAND = 'pnpm install --reporter=append-only --config.confirm-modules-purge=false';
+const INSTALL_COMMAND = 'pnpm install --frozen-lockfile --store-dir /var/cache/playcraft/pnpm-store --reporter=append-only --config.confirm-modules-purge=false';
 /** Installs whenever there is a package.json; the hash says whether a finished install is current. */
 export async function planInstall(root) {
     const manifest = await readOptional(join(root, 'package.json'));
@@ -159,7 +159,9 @@ async function installOnce(state, workspaceId, root) {
  */
 async function runInstall(state, workspaceId, root) {
     // Tests replace the install; a real registry is never reached from them.
-    const planned = process.env.PLAYCRAFT_DEPENDENCY_INSTALL_COMMAND || INSTALL_COMMAND;
+    const store = process.env.PLAYCRAFT_PNPM_STORE ?? (process.platform === 'linux' ? '/var/cache/playcraft/pnpm-store' : join(state.config.stateDir, 'pnpm-store'));
+    const quotedStore = `'${store.replaceAll("'", "'\\''")}'`;
+    const planned = process.env.PLAYCRAFT_DEPENDENCY_INSTALL_COMMAND || INSTALL_COMMAND.replace('/var/cache/playcraft/pnpm-store', quotedStore);
     const logDir = join(state.config.stateDir, 'dependency-logs');
     await mkdir(logDir, { recursive: true, mode: 0o700 });
     const logPath = join(logDir, `${workspaceId}.log`);

package/dist/workspace-runtime/workspaces/directories.js

@@ -0,0 +1,106 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { lstat, rename, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { workspaceDirectoryRegistrationSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceContainerRoot, workspaceRoot, WorkspaceContextError } from './registry.js';
+import { openDirectoryToDevelopment } from './directory-access.js';
+import { prepareWorkspaceCheckout } from './prepare.js';
+import { readDependencies, scheduleDependencyInstall } from './dependencies.js';
+import { revisionScope } from './registry.js';
+import { ensureWorkspaceSkills } from './skills.js';
+const execute = promisify(execFile);
+/** Trusted Runtime registration clones an immutable local commit; it never follows basic's current branch head. */
+export async function registerWorkspaceDirectory(state, input, leaseFence) {
+    const directory = workspaceDirectoryRegistrationSchema.parse(input);
+    if (directory.directoryName === 'basic')
+        throw new WorkspaceContextError('workspace_directory_binding_conflict');
+    return state.journal.exclusive(`directory:${directory.workspaceId}:${directory.directoryName}`, async () => {
+        if (state.journal.destroyed())
+            throw new WorkspaceContextError('runtime_destroyed');
+        if (leaseFence < state.acceptedLeaseFence)
+            throw new WorkspaceContextError('stale_lease');
+        const binding = state.journal.getWorkspace(directory.workspaceId);
+        if (!binding || !binding.repositoryUrl)
+            throw new WorkspaceContextError('workspace_not_registered');
+        const existing = binding.directories?.find(item => item.directoryName === directory.directoryName);
+        if (existing && (existing.remixId !== directory.remixId || existing.branchName !== directory.branchName || (existing.sourceCommit !== undefined && existing.sourceCommit !== directory.sourceCommit)))
+            throw new WorkspaceContextError('workspace_directory_binding_conflict');
+        const parent = await workspaceContainerRoot(state, directory.workspaceId);
+        const root = join(parent, directory.directoryName);
+        const git = async (cwd, ...args) => (await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'credential.helper=', '-c', 'core.fsmonitor=false', '-C', cwd, ...args], {
+            timeout: 90_000, maxBuffer: 1024 * 1024,
+            env: { PATH: process.env.PATH, HOME: state.config.stateDir, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
+        })).stdout.trim();
+        const stat = await lstat(root).catch(() => undefined);
+        if (stat) {
+            if (!stat.isDirectory() || stat.isSymbolicLink() || await git(root, 'symbolic-ref', '--short', 'HEAD') !== directory.branchName || await git(root, 'config', '--get', 'remote.origin.url') !== binding.repositoryUrl)
+                throw new WorkspaceContextError('workspace_checkout_mismatch');
+        }
+        else {
+            if (existing && existing.status !== 'pending')
+                throw new WorkspaceContextError('workspace_recovery_required');
+            if (!directory.sourceCommit)
+                throw new WorkspaceContextError('workspace_directory_source_commit_required');
+            const source = await workspaceRoot(state, directory.workspaceId, 'basic');
+            await git(source, 'cat-file', '-e', `${directory.sourceCommit}^{commit}`);
+            const staging = join(parent, `.directory-${randomUUID()}`);
+            try {
+                await execute('git', ['-c', 'core.hooksPath=/dev/null', 'clone', '--local', '--no-hardlinks', '--no-checkout', '--', source, staging], { timeout: 90_000, maxBuffer: 1024 * 1024 });
+                await git(staging, 'checkout', '-b', directory.branchName, directory.sourceCommit);
+                await git(staging, 'remote', 'set-url', 'origin', binding.repositoryUrl);
+                await git(staging, 'config', 'user.name', 'PlayCraft');
+                await git(staging, 'config', 'user.email', 'playcraft@localhost');
+                await ensureWorkspaceSkills(staging, join(state.config.stateDir, 'skill-artifacts'));
+                if (leaseFence < state.acceptedLeaseFence)
+                    throw new WorkspaceContextError('stale_lease');
+                await rename(staging, root);
+            }
+            finally {
+                await rm(staging, { recursive: true, force: true });
+            }
+        }
+        await openDirectoryToDevelopment(root, (await lstat(state.config.workspaceRoot)).gid);
+        state.acceptedLeaseFence = Math.max(state.acceptedLeaseFence, leaseFence);
+        await state.journal.setAcceptedLeaseFence(state.acceptedLeaseFence);
+        await state.journal.putWorkspace({ ...binding, directories: [...(binding.directories ?? []).filter(item => item.directoryName !== directory.directoryName), { ...directory, status: 'ready' }] });
+        if (state.gitCredentials)
+            await state.gitCredentials.configure(binding, await state.gitCredentials.prepareDirectory(directory.workspaceId, directory.directoryName), directory.directoryName);
+        return directory;
+    });
+}
+/** A reclaimed checkout recovers its existing remote branch; no new variant or moving basic head is used. */
+export async function restoreWorkspaceDirectory(state, workspaceId, directoryName = 'basic') {
+    if (directoryName === 'root')
+        return;
+    await state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
+        const binding = state.journal.getWorkspace(workspaceId);
+        const directory = binding?.directories?.find(item => item.directoryName === directoryName);
+        if (!binding || directory?.status !== 'reclaimed')
+            return;
+        if (binding.targetKind === 'standalone' || !state.gitCredentials)
+            throw new WorkspaceContextError('workspace_recovery_required');
+        const preparation = await state.gitCredentials.prepareDirectory(workspaceId, directoryName);
+        const { pendingFork: _pendingFork, directories: _directories, ...base } = binding;
+        const target = directoryName === 'basic' ? base : { ...base, targetKind: 'remix', remixId: directory.remixId, branchName: directory.branchName };
+        const root = join(state.config.workspaceRoot, workspaceId, directoryName);
+        if (!await lstat(root).catch(() => undefined))
+            await prepareWorkspaceCheckout(state, target, preparation, state.acceptedLeaseFence, directoryName, true);
+        await ensureWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'));
+        await openDirectoryToDevelopment(root, (await lstat(state.config.workspaceRoot)).gid);
+        await state.journal.putWorkspace({ ...binding, directories: binding.directories?.map(item => item.directoryName === directoryName ? { ...item, status: 'ready' } : item) });
+        try {
+            await state.gitCredentials.configure(binding, preparation, directoryName);
+            const scope = revisionScope(state, workspaceId, directoryName);
+            await scheduleDependencyInstall(state, scope, root);
+            if (!['ready', 'none'].includes(readDependencies(state, scope).status))
+                throw new WorkspaceContextError('workspace_directory_restore_dependencies_failed');
+        }
+        catch (error) {
+            const current = state.journal.getWorkspace(workspaceId);
+            await state.journal.putWorkspace({ ...current, directories: current.directories?.map(item => item.directoryName === directoryName ? { ...item, status: 'reclaimed' } : item) });
+            throw error;
+        }
+    });
+}

package/dist/workspace-runtime/workspaces/directory-access.js

@@ -0,0 +1,20 @@
+import { chmod, chown, lstat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The sandbox development group can edit engine directories. Symlinks never grant access outside the tree. */
+export async function openDirectoryToDevelopment(root, groupId) {
+    const visit = async (path) => {
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink())
+            return;
+        if (stat.gid !== groupId)
+            await chown(path, stat.uid, groupId);
+        if (stat.isDirectory()) {
+            await chmod(path, (stat.mode & 0o777) | 0o2770);
+            for (const entry of await readdir(path))
+                await visit(join(path, entry));
+        }
+        else if (stat.isFile())
+            await chmod(path, (stat.mode & 0o777) | 0o660);
+    };
+    await visit(root);
+}