@playcraft/cli 0.1.57-beta → 0.1.58-beta

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

@@ -2,9 +2,9 @@ import { readdir, readFile, realpath } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { posix, relative, resolve, sep } from 'node:path';
 import JSON5 from 'json5';
-import { parameterDocumentSchema, parameterPatchPayloadSchema, parameterCatalog, validateParameterChange, workspaceRelativePathSchema, WORKSPACE_FILE_CONTENT_MAX, } from '@playcraft/common/cloud-workspace/runtime';
+import { parameterDocumentSchema, parameterPatchPayloadSchema, parameterCatalog, parameterI18nCatalog, parameterRuntimeTranslations, PARAMETER_RUNTIME_LOCALES, validateParameterChange, validateParameterI18nChange, workspaceRelativePathSchema, WORKSPACE_FILE_CONTENT_MAX, } from '@playcraft/common/cloud-workspace/runtime';
 import { InvalidWorkspacePathError, writeWorkspaceFile } from './files.js';
-import { editJson5Paths, ParameterEditError } from './json5-edit.js';
+import { editJson5Paths, editJson5StringRecords, ParameterEditError } from './json5-edit.js';
 import { prepareParameterAssetRegistration, writeParameterAssetRegistration, } from './parameter-assets.js';
 import { themeAssetIndexFingerprint } from './theme-asset-index.js';
 const MANIFEST_PATH = '.playcraft/workspace.json';
@@ -32,6 +32,7 @@ async function sourceFingerprint(root, located, ownIndexWrite) {
         readOptionalText(root, MANIFEST_PATH),
         readOptionalText(root, THEME_INDEX_PATH),
         selectedIndex ? readOptionalText(root, selectedIndex) : undefined,
+        located.schemaPath ? readOptionalText(root, runtimeI18nGlobalPath(located.schemaPath)) : undefined,
     ]);
     const hashes = sources.map((text) => text === undefined ? null : createHash('sha256').update(text).digest('hex'));
     const rawIndexHash = hashes[4];
@@ -106,6 +107,10 @@ async function readParameterDocuments(root, revisions, located) {
             ? { platformI18n: platformFile.value, platformI18nPath: i18nPath }
             : {}),
     };
+    const runtimeI18n = await readRuntimeI18n(root, revisions, located);
+    if (runtimeI18n.errors.length)
+        return parameterDocumentSchema.parse({ ...schemaDocument, status: 'invalid', errors: runtimeI18n.errors });
+    Object.assign(schemaDocument, runtimeI18n.document ? { runtimeI18n: runtimeI18n.document } : {});
     if (platformFile.status === 'invalid') {
         return parameterDocumentSchema.parse({
             ...schemaDocument,
@@ -148,6 +153,8 @@ async function readParameterDocuments(root, revisions, located) {
 export async function patchWorkspaceParameters(root, revisions, payload, observed, options = {}) {
     const parsed = parameterPatchPayloadSchema.parse(payload);
     const document = await readWorkspaceParameters(root, revisions);
+    if ('documentId' in parsed)
+        return patchWorkspaceParameterI18n(root, document, parsed, observed);
     if (document.status === 'invalid')
         throw new ParameterEditError('parameter_document_invalid');
     if (document.status === 'missing' || document.status === 'schema_only' || !document.dataPath) {
@@ -169,7 +176,7 @@ export async function patchWorkspaceParameters(root, revisions, payload, observe
     if (observed && createHash('sha256').update(source).digest('hex') !== observed.contentHash) {
         throw new ParameterEditError('revision_conflict');
     }
-    const next = editJson5Paths(source, changes);
+    const next = formatParameterData(document.dataPath, source, editJson5Paths(source, changes));
     JSON5.parse(next);
     if (Buffer.byteLength(next, 'utf8') > WORKSPACE_FILE_CONTENT_MAX) {
         throw new ParameterEditError('parameter_document_invalid');
@@ -209,6 +216,91 @@ export async function patchWorkspaceParameters(root, revisions, payload, observe
     const written = await writeWorkspaceFile(root, document.dataPath, next);
     return { ...written, ...(additionalWrites.length ? { additionalWrites } : {}) };
 }
+/** Strict data files must remain consumable by the project's original production importer. */
+function formatParameterData(path, source, edited) {
+    if (!/\.json$/i.test(path))
+        return edited;
+    const indentation = source.match(/^[\t ]+(?=")/m)?.[0] ?? (/[\r\n]/.test(source.trim()) ? '  ' : undefined);
+    const next = JSON.stringify(JSON5.parse(edited), (_key, value) => {
+        // Unknown authored values must not silently change from non-finite numbers into null.
+        if (typeof value === 'number' && !Number.isFinite(value))
+            throw new ParameterEditError('parameter_document_invalid');
+        return value;
+    }, indentation);
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    return next.replaceAll('\n', eol) + (source.endsWith('\n') ? eol : '');
+}
+async function readRuntimeI18n(root, revisions, located) {
+    if (!located.schemaPath || !located.dataPath)
+        return { errors: [] };
+    const globalPath = runtimeI18nGlobalPath(located.schemaPath);
+    const themePath = runtimeI18nThemePath(located.dataPath);
+    const [globalFile, themeFile] = await Promise.all([readOptionalJson5(root, globalPath), readOptionalJson5(root, themePath)]);
+    const errors = [];
+    if (globalFile.status === 'invalid')
+        errors.push({ path: globalPath, reason: globalFile.reason });
+    if (themeFile.status === 'invalid')
+        errors.push({ path: themePath, reason: themeFile.reason });
+    if (errors.length || globalFile.status === 'missing' && themeFile.status === 'missing')
+        return { errors };
+    return { errors, document: {
+            globalPath, themePath,
+            global: globalFile.status === 'ok' ? globalFile.value : {},
+            theme: themeFile.status === 'ok' ? themeFile.value : {},
+            ...(globalFile.status === 'ok' ? { globalHash: globalFile.contentHash } : {}),
+            ...(themeFile.status === 'ok' ? { themeHash: themeFile.contentHash } : {}),
+            globalRevision: revisions[globalPath]?.revision ?? 0,
+            themeRevision: revisions[themePath]?.revision ?? 0,
+            locales: [...PARAMETER_RUNTIME_LOCALES],
+        } };
+}
+async function patchWorkspaceParameterI18n(root, document, payload, observed) {
+    if (document.status !== 'ready' || !document.runtimeI18n)
+        throw new ParameterEditError('parameter_i18n_global_invalid');
+    const runtime = document.runtimeI18n;
+    if (payload.sourceFingerprint !== document.sourceFingerprint || observed && observed.dataPath !== runtime.themePath)
+        throw new ParameterEditError('parameter_source_conflict');
+    for (const change of payload.changes) {
+        const error = validateParameterI18nChange(document, change);
+        if (error)
+            throw new ParameterEditError(error);
+    }
+    const source = await readOptionalText(root, runtime.themePath);
+    if (observed && (source === undefined ? '' : createHash('sha256').update(source).digest('hex')) !== observed.contentHash)
+        throw new ParameterEditError('revision_conflict');
+    const globals = runtime.global;
+    const themes = runtime.theme;
+    const nextEntries = new Map();
+    const changedLocales = new Set();
+    for (const change of payload.changes) {
+        const field = parameterI18nCatalog(document, change.locale).find(entry => entry.key === change.fieldPath.join('.'));
+        const key = field.runtimeI18nKey;
+        const identity = JSON.stringify([key, change.locale]);
+        if (changedLocales.has(identity))
+            throw new ParameterEditError('parameter_changes_overlap');
+        changedLocales.add(identity);
+        const defaults = parameterRuntimeTranslations(globals[key]);
+        const previous = parameterRuntimeTranslations(themes[key]) ?? defaults;
+        const entry = nextEntries.get(key) ?? { ...previous };
+        entry[change.locale] = change.op === 'remove' ? defaults[change.locale] : change.value;
+        nextEntries.set(key, entry);
+    }
+    const edits = [...nextEntries].map(([key, value]) => PARAMETER_RUNTIME_LOCALES.every(locale => value[locale] === globals[key][locale]) ? { key, op: 'remove' } : { key, value });
+    const next = editJson5StringRecords(source ?? '{}\n', edits);
+    if (Buffer.byteLength(next, 'utf8') > WORKSPACE_FILE_CONTENT_MAX)
+        throw new ParameterEditError('parameter_document_invalid');
+    if (await sourceFingerprint(root, await locateParameterFiles(root)) !== document.sourceFingerprint)
+        throw new ParameterEditError('parameter_source_conflict');
+    if (await readOptionalText(root, runtime.themePath) !== source)
+        throw new ParameterEditError('revision_conflict');
+    return writeWorkspaceFile(root, runtime.themePath, next);
+}
+function runtimeI18nGlobalPath(schemaPath) {
+    return posix.join(posix.dirname(schemaPath), 'i18n.runtime.json5');
+}
+function runtimeI18nThemePath(dataPath) {
+    return posix.join(posix.dirname(dataPath), 'theme.i18n.runtime.json5');
+}
 async function locateParameterFiles(root) {
     const manifest = await readOptionalJson5(root, MANIFEST_PATH);
     if (manifest.status === 'invalid') {

package/dist/workspace-runtime/workspaces/platform-export.js

@@ -100,6 +100,11 @@ export async function startPlatformExport(state, input) {
         clientRequestId: `${input.clientRequestId.slice(0, 80)}:export-save`,
         payload: {},
     });
+    if (['queued', 'dispatched', 'accepted'].includes(saved.status))
+        return {
+            status: 'pending', operationId: saved.operationId, stage: 'workspace.save', builds: [],
+            nextAction: 'Finish the current turn so the queued save can run. Do not poll or wait for it within this turn. In a later turn, call the delivery tool again to continue the export.',
+        };
     if (saved.status !== 'completed')
         throw new PlatformExportError('workspace_save_failed', saved.error);
     const status = await readWorkspaceGitStatus(target.root);

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

@@ -38,6 +38,7 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
     workspaceDirectoryNameSchema.parse(directoryName);
     const target = join(workspace, directoryName);
     const receiptDir = join(state.config.stateDir, 'workspace-preparations');
+    // private
     await mkdir(receiptDir, { recursive: true, mode: 0o700 });
     const receiptPath = join(receiptDir, `${binding.workspaceId}${directoryName === 'basic' ? '' : `--${directoryName}`}.json`);
     let previous = await readReceipt(receiptPath, binding);
@@ -73,6 +74,7 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
         // Persist ownership before creating/removing a staging directory, so a crash can be retried.
         await writeReceipt(receiptPath, receipt);
         await rm(staging, { recursive: true, force: true });
+        // private
         await mkdir(staging, { mode: 0o700 });
         const access = clone?.gitAccess;
         const credential = clone?.directAccess ?? access;
@@ -163,6 +165,7 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
         if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(workspace) !== workspace)
             throw new WorkspaceContextError('invalid_workspace_directory');
     }
+    // shared
     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
@@ -234,6 +237,7 @@ async function readReceipt(path, binding) {
 }
 async function writeReceipt(path, value) {
     const temp = `${path}.tmp`;
+    // private
     await writeFile(temp, `${JSON.stringify(value)}\n`, { mode: 0o600 });
     await rename(temp, path);
 }

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

@@ -11,6 +11,7 @@ import { loadWorkspaceSkillArtifact, workspacePlatformSkillAccess } from './skil
 import { writeWorkspaceCliContext } from './cli-context.js';
 import { attachWorkspaceRemote } from './git.js';
 import { ensureWorkspaceArtifactInstructions } from './instructions.js';
+import { repairWorkspaceShares } from './workspace-shares.js';
 export { WorkspaceContextError } from './context-error.js';
 const exec = promisify(execFile);
 export function revisionScope(state, workspaceId, directoryName = 'basic') {
@@ -128,6 +129,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
                 throw new WorkspaceContextError('invalid_workspace_registration');
             // Production restores its assigned result from durable bytes, without touching basic.
             const parent = await realpath(state.config.workspaceRoot);
+            // shared
             await mkdir(join(parent, binding.workspaceId), { mode: 0o2770 }).catch(error => {
                 if (error.code !== 'EEXIST')
                     throw error;
@@ -141,6 +143,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
             // Registration publishes trusted identity. Only an explicit basic ensure restores the checkout.
             const parent = await realpath(state.config.workspaceRoot);
             const container = join(parent, binding.workspaceId);
+            // shared
             await mkdir(container, { mode: 0o2770 }).catch(error => { if (error.code !== 'EEXIST')
                 throw error; });
             const registered = { ...binding, directories };
@@ -174,7 +177,9 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
         if (binding.targetKind === 'main' && !preservedLocalBasic && (remoteUpgrade || await lstat(attachMarker).then(() => true, () => false))) {
             if (preparation?.mode !== 'clone' || !state.gitCredentials)
                 throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            // private
             await mkdir(join(state.config.stateDir, 'workspace-remote-attach'), { recursive: true, mode: 0o700 });
+            // private
             await writeFile(attachMarker, JSON.stringify({ repositoryUrl: binding.repositoryUrl, branchName: binding.branchName }), { mode: 0o600 });
             // The credential helper only serves a workspace the journal knows to be bound.
             await state.journal.putWorkspace({ ...binding, directories });
@@ -240,6 +245,12 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
         await writeWorkspaceCliContext(root, binding.workspaceId);
         await ensureWorkspaceArtifactInstructions(root);
         await state.journal.putWorkspace({ ...binding, directories });
+        // Registration is the one point every reused container reaches: the root repair is skipped
+        // when the binding did not change, so the shared subtrees repair themselves here (idempotent).
+        // Keep registration latency independent of workspace size; build and scan paths also repair.
+        void repairWorkspaceShares(state, root).catch(error => {
+            console.warn('[workspace-runtime] share repair failed:', error instanceof Error ? error.message : error);
+        });
         try {
             await readWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'), entry => loadWorkspaceSkillArtifact(state, binding.workspaceId, entry));
         }

package/dist/workspace-runtime/workspaces/remix-references.js

@@ -24,6 +24,7 @@ async function safeDirectory(root, relative = '', create = false) {
     let current = root;
     for (const segment of relative.split('/').filter(Boolean)) {
         current = join(current, segment);
+        // shared
         if (create)
             await mkdir(current, { mode: 0o755 }).catch((error) => {
                 if (error.code !== 'EEXIST')
@@ -255,9 +256,12 @@ async function importReference(root, directoryName, input, assertCurrent) {
             for (const file of files) {
                 assertCurrent();
                 await safeDirectory(stage, dirname(file.targetPath) === '.' ? '' : dirname(file.targetPath), true);
+                // shared
                 await writeFile(join(stage, file.targetPath), file.bytes, { flag: 'wx', mode: 0o644 });
             }
+            // shared
             await writeFile(join(stage, RECEIPT), JSON.stringify(record), { flag: 'wx', mode: 0o644 });
+            // shared
             await writeFile(join(stage, ATTRIBUTES), SNAPSHOT_ATTRIBUTES, { flag: 'wx', mode: 0o644 });
             await chmod(stage, 0o755);
             assertCurrent();
@@ -276,6 +280,7 @@ async function importReference(root, directoryName, input, assertCurrent) {
     await safeDirectory(rootReal, '.playcraft', true);
     const temporary = join(rootReal, '.playcraft', `.remix-references-${randomUUID()}.tmp`);
     try {
+        // shared
         await writeFile(temporary, serialized, { flag: 'wx', mode: 0o644 });
         assertCurrent();
         await safeDirectory(rootReal, '.playcraft');

package/dist/workspace-runtime/workspaces/shared-write.js

@@ -0,0 +1,187 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, chown, lstat, mkdir, open, rename, rm, } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+/**
+ * Cloud workspaces are shared by two Linux identities: the controller (`playcraft-control`) and the
+ * development user that runs agents and builds (`playcraft-dev`). Every inode either of them must
+ * read or write has to carry the development group plus group read/write (and setgid on
+ * directories, so new entries inherit that group).
+ *
+ * Only the owner of an inode can chmod/chown it, so a call that finds a foreign owner leaves the
+ * entry alone instead of failing the operation; `repairWorkspaceShares` re-runs the same shaping as
+ * the owning identity.
+ */
+export const SHARED_DIRECTORY_MODE = 0o2770;
+export const SHARED_FILE_MODE = 0o660;
+const PERMISSION_BITS = 0o7777;
+const OWNER_ONLY_ERRORS = new Set(['EPERM', 'EACCES']);
+/** The development group, read from the workspace container that owns the tree. */
+export async function workspaceGroup(workspaceRoot) {
+    const stat = await lstat(workspaceRoot);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error('invalid_workspace_directory');
+    }
+    return stat.gid;
+}
+function currentUid() {
+    return typeof process.getuid === 'function' ? process.getuid() : undefined;
+}
+/** Another identity owns this inode; only its owner can re-shape it. */
+function canShape(owner) {
+    const current = currentUid();
+    return current === undefined || current === 0 || owner === current;
+}
+function isOwnerOnly(error) {
+    const code = error?.code;
+    return typeof code === 'string' && OWNER_ONLY_ERRORS.has(code);
+}
+async function shapePath(path, groupId, mode, union = false) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink())
+        throw new Error('invalid_shared_path');
+    const desired = union ? (stat.mode & 0o777) | mode : mode;
+    if (stat.gid === groupId && (stat.mode & PERMISSION_BITS) === desired)
+        return false;
+    if (!canShape(stat.uid))
+        return false;
+    try {
+        if (stat.gid !== groupId)
+            await chown(path, stat.uid, groupId);
+        await chmod(path, desired);
+        return true;
+    }
+    catch (error) {
+        if (isOwnerOnly(error))
+            return false;
+        throw error;
+    }
+}
+async function shapeHandle(handle, groupId, mode) {
+    const stat = await handle.stat();
+    if (stat.gid === groupId && (stat.mode & PERMISSION_BITS) === mode)
+        return false;
+    if (!canShape(stat.uid))
+        return false;
+    try {
+        if (stat.gid !== groupId)
+            await handle.chown(stat.uid, groupId);
+        await handle.chmod(mode);
+        return true;
+    }
+    catch (error) {
+        if (isOwnerOnly(error))
+            return false;
+        throw error;
+    }
+}
+/** True when `target` is the root itself or lives below it. */
+export function isInsideRoot(root, target) {
+    const base = resolve(root), path = resolve(target);
+    return path === base || path.startsWith(`${base}${sep}`);
+}
+/**
+ * Chain of directories below `root` down to `target`; empty when `target` is the root itself or
+ * outside it. The root is shared by checkout preparation, never as a side effect of a write.
+ */
+function directoryChain(root, target) {
+    if (!isInsideRoot(root, target))
+        return [];
+    const parts = relative(resolve(root), resolve(target)).split(sep).filter(Boolean);
+    return parts.map((_, index) => resolve(root, ...parts.slice(0, index + 1)));
+}
+/**
+ * Shares one existing path with the development group. Returns whether the mode changed; an entry
+ * owned by the other identity is reported as unchanged because this process cannot re-shape it.
+ */
+export async function shareIfNeeded(workspaceRoot, path) {
+    const groupId = await workspaceGroup(workspaceRoot);
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink())
+        throw new Error('invalid_shared_path');
+    return shapePath(path, groupId, stat.isDirectory() ? SHARED_DIRECTORY_MODE : SHARED_FILE_MODE);
+}
+/**
+ * Shapes an existing path with an explicit group and mode. Used by the legacy helpers that receive
+ * the group from their caller (scratch trees and checkout preparation) so there is one implementation.
+ */
+export async function sharePathWithGroup(path, groupId, mode, union = false) {
+    return shapePath(path, groupId, mode, union);
+}
+/** Shapes an already open file. Cross-owner failures are tolerated like `shareIfNeeded`. */
+export async function shareHandleWithGroup(handle, groupId, mode) {
+    return shapeHandle(handle, groupId, mode);
+}
+/**
+ * Creates a directory tree both identities can use. Missing ancestors are created with the shared
+ * mode and every segment below `workspaceRoot` is re-checked, so a pre-existing private parent is
+ * repaired when this process owns it.
+ */
+export async function ensureSharedDirectory(workspaceRoot, path) {
+    const root = resolve(workspaceRoot), target = resolve(path);
+    const groupId = await workspaceGroup(root);
+    const chain = directoryChain(root, target);
+    const shapes = isInsideRoot(root, target) ? chain : [target];
+    // Reject redirected ancestors before mkdir follows them.
+    for (const directory of chain) {
+        const stat = await lstat(directory).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) {
+            throw new Error('invalid_shared_directory');
+        }
+    }
+    await mkdir(target, { recursive: true, mode: SHARED_DIRECTORY_MODE });
+    for (const directory of shapes) {
+        const stat = await lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error('invalid_shared_directory');
+        }
+        await shapePath(directory, groupId, SHARED_DIRECTORY_MODE);
+    }
+    return target;
+}
+/**
+ * Opens (optionally creating) a file the development group can read and write. The handle keeps
+ * the descriptor, so a concurrent `chmod` cannot redirect what is written.
+ */
+export async function openSharedFile(workspaceRoot, path, flags) {
+    const groupId = await workspaceGroup(workspaceRoot);
+    const handle = await open(path, flags, SHARED_FILE_MODE);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error('invalid_shared_file');
+        await shapeHandle(handle, groupId, SHARED_FILE_MODE);
+        return handle;
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
+/** Writes through a temporary file in the same directory, then renames, so readers never see a partial file. */
+export async function writeSharedFile(workspaceRoot, path, data) {
+    const root = resolve(workspaceRoot), target = resolve(path);
+    if (isInsideRoot(root, target))
+        await ensureSharedDirectory(root, dirname(target));
+    const groupId = await workspaceGroup(root);
+    const temporary = join(dirname(target), `.${basename(target)}.${randomUUID()}.tmp`);
+    try {
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, SHARED_FILE_MODE);
+        try {
+            await shapeHandle(handle, groupId, SHARED_FILE_MODE);
+            await handle.writeFile(data);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, target);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

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

@@ -1,5 +1,5 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { cp, lstat, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { load } from 'js-yaml';
 import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
@@ -9,6 +9,7 @@ import { selectPlatformSkillSnapshot } from '../../project-skills/builtin-import
 import { EMPTY_WORKSPACE_REPOSITORY_SKILLS, EMPTY_WORKSPACE_PLATFORM_SKILLS } from './empty-template.js';
 import { excludeFromGit } from './dependencies.js';
 import { selectOptionalPlatformSkills } from './optional-platform-skills.js';
+import { ensureSharedDirectory, writeSharedFile } from './shared-write.js';
 /** Runtime availability is determined by the locked metadata, independent of unsynced source edits. */
 export async function readWorkspaceSkillSnapshot(root) {
     const management = await lstat(join(root, '.playcraft'));
@@ -42,7 +43,7 @@ export async function ensureWorkspaceSkills(root, cache, access, options = {}) {
                     continue;
                 await safeDirectory(root, '.agents/skills');
                 const source = `.agents/skills/${name}`;
-                await mkdir(join(root, source), { mode: 0o755 });
+                await ensureSharedDirectory(root, join(root, source));
                 added.add(source);
                 const template = join(resolveCliPackageRoot(), 'project-template/.claude/skills', name);
                 for (const child of await readdir(template))
@@ -61,12 +62,16 @@ async function safeDirectory(root, path) {
     let current = root;
     for (const segment of path.split('/')) {
         current = join(current, segment);
-        await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
-            throw error; });
-        const stat = await lstat(current);
-        if (!stat.isDirectory() || stat.isSymbolicLink())
+        // Validate every existing segment before creating anything, so a link never redirects the tree.
+        const stat = await lstat(current).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
             throw new Error('workspace_skills_invalid');
     }
+    await ensureSharedDirectory(root, current);
     return current;
 }
 /** Cache misses may reconstruct only the exact locked repository bytes, never a newer source. */
@@ -111,14 +116,7 @@ async function lockedFiles(root, cache, entry, view, loadArtifact) {
         throw new Error('workspace_skills_invalid_bundle');
     if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
         throw new Error('workspace_skills_digest_mismatch');
-    const temporary = `${saved}.${randomUUID()}.tmp`;
-    try {
-        await writeFile(temporary, archive, { flag: 'wx', mode: 0o644 });
-        await rename(temporary, saved);
-    }
-    finally {
-        await rm(temporary, { force: true });
-    }
+    await writeSharedFile(root, saved, archive);
     return extracted.files;
 }
 function metadata(entryKey, content) {
@@ -155,6 +153,7 @@ export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
             const relative = join(entry.entryKey, file.path);
             expectedFiles.add(relative);
             await safeDirectory(generation, dirname(relative));
+            // shared
             await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(async (error) => {
                 if (error.code !== 'EEXIST')
                     throw error;

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);