@playcraft/cli 0.1.30 → 0.1.32

package/dist/workspace-runtime/workspaces/attachment-content.js

@@ -4,6 +4,8 @@ import { extname } from 'node:path';
 import { pipeline } from 'node:stream/promises';
 import { attachmentIdsSchema, attachmentUploadSchema, WORKSPACE_ATTACHMENT_MAX_BYTES, WORKSPACE_USER_UPLOADS_DIRECTORY, WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES, } from '@playcraft/common/cloud-workspace/runtime';
 import { artifactMime, artifactPath } from './artifact-files.js';
+import { openLibraryAttachmentFile, readLibraryAttachmentMetadata } from './library-attachments.js';
+import { openWorkspaceDirectoryFile, readWorkspaceDirectoryMetadata } from './directory-attachments.js';
 const additionalMediaTypes = {
     '.aac': 'audio/aac', '.opus': 'audio/ogg', '.oga': 'audio/ogg', '.aif': 'audio/aiff', '.aiff': 'audio/aiff',
     '.bmp': 'image/bmp', '.ico': 'image/vnd.microsoft.icon', '.heic': 'image/heic', '.heif': 'image/heif',
@@ -24,13 +26,13 @@ function attachmentRange(header, size) {
     const end = first === undefined ? size - 1 : Math.min(last ?? size - 1, size - 1);
     return start >= size || start > end ? null : { start, end };
 }
-async function openAttachment(root, id) {
+async function openAttachment(root, id, filePath) {
     const metadataPath = await artifactPath(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata/${id}.json`);
     const metadataFile = await open(metadataPath, constants.O_RDONLY | constants.O_NOFOLLOW);
     let metadata;
     try {
         const stat = await metadataFile.stat();
-        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 8192)
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
             throw new Error('attachment_unavailable');
         metadata = JSON.parse(await metadataFile.readFile('utf8'));
         if (metadata.id !== id || !attachmentUploadSchema.shape.name.safeParse(metadata.name).success)
@@ -39,6 +41,16 @@ async function openAttachment(root, id) {
     finally {
         await metadataFile.close();
     }
+    if (metadata.origin?.kind === 'asset-library') {
+        const library = await readLibraryAttachmentMetadata(root, id);
+        return openLibraryAttachmentFile(root, library, filePath);
+    }
+    if (metadata.kind === 'directory') {
+        const directory = await readWorkspaceDirectoryMetadata(root, id);
+        return openWorkspaceDirectoryFile(root, directory, filePath);
+    }
+    if (filePath !== undefined)
+        throw new Error('attachment_unavailable');
     const path = await artifactPath(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}/${metadata.name}`);
     const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
@@ -56,7 +68,7 @@ async function openAttachment(root, id) {
     }
 }
 /** Serve only registered references; no caller-supplied file paths reach the filesystem. */
-export async function serveWorkspaceAttachment(root, attachmentId, request, response) {
+export async function serveWorkspaceAttachment(root, attachmentId, request, response, filePath) {
     if (!attachmentIdsSchema.safeParse([attachmentId]).success) {
         response.writeHead(400, { 'content-type': 'application/json', 'cache-control': 'no-store' });
         response.end(JSON.stringify({ error: 'invalid_attachment' }));
@@ -64,7 +76,7 @@ export async function serveWorkspaceAttachment(root, attachmentId, request, resp
     }
     let content;
     try {
-        content = await openAttachment(root, attachmentId);
+        content = await openAttachment(root, attachmentId, filePath);
     }
     catch {
         response.writeHead(404, { 'content-type': 'application/json', 'cache-control': 'no-store' });

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

@@ -6,6 +6,8 @@ import { WORKSPACE_USER_UPLOADS_DIRECTORY, attachmentIdsSchema, attachmentUpload
 import { NativePreparationError } from '../codex/native-adapter.js';
 import { excludeFromGit } from './dependencies.js';
 import { hashAttachment, probeAttachmentVideo } from './video-attachments.js';
+import { resolveLibraryAttachment } from './library-attachments.js';
+import { resolveWorkspaceDirectoryAttachment } from './directory-attachments.js';
 async function attachmentRoot(root) {
     // Reject redirected upload directories, including symlinks that stay inside the workspace.
     let directory = root;
@@ -136,13 +138,17 @@ export async function resolveWorkspaceAttachments(root, input) {
             let metadata;
             try {
                 const stat = await metadataHandle.stat();
-                if (!stat.isFile() || stat.nlink !== 1 || stat.size > 8192)
+                if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
                     throw new Error('invalid_attachment');
                 metadata = JSON.parse(await metadataHandle.readFile('utf8'));
             }
             finally {
                 await metadataHandle.close();
             }
+            if (metadata.origin?.kind === 'asset-library')
+                return resolveLibraryAttachment(root, id);
+            if (metadata.kind === 'directory')
+                return resolveWorkspaceDirectoryAttachment(root, id);
             attachmentUploadSchema.shape.name.parse(metadata.name);
             if (metadata.id !== id)
                 throw new Error('invalid_attachment');

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

@@ -11,6 +11,7 @@ import { readDependencies, scheduleDependencyInstall } from './dependencies.js';
 import { revisionScope } from './registry.js';
 import { ensureWorkspaceSkills } from './skills.js';
 import { checkoutBatchCommit, freezeBatchCommit } from './batch-commit.js';
+import { ensureWorkspaceArtifactInstructions } from './instructions.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, sourceDirectoryName) {
@@ -68,12 +69,16 @@ export async function registerWorkspaceDirectory(state, input, leaseFence, sourc
                 await rm(staging, { recursive: true, force: true });
             }
         }
+        await ensureWorkspaceArtifactInstructions(root);
         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' }] });
+        await state.journal.exclusive(`workspace:${directory.workspaceId}`, async () => {
+            state.acceptedLeaseFence = Math.max(state.acceptedLeaseFence, leaseFence);
+            await state.journal.setAcceptedLeaseFence(state.acceptedLeaseFence);
+            const latest = state.journal.getWorkspace(directory.workspaceId) ?? binding;
+            await state.journal.putWorkspace({ ...latest, directories: [...(latest.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);
+            await state.gitCredentials.configure(state.journal.getWorkspace(directory.workspaceId) ?? binding, await state.gitCredentials.prepareDirectory(directory.workspaceId, directory.directoryName), directory.directoryName);
         return directory;
     });
 }
@@ -84,8 +89,12 @@ export async function restoreWorkspaceDirectory(state, workspaceId, directoryNam
     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')
+        if (!binding)
             return;
+        if (directory?.status !== 'reclaimed') {
+            await ensureWorkspaceArtifactInstructions(await workspaceRoot(state, workspaceId, directoryName));
+            return;
+        }
         if (binding.targetKind === 'standalone' || !state.gitCredentials)
             throw new WorkspaceContextError('workspace_recovery_required');
         const preparation = await state.gitCredentials.prepareDirectory(workspaceId, directoryName);
@@ -95,6 +104,7 @@ export async function restoreWorkspaceDirectory(state, workspaceId, directoryNam
         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 ensureWorkspaceArtifactInstructions(root);
         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 {

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

@@ -11,18 +11,26 @@ export async function grantWorkspaceTraversal(root, groupId) {
 }
 /** The sandbox development group can edit engine directories. Symlinks never grant access outside the tree. */
 export async function openDirectoryToDevelopment(root, groupId) {
+    const currentUid = typeof process.getuid === 'function' ? process.getuid() : undefined;
     const visit = async (path) => {
         const stat = await lstat(path);
         if (stat.isSymbolicLink())
             return;
-        if (stat.gid !== groupId)
+        const canModify = currentUid === undefined || currentUid === 0 || stat.uid === currentUid;
+        if (canModify && 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))
+            if (canModify)
+                await chmod(path, (stat.mode & 0o777) | 0o2770);
+            const entries = await readdir(path).catch(error => {
+                if (!canModify && error.code === 'EACCES')
+                    return [];
+                throw error;
+            });
+            for (const entry of entries)
                 await visit(join(path, entry));
         }
-        else if (stat.isFile())
+        else if (stat.isFile() && canModify)
             await chmod(path, (stat.mode & 0o777) | 0o660);
     };
     await visit(root);

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

@@ -0,0 +1,245 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { attachmentIdsSchema, WORKSPACE_USER_UPLOADS_DIRECTORY, WORKSPACE_ATTACHMENT_MAX_BYTES, WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES, WORKSPACE_DIRECTORY_ATTACHMENT_MAX_BYTES, workspaceAttachmentSchema, workspaceDirectoryAttachmentUploadSchema, workspaceDirectoryAttachmentFilePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactMime } from './artifact-files.js';
+import { excludeFromGit } from './dependencies.js';
+import { hashAttachment, probeAttachmentVideo } from './video-attachments.js';
+const stagingPath = `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.directory-uploads`;
+const locks = new Map();
+async function withUploadLock(root, id, action) {
+    const key = `${root}\0${id}`;
+    const previous = locks.get(key) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(action);
+    locks.set(key, current);
+    try {
+        return await current;
+    }
+    finally {
+        if (locks.get(key) === current)
+            locks.delete(key);
+    }
+}
+async function safeDirectory(root, relative, create = false) {
+    let directory = root;
+    for (const part of relative.split('/')) {
+        directory = join(directory, part);
+        if (create)
+            await mkdir(directory, { mode: 0o755 }).catch((error) => {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            });
+        if (!(await lstat(directory)).isDirectory())
+            throw new Error('invalid_attachment');
+    }
+    return directory;
+}
+function validId(id) {
+    if (!attachmentIdsSchema.safeParse([id]).success)
+        throw new Error('invalid_attachment');
+}
+async function readManifest(root, id) {
+    validId(id);
+    const stage = await safeDirectory(root, `${stagingPath}/${id}`);
+    const handle = await open(join(stage, 'manifest.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('invalid_attachment');
+        return workspaceDirectoryAttachmentUploadSchema.parse(JSON.parse(await handle.readFile('utf8')));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function beginWorkspaceDirectoryAttachment(root, body) {
+    const manifest = workspaceDirectoryAttachmentUploadSchema.parse(body);
+    await excludeFromGit(root, `/${WORKSPACE_USER_UPLOADS_DIRECTORY}/`);
+    const staging = await safeDirectory(root, stagingPath, true);
+    const id = randomUUID();
+    const stage = join(staging, id);
+    await mkdir(stage, { mode: 0o755 });
+    try {
+        await mkdir(join(stage, 'data'), { mode: 0o755 });
+        await mkdir(join(stage, 'data', manifest.name), { mode: 0o755 });
+        await writeFile(join(stage, 'manifest.json'), JSON.stringify(manifest), { flag: 'wx', mode: 0o644 });
+        return { uploadId: id };
+    }
+    catch (error) {
+        await rm(stage, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** Each member is streamed and created exclusively; no completed member can be overwritten. */
+export async function uploadWorkspaceDirectoryFile(root, id, path, request) {
+    return withUploadLock(root, id, async () => {
+        workspaceDirectoryAttachmentFilePathSchema.parse(path);
+        const manifest = await readManifest(root, id);
+        const member = manifest.files.find(file => file.path === path);
+        if (!member)
+            throw new Error('invalid_attachment');
+        const length = request.headers['content-length'];
+        if (length !== undefined && (!/^\d+$/.test(length) || Number(length) !== member.size))
+            throw new Error('invalid_attachment');
+        const relative = `${stagingPath}/${id}/data/${manifest.name}/${path}`;
+        await safeDirectory(root, dirname(relative), true);
+        const handle = await open(join(root, relative), constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o644);
+        try {
+            let size = 0;
+            for await (const chunk of request) {
+                const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                if (size + bytes.length > member.size)
+                    throw new Error('invalid_attachment');
+                let offset = 0;
+                while (offset < bytes.length)
+                    offset += (await handle.write(bytes, offset, bytes.length - offset, size + offset)).bytesWritten;
+                size += bytes.length;
+            }
+            if (size !== member.size)
+                throw new Error('invalid_attachment');
+            await handle.sync();
+            if (member.mimeType.startsWith('video/')) {
+                const media = await probeAttachmentVideo(handle);
+                if (media.mimeType !== member.mimeType && !(member.mimeType === 'video/quicktime' && media.mimeType === 'video/mp4'))
+                    throw new Error('invalid_attachment');
+            }
+            return { path, size };
+        }
+        catch (error) {
+            await rm(join(root, relative), { force: true });
+            throw error;
+        }
+        finally {
+            await handle.close();
+        }
+    });
+}
+async function assertExactFiles(directory, expected, prefix = '') {
+    for (const name of await readdir(directory)) {
+        const relative = prefix ? `${prefix}/${name}` : name;
+        const path = join(directory, name);
+        const stat = await lstat(path);
+        if (stat.isDirectory())
+            await assertExactFiles(path, expected, relative);
+        else if (!stat.isFile() || stat.nlink !== 1 || !expected.delete(relative))
+            throw new Error('invalid_attachment');
+    }
+    if (!prefix && expected.size)
+        throw new Error('invalid_attachment');
+}
+async function directoryFiles(root, relative, manifest) {
+    const directory = await safeDirectory(root, relative);
+    await assertExactFiles(directory, new Set(manifest.files.map(file => file.path)));
+    const files = [];
+    for (const file of manifest.files) {
+        await safeDirectory(directory, dirname(file.path) === '.' ? '' : dirname(file.path));
+        const handle = await open(join(directory, file.path), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size !== file.size)
+                throw new Error('invalid_attachment');
+            const media = file.mimeType.startsWith('video/') ? await probeAttachmentVideo(handle) : undefined;
+            if (media && media.mimeType !== file.mimeType && !(file.mimeType === 'video/quicktime' && media.mimeType === 'video/mp4'))
+                throw new Error('invalid_attachment');
+            const inferred = artifactMime(file.path);
+            files.push({ path: file.path, size: stat.size, sha256: await hashAttachment(handle),
+                mimeType: media?.mimeType ?? (inferred === 'application/octet-stream' ? file.mimeType : inferred) });
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    return files;
+}
+export async function completeWorkspaceDirectoryAttachment(root, id) {
+    return withUploadLock(root, id, async () => {
+        const manifest = await readManifest(root, id);
+        const stage = await safeDirectory(root, `${stagingPath}/${id}`);
+        const files = await directoryFiles(root, `${stagingPath}/${id}/data/${manifest.name}`, manifest);
+        const metadata = await safeDirectory(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata`, true);
+        const uploads = await safeDirectory(root, WORKSPACE_USER_UPLOADS_DIRECTORY);
+        const attachment = { id, name: manifest.name, kind: 'directory',
+            size: files.reduce((size, file) => size + file.size, 0), mimeType: 'application/vnd.playcraft.directory',
+            path: `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}/${manifest.name}`, files };
+        workspaceAttachmentSchema.parse(attachment);
+        const target = join(uploads, id);
+        await mkdir(target, { mode: 0o755 });
+        try {
+            await rename(join(stage, 'data', manifest.name), join(target, manifest.name));
+            await writeFile(join(metadata, `${id}.json`), JSON.stringify(attachment), { flag: 'wx', mode: 0o644 });
+        }
+        catch (error) {
+            await rm(target, { recursive: true, force: true });
+            throw error;
+        }
+        await rm(stage, { recursive: true, force: true });
+        return attachment;
+    });
+}
+export async function cancelWorkspaceDirectoryAttachment(root, id) {
+    validId(id);
+    return withUploadLock(root, id, async () => {
+        const parent = await safeDirectory(root, stagingPath);
+        const stage = join(parent, id);
+        try {
+            if (!(await lstat(stage)).isDirectory())
+                throw new Error('invalid_attachment');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await rm(stage, { recursive: true, force: true });
+        return { uploadId: id, cancelled: true };
+    });
+}
+export async function readWorkspaceDirectoryMetadata(root, id) {
+    validId(id);
+    const metadata = await safeDirectory(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata`);
+    const handle = await open(join(metadata, `${id}.json`), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+            throw new Error('invalid_attachment');
+        const attachment = workspaceAttachmentSchema.parse(JSON.parse(await handle.readFile('utf8')));
+        if (attachment.id !== id || attachment.kind !== 'directory' || attachment.origin || !attachment.files ||
+            attachment.path !== `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}/${attachment.name}` || attachment.mimeType !== 'application/vnd.playcraft.directory')
+            throw new Error('invalid_attachment');
+        workspaceDirectoryAttachmentUploadSchema.parse({ name: attachment.name, files: attachment.files.map(({ sha256: _digest, ...file }) => file) });
+        if (attachment.size !== attachment.files.reduce((size, file) => size + file.size, 0) || attachment.size > WORKSPACE_DIRECTORY_ATTACHMENT_MAX_BYTES)
+            throw new Error('invalid_attachment');
+        return attachment;
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function openWorkspaceDirectoryFile(root, attachment, path) {
+    workspaceDirectoryAttachmentFilePathSchema.parse(path);
+    const file = attachment.files?.find(file => file.path === path);
+    if (!file || !attachment.path)
+        throw new Error('attachment_unavailable');
+    const directory = await safeDirectory(root, attachment.path);
+    if (dirname(file.path) !== '.')
+        await safeDirectory(directory, dirname(file.path));
+    const handle = await open(join(directory, file.path), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        const limit = file.mimeType.startsWith('video/') ? WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES : WORKSPACE_ATTACHMENT_MAX_BYTES;
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size !== file.size || stat.size > limit || await hashAttachment(handle) !== file.sha256)
+            throw new Error('attachment_unavailable');
+        return { handle, name: file.path.split('/').at(-1), mimeType: file.mimeType, size: file.size };
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+export async function resolveWorkspaceDirectoryAttachment(root, id) {
+    const attachment = await readWorkspaceDirectoryMetadata(root, id);
+    const files = await directoryFiles(root, attachment.path, { name: attachment.name, files: attachment.files.map(({ sha256: _digest, ...file }) => file) });
+    if (files.some((file, index) => file.sha256 !== attachment.files[index].sha256 || file.mimeType !== attachment.files[index].mimeType))
+        throw new Error('attachment_unavailable');
+    return { ...attachment, path: join(root, attachment.path) };
+}

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

@@ -1,9 +1,10 @@
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { excludeFromGit } from './dependencies.js';
-import { lstat, readFile, realpath, stat, unlink } from 'node:fs/promises';
+import { copyFile, lstat, readFile, realpath, rm, stat, unlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
-import { WORKSPACE_FILE_CONTENT_MAX, gitDiffSchema, gitFileContentSchema, gitGraphSchema, gitStatusSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { TURN_CHANGED_FILES_MAX, WORKSPACE_FILE_CONTENT_MAX, gitDiffSchema, gitFileContentSchema, gitGraphSchema, gitStatusSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
 const GIT_DIFF_MAX_BYTES = 1024 * 1024;
 const GIT_PREFIX = [
     '-c',
@@ -63,14 +64,74 @@ export async function readWorkspaceGitStatus(root) {
         })),
     });
 }
+const SNAPSHOT_TIMEOUT_MS = 120_000;
 /**
- * One file as stored in the last commit or in the index. Reads the blob as is, without filters,
- * so the browser compares exactly what Git holds.
+ * Writes the work tree, as `git add -A` would stage it, to a tree object without touching the
+ * repository's own index or history. A copy of the index keeps its stat cache, so unchanged files
+ * are not hashed again. Ignored files and credential files are left out of the snapshot.
+ */
+export async function snapshotWorkspaceTree(root) {
+    const rootReal = await existingWorkspaceGit(root);
+    const env = { GIT_INDEX_FILE: join(rootReal, '.git', `playcraft-snapshot-${randomUUID()}.index`) };
+    const run = async (args) => {
+        const result = await runGitProcess(rootReal, [...GIT_PREFIX, `--git-dir=${join(rootReal, '.git')}`,
+            `--work-tree=${rootReal}`, ...args], SNAPSHOT_TIMEOUT_MS, env);
+        if (result.code !== 0)
+            throw new GitWorkspaceError('git_command_failed', result.stderr.trim() || `git_exit_${result.code}`);
+        return result.stdout;
+    };
+    try {
+        await copyFile(join(rootReal, '.git', 'index'), env.GIT_INDEX_FILE).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+        await run(['add', '-A']);
+        const credentials = (await run(['ls-files', '-z'])).split('\0').filter((path) => path && isCredentialFile(path));
+        if (credentials.length)
+            await run(['rm', '--cached', '--quiet', '--', ...credentials]);
+        return (await run(['write-tree'])).trim();
+    }
+    finally {
+        await rm(env.GIT_INDEX_FILE, { force: true });
+    }
+}
+/** Keeps a turn's snapshots from being pruned, so its changes stay readable after Git cleans up. */
+export async function retainTurnSnapshots(root, turnId, before, after) {
+    const rootReal = await existingWorkspaceGit(root);
+    const name = turnId.replace(/[^A-Za-z0-9_-]/g, '_');
+    await git(rootReal, ['update-ref', `refs/playcraft/turns/${name}/before`, before]);
+    await git(rootReal, ['update-ref', `refs/playcraft/turns/${name}/after`, after]);
+}
+/** The files that differ between two snapshot trees, with line counts for text files. */
+export async function diffWorkspaceTrees(root, before, after) {
+    const rootReal = await existingWorkspaceGit(root);
+    const diff = (format) => git(rootReal, ['diff-tree', '-r', '-z', '--no-renames', format, before, after], 60000);
+    const [statuses, counts] = await Promise.all([diff('--name-status'), diff('--numstat')]);
+    const lines = new Map();
+    for (const entry of counts.split('\0')) {
+        const match = /^(\d+|-)\t(\d+|-)\t(.+)$/s.exec(entry);
+        if (!match)
+            continue;
+        const binary = match[1] === '-';
+        lines.set(match[3], { added: binary ? 0 : Number(match[1]), removed: binary ? 0 : Number(match[2]), binary });
+    }
+    const parts = statuses.split('\0');
+    const files = [];
+    for (let index = 0; index + 1 < parts.length; index += 2) {
+        const status = parts[index] === 'A' ? 'added' : parts[index] === 'D' ? 'deleted' : 'modified';
+        const path = parts[index + 1];
+        files.push({ path, status, ...(lines.get(path) ?? { added: 0, removed: 0, binary: false }) });
+    }
+    return { files: files.slice(0, TURN_CHANGED_FILES_MAX), truncated: files.length > TURN_CHANGED_FILES_MAX };
+}
+/**
+ * One file as stored in the last commit, in the index or in a turn snapshot. Reads the blob as is,
+ * without filters, so the browser compares exactly what Git holds.
  */
 export async function readWorkspaceGitFile(root, path, ref) {
     const rootReal = await ensureWorkspaceGit(root);
     assertWorkspacePaths([path]);
-    const object = ref === 'HEAD' ? `HEAD:${path}` : `:${path}`;
+    const object = ref === 'INDEX' ? `:${path}` : `${ref}:${path}`;
     const absent = gitFileContentSchema.parse({ path, ref, exists: false, binary: false, content: '' });
     const size = await gitAllowFail(rootReal, ['cat-file', '-s', object]);
     if (size.code !== 0)
@@ -382,6 +443,14 @@ export async function ensureWorkspaceGit(root) {
     await excludeFromGit(rootReal, '/.tmp/user_uploads/');
     return rootReal;
 }
+/** Turn snapshots never create a repository; a directory without one simply has no turn changes. */
+async function existingWorkspaceGit(root) {
+    const rootReal = await realpath(root);
+    if (!(await gitMarkerExists(rootReal)))
+        throw new GitWorkspaceError('git_command_failed', 'not_a_repository');
+    await assertWorkspaceGitRoot(rootReal);
+    return rootReal;
+}
 async function gitMarkerExists(rootReal) {
     try {
         await stat(join(rootReal, '.git'));
@@ -481,9 +550,9 @@ function gitEnv() {
     env.GIT_TERMINAL_PROMPT = '0';
     return env;
 }
-function runGitProcess(cwd, args, timeoutMs) {
+function runGitProcess(cwd, args, timeoutMs, env) {
     return new Promise((resolve, reject) => {
-        const child = spawn('git', args, { cwd, env: gitEnv(), windowsHide: true });
+        const child = spawn('git', args, { cwd, env: { ...gitEnv(), ...env }, windowsHide: true });
         // Chunks are decoded together; a character split across two chunks would otherwise be corrupted.
         const stdout = [];
         const stderr = [];

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

@@ -0,0 +1,56 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, lstat, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveCliPackageRoot } from '../../scaffold/compose.js';
+const START = '<!-- playcraft:workspace-artifacts:start -->';
+const END = '<!-- playcraft:workspace-artifacts:end -->';
+/** Refresh only the platform-owned section; project and user instructions remain intact. */
+export async function ensureWorkspaceArtifactInstructions(root) {
+    const template = await readFile(join(resolveCliPackageRoot(), 'project-templates/empty/AGENTS.md'), 'utf8');
+    const start = template.indexOf(START), end = template.indexOf(END, start);
+    if (start < 0 || end < start)
+        throw new Error('workspace_instructions_invalid');
+    const section = template.slice(start, end + END.length);
+    const path = join(root, 'AGENTS.md');
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch(error => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    let previous = '', mode = 0o664;
+    try {
+        if (handle) {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
+                throw new Error('workspace_instructions_invalid');
+            mode = stat.mode & 0o777;
+            previous = await handle.readFile('utf8');
+        }
+    }
+    finally {
+        await handle?.close();
+    }
+    const existingStart = previous.indexOf(START), existingEnd = previous.indexOf(END);
+    if ((existingStart < 0) !== (existingEnd < 0) || existingEnd < existingStart ||
+        previous.indexOf(START, existingStart + START.length) >= 0 || previous.indexOf(END, existingEnd + END.length) >= 0)
+        throw new Error('workspace_instructions_invalid');
+    const next = existingStart >= 0
+        ? previous.slice(0, existingStart) + section + previous.slice(existingEnd + END.length)
+        : `${previous}${previous ? (previous.endsWith('\n') ? '\n' : '\n\n') : '# PlayCraft Workspace\n\n'}${section}\n`;
+    if (next === previous)
+        return;
+    const temporary = join(root, `.AGENTS.${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, next, { flag: 'wx', mode });
+        await chmod(temporary, mode);
+        const current = await lstat(path).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; });
+        if (current && (!current.isFile() || current.isSymbolicLink() || current.nlink !== 1))
+            throw new Error('workspace_instructions_invalid');
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}