@playcraft/cli 0.1.31 → 0.1.33

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

@@ -0,0 +1,268 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, open, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { WORKSPACE_USER_UPLOADS_DIRECTORY, WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES, WORKSPACE_ATTACHMENT_MAX_COUNT, workspaceAttachmentSchema, workspaceLibraryAttachmentUploadSchema, workspaceLibraryFilePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { excludeFromGit } from './dependencies.js';
+const METADATA_MAX_BYTES = 1024 * 1024;
+const locks = new Map();
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+async function safeDirectory(root, path, create = false) {
+    let directory = root;
+    for (const part of path.split('/').filter(Boolean)) {
+        directory = join(directory, part);
+        if (create)
+            await mkdir(directory, { mode: 0o755 }).catch((error) => {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            });
+        const stat = await lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('invalid_library_attachment');
+    }
+    return directory;
+}
+async function metadataDirectory(root, create = false) {
+    return safeDirectory(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata`, create);
+}
+export async function readLibraryAttachmentMetadata(root, id) {
+    if (!/^[a-f0-9-]{36}$/.test(id))
+        throw new Error('invalid_library_attachment');
+    const directory = await metadataDirectory(root);
+    const handle = await open(join(directory, `${id}.json`), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > METADATA_MAX_BYTES)
+            throw new Error('invalid_library_attachment');
+        const raw = JSON.parse(await handle.readFile('utf8'));
+        const { sessionIds, unbound, clientRequestIds = [], ...publicFields } = raw;
+        const attachment = workspaceAttachmentSchema.parse(publicFields);
+        if (attachment.id !== id || !attachment.origin || !['file', 'bundle'].includes(attachment.kind ?? '') || !attachment.files?.length)
+            throw new Error('invalid_library_attachment');
+        const prefix = `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}`;
+        const expected = attachment.kind === 'bundle' ? prefix : `${prefix}/${attachment.files[0].path}`;
+        if (attachment.path !== expected || (attachment.kind === 'file' && attachment.files.length !== 1))
+            throw new Error('invalid_library_attachment');
+        if (!Array.isArray(sessionIds) || sessionIds.some(session => typeof session !== 'string' || session.length > 128))
+            throw new Error('invalid_library_attachment');
+        if (!Array.isArray(clientRequestIds) || clientRequestIds.some(id => typeof id !== 'string' || !/^[a-f0-9-]{36}$/.test(id)))
+            throw new Error('invalid_library_attachment');
+        return { ...attachment, sessionIds: sessionIds, unbound: unbound === true, clientRequestIds: clientRequestIds };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function publicAttachment({ sessionIds: _sessionIds, unbound: _unbound, clientRequestIds: _clientRequestIds, ...attachment }) {
+    return attachment;
+}
+export async function openLibraryAttachmentFile(root, attachment, filePath) {
+    const selected = filePath ?? (attachment.kind === 'file' ? attachment.files?.[0]?.path : undefined);
+    const file = attachment.files?.find(file => file.path === selected);
+    if (!file || !workspaceLibraryFilePathSchema.safeParse(selected).success)
+        throw new Error('attachment_unavailable');
+    const relative = `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${attachment.id}/${file.path}`;
+    await safeDirectory(root, dirname(relative));
+    const handle = await open(join(root, relative), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size !== file.size || stat.size > WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES)
+            throw new Error('attachment_unavailable');
+        return { handle, name: file.path.split('/').at(-1), mimeType: file.mimeType, size: file.size, sha256: file.sha256 };
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+export async function resolveLibraryAttachment(root, id) {
+    const record = await readLibraryAttachmentMetadata(root, id);
+    let total = 0;
+    for (const file of record.files) {
+        const opened = await openLibraryAttachmentFile(root, record, file.path);
+        try {
+            if (hash(await opened.handle.readFile()) !== file.sha256)
+                throw new Error('library_asset_changed');
+            total += file.size;
+        }
+        finally {
+            await opened.handle.close();
+        }
+    }
+    if (total !== record.size || total > WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES)
+        throw new Error('invalid_library_attachment');
+    return { ...publicAttachment(record), path: join(root, record.path) };
+}
+async function listLibraryRecords(root, sessionId) {
+    let directory;
+    try {
+        directory = await metadataDirectory(root);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    const attachments = [];
+    for (const name of await readdir(directory)) {
+        if (!/^[a-f0-9-]{36}\.json$/.test(name))
+            continue;
+        try {
+            const record = await readLibraryAttachmentMetadata(root, name.slice(0, -5));
+            if (record.unbound || (sessionId && record.sessionIds.includes(sessionId)))
+                attachments.push(record);
+        }
+        catch { /* Legacy upload metadata and incomplete records are not library sources. */ }
+    }
+    return attachments.sort((a, b) => b.origin.importedAt.localeCompare(a.origin.importedAt));
+}
+export async function listWorkspaceLibraryAttachments(root, sessionId) {
+    return (await listLibraryRecords(root, sessionId)).map(publicAttachment);
+}
+export async function listWorkspaceLibraryImportReceipts(root, sessionId) {
+    const receipts = new Map();
+    for (const record of await listLibraryRecords(root, sessionId)) {
+        for (const id of record.clientRequestIds)
+            receipts.set(id, [...(receipts.get(id) ?? []), record.id]);
+    }
+    return [...receipts].map(([clientRequestId, attachmentIds]) => ({ clientRequestId, attachmentIds }));
+}
+function attachmentId(asset) {
+    const hex = hash(JSON.stringify([asset.assetId, asset.contentHash])).slice(0, 32).split('');
+    hex[12] = '5';
+    hex[16] = ['8', '9', 'a', 'b'][parseInt(hex[16], 16) % 4];
+    const value = hex.join('');
+    return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
+}
+async function importAttachment(root, body) {
+    const { asset, sessionId, clientRequestId } = workspaceLibraryAttachmentUploadSchema.parse(body);
+    const previousImports = (await listLibraryRecords(root, sessionId)).filter(record => record.clientRequestIds.includes(clientRequestId));
+    const replay = previousImports.find(record => record.origin.assetId === asset.assetId);
+    if (replay) {
+        await resolveLibraryAttachment(root, replay.id);
+        return publicAttachment(replay);
+    }
+    if (previousImports.length >= WORKSPACE_ATTACHMENT_MAX_COUNT)
+        throw new Error('library_attachment_limit');
+    const files = asset.files.map(file => {
+        const bytes = Buffer.from(file.content, 'base64');
+        if (bytes.toString('base64') !== file.content || hash(bytes) !== file.sha256)
+            throw new Error('library_asset_changed');
+        return { ...file, bytes };
+    });
+    const size = files.reduce((sum, file) => sum + file.bytes.length, 0);
+    if (size > WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES)
+        throw new Error('library_asset_too_large');
+    const contentHash = hash(JSON.stringify(files.map(file => [file.path, file.sha256]).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)));
+    if (asset.contentHash !== contentHash)
+        throw new Error('library_asset_changed');
+    const id = attachmentId(asset);
+    await excludeFromGit(root, `/${WORKSPACE_USER_UPLOADS_DIRECTORY}/`);
+    const uploads = await safeDirectory(root, WORKSPACE_USER_UPLOADS_DIRECTORY, true);
+    const metadata = await metadataDirectory(root, true);
+    let record;
+    try {
+        record = await readLibraryAttachmentMetadata(root, id);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (record)
+        await resolveLibraryAttachment(root, id);
+    if (!record) {
+        const temporary = join(uploads, `.import-${randomUUID()}`);
+        const target = join(uploads, id);
+        await mkdir(temporary, { mode: 0o755 });
+        try {
+            for (const file of files) {
+                const parent = dirname(file.path);
+                if (parent !== '.')
+                    await safeDirectory(temporary, parent, true);
+                await writeFile(join(temporary, file.path), file.bytes, { flag: 'wx', mode: 0o644 });
+            }
+            const prefix = `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}`;
+            record = {
+                id, name: asset.kind === 'file' ? files[0].path.split('/').at(-1) : asset.name,
+                kind: asset.kind, size,
+                mimeType: asset.kind === 'file' ? files[0].mimeType : 'application/vnd.playcraft.asset-bundle',
+                path: asset.kind === 'file' ? `${prefix}/${files[0].path}` : prefix,
+                origin: { kind: 'asset-library', assetId: asset.assetId, name: asset.name,
+                    libraryPath: asset.libraryPath, visibility: asset.visibility, teamId: asset.teamId,
+                    contentHash, importedAt: new Date().toISOString() },
+                files: files.map(file => ({ path: file.path, size: file.bytes.length, mimeType: file.mimeType, sha256: file.sha256 })),
+                sessionIds: [], unbound: !sessionId, clientRequestIds: [],
+            };
+            // Publish the complete directory before making the source visible through its metadata.
+            let alreadyPublished = false;
+            try {
+                await safeDirectory(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}`);
+                for (const file of record.files) {
+                    const opened = await openLibraryAttachmentFile(root, record, file.path);
+                    try {
+                        if (hash(await opened.handle.readFile()) !== file.sha256)
+                            throw new Error('library_asset_changed');
+                    }
+                    finally {
+                        await opened.handle.close();
+                    }
+                }
+                alreadyPublished = true;
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                // A pre-existing incomplete directory must not be overwritten by a retry.
+                try {
+                    await lstat(target);
+                    throw new Error('invalid_library_attachment');
+                }
+                catch (targetError) {
+                    if (targetError.code !== 'ENOENT')
+                        throw targetError;
+                }
+            }
+            if (alreadyPublished)
+                await rm(temporary, { recursive: true, force: true });
+            else
+                await rename(temporary, target);
+        }
+        catch (error) {
+            await rm(temporary, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    record.sessionIds = [...new Set([...record.sessionIds, ...(sessionId ? [sessionId] : [])])];
+    record.clientRequestIds = [...new Set([...record.clientRequestIds, clientRequestId])];
+    record.unbound ||= !sessionId;
+    const tempMetadata = join(metadata, `.import-${randomUUID()}.json`);
+    await writeFile(tempMetadata, JSON.stringify(record), { flag: 'wx', mode: 0o644 });
+    await rename(tempMetadata, join(metadata, `${id}.json`));
+    await chmod(join(uploads, id), 0o755);
+    return publicAttachment(record);
+}
+export async function importWorkspaceLibraryAttachment(root, body) {
+    const previous = locks.get(root) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(() => importAttachment(root, body));
+    locks.set(root, current);
+    try {
+        return await current;
+    }
+    finally {
+        if (locks.get(root) === current)
+            locks.delete(root);
+    }
+}
+export async function readLibraryAttachmentUpload(request) {
+    const chunks = [];
+    let size = 0;
+    const limit = 4 * Math.ceil(WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES / 3) + 1024 * 1024;
+    for await (const chunk of request) {
+        const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += bytes.length;
+        if (size > limit)
+            throw new Error('library_asset_too_large');
+        chunks.push(bytes);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}

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

@@ -10,6 +10,7 @@ import { ensureWorkspaceSkills, readWorkspaceSkills } from './skills.js';
 import { loadWorkspaceSkillArtifact, workspacePlatformSkillAccess } from './skill-artifact-loader.js';
 import { writeWorkspaceCliContext } from './cli-context.js';
 import { attachWorkspaceRemote } from './git.js';
+import { ensureWorkspaceArtifactInstructions } from './instructions.js';
 export { WorkspaceContextError } from './context-error.js';
 const exec = promisify(execFile);
 export function revisionScope(state, workspaceId, directoryName = 'basic') {
@@ -222,6 +223,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
             throw new WorkspaceContextError('workspace_skills_unavailable');
         }
         await writeWorkspaceCliContext(root, binding.workspaceId);
+        await ensureWorkspaceArtifactInstructions(root);
         await state.journal.putWorkspace({ ...binding, directories });
         try {
             await readWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'), entry => loadWorkspaceSkillArtifact(state, binding.workspaceId, entry));

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

@@ -0,0 +1,288 @@
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, copyFile, lstat, mkdir, mkdtemp, open, readdir, realpath, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve, sep } from 'node:path';
+import { isCredentialFile } from './git.js';
+export const WORKSPACE_TRANSFER_MAX_BYTES = 256 * 1024 * 1024;
+const MAX_FILES = 20_000;
+const EXCLUDED = new Set(['.git', 'node_modules', '.playcraft-workspace.json', '.playcraft.json']);
+export class WorkspaceTransferError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+function excluded(path) {
+    const parts = path.split('/');
+    return parts.some(part => EXCLUDED.has(part.toLowerCase()) || /^\.playcraft-(?:credential|transfer)-.*\.tmp$/i.test(part)) ||
+        parts.some((part, index) => part === '.playcraft' && /^(?:workspace-context(?:\..*)?|video-replication)$/.test(parts[index + 1] ?? '')) ||
+        isCredentialFile(path);
+}
+export function transferGit(root, args) {
+    const env = { PATH: process.env.PATH, HOME: tmpdir(),
+        GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_TERMINAL_PROMPT: '0', GIT_ALLOW_PROTOCOL: 'file' };
+    const result = spawnSync('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'commit.gpgsign=false',
+        '-c', 'core.autocrlf=false', '-c', 'user.name=PlayCraft Workspace', '-c', 'user.email=workspace@playcraft.local', ...args], { cwd: root, encoding: 'utf8', env, timeout: 120_000, maxBuffer: 8 * 1024 * 1024 });
+    if (result.status !== 0)
+        throw new WorkspaceTransferError('workspace_transfer_git_failed');
+    return result.stdout.trim();
+}
+async function copySnapshot(source, target) {
+    let bytes = 0, files = 0;
+    async function copy(directory, prefix) {
+        const directoryInfo = await lstat(directory);
+        const directoryReal = await realpath(directory);
+        if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink() ||
+            (directoryReal !== source && !directoryReal.startsWith(`${source}${sep}`)))
+            throw new WorkspaceTransferError('workspace_transfer_conflict');
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (excluded(path))
+                continue;
+            const from = join(directory, entry.name), to = join(target, path);
+            const info = await lstat(from);
+            if (info.isSymbolicLink())
+                continue;
+            if (info.isDirectory()) {
+                await mkdir(to, { recursive: true });
+                await copy(from, path);
+            }
+            else if (info.isFile()) {
+                bytes += info.size;
+                files++;
+                if (bytes > WORKSPACE_TRANSFER_MAX_BYTES || files > MAX_FILES)
+                    throw new WorkspaceTransferError('workspace_transfer_too_large');
+                if (!(await realpath(from)).startsWith(`${source}${sep}`))
+                    throw new WorkspaceTransferError('workspace_transfer_conflict');
+                const handle = await open(from, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const before = await handle.stat();
+                    if (!before.isFile() || before.dev !== info.dev || before.ino !== info.ino || before.size !== info.size ||
+                        before.mtimeMs !== info.mtimeMs || before.ctimeMs !== info.ctimeMs)
+                        throw new WorkspaceTransferError('workspace_transfer_conflict');
+                    const chunks = [];
+                    let size = 0;
+                    for await (const chunk of handle.createReadStream({ autoClose: false })) {
+                        size += chunk.length;
+                        if (size > before.size)
+                            throw new WorkspaceTransferError('workspace_transfer_conflict');
+                        chunks.push(chunk);
+                    }
+                    const after = await handle.stat();
+                    if (size !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs)
+                        throw new WorkspaceTransferError('workspace_transfer_conflict');
+                    await writeFile(to, Buffer.concat(chunks));
+                }
+                finally {
+                    await handle.close();
+                }
+                await chmod(to, info.mode & 0o111 ? 0o755 : 0o644);
+            }
+        }
+    }
+    await copy(source, '');
+}
+async function matchesFile(root, path, expected) {
+    const target = await safeTarget(root, path);
+    const info = await lstat(target).catch(error => { if (['ENOENT', 'ENOTDIR'].includes(error.code))
+        return undefined; throw error; });
+    if (!expected)
+        return !info || info.isDirectory();
+    if (!info?.isFile() || Boolean(info.mode & 0o111) !== expected.executable)
+        return false;
+    const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        const hash = createHash(expected.sha.length === 64 ? 'sha256' : 'sha1');
+        hash.update(`blob ${stat.size}\0`);
+        for await (const chunk of handle.createReadStream({ autoClose: false }))
+            hash.update(chunk);
+        return hash.digest('hex') === expected.sha;
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function removeEmptyParents(root, target) {
+    let parent = dirname(target);
+    while (parent !== root) {
+        if ((await readdir(parent)).length > 0)
+            break;
+        await rmdir(parent);
+        parent = dirname(parent);
+    }
+}
+async function installFile(root, path, source, executable) {
+    const target = await safeTarget(root, path);
+    const existing = await lstat(target).catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (existing?.isDirectory())
+        await rmdir(target);
+    await mkdir(dirname(target), { recursive: true });
+    const stage = join(dirname(target), `.playcraft-transfer-${randomUUID()}.tmp`);
+    try {
+        await copyFile(source, stage);
+        await chmod(stage, executable ? 0o755 : 0o644);
+        await rename(stage, target);
+    }
+    catch (error) {
+        await rm(stage, { force: true }).catch(() => undefined);
+        await removeEmptyParents(root, target).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        await rm(stage, { force: true }).catch(() => undefined);
+    }
+}
+/** A fresh history contains only the current portable files, including uncommitted changes. */
+export async function createWorkspaceTransfer(root) {
+    const temporary = await mkdtemp(join(tmpdir(), 'playcraft-transfer-'));
+    const cleanup = () => rm(temporary, { recursive: true, force: true });
+    try {
+        const checkout = join(temporary, 'checkout');
+        await mkdir(checkout);
+        await copySnapshot(await realpath(root), checkout);
+        transferGit(checkout, ['init', '--initial-branch=main']);
+        transferGit(checkout, ['add', '--force', '--all']);
+        transferGit(checkout, ['commit', '--allow-empty', '-m', 'Workspace snapshot']);
+        const tree = transferGit(checkout, ['rev-parse', 'HEAD^{tree}']);
+        const head = transferGit(checkout, ['rev-parse', 'HEAD']);
+        const bundlePath = join(temporary, 'workspace.bundle');
+        transferGit(checkout, ['bundle', 'create', bundlePath, 'HEAD']);
+        return { bundlePath, tree, head, cleanup };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+function treeEntries(root) {
+    const entries = transferGit(root, ['ls-tree', '-r', '-z', 'HEAD']).split('\0').filter(Boolean).map(line => {
+        const match = /^(100644|100755) blob ([a-f0-9]{40,64})\t(.+)$/s.exec(line);
+        if (!match)
+            throw new WorkspaceTransferError('invalid_workspace_transfer');
+        const path = match[3];
+        if (path.length > 1024 || path.includes('\\') || path.startsWith('/') || /[\x00-\x1f\x7f]/.test(path) ||
+            path.split('/').some(part => !part || part === '.' || part === '..') || excluded(path))
+            throw new WorkspaceTransferError('invalid_workspace_transfer');
+        return { path, sha: match[2], executable: match[1] === '100755' };
+    });
+    if (entries.length > MAX_FILES)
+        throw new WorkspaceTransferError('workspace_transfer_too_large');
+    const normalized = entries.map(entry => entry.path.toLowerCase());
+    if (new Set(normalized).size !== entries.length)
+        throw new WorkspaceTransferError('invalid_workspace_transfer');
+    return entries;
+}
+async function safeTarget(root, path) {
+    const target = resolve(root, path);
+    if (!target.startsWith(`${root}${sep}`))
+        throw new WorkspaceTransferError('invalid_workspace_transfer');
+    let current = root;
+    for (const segment of path.split('/')) {
+        current = join(current, segment);
+        const info = await lstat(current).catch(error => { if (['ENOENT', 'ENOTDIR'].includes(error.code))
+            return undefined; throw error; });
+        if (info?.isSymbolicLink())
+            throw new WorkspaceTransferError('workspace_transfer_symlink');
+    }
+    return target;
+}
+/** Compare the entire checkout before applying local commits, so cloud edits are never overwritten. */
+export async function applyWorkspaceTransfer(root, bundle, expectedTree) {
+    if (!/^[a-f0-9]{40,64}$/.test(expectedTree))
+        throw new WorkspaceTransferError('invalid_workspace_transfer');
+    if (!bundle.byteLength || bundle.byteLength > WORKSPACE_TRANSFER_MAX_BYTES)
+        throw new WorkspaceTransferError('workspace_transfer_too_large');
+    const rootReal = await realpath(root);
+    const temporary = await mkdtemp(join(tmpdir(), 'playcraft-import-'));
+    let current;
+    try {
+        const bundlePath = join(temporary, 'incoming.bundle'), incoming = join(temporary, 'checkout');
+        await writeFile(bundlePath, bundle, { mode: 0o600 });
+        transferGit(temporary, ['clone', '--no-checkout', '--', bundlePath, incoming]);
+        const entries = treeEntries(incoming);
+        const tree = transferGit(incoming, ['rev-parse', 'HEAD^{tree}']);
+        const head = transferGit(incoming, ['rev-parse', 'HEAD']);
+        let bytes = 0;
+        for (const entry of entries) {
+            bytes += Number(transferGit(incoming, ['cat-file', '-s', entry.sha]));
+            if (bytes > WORKSPACE_TRANSFER_MAX_BYTES)
+                throw new WorkspaceTransferError('workspace_transfer_too_large');
+        }
+        current = await createWorkspaceTransfer(rootReal);
+        if (current.tree === tree)
+            return { tree, head, changedPaths: [] };
+        if (current.tree !== expectedTree)
+            throw new WorkspaceTransferError('workspace_transfer_conflict');
+        const baseline = join(dirname(current.bundlePath), 'checkout');
+        const previous = new Map(treeEntries(baseline).map(entry => [entry.path, entry]));
+        const next = new Map(entries.map(entry => [entry.path, entry]));
+        const changedPaths = [...new Set([...previous.keys(), ...next.keys()])]
+            .filter(path => previous.get(path)?.sha !== next.get(path)?.sha || previous.get(path)?.executable !== next.get(path)?.executable);
+        for (const path of changedPaths) {
+            const target = await safeTarget(rootReal, path);
+            const info = await lstat(target).catch(error => { if (['ENOENT', 'ENOTDIR'].includes(error.code))
+                return undefined; throw error; });
+            if (next.has(path) && info?.isDirectory()) {
+                const children = await readdir(target, { recursive: true });
+                for (const child of children) {
+                    const childPath = `${path}/${child.split(sep).join('/')}`;
+                    const childInfo = await lstat(join(target, child));
+                    if (!childInfo.isDirectory() && (!previous.has(childPath) || next.has(childPath)))
+                        throw new WorkspaceTransferError('workspace_transfer_conflict');
+                }
+            }
+        }
+        transferGit(incoming, ['checkout', '--force']);
+        const recheck = await createWorkspaceTransfer(rootReal);
+        try {
+            if (recheck.tree !== expectedTree)
+                throw new WorkspaceTransferError('workspace_transfer_conflict');
+        }
+        finally {
+            await recheck.cleanup();
+        }
+        const applied = [];
+        try {
+            // Deleting files first also permits a file to become a directory, or the reverse.
+            for (const path of changedPaths.filter(path => !next.has(path)).sort((a, b) => b.length - a.length)) {
+                if (!await matchesFile(rootReal, path, previous.get(path)))
+                    throw new WorkspaceTransferError('workspace_transfer_conflict');
+                await rm(await safeTarget(rootReal, path), { force: true });
+                applied.push(path);
+                await removeEmptyParents(rootReal, join(rootReal, path));
+            }
+            for (const path of changedPaths.filter(path => next.has(path))) {
+                if (!await matchesFile(rootReal, path, previous.get(path)))
+                    throw new WorkspaceTransferError('workspace_transfer_conflict');
+                const entry = next.get(path);
+                await installFile(rootReal, path, join(incoming, path), entry.executable);
+                applied.push(path);
+            }
+        }
+        catch (error) {
+            // Roll back only our writes; never replace another writer's intervening content.
+            for (const path of applied.reverse()) {
+                if (!await matchesFile(rootReal, path, next.get(path)))
+                    throw new WorkspaceTransferError('workspace_transfer_rollback_conflict');
+                const old = previous.get(path);
+                if (old)
+                    await installFile(rootReal, path, join(baseline, path), old.executable);
+                else {
+                    await rm(await safeTarget(rootReal, path), { force: true });
+                    await removeEmptyParents(rootReal, join(rootReal, path));
+                }
+            }
+            throw error;
+        }
+        return { tree, head, changedPaths };
+    }
+    finally {
+        await current?.cleanup();
+        await rm(temporary, { recursive: true, force: true });
+    }
+}

package/dist/workspace-runtime/workspaces/turn-changes.js

@@ -0,0 +1,72 @@
+import { TURN_FILES_CHANGED_EVENT, } from '@playcraft/common/cloud-workspace/runtime';
+import { diffWorkspaceTrees, retainTurnSnapshots, snapshotWorkspaceTree } from './git.js';
+const TURN_ENDS = new Set(['turn/completed', 'turn.completed', 'turn.interrupted', 'turn.failed']);
+/**
+ * Snapshots taken when a session's turn starts, until that turn ends. Kept in memory only: a
+ * restart ends the native turn as well, and that turn then simply reports no changes.
+ */
+const started = new WeakMap();
+function turnsOf(state) {
+    let turns = started.get(state);
+    if (!turns)
+        started.set(state, turns = new Map());
+    return turns;
+}
+/**
+ * Records the work tree before a turn is sent. A directory that cannot be snapshotted (no
+ * repository, Git failure) gets no change summary; the turn itself is never held back by it.
+ */
+export async function beginTurnChanges(state, sessionId, input) {
+    turnsOf(state).delete(sessionId);
+    if (input.directoryName === 'root')
+        return;
+    const before = await snapshotWorkspaceTree(input.root).catch(() => undefined);
+    if (before)
+        turnsOf(state).set(sessionId, { ...input, before });
+}
+/** A turn that never started has nothing to compare. */
+export function abandonTurnChanges(state, sessionId) {
+    turnsOf(state).delete(sessionId);
+}
+/**
+ * When a session's turn ends, compares the work tree with its start and records the files that
+ * changed for that session's conversation. Returns no event when nothing changed.
+ */
+export async function finishTurnChanges(state, event) {
+    const { threadId, turnId } = event;
+    if (!TURN_ENDS.has(event.method) || !threadId || !turnId)
+        return [];
+    const session = state.journal.listSessions().find((item) => item.threadId === threadId);
+    const start = session && turnsOf(state).get(session.sessionId);
+    if (!session || !start)
+        return [];
+    turnsOf(state).delete(session.sessionId);
+    try {
+        const after = await snapshotWorkspaceTree(start.root);
+        const { files, truncated } = await diffWorkspaceTrees(start.root, start.before, after);
+        if (!files.length)
+            return [];
+        await retainTurnSnapshots(start.root, turnId, start.before, after);
+        const changes = { threadId, turnId, before: start.before, after, files, truncated };
+        return [await state.journal.allocateSourceEvent({
+                runtimeId: state.config.runtimeId,
+                generation: state.config.generation,
+                runtimeEpoch: state.runtimeEpoch,
+                type: TURN_FILES_CHANGED_EVENT,
+                payload: {
+                    ...changes,
+                    sessionId: session.sessionId,
+                    ...(start.workspaceId ? { workspaceId: start.workspaceId } : {}),
+                    ...(start.directoryName ? { directoryName: start.directoryName } : {}),
+                },
+                occurredAt: new Date().toISOString(),
+                sessionId: session.sessionId,
+                workspaceId: start.workspaceId,
+                threadId,
+                turnId,
+            })];
+    }
+    catch {
+        return [];
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "private": false,
   "type": "module",
   "engines": {
@@ -50,8 +50,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.1.31",
-    "@playcraft/common": "^0.1.31",
+    "@playcraft/build": "^0.1.33",
+    "@playcraft/common": "^0.1.33",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",