@playcraft/cli 0.1.56-beta → 0.1.58-beta

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

@@ -1,5 +1,6 @@
 import { chmod, chown, lstat, readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { SHARED_DIRECTORY_MODE, SHARED_FILE_MODE, sharePathWithGroup, } from './shared-write.js';
 /** Grant development-group traversal of the workspace container without touching source checkouts. */
 export async function grantWorkspaceTraversal(root, groupId) {
     const stat = await lstat(root);
@@ -18,9 +19,7 @@ export async function openScratchToDevelopment(path, groupId) {
     const stat = await lstat(path);
     if (!stat.isDirectory() || stat.isSymbolicLink())
         throw new Error('invalid_scratch_directory');
-    if (stat.gid !== groupId)
-        await chown(path, stat.uid, groupId);
-    await chmod(path, 0o2770);
+    await sharePathWithGroup(path, groupId, SHARED_DIRECTORY_MODE);
 }
 /** The sandbox development group can edit engine directories. Symlinks never grant access outside the tree. */
 export async function openDirectoryToDevelopment(root, groupId) {
@@ -29,22 +28,18 @@ export async function openDirectoryToDevelopment(root, groupId) {
         const stat = await lstat(path);
         if (stat.isSymbolicLink())
             return;
+        // Entries owned by the other identity cannot be re-shaped from here; the owner repairs them.
         const canModify = currentUid === undefined || currentUid === 0 || stat.uid === currentUid;
-        if (canModify && stat.gid !== groupId)
-            await chown(path, stat.uid, groupId);
-        if (stat.isDirectory()) {
-            if (canModify)
-                await chmod(path, (stat.mode & 0o777) | 0o2770);
-            const entries = await readdir(path).catch(error => {
-                if (!canModify && error.code === 'EACCES')
-                    return [];
-                throw error;
-            });
-            for (const entry of entries)
-                await visit(join(path, entry));
-        }
-        else if (stat.isFile() && canModify)
-            await chmod(path, (stat.mode & 0o777) | 0o660);
+        await sharePathWithGroup(path, groupId, stat.isDirectory() ? SHARED_DIRECTORY_MODE : SHARED_FILE_MODE, stat.isFile());
+        if (!stat.isDirectory())
+            return;
+        const entries = await readdir(path).catch(error => {
+            if (!canModify && error.code === 'EACCES')
+                return [];
+            throw error;
+        });
+        for (const entry of entries)
+            await visit(join(path, entry));
     };
     await visit(root);
 }

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

@@ -25,6 +25,7 @@ async function safeDirectory(root, relative, create = false) {
     let directory = root;
     for (const part of relative.split('/')) {
         directory = join(directory, part);
+        // shared
         if (create)
             await mkdir(directory, { mode: 0o755 }).catch((error) => {
                 if (error.code !== 'EEXIST')
@@ -59,10 +60,14 @@ export async function beginWorkspaceDirectoryAttachment(root, body) {
     const staging = await safeDirectory(root, stagingPath, true);
     const id = randomUUID();
     const stage = join(staging, id);
+    // shared
     await mkdir(stage, { mode: 0o755 });
     try {
+        // shared
         await mkdir(join(stage, 'data'), { mode: 0o755 });
+        // shared
         await mkdir(join(stage, 'data', manifest.name), { mode: 0o755 });
+        // shared
         await writeFile(join(stage, 'manifest.json'), JSON.stringify(manifest), { flag: 'wx', mode: 0o644 });
         return { uploadId: id };
     }
@@ -84,6 +89,7 @@ export async function uploadWorkspaceDirectoryFile(root, id, path, request) {
             throw new Error('invalid_attachment');
         const relative = `${stagingPath}/${id}/data/${manifest.name}/${path}`;
         await safeDirectory(root, dirname(relative), true);
+        // shared
         const handle = await open(join(root, relative), constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o644);
         try {
             let size = 0;
@@ -164,9 +170,11 @@ export async function completeWorkspaceDirectoryAttachment(root, id) {
             path: `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}/${manifest.name}`, files };
         workspaceAttachmentSchema.parse(attachment);
         const target = join(uploads, id);
+        // shared
         await mkdir(target, { mode: 0o755 });
         try {
             await rename(join(stage, 'data', manifest.name), join(target, manifest.name));
+            // shared
             await writeFile(join(metadata, `${id}.json`), JSON.stringify(attachment), { flag: 'wx', mode: 0o644 });
         }
         catch (error) {

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

@@ -1,8 +1,9 @@
 import { constants } from 'node:fs';
-import { lstat, mkdir, open, realpath, rmdir } from 'node:fs/promises';
+import { lstat, mkdir, realpath, rmdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { directoryCreatePayloadSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { ensureWorkspaceRoot, InvalidWorkspacePathError } from './files.js';
+import { ensureSharedDirectory, openSharedFile } from './shared-write.js';
 const RESERVED_DIRECTORIES = new Set(['.git', 'node_modules', '.playcraft-temp']);
 export class WorkspaceDirectoryCreateError extends Error {
     code = 'directory_exists';
@@ -18,18 +19,29 @@ export async function createWorkspaceDirectory(root, input) {
     if (parts.some(part => RESERVED_DIRECTORIES.has(part)))
         throw new InvalidWorkspacePathError(path);
     const rootReal = await ensureWorkspaceRoot(root);
+    const share = async (path) => {
+        try {
+            await ensureSharedDirectory(rootReal, path);
+        }
+        catch (error) {
+            if (error.message === 'invalid_shared_directory')
+                throw new InvalidWorkspacePathError(path);
+            throw error;
+        }
+    };
     let parent = rootReal;
     for (const part of parts.slice(0, -1)) {
         parent = join(parent, part);
-        await mkdir(parent, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
-            throw error; });
+        // Created directories are visible to the development identity that runs agents and builds.
+        await share(parent);
         const stat = await lstat(parent);
         if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(parent) !== parent)
             throw new InvalidWorkspacePathError(path);
     }
     const target = join(parent, parts.at(-1));
+    // shared
     try {
-        await mkdir(target, { mode: 0o700 });
+        await mkdir(target, { mode: 0o2770 });
     }
     catch (error) {
         if (error.code !== 'EEXIST')
@@ -41,7 +53,8 @@ export async function createWorkspaceDirectory(root, input) {
     try {
         if (!(await lstat(target)).isDirectory() || await realpath(target) !== target)
             throw new InvalidWorkspacePathError(path);
-        const marker = await open(join(target, '.gitkeep'), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        await share(target);
+        const marker = await openSharedFile(rootReal, join(target, '.gitkeep'), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW);
         try {
             await marker.sync();
         }

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

@@ -6,6 +6,7 @@ import { promisify } from 'node:util';
 import { workspaceDirectoryNameSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { batchDirectoryHeld } from '../batch/occupancy.js';
 import { workspaceRoot, workspaceSessions } from './registry.js';
+import { withDirectoryWrite } from '../server/directory-access.js';
 const execute = promisify(execFile);
 const git = async (state, root, ...args) => (await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root, ...args], {
     timeout: 30_000, maxBuffer: 1024 * 1024, env: { PATH: process.env.PATH, HOME: state.config.stateDir, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
@@ -39,7 +40,7 @@ export async function cleanupWorkspaceDirectories(state, workspaceId, directoryN
         const blocked = [];
         for (const directoryName of names) {
             try {
-                await state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
+                await withDirectoryWrite(state, { workspaceId, directoryName, mode: 'exclusive', wait: false }, () => state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
                     if (await workspaceDirectoryOccupied(state, workspaceId, directoryName))
                         throw new Error('workspace_directory_occupied');
                     const root = await workspaceRoot(state, workspaceId, directoryName);
@@ -51,7 +52,7 @@ export async function cleanupWorkspaceDirectories(state, workspaceId, directoryN
                     await state.journal.putWorkspace({ ...binding, directories: [...(binding.directories ?? []).filter(item => item.directoryName !== directoryName), { ...directory, status: 'reclaimed' }] });
                     await rm(root, { recursive: true });
                     cleaned.push(directoryName);
-                });
+                }));
             }
             catch (error) {
                 blocked.push({ directoryName, reason: error instanceof Error && /^[a-z0-9_]+$/.test(error.message) ? error.message : 'workspace_cleanup_failed' });
@@ -70,42 +71,52 @@ export async function syncWorkspaceDirectories(state, workspaceId, commitHash, t
     for (const directoryName of [...new Set(targetDirectoryNames.map(name => workspaceDirectoryNameSchema.parse(name)))]) {
         if (directoryName === 'basic')
             throw new Error('workspace_sync_target_invalid');
-        await state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
-            if (await workspaceDirectoryOccupied(state, workspaceId, directoryName)) {
-                skipped.push({ directoryName, reason: 'directory_busy' });
-                return;
-            }
-            const root = await workspaceRoot(state, workspaceId, directoryName);
-            const ledger = join(state.config.stateDir, 'directory-sync', workspaceId, `${directoryName}.json`);
-            const applied = await readFile(ledger, 'utf8').then(value => JSON.parse(value), () => undefined);
-            await assertCleanAndPushed(state, root, applied?.sourceCommit === commitHash ? applied.targetCommit : undefined);
-            if (applied?.sourceCommit === commitHash && await git(state, root, 'rev-parse', 'HEAD') === applied.targetCommit) {
-                synced.push(directoryName);
-                return;
-            }
-            const containing = await git(state, root, 'merge-base', '--is-ancestor', commitHash, 'HEAD').then(() => true, () => false);
-            if (containing) {
-                synced.push(directoryName);
-                return;
-            }
-            // Import the exact preserved basic commit, without fetching a moving remote branch.
-            await execute('git', ['-c', 'core.hooksPath=/dev/null', '-C', root, 'fetch', '--no-tags', '--', basic, commitHash], { timeout: 30_000, maxBuffer: 1024 * 1024 });
-            const equivalent = (await git(state, root, 'cherry', 'HEAD', commitHash)).split('\n').some(line => line === `- ${commitHash}`);
-            if (!equivalent) {
-                try {
-                    await git(state, root, '-c', 'user.name=PlayCraft', '-c', 'user.email=playcraft@localhost', 'cherry-pick', commitHash);
+        try {
+            await withDirectoryWrite(state, { workspaceId, directoryName, mode: 'exclusive', wait: false }, () => state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
+                if (await workspaceDirectoryOccupied(state, workspaceId, directoryName)) {
+                    skipped.push({ directoryName, reason: 'directory_busy' });
+                    return;
                 }
-                catch {
-                    conflicts.push(directoryName);
+                const root = await workspaceRoot(state, workspaceId, directoryName);
+                const ledger = join(state.config.stateDir, 'directory-sync', workspaceId, `${directoryName}.json`);
+                const applied = await readFile(ledger, 'utf8').then(value => JSON.parse(value), () => undefined);
+                await assertCleanAndPushed(state, root, applied?.sourceCommit === commitHash ? applied.targetCommit : undefined);
+                if (applied?.sourceCommit === commitHash && await git(state, root, 'rev-parse', 'HEAD') === applied.targetCommit) {
+                    synced.push(directoryName);
                     return;
                 }
-            }
-            await mkdir(join(state.config.stateDir, 'directory-sync', workspaceId), { recursive: true, mode: 0o700 });
-            const temporary = `${ledger}.${randomUUID()}.tmp`;
-            await writeFile(temporary, JSON.stringify({ sourceCommit: commitHash, targetCommit: await git(state, root, 'rev-parse', 'HEAD') }), { mode: 0o600 });
-            await rename(temporary, ledger);
-            synced.push(directoryName);
-        });
+                const containing = await git(state, root, 'merge-base', '--is-ancestor', commitHash, 'HEAD').then(() => true, () => false);
+                if (containing) {
+                    synced.push(directoryName);
+                    return;
+                }
+                // Import the exact preserved basic commit, without fetching a moving remote branch.
+                await execute('git', ['-c', 'core.hooksPath=/dev/null', '-C', root, 'fetch', '--no-tags', '--', basic, commitHash], { timeout: 30_000, maxBuffer: 1024 * 1024 });
+                const equivalent = (await git(state, root, 'cherry', 'HEAD', commitHash)).split('\n').some(line => line === `- ${commitHash}`);
+                if (!equivalent) {
+                    try {
+                        await git(state, root, '-c', 'user.name=PlayCraft', '-c', 'user.email=playcraft@localhost', 'cherry-pick', commitHash);
+                    }
+                    catch {
+                        conflicts.push(directoryName);
+                        return;
+                    }
+                }
+                // private
+                await mkdir(join(state.config.stateDir, 'directory-sync', workspaceId), { recursive: true, mode: 0o700 });
+                const temporary = `${ledger}.${randomUUID()}.tmp`;
+                // private
+                await writeFile(temporary, JSON.stringify({ sourceCommit: commitHash, targetCommit: await git(state, root, 'rev-parse', 'HEAD') }), { mode: 0o600 });
+                await rename(temporary, ledger);
+                synced.push(directoryName);
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === 'directory_busy')
+                skipped.push({ directoryName, reason: 'directory_busy' });
+            else
+                throw error;
+        }
     }
     return { synced, skipped, conflicts, previewStale: true };
 }

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

@@ -1,10 +1,11 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
-import { lstat, mkdir, open, readdir, realpath, rename, rm } from 'node:fs/promises';
+import { lstat, open, readdir, realpath, rename, rm } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { z } from 'zod';
 import { directoryDeletePayloadSchema, directoryRenamePayloadSchema, hashOperationPayload, isMutableWorkspaceDirectoryPath, } from '@playcraft/common/cloud-workspace/runtime';
 import { safeAssetTransferDirectory, syncAssetTransferDirectory } from './asset-transfer-storage.js';
+import { ensureSharedDirectory } from './shared-write.js';
 export class DirectoryMutationError extends Error {
     code;
     constructor(code) {
@@ -60,6 +61,7 @@ async function validateTree(root, path) {
 async function saveRecord(directory, record) {
     await safeAssetTransferDirectory(directory);
     const temporary = join(directory, `${randomUUID()}.tmp`);
+    // private
     const file = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
     try {
         await file.writeFile(JSON.stringify(record));
@@ -183,8 +185,11 @@ export async function mutateWorkspaceDirectory(root, kind, input, options) {
         if (newPath) {
             // Reserve an absent destination atomically; only our recorded empty placeholder may be replaced.
             if (!destinationIdentity) {
-                await mkdir(destination, { mode: 0o700 }).catch(error => { if (error.code === 'EEXIST')
-                    return fail('directory_exists'); throw error; });
+                if (await lstat(destination).catch(error => { if (missing(error))
+                    return undefined; throw error; }))
+                    return fail('directory_exists');
+                // A renamed directory is a workspace entry both identities must reach.
+                await ensureSharedDirectory(root, destination);
                 record.reservation = await identity(destination);
                 await saveRecord(directory, record);
             }

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

@@ -13,6 +13,7 @@ export class InvalidWorkspacePathError extends Error {
     }
 }
 export async function ensureWorkspaceRoot(root) {
+    // private
     await mkdir(root, { recursive: true, mode: 0o700 });
     return realpath(root);
 }
@@ -37,8 +38,10 @@ export async function resolveWorkspaceFile(root, relativePath) {
 }
 export async function writeWorkspaceFile(root, relativePath, content) {
     const target = await resolveWorkspaceFile(root, relativePath);
+    // private
     await mkdir(dirname(target), { recursive: true, mode: 0o700 });
     const bytes = Buffer.from(content, 'utf8');
+    // private
     await writeFile(target, bytes, { mode: 0o600 });
     return { path: relativePath, contentHash: hashWorkspaceFileContent(content), size: bytes.byteLength };
 }
@@ -134,6 +137,7 @@ async function assertParentInsideRoot(rootReal, parent) {
     catch (error) {
         if (error.code !== 'ENOENT')
             throw error;
+        // private
         await mkdir(parent, { recursive: true, mode: 0o700 });
         const parentReal = await realpath(parent);
         assertInsideRoot(rootReal, parentReal);

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

@@ -240,6 +240,7 @@ async function configureGitFile(root, stateDir, commands, repositoryUrl) {
         gitDirectory = await open(join(pinnedRoot, '.git'), directoryFlags);
         const gitPath = process.platform === 'linux' ? `/proc/self/fd/${gitDirectory.fd}` : join(root, '.git');
         const configPath = join(gitPath, 'config');
+        // private
         lock = await open(join(gitPath, 'config.lock'), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o640);
         lockPath = join(gitPath, 'config.lock');
         const source = await open(configPath, constants.O_RDONLY | constants.O_NOFOLLOW);
@@ -254,9 +255,11 @@ async function configureGitFile(root, stateDir, commands, repositoryUrl) {
         finally {
             await source.close();
         }
+        // private
         await mkdir(stateDir, { recursive: true, mode: 0o700 });
         temporary = await mkdtemp(join(stateDir, 'git-config-'));
         const staging = join(temporary, 'config');
+        // private
         await writeFile(staging, content, { mode: 0o600 });
         await clearManagedGitConfig(staging, repositoryUrl);
         for (const args of commands)

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

@@ -39,6 +39,7 @@ export class WorkspaceGitDirectStore {
             throw new Error('git_control_directory_rejected');
         }
         for (const path of [stateDir, directory]) {
+            // private
             if (path === directory && create)
                 await mkdir(path, { mode: 0o700 }).catch(error => {
                     if (error.code !== 'EEXIST')
@@ -105,6 +106,7 @@ export class WorkspaceGitDirectStore {
             if (rejectedPassword !== undefined && old?.access?.password !== rejectedPassword)
                 return;
             const temporary = join(path, `${randomUUID()}.tmp`);
+            // private
             const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
             try {
                 await handle.writeFile(JSON.stringify({ identity: this.identity(), binding, access }));

package/dist/workspace-runtime/workspaces/json5-edit.js

@@ -33,6 +33,42 @@ export function editJson5Paths(source, changes) {
     JSON5.parse(next);
     return next;
 }
+/** Replace complete language records while preserving every unrelated authored member. */
+export function editJson5StringRecords(source, changes) {
+    const parsed = JSON5.parse(source);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new ParameterEditError('parameter_document_invalid');
+    if (new Set(changes.map(change => change.key)).size !== changes.length)
+        throw new ParameterEditError('parameter_changes_overlap');
+    let next = source;
+    for (const change of changes) {
+        if (!change.key || ['__proto__', 'prototype', 'constructor'].includes(change.key))
+            throw new ParameterEditError('parameter_value_invalid');
+        const object = readJson5Object(next, skipTrivia(next, 0, next.length));
+        const memberIndex = object.members.findIndex(member => member.name === change.key);
+        const member = object.members[memberIndex];
+        if ('op' in change) {
+            if (!member)
+                continue;
+            const comma = member.comma ?? object.members[memberIndex - 1]?.comma;
+            const spans = [{ start: member.keyStart, end: member.value.end }, ...(comma === undefined ? [] : [{ start: comma, end: comma + 1 }])].sort((left, right) => right.start - left.start);
+            for (const span of spans)
+                next = next.slice(0, span.start) + next.slice(span.end);
+        }
+        else {
+            if (!change.value || typeof change.value !== 'object' || Array.isArray(change.value) || Object.values(change.value).some(value => typeof value !== 'string'))
+                throw new ParameterEditError('parameter_value_invalid');
+            if (!member)
+                next = editJson5Paths(next, [{ fieldPath: [change.key], value: '' }]);
+            const span = findJson5ValueSpan(next, [change.key]);
+            if (!span)
+                throw new ParameterEditError('parameter_field_missing');
+            next = next.slice(0, span.start) + JSON.stringify(change.value) + next.slice(span.end);
+        }
+    }
+    JSON5.parse(next);
+    return next;
+}
 function editJson5Object(source, braceIndex, change, depth) {
     const object = readJson5Object(source, braceIndex);
     const memberIndex = object.members.findIndex((member) => member.name === change.fieldPath[depth]);

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

@@ -11,6 +11,7 @@ async function safeDirectory(root, path, create = false) {
     let directory = root;
     for (const part of path.split('/').filter(Boolean)) {
         directory = join(directory, part);
+        // shared
         if (create)
             await mkdir(directory, { mode: 0o755 }).catch((error) => {
                 if (error.code !== 'EEXIST')
@@ -173,12 +174,14 @@ async function importAttachment(root, body) {
     if (!record) {
         const temporary = join(uploads, `.import-${randomUUID()}`);
         const target = join(uploads, id);
+        // shared
         await mkdir(temporary, { mode: 0o755 });
         try {
             for (const file of files) {
                 const parent = dirname(file.path);
                 if (parent !== '.')
                     await safeDirectory(temporary, parent, true);
+                // shared
                 await writeFile(join(temporary, file.path), file.bytes, { flag: 'wx', mode: 0o644 });
             }
             const prefix = `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}`;
@@ -236,6 +239,7 @@ async function importAttachment(root, body) {
     record.clientRequestIds = [...new Set([...record.clientRequestIds, clientRequestId])];
     record.unbound ||= !sessionId;
     const tempMetadata = join(metadata, `.import-${randomUUID()}.json`);
+    // shared
     await writeFile(tempMetadata, JSON.stringify(record), { flag: 'wx', mode: 0o644 });
     await rename(tempMetadata, join(metadata, `${id}.json`));
     await chmod(join(uploads, id), 0o755);

package/dist/workspace-runtime/workspaces/parameter-agent-protocol.js

@@ -38,3 +38,5 @@ Report JSON (JavaScript Object Notation, JavaScript 对象表示法) contract (n
 - No passed/ready/live/checks fields are accepted in the report. All implementation and validation statements remain claims until platform verification.
 - If blocked or partial, preserve reviewable changes and list concrete missing work. Do not overwrite later user edits or claim multi-file changes were atomic.
 `;
+/** Initialization strategy comes from the locked skill; report validation stays platform-owned. */
+export const PARAMETER_AGENT_REPORT_PROTOCOL = PARAMETER_AGENT_PROTOCOL.slice(PARAMETER_AGENT_PROTOCOL.indexOf('Report JSON'));

package/dist/workspace-runtime/workspaces/parameter-agent-store.js

@@ -17,6 +17,7 @@ async function taskDirectory(state, workspaceId, directoryName, root) {
     }
     const scope = [state.config.environment, state.config.userId, state.config.runtimeId, workspaceId, directoryName];
     const directory = join(parent, parameterDigest(JSON.stringify(scope)));
+    // private
     await mkdir(directory, { recursive: true, mode: 0o700 });
     if ((await lstat(parent)).isSymbolicLink() || (await lstat(directory)).isSymbolicLink())
         throw new ParameterAgentError('parameter_agent_state_invalid');
@@ -47,6 +48,7 @@ export async function writePrivateParameterTask(state, task, root) {
     const directory = await taskDirectory(state, task.record.workspaceId, task.record.directoryName, root);
     const record = parameterAgentTaskRecordSchema.parse(task.record);
     const temporary = join(directory, `.${record.taskId}.${randomUUID()}.tmp`);
+    // private
     await writeFile(temporary, JSON.stringify({ ...task, record }), { mode: 0o600 });
     await rename(temporary, join(directory, `${record.taskId}.json`));
 }

package/dist/workspace-runtime/workspaces/parameter-agent.js

@@ -1,9 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { parameterAgentReportSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, parameterCatalog, stableStringify, validateParameterChange, } from '@playcraft/common/cloud-workspace/runtime';
+import { parameterAgentReportSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, parameterI18nCatalog, stableStringify, validateParameterChange, validateParameterI18nChange, } from '@playcraft/common/cloud-workspace/runtime';
 import { readWorkspaceParameters } from './parameters.js';
 import { revisionScope } from './registry.js';
 import { runDeveloperCommand } from './developer-command.js';
-import { PARAMETER_AGENT_PROTOCOL } from './parameter-agent-protocol.js';
+import { PARAMETER_AGENT_PROTOCOL, PARAMETER_AGENT_REPORT_PROTOCOL } from './parameter-agent-protocol.js';
+import { inspectParameterInitialization } from './parameter-initialization.js';
+import { inspectParameterProductionCheck, prepareParameterProductionCheck } from './parameter-production.js';
 import { ParameterAgentError, parameterDigest, parameterInputSnapshot, readParameterAgentFile } from './parameter-agent-inputs.js';
 import { listPrivateParameterTaskIds, parameterTaskWorkspace, readPrivateParameterTask, writePrivateParameterTask } from './parameter-agent-store.js';
 export { ParameterAgentError } from './parameter-agent-inputs.js';
@@ -58,14 +60,19 @@ async function inspectReport(root, task, snapshot) {
     }
     return report;
 }
-export async function prepareParameterAgentTask(state, operation, value, root) {
+export async function prepareParameterAgentTask(state, operation, value, root, options = {}) {
     const request = parameterAgentTaskRequestSchema.parse(value);
     if (operation.kind !== 'session.turn' || operation.clientRequestId !== request.taskId)
         throw new ParameterAgentError('parameter_agent_task_identity_invalid');
     const owner = scope(state, operation);
+    const skill = request.action === 'initialize' ? options.initializationSkill : undefined;
+    if (request.action === 'initialize' && (!skill || !skill.entryKey || !/^[a-f0-9]{64}$/.test(skill.lockHash) || !skill.path))
+        throw new ParameterAgentError('parameter_initialization_skill_unavailable');
     const existing = await readPrivateParameterTask(state, owner.workspaceId, owner.directoryName, request.taskId, root);
     if (existing && (existing.record.sessionId !== owner.sessionId || !current(state, existing) || stableStringify(existing.request) !== stableStringify(request)))
         throw new ParameterAgentError('parameter_agent_task_conflict');
+    if (existing && skill && (existing.record.initializationSkill?.entryKey !== skill.entryKey || existing.record.initializationSkill.lockHash !== skill.lockHash))
+        throw new ParameterAgentError('parameter_initialization_skill_changed');
     const document = await readWorkspaceParameters(root, state.journal.fileRevisions(revisionScope(state, operation.workspaceId, owner.directoryName)));
     if (request.sourceFingerprint && request.sourceFingerprint !== document.sourceFingerprint)
         throw new ParameterAgentError('parameter_source_conflict');
@@ -84,7 +91,7 @@ export async function prepareParameterAgentTask(state, operation, value, root) {
     const timestamp = now();
     const task = existing ?? {
         request, initialDigest: initial.digest, instanceToken: state.instanceToken,
-        record: { version: 1, taskId: request.taskId, action: request.action, ...(request.goal ? { goal: request.goal } : {}), ...owner, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch, status: 'running', reportPath: reportPath(request.taskId), checks: [], createdAt: timestamp, updatedAt: timestamp },
+        record: { version: 1, taskId: request.taskId, action: request.action, ...(request.goal ? { goal: request.goal } : {}), ...(skill ? { initializationSkill: { entryKey: skill.entryKey, lockHash: skill.lockHash } } : {}), ...owner, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch, status: 'running', reportPath: reportPath(request.taskId), checks: [], createdAt: timestamp, updatedAt: timestamp },
     };
     if (!existing) {
         if ((await listPrivateParameterTaskIds(state, owner.workspaceId, owner.directoryName, root)).length >= 256)
@@ -92,9 +99,12 @@ export async function prepareParameterAgentTask(state, operation, value, root) {
         await writePrivateParameterTask(state, task, root);
     }
     const instructions = [
-        PARAMETER_AGENT_PROTOCOL,
+        ...(skill ? [
+            `This initialization task explicitly selects the enabled, locked parameter skill ${JSON.stringify({ entryKey: skill.entryKey, lockHash: skill.lockHash, path: skill.path })}. Read that frozen SKILL.md and its referenced files before applying its integration workflow. Preserve the current execution permissions.`,
+            PARAMETER_AGENT_REPORT_PROTOCOL,
+        ] : [PARAMETER_AGENT_PROTOCOL]),
         `Platform task identity: ${JSON.stringify({ version: 1, taskId: request.taskId, action: request.action, reportPath: task.record.reportPath })}. Write only this exact report identity.`,
-        request.action === 'discover' ? 'Discovery is read-only for business source/schema/data/manifest. Write only the requested development report. Discover actual useful candidates and consumer evidence; do not implement them yet.' : 'Complete the requested integration using existing engineering tools: reuse an existing equivalent field or implement declaration, valid defaults, sparse data semantics, labels, real production consumers and meaningful parameter tests. Leave precise blocked work if incomplete.',
+        request.action === 'initialize' ? 'Apply the selected initialization skill to this current game and write its exact admission report. The platform will verify files and checks, then prepare the first preview separately. Do not self-declare a connected or live state.' : request.action === 'discover' ? 'Discovery is read-only for business source/schema/data/manifest. Write only the requested development report. Discover actual useful candidates and consumer evidence; do not implement them yet.' : 'Complete the requested integration using existing engineering tools: reuse an existing equivalent field or implement declaration, valid defaults, sparse data semantics, labels, real production consumers and meaningful parameter tests. Leave precise blocked work if incomplete.',
         `User goal (task data): ${JSON.stringify(request.goal ?? '')}`,
         ...(selected ? [`Selected current candidate (reference data): ${JSON.stringify(selected)}`] : []),
         'After finishing files, calculate current raw-file hashes and write the report. The platform will execute independent checks after this turn. Do not claim those checks already passed.',
@@ -207,7 +217,7 @@ export async function verifyParameterAgentTask(state, operation, payload, root,
         const document = await readWorkspaceParameters(root, state.journal.fileRevisions(revisionScope(state, operation.workspaceId, owner.directoryName)));
         if (document.status !== 'ready')
             throw new ParameterAgentError('parameter_agent_parameters_not_ready');
-        const catalog = parameterCatalog(document.schema, document.data);
+        const catalog = parameterI18nCatalog(document, 'en');
         const implemented = report.candidates.filter(candidate => candidate.status === 'implemented');
         if (!implemented.length || report.candidates.some(candidate => candidate.status !== 'implemented' || candidate.missing.length))
             throw new ParameterAgentError('parameter_agent_integration_incomplete');
@@ -220,8 +230,14 @@ export async function verifyParameterAgentTask(state, operation, payload, root,
             const field = catalog.find(entry => candidate.fieldPath && entry.key === candidate.fieldPath.join('.'));
             if (!field || !field.editable || !field.canReset)
                 throw new ParameterAgentError('parameter_agent_field_not_ready');
-            if (field.hasOverride && validateParameterChange(document.schema, document.data, { fieldPath: field.fieldPath, value: field.value }))
+            const invalidValue = field.kind === 'i18n'
+                ? validateParameterI18nChange(document, { fieldPath: field.fieldPath, locale: 'en', value: String(field.value ?? '') })
+                : field.hasOverride && validateParameterChange(document.schema, document.data, { fieldPath: field.fieldPath, value: field.value });
+            if (invalidValue)
                 throw new ParameterAgentError('parameter_agent_field_not_ready');
+            if (field.kind === 'i18n' && document.runtimeI18n &&
+                (!evidence.has(document.runtimeI18n.globalPath) || (document.runtimeI18n.themeHash && !evidence.has(document.runtimeI18n.themePath))))
+                throw new ParameterAgentError('parameter_agent_evidence_missing');
             if (!candidate.consumers.length)
                 throw new ParameterAgentError('parameter_agent_consumer_missing');
         }
@@ -230,11 +246,17 @@ export async function verifyParameterAgentTask(state, operation, payload, root,
             if (typeof packageData.scripts?.[script] !== 'string' || !packageData.scripts[script].trim())
                 throw new ParameterAgentError('parameter_agent_check_script_missing');
         }
+        const initialization = task.request.action === 'initialize'
+            ? await inspectParameterInitialization(root, document, report) : undefined;
         task.instanceToken = state.instanceToken;
-        await update(state, task, { status: 'checking', checks: [], error: undefined, receiptId: undefined, sourceDigest: before.digest }, root);
+        await update(state, task, { status: 'checking', checks: [], error: undefined, receiptId: undefined, productionCheck: undefined, sourceDigest: before.digest }, root);
         const scripts = ['test:parameters', 'build', ...(typeof packageData.scripts?.typecheck === 'string' ? ['typecheck'] : [])];
+        let productionPlan;
+        let productionEvidence;
         for (const script of scripts) {
             assertActive();
+            if (initialization && script === 'build')
+                productionPlan = await prepareParameterProductionCheck(root);
             const controller = new AbortController();
             const abort = () => controller.abort();
             options.signal?.addEventListener('abort', abort, { once: true });
@@ -269,16 +291,23 @@ export async function verifyParameterAgentTask(state, operation, payload, root,
             await writePrivateParameterTask(state, task, root);
             if (outcome.code !== 0 || outcome.timedOut || outcome.canceled)
                 throw new ParameterAgentError(outcome.timedOut ? 'parameter_agent_check_timeout' : outcome.canceled ? 'parameter_agent_check_canceled' : 'parameter_agent_check_failed');
+            if (productionPlan && script === 'build')
+                productionEvidence = await inspectParameterProductionCheck(productionPlan, assertActive);
         }
         assertActive();
         const after = await parameterInputSnapshot(root);
         if (after.digest !== before.digest || parameterDigest(await readParameterAgentFile(root, task.record.reportPath, 1024 * 1024)) !== task.reportHash)
             throw new ParameterAgentError('parameter_agent_inputs_changed');
-        return update(state, task, { status: 'verified', sourceDigest: after.digest, receiptId: randomUUID(), error: undefined }, root);
+        if (initialization && initialization !== await inspectParameterInitialization(root, document, report))
+            throw new ParameterAgentError('parameter_agent_inputs_changed');
+        if (productionPlan && stableStringify(productionEvidence) !== stableStringify(await inspectParameterProductionCheck(productionPlan, assertActive)))
+            throw new ParameterAgentError('parameter_agent_production_outputs_not_ready');
+        return update(state, task, { status: 'verified', sourceDigest: after.digest, receiptId: randomUUID(), error: undefined,
+            ...(productionEvidence ? { productionCheck: { ...productionEvidence, checkedAt: now() } } : {}) }, root);
     }
     catch (cause) {
         const code = errorCode(cause);
         const status = code === 'ENOENT' ? 'missing' : /stale|changed|expired/.test(code) ? 'stale' : /(?:not_ready|incomplete|consumer_missing|script_missing|evidence_missing)$/.test(code) ? 'needs-verification' : /report_|evidence_invalid|path_invalid/.test(code) ? 'invalid' : 'failed';
-        return update(state, task, { status, error: code === 'ENOENT' ? 'parameter_agent_report_missing' : code, receiptId: undefined }, root);
+        return update(state, task, { status, error: code === 'ENOENT' ? 'parameter_agent_report_missing' : code, receiptId: undefined, productionCheck: undefined }, root);
     }
 }

package/dist/workspace-runtime/workspaces/parameter-assets.js

@@ -159,6 +159,7 @@ export async function writeParameterAssetRegistration(root, plan) {
             throw new ParameterAssetError('parameter_asset_index_conflict');
         const parent = await lstat(dirname(target));
         const bytes = Buffer.from(plan.content);
+        // private
         staged = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
         // Metadata restoration must succeed before publication; never downgrade to a partial text write.
         await staged.chown(before.uid, before.gid);