@playcraft/cli 0.1.53-beta → 0.1.55-beta

package/dist/commands/image.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'url';
 import sharp from 'sharp';
 import yaml from 'js-yaml';
 import { AgentApiClient } from '../utils/agent-api-client.js';
+import { registerImageLayerTools } from './image-layer-tools.js';
 import { resolveSandboxPath } from '../utils/sandbox-path.js';
 /** 单文件输入上限（字节），防止误处理巨型文件导致 OOM */
 const DEFAULT_MAX_INPUT_BYTES = 512 * 1024 * 1024;
@@ -1853,79 +1854,7 @@ export function registerImageCommands(program) {
             handleError(e);
         }
     });
-    // ─── decompose-layers ──────────────────────────────────────────────────────
-    img
-        .command('decompose-layers')
-        .description([
-        '302 Qwen-Image-Layered 整图语义分层：将合成图拆成 N 个 RGBA 图层',
-        '',
-        '  示例:',
-        '    playcraft image decompose-layers --input composite.png --output-dir ./layers',
-        '    playcraft image decompose-layers --input https://example.com/a.png --num-layers 4',
-        '',
-        '  需 Admin 配置 provider=302、modelKind=image 的 API Key；耗时约 1–2 分钟。',
-        '  本地文件需 storage 公网 URL，或 --input 使用 HTTPS 直链。',
-    ].join('\n'))
-        .requiredOption('--input <path>', '输入图片路径或 HTTPS URL')
-        .option('--output-dir <dir>', '输出目录', './decompose-layers-output')
-        .option('--num-layers <n>', '分层数量 2–10', cliParseInt, 4)
-        .option('--prompt <text>', '可选分层语义引导', '')
-        .option('--no-safety-checker', '关闭安全检测')
-        .option('--output-format <fmt>', '输出格式', 'png')
-        .action(async (opts) => {
-        try {
-            const payload = {
-                numLayers: opts.numLayers,
-                prompt: opts.prompt || '',
-                enableSafetyChecker: opts.safetyChecker !== false,
-                outputFormat: opts.outputFormat,
-            };
-            const input = opts.input;
-            const isUrl = input.startsWith('http://') || input.startsWith('https://');
-            if (isUrl) {
-                payload.imageUrl = input;
-                console.log(`Using image URL: ${input}`);
-            }
-            else {
-                const resolvedDecomposeInput = assertInputWithinLimit(input);
-                payload.imageBase64 = readFileSync(resolvedDecomposeInput).toString('base64');
-                console.log(`Uploading local image: ${input}`);
-            }
-            console.log(`Decomposing into ${payload.numLayers} layer(s) via 302 Qwen-Image-Layered (may take 1–2 min)…`);
-            const t0 = Date.now();
-            const client = new AgentApiClient();
-            const result = await client.post('/image-layered/decompose', payload);
-            const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
-            const outputDir = opts.outputDir;
-            mkdirSync(outputDir, { recursive: true });
-            for (const layer of result.layers) {
-                const ext = layer.mimeType.includes('png') ? 'png' : 'png';
-                const filename = `layer_${String(layer.index).padStart(2, '0')}.${ext}`;
-                writeFileSync(join(outputDir, filename), Buffer.from(layer.imageBase64, 'base64'));
-                const dim = layer.width && layer.height ? ` ${layer.width}×${layer.height}` : '';
-                console.log(`  ${filename}${dim}`);
-            }
-            const meta = {
-                source: input,
-                requestId: result.requestId,
-                numLayers: result.numLayers,
-                elapsed: `${elapsed}s`,
-                hasNsfwConcepts: result.hasNsfwConcepts,
-                layers: result.layers.map((l) => ({
-                    index: l.index,
-                    url: l.url,
-                    width: l.width,
-                    height: l.height,
-                    seed: l.seed,
-                })),
-            };
-            writeFileSync(join(outputDir, 'decompose-layers-meta.json'), JSON.stringify(meta, null, 2), 'utf-8');
-            console.log(`\nDone in ${elapsed}s — ${result.layers.length} layer(s) → ${outputDir}/`);
-        }
-        catch (e) {
-            handleError(e);
-        }
-    });
+    registerImageLayerTools(img);
     // ─── segment ─────────────────────────────────────────────────────────────
     img
         .command('segment')

package/dist/commands/library-messages.js

@@ -0,0 +1,46 @@
+const messages = {
+    en: {
+        topic: 'Find and download authorized shared asset library content',
+        list: 'List library assets with filters and pagination', search: 'Search library names and content metadata',
+        get: 'Read asset metadata', files: 'List every file in an asset or bundle', facets: 'Inspect available categories and tags',
+        download: 'Download an asset or a complete bundle with relative dependencies',
+        query: 'Search text', id: 'Library asset identifier', type: 'Asset type', path: 'Library path prefix',
+        category: 'Category', subcategory: 'Subcategory', tags: 'Comma-separated tags',
+        visibility: 'public | team', team: 'Authorized team identifier', page: 'Page number, starting at 1',
+        limit: 'Results per page (1–100)', sort: 'modifiedAt | createdAt | name | referenceCount | size', order: 'asc | desc',
+        expand: 'Return individual files instead of collapsed bundles',
+        output: 'New file path, or a new directory for a bundle', outputDir: 'New directory for the downloaded content',
+        json: 'Print machine-readable JSON (JavaScript Object Notation, 数据交换格式; always enabled)',
+        invalidNumber: 'Expected a positive integer.', invalidId: 'Invalid library asset identifier.',
+        invalidManifest: 'The library returned an invalid or unsafe file manifest.',
+        outputRequired: 'Specify exactly one of --output or --output-dir.',
+        outputExists: 'The output already exists. Choose a new path to preserve existing files.',
+        failed: 'Asset library command failed.',
+    },
+    zh: {
+        topic: '检索和下载有权访问的共享素材库内容',
+        list: '按条件分页列出素材库内容', search: '检索素材名称和内容元数据',
+        get: '读取素材详情', files: '列出素材或素材包内的全部文件', facets: '查看可用分类与标签',
+        download: '下载素材或完整素材包，保留依赖文件的相对路径',
+        query: '检索文本', id: '素材库中的素材编号', type: '素材类型', path: '素材库路径前缀',
+        category: '分类', subcategory: '子分类', tags: '标签，逗号分隔',
+        visibility: 'public（公共）或 team（团队）', team: '有权访问的团队编号', page: '页码，从 1 开始',
+        limit: '每页数量（1–100）', sort: 'modifiedAt | createdAt | name | referenceCount | size', order: 'asc | desc',
+        expand: '返回单独文件，不折叠素材包', output: '新的文件路径；素材包则为新的目录', outputDir: '下载内容的新目录',
+        json: '输出机器可读的 JSON (JavaScript Object Notation, 数据交换格式)，始终启用',
+        invalidNumber: '请输入正整数。', invalidId: '素材库编号无效。',
+        invalidManifest: '素材库返回的文件清单无效或包含不安全路径。',
+        outputRequired: '请指定 --output 或 --output-dir，且只指定一项。',
+        outputExists: '输出路径已存在，请选择新路径以保留已有文件。', failed: '素材库命令执行失败。',
+    },
+};
+export function libraryMessage(key) {
+    return messages[(process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en').startsWith('zh') ? 'zh' : 'en'][key];
+}
+export class LibraryError extends Error {
+    code;
+    constructor(code) {
+        super(libraryMessage(code));
+        this.code = code;
+    }
+}

package/dist/commands/library.js

@@ -0,0 +1,130 @@
+import { InvalidArgumentError, Option } from 'commander';
+import { link, lstat, mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
+import { dirname, join, posix, resolve } from 'node:path';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { resolveSandboxPath } from '../utils/sandbox-path.js';
+import { libraryMessage as t, LibraryError } from './library-messages.js';
+function assetId(value) {
+    if (!/^(?:\d{1,20}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$/i.test(value))
+        throw new InvalidArgumentError(t('invalidId'));
+    return value;
+}
+function positiveInteger(value) {
+    if (!/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value)))
+        throw new InvalidArgumentError(t('invalidNumber'));
+    return value;
+}
+function filters(command) {
+    return command.option('--search <text>', t('query')).option('--type <type>', t('type'))
+        .option('--path <path>', t('path')).option('--category <category>', t('category'))
+        .option('--subcategory <category>', t('subcategory')).option('--tags <tags>', t('tags'))
+        .addOption(new Option('--visibility <scope>', t('visibility')).choices(['public', 'team']))
+        .option('--team-id <id>', t('team')).option('--page <number>', t('page'), positiveInteger, '1')
+        .option('--limit <number>', t('limit'), value => {
+        positiveInteger(value);
+        if (Number(value) > 100)
+            throw new InvalidArgumentError(t('limit'));
+        return value;
+    }, '30')
+        .addOption(new Option('--sort-by <field>', t('sort')).choices(['modifiedAt', 'createdAt', 'name', 'referenceCount', 'size']))
+        .addOption(new Option('--sort-order <order>', t('order')).choices(['asc', 'desc']))
+        .option('--expand-prefabs', t('expand')).option('--json', t('json'));
+}
+function query(options) {
+    return Object.fromEntries(Object.entries(options)
+        .filter(([key, value]) => key !== 'json' && value !== undefined && value !== false)
+        .map(([key, value]) => [key, String(value)]));
+}
+async function action(run) {
+    try {
+        console.log(JSON.stringify({ ok: true, result: await run() }, null, 2));
+    }
+    catch (error) {
+        const code = error instanceof LibraryError ? error.code : 'failed';
+        console.error(`${t('failed')} ${error instanceof Error ? error.message : String(error)}`);
+        console.log(JSON.stringify({ ok: false, error: { code, message: error instanceof Error ? error.message : String(error) } }));
+        process.exitCode = 1;
+    }
+}
+function validatedFiles(manifest) {
+    if (!manifest || !['file', 'bundle'].includes(manifest.kind) || !Array.isArray(manifest.files) ||
+        !manifest.files.length || (manifest.kind === 'file' && manifest.files.length !== 1))
+        throw new LibraryError('invalidManifest');
+    const seen = new Set();
+    for (const file of manifest.files) {
+        try {
+            assetId(file.id);
+        }
+        catch {
+            throw new LibraryError('invalidManifest');
+        }
+        const path = file.path;
+        if (typeof path !== 'string' || !path || path.startsWith('/') || /[\\:\x00-\x1f]/.test(path) ||
+            path.split('/').some(part => !part || part === '.' || part === '..') || posix.normalize(path) !== path)
+            throw new LibraryError('invalidManifest');
+        const key = path.toLowerCase();
+        if (seen.has(key))
+            throw new LibraryError('invalidManifest');
+        seen.add(key);
+    }
+    for (const key of seen) {
+        for (let parent = posix.dirname(key); parent !== '.'; parent = posix.dirname(parent)) {
+            if (seen.has(parent))
+                throw new LibraryError('invalidManifest');
+        }
+    }
+    return manifest.files;
+}
+export async function downloadLibraryAsset(client, id, options) {
+    if (Boolean(options.output) === Boolean(options.outputDir))
+        throw new LibraryError('outputRequired');
+    assetId(id);
+    const manifest = await client.get(`/asset-library/${encodeURIComponent(id)}/files`);
+    const files = validatedFiles(manifest);
+    const destination = resolve(resolveSandboxPath(options.output ?? options.outputDir));
+    const existing = await lstat(destination).catch(error => { if (error.code === 'ENOENT')
+        return undefined; throw error; });
+    if (existing)
+        throw new LibraryError('outputExists');
+    await mkdir(dirname(destination), { recursive: true });
+    const staging = await mkdtemp(join(dirname(destination), '.playcraft-library-'));
+    const directory = manifest.kind === 'bundle' || Boolean(options.outputDir);
+    const downloaded = [];
+    try {
+        for (const file of files) {
+            const target = directory ? join(staging, file.path) : join(staging, 'content');
+            const { bytes } = await client.download(`/asset-library/${encodeURIComponent(file.id)}/file`, target);
+            downloaded.push({ id: file.id, path: directory ? join(destination, file.path) : destination, bytes });
+        }
+        // Recheck before publishing the complete bundle; failures never expose a partial download.
+        if (await lstat(destination).catch(error => { if (error.code === 'ENOENT')
+            return undefined; throw error; }))
+            throw new LibraryError('outputExists');
+        if (directory)
+            await rename(staging, destination);
+        else
+            await link(join(staging, 'content'), destination);
+        return { assetId: manifest.assetId, kind: manifest.kind, output: destination, files: downloaded };
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+export function registerLibraryCommands(program) {
+    const library = program.command('library').description(t('topic'));
+    filters(library.command('list').description(t('list')))
+        .action((options) => action(() => new AgentApiClient().get('/asset-library', query(options))));
+    filters(library.command('search').description(t('search')).argument('<query>', t('query')))
+        .action((search, options) => action(() => new AgentApiClient().get('/asset-library', query({ ...options, search }))));
+    library.command('facets').description(t('facets')).option('--path <path>', t('path'))
+        .addOption(new Option('--visibility <scope>', t('visibility')).choices(['public', 'team']))
+        .option('--team-id <id>', t('team')).option('--json', t('json'))
+        .action((options) => action(() => new AgentApiClient().get('/asset-library/facets', query(options))));
+    for (const command of ['get', 'files']) {
+        library.command(command).description(t(command)).argument('<assetId>', t('id'), assetId).option('--json', t('json'))
+            .action((id) => action(() => new AgentApiClient().get(`/asset-library/${encodeURIComponent(id)}${command === 'files' ? '/files' : ''}`)));
+    }
+    library.command('download').description(t('download')).argument('<assetId>', t('id'), assetId)
+        .option('--output <path>', t('output')).option('--output-dir <directory>', t('outputDir')).option('--json', t('json'))
+        .action((id, options) => action(() => downloadLibraryAsset(new AgentApiClient(), id, options)));
+}

package/dist/index.js

@@ -18,6 +18,8 @@ import { checkForUpdates } from './utils/version-checker.js';
 import { syncCommand } from './commands/sync.js';
 import { fixIdsCommand } from './commands/fix-ids.js';
 import { registerToolsCommands } from './commands/tools.js';
+import { registerLibraryCommands } from './commands/library.js';
+import { registerWorkspaceAssetCommands } from './commands/assets.js';
 import { registerImageCommands } from './commands/image.js';
 import { registerAudioCommands } from './commands/audio.js';
 import { registerPrefabCommands } from './commands/prefab.js';
@@ -40,6 +42,7 @@ const __dirname = dirname(__filename);
 const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const program = new Command();
 const structuredVideoTopic = ['video', 'playable'].includes(process.argv[2] ?? '');
+const assetTopic = ['assets', 'library'].includes(process.argv[2] ?? '');
 const registryTopic = process.argv[2] === 'skills' && process.argv[3] === 'registry';
 if (structuredVideoTopic)
     program.exitOverride();
@@ -50,7 +53,7 @@ if (registryTopic)
 registerRootProgramHelp(program);
 // 版本检查（非阻塞，后台执行）
 // 只在非 upgrade 命令时检查，避免重复提示
-if (!structuredVideoTopic && !registryTopic && !process.argv.includes('upgrade') && !process.argv.includes('workspace-runtime')) {
+if (!structuredVideoTopic && !assetTopic && !registryTopic && !process.argv.includes('upgrade') && !process.argv.includes('workspace-runtime')) {
     checkForUpdates(packageJson);
 }
 // create 命令
@@ -366,6 +369,8 @@ program
 });
 // Agent domain tools (playcraft tools <command>)
 registerToolsCommands(program);
+registerLibraryCommands(program);
+registerWorkspaceAssetCommands(program);
 // Local image processing (playcraft image <command>)
 registerImageCommands(program);
 // Local audio processing (playcraft audio <command>)

package/dist/utils/agent-api-client.js

@@ -1,4 +1,9 @@
 import { readFileSync, existsSync } from 'fs';
+import { createWriteStream } from 'node:fs';
+import { link, mkdir, stat, unlink } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
 import { dirname, join } from 'path';
 import { homedir } from 'os';
 import { loadGlobalConfig } from '../config.js';
@@ -216,6 +221,36 @@ export class AgentApiClient {
         }
         return res.json();
     }
+    /** Stream authenticated tool content to a new file; credentials never follow redirects. */
+    async download(path, destination, options) {
+        const url = this.toolsRequestUrl(path);
+        if (!url.pathname.startsWith(this.toolsRequestUrl('/').pathname))
+            throw new Error('invalid_tool_download_target');
+        const signal = options?.signal ?? AbortSignal.timeout(10 * 60_000);
+        const response = await fetch(url, { headers: this.authHeaders(), redirect: 'error', signal });
+        if (!response.ok) {
+            const body = await response.text().catch(() => response.statusText);
+            const pending = pendingAccountActivationError(response.status, parseErrorPayload(body));
+            if (pending)
+                throw pending;
+            throw new Error(`tool_download_failed:${response.status}: ${responseErrorReason(body)}`);
+        }
+        if (!response.body)
+            throw new Error('tool_download_empty_response');
+        await mkdir(dirname(destination), { recursive: true });
+        const temporary = join(dirname(destination), `.playcraft-download-${randomUUID()}.tmp`);
+        try {
+            await pipeline(Readable.fromWeb(response.body), createWriteStream(temporary, { flags: 'wx', mode: 0o644 }), { signal });
+            const bytes = (await stat(temporary)).size;
+            // A hard link publishes the completed file without replacing existing user content.
+            await link(temporary, destination);
+            return { bytes };
+        }
+        finally {
+            await unlink(temporary).catch(error => { if (error.code !== 'ENOENT')
+                throw error; });
+        }
+    }
     /** Stream only to the authenticated, same-service video upload endpoint. */
     async putVideoMedia(path, body, headers, signal) {
         if (!/^\/video-media\/[a-f0-9-]{36}\/content\?/.test(path))

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

@@ -3,7 +3,7 @@ import { observeWorkspaceDirectories } from '../workspaces/directory-revisions.j
 import { registerWorkspace, revisionScope, sessionWorkspaceRoot, workspaceRoot, WorkspaceContextError } from '../workspaces/registry.js';
 import { constants } from 'node:fs';
 import { access as accessDirectory, stat } from 'node:fs/promises';
-import { workspaceRegistrationRequestSchema, workspaceFileSearchQuerySchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, sourceAckSchema, operationAcceptRequestSchema, operationLogSchema, operationKindSchema, operationScopeKey, productionSessionAttemptId, takesWorkspaceDirectory, nativeHistoryReadSchema, runtimeError, runtimeConnectivityDocumentSchema, unavailableRuntimeCapabilities, workspaceUiResultSchema, workspaceRemixReferenceImportRequestSchema, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES, WORKSPACE_ASSET_LIBRARY_IMPORT_BODY_MAX_BYTES, workspaceSessionRestoreRequestSchema, workspaceSessionRestoreResponseSchema, deliveryValidatePayloadSchema, deliveryBuildListQuerySchema, deliveryBuildListSchema, deliveryBuildDetailSchema, deliveryBuildLogSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRegistrationRequestSchema, workspaceFileSearchQuerySchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, sourceAckSchema, operationAcceptRequestSchema, operationLogSchema, operationKindSchema, operationScopeKey, productionSessionAttemptId, takesWorkspaceDirectory, nativeHistoryReadSchema, runtimeError, runtimeConnectivityDocumentSchema, unavailableRuntimeCapabilities, workspaceUiResultSchema, workspaceRemixReferenceImportRequestSchema, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES, WORKSPACE_ASSET_LIBRARY_IMPORT_BODY_MAX_BYTES, workspaceSessionRestoreRequestSchema, workspaceSessionRestoreResponseSchema, deliveryValidatePayloadSchema, deliveryBuildListQuerySchema, deliveryBuildListSchema, deliveryBuildDetailSchema, deliveryBuildLogSchema, workspaceDirectoryNameSchema, attachmentIdsSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { controlTokenMatches, extractControlToken } from './auth.js';
 import { applyRuntimeEndpointPatch } from './endpoints.js';
 import { wakeSourceEventUploader } from './source-uploader.js';
@@ -43,6 +43,7 @@ import { handleWorkspaceTransfer } from './workspace-transfer.js';
 import { serveSessionImage } from '../workspaces/session-image.js';
 import { restoreNativeSession, SessionRestoreError } from './session-restore.js';
 import { handleAssetTransferRequest } from './asset-transfers.js';
+import { readWorktreeSource, registerChatWorktree } from '../workspaces/worktrees.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';
@@ -202,7 +203,30 @@ export async function handleRuntimeRequest(state, request, response) {
                 writeJson(response, 409, { error: 'invalid_workspace_registration' });
                 return;
             }
-            writeJson(response, 200, await registerWorkspaceDirectory(state, body.directory, Number(body.leaseFence)));
+            if (body.worktree === true) {
+                const source = workspaceDirectoryNameSchema.safeParse(body.sourceDirectoryName);
+                const attachments = attachmentIdsSchema.safeParse(body.attachmentIds ?? []);
+                if (!source.success || !attachments.success || typeof body.sourceBranchName !== 'string') {
+                    writeJson(response, 400, { error: 'invalid_workspace_registration' });
+                    return;
+                }
+                writeJson(response, 200, await registerChatWorktree(state, body.directory, Number(body.leaseFence), source.data, body.sourceBranchName, attachments.data));
+            }
+            else
+                writeJson(response, 200, await registerWorkspaceDirectory(state, body.directory, Number(body.leaseFence)));
+            return;
+        }
+        if (request.method === 'POST' && url.pathname === '/runtime/workspaces/directories/worktree-source') {
+            if (writeDestroyed(state, response))
+                return;
+            const body = asRecord(await readJson(request));
+            const source = workspaceDirectoryNameSchema.safeParse(body.sourceDirectoryName);
+            if (body.generation !== state.config.generation || body.runtimeEpoch !== state.runtimeEpoch || !Number.isSafeInteger(body.leaseFence)
+                || !source.success || typeof body.workspaceId !== 'string' || typeof body.sourceBranchName !== 'string') {
+                writeJson(response, 409, { error: 'invalid_workspace_registration' });
+                return;
+            }
+            writeJson(response, 200, await readWorktreeSource(state, body.workspaceId, source.data, Number(body.leaseFence), body.sourceBranchName));
             return;
         }
         const maintenance = /^\/runtime\/workspaces\/([a-f0-9-]{36})\/directories\/(cleanup|sync|stats)$/.exec(url.pathname);

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

@@ -13,9 +13,10 @@ import { ensureWorkspaceSkills } from './skills.js';
 import { checkoutBatchCommit, freezeBatchCommit } from './batch-commit.js';
 import { ensureWorkspaceArtifactInstructions } from './instructions.js';
 import { shareWorkspaceRepository } from './git.js';
+import { checkoutChatWorktree } from './worktree-checkout.js';
 const execute = promisify(execFile);
 /** Trusted Runtime registration restores immutable input; it never follows basic's current branch head. */
-export async function registerWorkspaceDirectory(state, input, leaseFence, sourceDirectoryName) {
+export async function registerWorkspaceDirectory(state, input, leaseFence, sourceDirectoryName, worktree = false) {
     const directory = workspaceDirectoryRegistrationSchema.parse(input);
     if (directory.directoryName === 'basic')
         throw new WorkspaceContextError('workspace_directory_binding_conflict');
@@ -51,7 +52,9 @@ export async function registerWorkspaceDirectory(state, input, leaseFence, sourc
             try {
                 const source = await workspaceRoot(state, directory.workspaceId, sourceDirectoryName ?? 'basic');
                 await git(source, 'cat-file', '-e', `${directory.sourceCommit}^{commit}`);
-                if (sourceDirectoryName !== undefined) {
+                if (worktree)
+                    await checkoutChatWorktree(source, staging, directory.sourceCommit, state.config.stateDir);
+                else if (sourceDirectoryName !== undefined) {
                     const frozen = await freezeBatchCommit({ source: { workspaceId: directory.workspaceId, root: source },
                         commitHash: directory.sourceCommit, snapshotId: `directory-${directory.remixId}` });
                     await checkoutBatchCommit({ source: { workspaceId: directory.workspaceId, root: source }, frozen, destination: staging });

package/dist/workspace-runtime/workspaces/empty-template.js

@@ -11,6 +11,7 @@ export const EMPTY_WORKSPACE_REPOSITORY_SKILLS = [
     'playcraft-image-generation',
     'playcraft-audio-generation',
     'playcraft-image-processing',
+    'playcraft-workspace-assets',
     'playcraft-build-optimizer',
 ];
 export const EMPTY_WORKSPACE_PLATFORM_SKILLS = ['playcraft-video-understanding', 'playcraft-replica-validation'];

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

@@ -4,6 +4,7 @@ import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs
 import { join } from 'node:path';
 import { isLocalWorkspaceGitAuthMode, isLocalWorkspaceGitEnvironment, matchWorkspaceGitGatewayCloneUrl, sameWorkspaceRegistration, workspacePreparationSchema, workspaceRegistrationSchema, workspaceDirectoryNameSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceContextError } from './context-error.js';
+import { openDirectoryToDevelopment } from './directory-access.js';
 import { workspacePlatformSkillAccess } from './skill-artifact-loader.js';
 import { scaffoldEmptyWorkspace } from './empty-template.js';
 const SKILL_PREPARATION_ERRORS = new Set([
@@ -164,6 +165,11 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
     }
     await mkdir(workspace, { recursive: true, mode: 0o700 });
     await rename(staging, target);
+    // The terminal and Codex run as the development user, so a checkout only the control user can
+    // traverse makes every command fail with EACCES on its own cwd. The backend's root repair is
+    // skipped when it reuses a container whose binding is unchanged, so a re-prepared tree (fresh
+    // volume, reclaimed checkout) has to open itself to the development group here.
+    await openDirectoryToDevelopment(workspace, (await lstat(parent)).gid);
     receipt.status = 'published';
     await writeReceipt(receiptPath, receipt);
 }

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

@@ -0,0 +1,74 @@
+import { constants } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { attachmentIdsSchema, WORKSPACE_USER_UPLOADS_DIRECTORY } from '@playcraft/common/cloud-workspace/runtime';
+import { resolveWorkspaceAttachments } from './attachments.js';
+import { excludeFromGit } from './dependencies.js';
+async function safeParents(root, path, create = false) {
+    let current = root;
+    for (const segment of path.split('/')) {
+        if (!segment || segment === '.' || segment === '..')
+            throw new Error('workspace_worktree_attachment_unavailable');
+        current = join(current, segment);
+        if (create)
+            await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
+                throw error; });
+        const stat = await lstat(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('workspace_worktree_attachment_unavailable');
+    }
+}
+async function readSafe(root, path, max) {
+    await safeParents(root, dirname(path));
+    const handle = await open(join(root, path), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > max)
+            throw new Error('workspace_worktree_attachment_unavailable');
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function copyExact(source, target, path, limit) {
+    const body = await readSafe(source, path, limit);
+    await safeParents(target, dirname(path), true);
+    const existing = await lstat(join(target, path)).catch(() => undefined);
+    if (existing) {
+        const previous = await readSafe(target, path, limit);
+        if (!createHash('sha256').update(previous).digest().equals(createHash('sha256').update(body).digest()))
+            throw new Error('workspace_worktree_attachment_conflict');
+        return;
+    }
+    const temporary = `${join(target, path)}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, body, { flag: 'wx', mode: 0o644 });
+        await rename(temporary, join(target, path));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Copy only the selected, fully validated attachment files; retries never replace different content. */
+export async function copyWorktreeAttachments(source, target, input) {
+    const ids = [...new Set(attachmentIdsSchema.parse(input ?? []))];
+    if (!ids.length)
+        return;
+    const attachments = await resolveWorkspaceAttachments(source, ids);
+    await excludeFromGit(target, `/${WORKSPACE_USER_UPLOADS_DIRECTORY}/`);
+    for (const attachment of attachments) {
+        const prefix = `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${attachment.id}/`;
+        const files = attachment.files
+            ? attachment.files.map(file => ({ path: `${prefix}${attachment.kind === 'directory' ? `${attachment.name}/` : ''}${file.path}`, size: file.size }))
+            : [{ path: relative(source, attachment.path), size: attachment.size }];
+        for (const file of files) {
+            if (!file.path.startsWith(prefix) || file.path.split('/').some(segment => segment === '..' || !segment))
+                throw new Error('workspace_worktree_attachment_unavailable');
+            await copyExact(source, target, file.path, file.size);
+        }
+        await copyExact(source, target, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata/${attachment.id}.json`, 1024 * 1024);
+    }
+    await resolveWorkspaceAttachments(target, ids);
+}

package/dist/workspace-runtime/workspaces/worktree-checkout.js

@@ -0,0 +1,67 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { validateProjectSkillsSnapshot } from '@playcraft/common/project-skills';
+import { readWorkspaceSkills } from './skills.js';
+const execute = promisify(execFile);
+async function archiveDirectory(root) {
+    let directory = root;
+    for (const segment of ['.playcraft', 'skill-artifacts']) {
+        directory = join(directory, segment);
+        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('workspace_worktree_skill_archive_unavailable');
+    }
+}
+/** Clone the saved commit and its exact skill archives, without copying unsaved files or credentials. */
+export async function checkoutChatWorktree(source, destination, commit, stateDir) {
+    const options = { timeout: 90_000, maxBuffer: 8 * 1024 * 1024,
+        env: { PATH: process.env.PATH, HOME: stateDir, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' } };
+    const git = async (root, ...args) => (await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root, ...args], options)).stdout;
+    await execute('git', ['-c', 'core.hooksPath=/dev/null', 'clone', '--local', '--no-hardlinks', '--no-checkout', '--', source, destination], options);
+    await git(destination, 'checkout', '--detach', commit);
+    const management = await lstat(join(destination, '.playcraft')).catch(() => undefined);
+    if (management && (!management.isDirectory() || management.isSymbolicLink()))
+        throw new Error('workspace_worktree_skill_archive_unavailable');
+    const lock = await lstat(join(destination, '.playcraft/skills.lock.json')).catch(() => undefined);
+    if (!lock)
+        return;
+    const snapshot = validateProjectSkillsSnapshot(await git(destination, 'show', `${commit}:.playcraft/skills.json`), await git(destination, 'show', `${commit}:.playcraft/skills.lock.json`));
+    const copied = new Set();
+    for (const entry of snapshot.lock.entries) {
+        const path = `.playcraft/skill-artifacts/${entry.revision.artifactHash}.tar.gz`;
+        if (copied.has(path))
+            continue;
+        copied.add(path);
+        const saved = join(destination, path);
+        if (await lstat(saved).catch(() => undefined))
+            throw new Error('workspace_worktree_skill_archive_tracked');
+        const original = join(source, path);
+        if (!await lstat(original).catch(() => undefined))
+            continue;
+        if (await realpath(dirname(original)).catch(() => '') !== join(source, '.playcraft/skill-artifacts'))
+            throw new Error('workspace_worktree_skill_archive_unavailable');
+        const handle = await open(original, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let archive;
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > 80 * 1024 * 1024)
+                throw new Error('workspace_worktree_skill_archive_unavailable');
+            archive = await handle.readFile();
+        }
+        finally {
+            await handle.close();
+        }
+        if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+            throw new Error('workspace_worktree_skill_archive_unavailable');
+        await archiveDirectory(destination);
+        await writeFile(saved, archive, { flag: 'wx', mode: 0o644 });
+    }
+    // Existing locked repository bytes and the exact runtime cache can fill missing archives.
+    await readWorkspaceSkills(destination, join(stateDir, 'skill-artifacts'));
+}