@playcraft/cli 0.1.57-beta → 0.1.59-beta

package/dist/workspace-runtime/workspaces/storage-snapshot.js

@@ -0,0 +1,235 @@
+import { createHash } from 'node:crypto';
+import { constants, createReadStream, createWriteStream } from 'node:fs';
+import { chmod, lstat, mkdir, mkdtemp, open, readlink, readdir, realpath, rm, symlink, utimes } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip, createGzip } from 'node:zlib';
+const MAGIC = Buffer.from('PLAYCRAFT-STORAGE-1\n');
+export const STORAGE_SNAPSHOT_MAX_BYTES = 16 * 1024 * 1024 * 1024;
+const MAX_ENTRIES = 250_000, MAX_MANIFEST_BYTES = 32 * 1024 * 1024;
+const EXCLUDED = new Set(['node_modules', '.next', '.cache', '.turbo', '.vite', '.pnpm-store', '.playcraft.json']);
+function inside(root, path) {
+    const part = relative(root, path);
+    return part === '' || (!isAbsolute(part) && part !== '..' && !part.startsWith(`..${sep}`));
+}
+function excluded(path) {
+    const parts = path.split('/');
+    return parts.some(name => EXCLUDED.has(name.toLowerCase()) || /^\.playcraft-credential-/.test(name));
+}
+function safeLink(root, parent, link) {
+    // Parent traversals may precede a target, but cannot follow a symlinkable path component.
+    // For example, `link/../outside` can escape even though its lexical path looks internal.
+    return Boolean(link) && !isAbsolute(link) && !/[\0\\]/.test(link) && /^(?:\.\.\/)*(?!.*(?:^|\/)\.\.(?:\/|$)).+$/.test(link) &&
+        inside(root, resolve(parent, link));
+}
+function same(before, after) {
+    return before.dev === after.dev && before.ino === after.ino && before.mode === after.mode && before.size === after.size &&
+        before.mtimeMs === after.mtimeMs && before.ctimeMs === after.ctimeMs;
+}
+async function scan(root, options) {
+    const entries = [], excludedRoots = await Promise.all((options.excludedRoots ?? []).map(path => realpath(path).catch(() => resolve(path))));
+    let bytes = 0;
+    async function walk(directory) {
+        options.signal?.throwIfAborted();
+        const before = await lstat(directory);
+        if (!before.isDirectory() || before.isSymbolicLink() || !inside(root, await realpath(directory)))
+            throw new Error('storage_snapshot_changed');
+        for (const name of (await readdir(directory)).sort()) {
+            const source = join(directory, name), path = relative(root, source).split(sep).join('/');
+            if (excluded(path) || excludedRoots.some(item => inside(item, source)))
+                continue;
+            if (Buffer.byteLength(path) > 65_535 || /[\0\\]/.test(path))
+                throw new Error('storage_snapshot_invalid_path');
+            const info = await lstat(source);
+            if (/(?:^|\/)\.git\/objects\/info\/alternates$/.test(path))
+                throw new Error('storage_snapshot_unsupported');
+            const type = info.isSymbolicLink() ? 'symlink' : info.isDirectory() ? 'directory' : info.isFile() ? 'file' : undefined;
+            if (!type || entries.length >= MAX_ENTRIES)
+                throw new Error('storage_snapshot_unsupported');
+            const entry = { path, source, info, type, mode: info.mode & 0o777, mtime: info.mtimeMs, size: type === 'file' ? info.size : 0 };
+            if (type === 'symlink') {
+                entry.link = await readlink(source);
+                if (!safeLink(root, dirname(source), entry.link))
+                    throw new Error('storage_snapshot_unsafe_link');
+            }
+            else if (type === 'file' && /(?:^|\/)\.git$/.test(path)) {
+                if (info.size > 4096)
+                    throw new Error('storage_snapshot_unsupported');
+                const handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    const pointer = /^gitdir: ([^\r\n]+)\n?$/.exec(await handle.readFile('utf8'));
+                    if (!pointer || !inside(root, resolve(directory, pointer[1])))
+                        throw new Error('storage_snapshot_unsupported');
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            bytes += entry.size;
+            if (bytes > STORAGE_SNAPSHOT_MAX_BYTES)
+                throw new Error('storage_snapshot_too_large');
+            entries.push(entry);
+            if (type === 'directory')
+                await walk(source);
+        }
+        if (!same(before, await lstat(directory)))
+            throw new Error('storage_snapshot_changed');
+    }
+    await walk(root);
+    return entries;
+}
+export async function createStorageSnapshot(root, options = {}) {
+    const temporary = await mkdtemp(join(tmpdir(), 'playcraft-storage-'));
+    const cleanup = () => rm(temporary, { recursive: true, force: true });
+    try {
+        const canonical = await realpath(root), rootInfo = await lstat(canonical), entries = await scan(canonical, options);
+        const manifest = Buffer.from(JSON.stringify(entries.map(({ path, type, mode, mtime, size, link }) => ({ path, type, mode, mtime, size, ...(link === undefined ? {} : { link }) }))));
+        if (manifest.length > MAX_MANIFEST_BYTES)
+            throw new Error('storage_snapshot_too_large');
+        const length = Buffer.alloc(4);
+        length.writeUInt32BE(manifest.length);
+        async function* contents() {
+            yield MAGIC;
+            yield length;
+            yield manifest;
+            for (const entry of entries) {
+                options.signal?.throwIfAborted();
+                if (!same(entry.info, await lstat(entry.source)))
+                    throw new Error('storage_snapshot_changed');
+                if (entry.type !== 'file')
+                    continue;
+                const file = await open(entry.source, constants.O_RDONLY | constants.O_NOFOLLOW);
+                try {
+                    if (!same(entry.info, await file.stat()))
+                        throw new Error('storage_snapshot_changed');
+                    let bytes = 0;
+                    for await (const chunk of file.createReadStream({ autoClose: false })) {
+                        bytes += chunk.length;
+                        if (bytes > entry.size)
+                            throw new Error('storage_snapshot_changed');
+                        yield chunk;
+                    }
+                    if (bytes !== entry.size)
+                        throw new Error('storage_snapshot_changed');
+                    if (!same(entry.info, await file.stat()))
+                        throw new Error('storage_snapshot_changed');
+                }
+                finally {
+                    await file.close();
+                }
+            }
+            for (const entry of entries)
+                if (!same(entry.info, await lstat(entry.source)))
+                    throw new Error('storage_snapshot_changed');
+            if (!same(rootInfo, await lstat(canonical)))
+                throw new Error('storage_snapshot_changed');
+        }
+        const path = join(temporary, 'snapshot.gz'), hash = createHash('sha256');
+        let bytes = 0;
+        await pipeline(Readable.from(contents()), createGzip(), new Transform({ transform(chunk, _encoding, done) { bytes += chunk.length; hash.update(chunk); done(bytes > STORAGE_SNAPSHOT_MAX_BYTES ? new Error('storage_snapshot_too_large') : null, chunk); } }), 
+        // private
+        createWriteStream(path, { flags: 'wx', mode: 0o600 }), { signal: options.signal });
+        return { path, bytes, sha256: hash.digest('hex'), cleanup };
+    }
+    catch (error) {
+        await cleanup();
+        throw error;
+    }
+}
+/** Extract only a validated manifest into a newly-created private directory; create links last. */
+export async function extractStorageSnapshot(path, target, options = {}) {
+    const input = createReadStream(path), stream = input.pipe(createGunzip());
+    input.on('error', error => stream.destroy(error));
+    const iterator = stream[Symbol.asyncIterator]();
+    let chunk = Buffer.alloc(0), offset = 0, total = 0;
+    const read = async (length) => {
+        const result = Buffer.allocUnsafe(length);
+        let written = 0;
+        while (written < length) {
+            options.signal?.throwIfAborted();
+            if (offset === chunk.length) {
+                const next = await iterator.next();
+                if (next.done)
+                    throw new Error('storage_snapshot_invalid');
+                chunk = next.value;
+                offset = 0;
+                total += chunk.length;
+                if (total > STORAGE_SNAPSHOT_MAX_BYTES + MAX_MANIFEST_BYTES)
+                    throw new Error('storage_snapshot_too_large');
+            }
+            const count = Math.min(length - written, chunk.length - offset);
+            chunk.copy(result, written, offset, offset + count);
+            written += count;
+            offset += count;
+        }
+        return result;
+    };
+    try {
+        if (!(await read(MAGIC.length)).equals(MAGIC))
+            throw new Error('storage_snapshot_invalid');
+        const size = (await read(4)).readUInt32BE();
+        if (size > MAX_MANIFEST_BYTES)
+            throw new Error('storage_snapshot_too_large');
+        const entries = JSON.parse((await read(size)).toString('utf8'));
+        if (!Array.isArray(entries) || entries.length > MAX_ENTRIES)
+            throw new Error('storage_snapshot_invalid');
+        const known = new Map();
+        let bytes = 0;
+        for (const raw of entries) {
+            const entry = raw;
+            if (!entry || typeof entry.path !== 'string' || !entry.path || Buffer.byteLength(entry.path) > 65_535 || /[\0\\]/.test(entry.path) || entry.path.split('/').some(part => !part || part === '.' || part === '..') || isAbsolute(entry.path) || known.has(entry.path) ||
+                !['file', 'directory', 'symlink'].includes(entry.type) || !Number.isSafeInteger(entry.mode) || entry.mode < 0 || entry.mode > 0o777 || !Number.isFinite(entry.mtime) ||
+                !Number.isSafeInteger(entry.size) || entry.size < 0 || (entry.type !== 'file' && entry.size !== 0))
+                throw new Error('storage_snapshot_invalid');
+            const parent = dirname(entry.path);
+            if (parent !== '.' && known.get(parent)?.type !== 'directory')
+                throw new Error('storage_snapshot_invalid');
+            if (entry.type === 'symlink' && (typeof entry.link !== 'string' || !safeLink(target, join(target, parent), entry.link)))
+                throw new Error('storage_snapshot_unsafe_link');
+            bytes += entry.size;
+            if (bytes > STORAGE_SNAPSHOT_MAX_BYTES)
+                throw new Error('storage_snapshot_too_large');
+            known.set(entry.path, entry);
+        }
+        for (const entry of known.values()) {
+            const destination = join(target, entry.path);
+            // private
+            if (entry.type === 'directory')
+                await mkdir(destination, { mode: 0o700 });
+            if (entry.type !== 'file')
+                continue;
+            // private
+            const handle = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                let remaining = entry.size;
+                while (remaining > 0) {
+                    const value = await read(Math.min(64 * 1024, remaining));
+                    await handle.writeFile(value);
+                    remaining -= value.length;
+                }
+            }
+            finally {
+                await handle.close();
+            }
+            await chmod(destination, entry.mode);
+            await utimes(destination, entry.mtime / 1000, entry.mtime / 1000);
+        }
+        if (offset !== chunk.length || !(await iterator.next()).done)
+            throw new Error('storage_snapshot_invalid');
+        for (const entry of known.values())
+            if (entry.type === 'symlink')
+                await symlink(entry.link, join(target, entry.path));
+        for (const entry of [...known.values()].reverse())
+            if (entry.type === 'directory') {
+                await chmod(join(target, entry.path), entry.mode);
+                await utimes(join(target, entry.path), entry.mtime / 1000, entry.mtime / 1000);
+            }
+    }
+    finally {
+        input.destroy();
+        stream.destroy();
+        await iterator.return?.();
+    }
+}

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

@@ -138,7 +138,9 @@ async function copySnapshot(source, target, signal, hashOnly = false) {
                                 size += chunk.length;
                                 callback(size > before.size ? new WorkspaceTransferError('workspace_transfer_conflict') : null, chunk);
                             } });
-                        await pipeline(handle.createReadStream({ autoClose: false }), guard, createWriteStream(to, { flags: 'wx', mode: 0o600 }), { signal });
+                        await pipeline(handle.createReadStream({ autoClose: false }), guard, 
+                        // private
+                        createWriteStream(to, { flags: 'wx', mode: 0o600 }), { signal });
                     }
                     else {
                         for await (const chunk of handle.createReadStream({ autoClose: false })) {
@@ -366,6 +368,7 @@ export async function applyWorkspaceTransfer(root, bundle, expectedTree, options
     try {
         const bundlePath = typeof bundle === 'string' ? resolve(bundle) : join(temporary, 'incoming.bundle');
         const incoming = join(temporary, 'checkout');
+        // private
         if (typeof bundle !== 'string')
             await writeFile(bundlePath, bundle, { mode: 0o600 });
         const bundleInfo = await stat(bundlePath);

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

@@ -0,0 +1,235 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { dirname, join, relative as relativePath } from 'node:path';
+import { runDeveloperCommand } from './developer-command.js';
+import { SHARED_DIRECTORY_MODE, SHARED_FILE_MODE, sharePathWithGroup, workspaceGroup, } from './shared-write.js';
+/**
+ * Subtrees both sandbox identities read and write. Repair never walks the whole checkout: source
+ * files belong to Git and are opened once during preparation; these are the trees a session keeps
+ * writing after that point.
+ */
+export const WORKSPACE_SHARED_PATHS = [
+    '.playcraft/artifact-receipts',
+    '.playcraft/skills',
+    '.playcraft/skill-artifacts',
+    '.playcraft-temp',
+    'dist',
+];
+/** Only the root is shared here; the transaction directories below it stay private. */
+const SHARED_ROOT_ONLY = new Set(['.playcraft-temp']);
+const PERMISSION_CODES = new Set(['EACCES', 'EPERM']);
+export function isWorkspacePermissionError(error) {
+    const code = error?.code;
+    return typeof code === 'string' && PERMISSION_CODES.has(code);
+}
+/** Recognises a filesystem EACCES/EPERM, unwrapping the `cause` some guards attach. */
+export function permissionDriftFromError(error) {
+    const seen = error instanceof Error && error.cause ? error.cause : error;
+    const node = seen;
+    if (!isWorkspacePermissionError(node) || typeof node.path !== 'string' || !node.path)
+        return undefined;
+    const search = ['scandir', 'readdir', 'stat', 'access', 'opendir'].includes(String(node.syscall));
+    return { path: node.path, missing: search ? 'group_search' : 'group_write' };
+}
+/** Recognises the EACCES/EPERM line a failed command or scan leaves in its log. */
+export function permissionDriftFromOutput(output) {
+    const match = /(?:EACCES|EPERM): permission denied, (stat|scandir|open|access|readdir|mkdir|unlink|rename) '([^']+)'/
+        .exec(output);
+    if (!match)
+        return undefined;
+    const operation = match[1];
+    return {
+        path: match[2],
+        missing: operation === 'scandir' || operation === 'readdir' || operation === 'stat' || operation === 'access'
+            ? 'group_search'
+            : 'group_write',
+    };
+}
+function isMissing(error) {
+    return error?.code === 'ENOENT';
+}
+async function shapeOwnedTree(path, groupId, recursive = true) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink())
+        return { repaired: 0, foreign: false };
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+    // The other identity owns this inode; its own pass repairs the subtree.
+    if (uid !== undefined && uid !== 0 && stat.uid !== uid)
+        return { repaired: 0, foreign: true };
+    const changed = await sharePathWithGroup(path, groupId, stat.isDirectory() ? SHARED_DIRECTORY_MODE : SHARED_FILE_MODE, stat.isFile());
+    let repaired = changed ? 1 : 0;
+    let foreign = false;
+    if (!stat.isDirectory() || !recursive)
+        return { repaired, foreign };
+    const entries = await readdir(path).catch(error => {
+        // An unreadable directory can only be opened by its owner.
+        if (isWorkspacePermissionError(error)) {
+            foreign = true;
+            return [];
+        }
+        throw error;
+    });
+    for (const entry of entries) {
+        const result = await shapeOwnedTree(join(path, entry), groupId);
+        repaired += result.repaired;
+        foreign ||= result.foreign;
+    }
+    return { repaired, foreign };
+}
+function missingShare(stat, groupId) {
+    if (stat.gid !== groupId)
+        return 'group_write';
+    const mode = Number(stat.mode);
+    if (stat.isDirectory()) {
+        if ((mode & 0o010) === 0)
+            return 'group_search';
+        if ((mode & 0o060) !== 0o060 || (mode & 0o2000) === 0)
+            return 'group_write';
+    }
+    else if ((mode & 0o020) === 0)
+        return 'group_write';
+    return undefined;
+}
+/**
+ * Lists entries of the shared subtrees that lost development-group access. Read-only: the owner of
+ * each entry (or `repairWorkspaceShares` at registration) is what changes them.
+ */
+export async function diagnoseWorkspaceShares(root, scope = 'workspace') {
+    const groupId = await workspaceGroup(root);
+    const targets = scope === 'workspace'
+        ? WORKSPACE_SHARED_PATHS.map((path) => join(root, path))
+        : [scope];
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+    const drifts = [];
+    const visit = async (path, recursive) => {
+        const stat = await lstat(path);
+        if (stat.isSymbolicLink())
+            return;
+        const missing = missingShare(stat, groupId);
+        if (missing)
+            drifts.push({ path, missing, owner: uid !== undefined && stat.uid === uid ? 'self' : 'other' });
+        if (!stat.isDirectory() || !recursive)
+            return;
+        const entries = await readdir(path).catch(error => {
+            if (isWorkspacePermissionError(error))
+                return [];
+            throw error;
+        });
+        for (const entry of entries)
+            await visit(join(path, entry), true);
+    };
+    for (const target of targets) {
+        const stat = await lstat(target).catch(error => { if (isMissing(error))
+            return undefined; throw error; });
+        if (!stat)
+            continue;
+        await visit(target, !SHARED_ROOT_ONLY.has(relativePath(root, target)));
+    }
+    return drifts;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The launcher runs commands as the development identity. Entries that identity owns cannot be
+ * re-shaped from the controller, so the same invariants are applied from the owning side.
+ */
+async function repairAsOwner(state, root, targets, groupId) {
+    if (!targets.length)
+        return 0;
+    const command = [
+        'set -u',
+        'count=0',
+        ...targets.map((target) => {
+            const quoted = shellQuote(target);
+            return [
+                `if test -e ${quoted}; then`,
+                `  n=$(find ${quoted} -uid "$(id -u)" \\( -type d ! -perm -2770 -o -type f ! -perm -g+w \\) -print 2>/dev/null | wc -l)`,
+                '  count=$((count+n))',
+                `  find ${quoted} -uid "$(id -u)" -type d ! -perm -2770 -exec chmod 2770 {} + 2>/dev/null || true`,
+                `  find ${quoted} -uid "$(id -u)" -type f ! -perm -g+w -exec chmod g+rw {} + 2>/dev/null || true`,
+                `  find ${quoted} -uid "$(id -u)" ! -group ${groupId} -exec chgrp ${groupId} {} + 2>/dev/null || true`,
+                'fi',
+            ].join('\n');
+        }),
+        'printf "repaired=%s\\n" "$count"',
+    ].join('\n');
+    let repaired = 0;
+    await runDeveloperCommand(state, {
+        processId: `share-repair-${Date.now().toString(36)}`,
+        // The target itself may be unreadable to the controller; the workspace root is not.
+        cwd: root,
+        command,
+        timeoutMs: 30_000,
+        onOutput: (chunk) => {
+            const found = /repaired=(\d+)/.exec(String(chunk));
+            if (found)
+                repaired = Math.max(repaired, Number(found[1]));
+        },
+    });
+    return repaired;
+}
+/**
+ * Re-applies the shared mode to the subtrees both identities use. Idempotent: only entries missing
+ * group access are touched. `scope` names one path when a failure already identified the drift.
+ */
+export async function repairWorkspaceShares(state, root, scope = 'workspace') {
+    const groupId = await workspaceGroup(root);
+    const targets = scope === 'workspace'
+        ? WORKSPACE_SHARED_PATHS.map((path) => ({
+            path: join(root, path),
+            recursive: !SHARED_ROOT_ONLY.has(path),
+        }))
+        : [{ path: scope, recursive: true }];
+    const existing = [];
+    let repaired = 0;
+    const foreign = [];
+    for (const target of targets) {
+        const stat = await lstat(target.path).catch(error => { if (isMissing(error))
+            return undefined; throw error; });
+        if (!stat || !stat.isDirectory() || stat.isSymbolicLink())
+            continue;
+        existing.push(target.path);
+        const result = await shapeOwnedTree(target.path, groupId, target.recursive);
+        repaired += result.repaired;
+        if (result.foreign)
+            foreign.push(target.path);
+    }
+    if (foreign.length)
+        repaired += await repairAsOwner(state, root, foreign, groupId);
+    const report = { scope, repaired, paths: existing, delegated: foreign.length > 0 };
+    if (repaired > 0 || foreign.length > 0) {
+        console.log(JSON.stringify({
+            event: 'workspace_share_repaired',
+            scope,
+            root,
+            repaired,
+            paths: existing.map((path) => (scope === 'workspace' ? path.slice(root.length + 1) : path)),
+            delegated: report.delegated,
+        }));
+    }
+    return report;
+}
+/** Repairs once and retries a read/build that failed only because of a shared-permission drift. */
+export async function withShareRepair(state, root, action, drift) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        if (!isWorkspacePermissionError(error))
+            throw error;
+        const path = drift?.path ?? permissionDriftFromError(error)?.path;
+        await repairWorkspaceShares(state, root, await driftScope(root, path));
+        return action();
+    }
+}
+/** The shared subtree (or explicit path) that contains a drifting path. */
+export async function driftScope(root, path) {
+    if (!path)
+        return 'workspace';
+    for (const relative of WORKSPACE_SHARED_PATHS) {
+        const candidate = join(root, relative);
+        if (path === candidate || path.startsWith(`${candidate}/`))
+            return candidate;
+    }
+    return dirname(path);
+}

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

@@ -11,6 +11,7 @@ async function safeParents(root, path, create = false) {
         if (!segment || segment === '.' || segment === '..')
             throw new Error('workspace_worktree_attachment_unavailable');
         current = join(current, segment);
+        // shared
         if (create)
             await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
                 throw error; });
@@ -43,6 +44,7 @@ async function copyExact(source, target, path, limit) {
         return;
     }
     const temporary = `${join(target, path)}.${randomUUID()}.tmp`;
+    // shared
     try {
         await writeFile(temporary, body, { flag: 'wx', mode: 0o644 });
         await rename(temporary, join(target, path));

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

@@ -1,22 +1,27 @@
 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 { lstat, open, realpath } 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';
+import { ensureSharedDirectory, writeSharedFile } from './shared-write.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())
+        // Reject a redirected archive directory before creating or sharing anything below it.
+        const existing = await lstat(directory).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (existing && (!existing.isDirectory() || existing.isSymbolicLink()))
             throw new Error('workspace_worktree_skill_archive_unavailable');
     }
+    await ensureSharedDirectory(root, join(root, '.playcraft/skill-artifacts'));
 }
 /** Clone the saved commit and its exact skill archives, without copying unsaved files or credentials. */
 export async function checkoutChatWorktree(source, destination, commit, stateDir) {
@@ -60,7 +65,7 @@ export async function checkoutChatWorktree(source, destination, commit, stateDir
         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 });
+        await writeSharedFile(destination, saved, archive);
     }
     // Existing locked repository bytes and the exact runtime cache can fill missing archives.
     await readWorkspaceSkills(destination, join(stateDir, 'skill-artifacts'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.57-beta",
+  "version": "0.1.59-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -23,7 +23,7 @@
   ],
   "scripts": {
     "dev": "tsc -w",
-    "build": "node scripts/generate-asset-skills.mjs && node scripts/generate-video-skills.mjs && node scripts/generate-preview-runtime.mjs && tsc",
+    "build": "node scripts/generate-asset-skills.mjs && node scripts/generate-video-skills.mjs && node scripts/generate-parameter-skill.mjs && node scripts/generate-preview-runtime.mjs && tsc",
     "start": "node dist/index.js",
     "test": "pnpm build && vitest run",
     "test:agent": "node scripts/run-agent-tests.mjs --list",
@@ -41,6 +41,7 @@
     "verify:platform-skills": "node scripts/generate-platform-skills.mjs --check",
     "generate:video-skills": "node scripts/generate-video-skills.mjs",
     "verify:video-skills": "node scripts/generate-video-skills.mjs --check && node --test scripts/generate-video-skills.test.mjs",
+    "verify:parameter-skill": "node scripts/generate-parameter-skill.mjs --check && node --test scripts/generate-parameter-skill.test.mjs",
     "verify:asset-skills": "node scripts/generate-asset-skills.mjs --check && node --test scripts/generate-asset-skills.test.mjs",
     "verify:agent-stop": "node scripts/verify-agent-stop.mjs",
     "verify-sprite-overlay": "node scripts/verify-sprite-overlay.mjs",
@@ -52,8 +53,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.57-beta",
-    "@playcraft/common": "0.1.57-beta",
+    "@playcraft/build": "0.1.59-beta",
+    "@playcraft/common": "0.1.59-beta",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",

package/project-template/.claude/skills/playcraft-runtime-parameters/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: playcraft-runtime-parameters
+description: Initialize or extend configurable parameters in a Cloud Workspace game by extracting real controls, connecting production consumers and a separate development preview, and generating the platform parameter panel from the project declarations.
+compatibility: agent,opencode
+version: 1.0.0
+surfaces:
+  - sandbox-agent
+metadata:
+  protocol: platform-protocol
+---
+
+# Initialize game parameters
+
+Turn the current game into a configurable engineering project. The platform renders its panel from the actual declaration; do not develop a game-specific platform panel. Work in the authorized engineering directory using the current execution mode and permissions.
+
+Read [the parameter protocol](references/platform-protocol.md) before changing configuration, then [development preview integration](references/preview-integration.md) before connecting the game. The runtime supplies the task identity, report path and report structure separately; use those exact values.
+
+## Extract and connect
+
+Inspect the production entry, engine, configuration and real consumers. Preserve existing paths, settings, scripts and gameplay. Reuse existing equivalent parameters before extracting constants. Select a bounded first group of useful controls whose effects can be tested; a game with different behavior should produce different controls. Do not copy a prior game's catalog or expose every constant.
+
+Create or extend the schema, sparse theme overrides and platform labels. Connect a neutral resolver shared by production and preview to real consumers. A field declaration or unused getter alone is incomplete. Keep current visuals and behavior as defaults. Preserve user overrides, translated text and selected resources on repeated initialization.
+
+For each consumed field, select an honest application mode: `live` for an in-place change, `restart-scene` for a change requiring a new game or scene, or `reload` when a new build is necessary. Register only real consumers. At least one meaningful live consumer should be connected when the game supports it; do not mark every field live to make initialization appear successful. Reuse the existing game's start/reset/dispose lifecycle for a restart.
+
+## Validate the generated project
+
+Add or extend `test:parameters` with executable checks for defaults, sparse overrides and changed real-consumer behavior. Keep or restore a successful production `build`; retain an existing `typecheck`. Use the separate preview entry and production release boundary described in the integration reference.
+
+The platform runs its own checks, builds the first development preview and derives capabilities from the real handshake. Report concrete incomplete work when the project cannot be adapted; do not fabricate receipts, successful builds or live capability. Preserve reviewable partial changes on failure.
+
+Initialization may need one preview build because it changes source. Subsequent ordinary value edits must use the connected runtime and existing persistence, without calling the Agent or rebuilding. Keep development runtime modules out of production output under `dist/`.

package/project-template/.claude/skills/playcraft-runtime-parameters/references/platform-protocol.md

@@ -0,0 +1,21 @@
+# Existing parameter protocol
+
+This is the Cloud Workspace-compatible interpretation of the supplied `platform-protocol` skill. Reuse its schema, `xplatform`, platform translations and sparse theme data; do not introduce a parallel `xplatform.parameter` declaration.
+
+## Declaration and defaults
+
+`.playcraft/workspace.json` may declare `parameters: {schemaPath, dataPath, themeId}`. These are engineering-relative paths and the selected theme identity. Preserve unrelated manifest keys. Prefer an existing declaration and theme layout. For a new layout, use `gamePlay.preloaded`, `gamePlay.sections` and `gamePlay.settlement` for the three game-screen areas; organize their children around the current game rather than a sample catalog.
+
+Object nodes use `type: "object"` and `properties`. Leaves use supported primitive types, valid defaults, meaningful units and known bounds or enums. Basic editable leaves support string, finite number, integer, boolean and null. Preserve existing standard `required` arrays. Unsupported references and conditional composition are not a reason to flatten complex data or silently remove constraints.
+
+Missing theme values inherit supported schema defaults. A data file containing `{}` is valid. Editing creates a raw override; restoring a default removes that override. Never write every resolved value into the theme data. Preserve comments, unknown data, unrelated overrides and empty parent objects already present in the project.
+
+Use `i18n.platform.json5` beside the schema with the same tree. `_self.title` and `_self.description` contain `zh` and `en` labels for the panel. Preserve `xplatform.ext.readonly`, ancestor read-only rules and `xplatform.showIf` / `showIfAny`. Visibility controls presentation rather than write permission.
+
+## Specialized values
+
+Image, video and other resource leaves retain `xplatform.value_type: "path"` plus `mime_type`. Preserve their actual theme/shared path resolution and production asset registration. The platform already provides local upload, shared asset library, intelligent production and engineering-file selection; generated adapters consume the selected logical path rather than adding another asset-upload implementation.
+
+Game text retains `xplatform.value_type: "i18n"` and an `i18n.runtime.<key>` reference. Keep global `i18n.runtime.json5` and per-theme `theme.i18n.runtime.json5` semantics and export the text from the real theme entry used in production. Supported languages are `en`, `zh`, `zh-TW`, `de`, `fr`, `es`, `ja`, `ko`, `pt`, `it`, `hi`, `bn`, `ur`, `ar`, `tr`, `ru`, `ms`, `id`. Keep complete language maps for overridden keys and remove an override only when its full value matches the inherited default. Explicit blank strings remain blank rather than falling back to another language.
+
+Arrays, complex structures and unsupported constraints keep their original meaning. Do not disguise them as ordinary primitive controls to obtain a writable panel. An initialization can leave such controls explicitly unsupported while connecting a useful supported set.