@playcraft/cli 0.1.80 → 0.1.82

package/dist/utils/video-evidence-git.js

@@ -1,9 +1,14 @@
 import { constants } from 'node:fs';
 import { lstat, mkdir, open, realpath } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-const ENTRY = '/.playcraft/video-replication/';
+export function ensureVideoEvidenceGitExcluded(directory) {
+    return ensureGitExcluded(directory, '/.playcraft/video-replication/');
+}
+export function ensureApkEvidenceGitExcluded(directory) {
+    return ensureGitExcluded(directory, '/.playcraft/apk-replication/');
+}
 /** Keep local analysis evidence out of a repository without changing its tracked ignore rules. */
-export async function ensureVideoEvidenceGitExcluded(directory) {
+async function ensureGitExcluded(directory, entry) {
     let root = await realpath(directory);
     while (true) {
         const marker = await lstat(join(root, '.git')).catch((error) => {
@@ -16,7 +21,7 @@ export async function ensureVideoEvidenceGitExcluded(directory) {
             if (!marker.isDirectory() || marker.isSymbolicLink())
                 return false;
             try {
-                await appendExclude(root);
+                await appendExclude(root, entry);
                 return true;
             }
             catch (error) {
@@ -31,7 +36,7 @@ export async function ensureVideoEvidenceGitExcluded(directory) {
         root = parent;
     }
 }
-async function appendExclude(root) {
+async function appendExclude(root, entry) {
     const flags = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
     const handles = [];
     let file;
@@ -57,7 +62,7 @@ async function appendExclude(root) {
                 const stat = await readable.stat();
                 if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
                     throw new Error('invalid_git_exclude');
-                if ((await readable.readFile('utf8')).split('\n').some(line => line.trim() === ENTRY))
+                if ((await readable.readFile('utf8')).split('\n').some(line => line.trim() === entry))
                     return;
             }
             finally {
@@ -69,8 +74,8 @@ async function appendExclude(root) {
         if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024 * 1024)
             throw new Error('invalid_git_exclude');
         const current = await file.readFile('utf8');
-        if (!current.split('\n').some(line => line.trim() === ENTRY)) {
-            await file.writeFile(`${current && !current.endsWith('\n') ? '\n' : ''}${ENTRY}\n`);
+        if (!current.split('\n').some(line => line.trim() === entry)) {
+            await file.writeFile(`${current && !current.endsWith('\n') ? '\n' : ''}${entry}\n`);
         }
     }
     finally {

package/dist/workspace-runtime/batch/deliver.js

@@ -1,25 +1,42 @@
 import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
-import { lstat, mkdir, open, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { hashOperationPayload, sandboxBatchMemberDeliverSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { mkdir, mkdtemp, open, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { hashOperationPayload, PREVIEW_HTML_MAX_BYTES, sandboxBatchMemberDeliverSchema, WORKSPACE_PLAYABLE_OUTPUT_PATH, } from '@playcraft/common/cloud-workspace/runtime';
+import { finalizeWorkspacePlayable, validateWorkspacePlayable } from '../previews/finalize.js';
 import { claimBatchDirectory, withDirectoryOwner } from '../server/directory-access.js';
-import { runDeveloperCommand } from '../workspaces/developer-command.js';
+import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
+import { artifactPath } from '../workspaces/artifact-files.js';
+import { markAudioBuildInputs, verifyAudioBuildInputs } from '../workspaces/audio-assets/build-inputs.js';
+import { isolateWorkspaceForBuild } from '../workspaces/build-isolation.js';
+import { launcherSocket, runDeveloperCommand } from '../workspaces/developer-command.js';
+import { openDirectoryToDevelopment, openScratchToDevelopment } from '../workspaces/directory-access.js';
 import { workspaceRoot } from '../workspaces/registry.js';
+import { workspaceGroup, writeSharedFile } from '../workspaces/shared-write.js';
+import { withShareRepair } from '../workspaces/workspace-shares.js';
 import { processHasExited, runProcessGroup, stopProcessGroup } from './processes.js';
 import { stopMemberWriters } from './writer-proof.js';
 import { memberStatus, readMember, readStopMarker, serializeRun, writeMember, } from './records.js';
-/** Base build writes dist/index.html. Channel packaging is done by platform export. */
+const DELIVERY_OUTPUT_PATH = 'dist/index.html';
+/** Compile the review playable once in a fresh copy. Keep the existing custom builder contract. */
 function buildCommand() {
-    return (process.env.PLAYCRAFT_BATCH_BUILD_COMMAND
-        ?? 'umask 002 && CI=1 playcraft build --base --output dist .');
+    const custom = process.env.PLAYCRAFT_BATCH_BUILD_COMMAND;
+    const outputPath = custom ? DELIVERY_OUTPUT_PATH : WORKSPACE_PLAYABLE_OUTPUT_PATH;
+    const build = custom || 'umask 002 && CI=1 PLAYCRAFT_BUILD_ISOLATED=1 playcraft build .';
+    const directory = dirname(outputPath);
+    return {
+        outputPath,
+        command: [
+            `(${build})`,
+            `test ! -L dist && test ! -L ${directory} && test ! -L ${outputPath}`,
+            `chmod g+rX dist ${directory} ${outputPath}`,
+        ].join(' && '),
+    };
 }
 /**
- * The batch build runs as the runtime identity while the agent wrote the tree as the development
- * identity. Directories the agent created private (browser profiles, tool caches) are unreadable to
- * the build user, and the build's pre-build scan fails hard on the first one — which is how a
- * delivered-looking member used to end as `batch_build_failed`. Only the owning identity may chmod,
- * so the repair has to run through the launcher rather than the runtime user.
+ * The controller also reads the member tree. Only the development identity can grant group access
+ * to the private files and directories it created.
  */
 const PERMISSION_REPAIR_COMMAND = [
     'find . \\( -path ./node_modules -o -path ./.git \\) -prune -o',
@@ -32,6 +49,16 @@ const BUILD_LOG_LIMIT = 64 * 1024;
 async function repairGroupAccess(state, root, runId) {
     let output = '';
     try {
+        if (launcherSocket(state)) {
+            // Earlier deliveries built as the controller, leaving these caches owned by it.
+            const group = await workspaceGroup(root);
+            for (const directory of ['.cache', 'temp', 'library', 'build', 'dist']) {
+                await openDirectoryToDevelopment(join(root, directory), group).catch(error => {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                });
+            }
+        }
         const outcome = await runDeveloperCommand(state, {
             processId: `batch-deliver-repair-${runId}-${randomUUID()}`,
             cwd: root,
@@ -55,19 +82,24 @@ async function writeBuildLog(state, runId, text) {
     await mkdir(directory, { recursive: true });
     await writeFile(join(directory, 'build.log'), text.slice(-BUILD_LOG_LIMIT));
 }
-/** A build command that writes nothing must not inherit an earlier run's index.html as success. */
-async function clearBuiltHtml(root) {
-    await rm(join(root, 'dist', 'index.html'), { force: true }).catch(() => undefined);
-}
-async function readBuiltHtml(root) {
-    const htmlPath = join(root, 'dist', 'index.html');
-    const info = await lstat(htmlPath).catch(() => undefined);
-    if (!info?.isFile() || info.isSymbolicLink())
-        throw new Error('batch_build_failed');
-    const handle = await open(htmlPath, constants.O_RDONLY | constants.O_NOFOLLOW).catch(() => {
+async function readBuiltHtml(root, path) {
+    try {
+        const handle = await open(await artifactPath(root, path), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > PREVIEW_HTML_MAX_BYTES)
+                throw new Error('preview_not_single_file');
+            const bytes = await handle.readFile();
+            validateWorkspacePlayable(bytes);
+            return bytes;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
         throw new Error('batch_build_failed');
-    });
-    await handle.close();
+    }
 }
 async function prove(record) {
     let stopped = true;
@@ -97,9 +129,9 @@ export async function deliverBatchMember(state, body) {
         const existing = await readMember(state, command.runId);
         if (existing && command.ownerFence < existing.ownerFence)
             throw new Error('stale_owner');
-        if (existing?.state === 'completed' &&
-            existing.phase === 'deliver' &&
-            existing.evidence &&
+        if (existing?.phase === 'deliver' &&
+            existing.writersStopped &&
+            (existing.state === 'failed' || (existing.state === 'completed' && existing.evidence)) &&
             existing.commandHash?.deliver === hash &&
             existing.ownerFence === command.ownerFence) {
             return memberStatus(existing);
@@ -110,6 +142,10 @@ export async function deliverBatchMember(state, body) {
             return memberStatus(existing);
         if (await readStopMarker(state, command.runId))
             return memberStatus(await markStopped(state, command, existing));
+        if (existing?.phase === 'generate' && !existing.writersStopped)
+            return memberStatus(existing);
+        if (existing?.processes.some(process => process.role === 'build' && !processHasExited(process)))
+            return memberStatus(existing);
         if (existing &&
             existing.ownerFence === command.ownerFence &&
             existing.commandHash?.deliver &&
@@ -133,6 +169,7 @@ export async function deliverBatchMember(state, body) {
                 stopRequested: false,
                 processes: existing?.processes ?? [],
                 sessionId: existing?.sessionId,
+                scratchDir: existing?.scratchDir,
                 operationId: existing?.operationId,
                 evidence: existing?.evidence,
                 commandHash: { ...existing?.commandHash, deliver: hash },
@@ -146,30 +183,51 @@ export async function deliverBatchMember(state, body) {
                         ?.sourceCommit,
                 beforeTree: existing?.beforeTree,
             });
+            let buildLog = '';
             try {
                 if (await readStopMarker(state, command.runId))
                     return memberStatus(await markStopped(state, command, record));
-                const repairOutput = await repairGroupAccess(state, root, command.runId);
-                await clearBuiltHtml(root);
-                const built = await runProcessGroup(root, buildCommand(), 'build', async (process) => {
-                    record = await writeMember(state, { ...record, processes: [...record.processes, process] });
-                });
-                record = await writeMember(state, {
-                    ...record,
-                    processes: record.processes.map((process) => process.pid === built.process.pid ? built.process : process),
+                buildLog = await repairGroupAccess(state, root, command.runId);
+                const group = await workspaceGroup(root);
+                const scratch = record.scratchDir ?? await mkdtemp(join(tmpdir(), 'playcraft-batch-'));
+                if (!record.scratchDir) {
+                    try {
+                        await openScratchToDevelopment(scratch, group);
+                        record = await writeMember(state, { ...record, scratchDir: scratch });
+                    }
+                    catch (error) {
+                        await rm(scratch, { recursive: true, force: true }).catch(() => undefined);
+                        throw error;
+                    }
+                }
+                // Scratch remains recorded until the run proves all writers stopped, including on cancellation.
+                const project = await mkdtemp(join(scratch, 'delivery-'));
+                const audioInputs = await isolateWorkspaceForBuild(root, project);
+                // The controller owns the copied files. Cocos updates metadata throughout the copy as the development user.
+                await openDirectoryToDevelopment(project, group);
+                if (await readStopMarker(state, command.runId))
+                    return memberStatus(await markStopped(state, command, record));
+                const saveProcess = async (process) => {
+                    const others = record.processes.filter(item => item.role !== 'build' || (process.launcher
+                        ? item.launcher?.processId !== process.launcher.processId
+                        : item.pid !== process.pid));
+                    record = await writeMember(state, { ...record, processes: [...others, process] });
+                };
+                const build = buildCommand();
+                const built = await runProcessGroup(project, build.command, 'build', saveProcess, {
+                    state, processId: `batch-build-${command.runId}-${randomUUID()}`,
                 });
+                await saveProcess(built.process);
+                buildLog = [buildLog, built.output].filter(Boolean).join('\n');
                 if (await readStopMarker(state, command.runId))
                     return memberStatus(await markStopped(state, command, record));
-                const buildLog = [repairOutput, built.output].filter(Boolean).join('\n');
                 if (built.code !== 0) {
-                    await writeBuildLog(state, command.runId, buildLog).catch(() => undefined);
                     const tail = built.output.trim().split('\n').slice(-3).join(' | ').slice(0, 400);
                     if (tail)
                         console.warn(`[workspace-runtime] batch build failed run=${command.runId} code=${built.code}: ${tail}`);
                     throw new Error('batch_build_failed');
                 }
                 await writeBuildLog(state, command.runId, buildLog).catch(() => undefined);
-                await readBuiltHtml(root);
                 const writersStopped = await prove(record);
                 if (!writersStopped)
                     return memberStatus(await writeMember(state, {
@@ -177,9 +235,20 @@ export async function deliverBatchMember(state, body) {
                         state: 'stopping',
                         writersStopped: false,
                         holding: true,
+                        error: 'batch_build_failed',
                     }));
+                const html = await readBuiltHtml(project, build.outputPath);
+                await verifyAudioBuildInputs(root, audioInputs);
                 if (await readStopMarker(state, command.runId))
                     return memberStatus(await markStopped(state, command, record));
+                // Keep the delivery entry point and register the same build as the current workspace preview.
+                await withShareRepair(state, root, () => writeSharedFile(root, join(root, DELIVERY_OUTPUT_PATH), html));
+                const source = {
+                    sessionId: record.sessionId,
+                    operationId: `batch-delivery:${command.runId}:${state.config.generation}`,
+                };
+                await withShareRepair(state, root, () => finalizeWorkspacePlayable(root, markAudioBuildInputs(html, audioInputs), 'batch delivery', { source }));
+                await refreshWorkspaceArtifacts(state, command.workspaceId, undefined, command.directoryName);
                 record = await writeMember(state, {
                     ...record,
                     state: 'completed',
@@ -191,6 +260,8 @@ export async function deliverBatchMember(state, body) {
                 return memberStatus(record);
             }
             catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                await writeBuildLog(state, command.runId, `${buildLog}\n[build] ${detail}`).catch(() => undefined);
                 const code = error instanceof Error && /^[a-z0-9_]+$/.test(error.message)
                     ? error.message
                     : 'batch_deliver_failed';
@@ -222,6 +293,7 @@ async function markStopped(state, command, existing) {
         stopRequested: true,
         processes: existing?.processes ?? [],
         sessionId: existing?.sessionId,
+        scratchDir: existing?.scratchDir,
         operationId: existing?.operationId,
         headCommit: existing?.headCommit,
         evidence: existing?.evidence,

package/dist/workspace-runtime/batch/generate.js

@@ -1,5 +1,7 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { access, mkdir, mkdtemp, realpath, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { hashOperationPayload, operationScopeKey, sandboxBatchMemberGenerateSchema, } from '@playcraft/common/cloud-workspace/runtime';
@@ -7,11 +9,14 @@ import { attachNativeCollector, executeOperation } from '../server/dispatch.js';
 import { claimBatchDirectory, withDirectoryOwner } from '../server/directory-access.js';
 import { workspaceRoot } from '../workspaces/registry.js';
 import { snapshotWorkspaceTree } from '../workspaces/git.js';
+import { openScratchToDevelopment } from '../workspaces/directory-access.js';
+import { workspaceGroup } from '../workspaces/shared-write.js';
 import { requireBatchContentChanges } from './content-changes.js';
 import { bindMemberPolicy, memberExecutionPolicy } from './policy.js';
 import { processHasExited, stopProcessGroup } from './processes.js';
 import { memberStatus, readMember, readStopMarker, serializeRun, writeMember } from './records.js';
 import { stopMemberWriters } from './writer-proof.js';
+const LOCAL_CHROMIUM = '/opt/playcraft/renderer-arm64/chromium';
 function hashCommand(value) {
     return hashOperationPayload(value);
 }
@@ -68,6 +73,25 @@ async function proveStopped(record) {
     }
     return stopped;
 }
+async function createMemberScratch(root) {
+    // Chromium creates Unix sockets below TMPDIR, so keep the base path short.
+    const scratch = await realpath(await mkdtemp(join(process.platform === 'win32' ? tmpdir() : '/tmp', 'pc-')));
+    try {
+        const group = await workspaceGroup(root);
+        const config = join(scratch, 'config');
+        const cache = join(scratch, 'cache');
+        await mkdir(config);
+        await mkdir(cache);
+        await openScratchToDevelopment(config, group);
+        await openScratchToDevelopment(cache, group);
+        await openScratchToDevelopment(scratch, group);
+        return scratch;
+    }
+    catch (error) {
+        await rm(scratch, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}
 export async function generateBatchMember(state, body) {
     if (!body || typeof body !== 'object' || !('occupancyId' in body) || !body.occupancyId)
         throw new Error('occupancy_required');
@@ -94,11 +118,6 @@ export async function generateBatchMember(state, body) {
         return withDirectoryOwner(state, command, `run:${command.runId}`, async () => {
             const root = await workspaceRoot(state, command.workspaceId, command.directoryName);
             const sessionId = command.sessionId ?? existing?.sessionId ?? `member-${command.runId}`;
-            const tempDir = join(state.config.stateDir, 'batch-temp', command.runId);
-            // private
-            await mkdir(tempDir, { recursive: true, mode: 0o700 });
-            const policy = memberExecutionPolicy(root, tempDir);
-            await bindMemberPolicy(state, sessionId, policy, { runId: command.runId, ownerFence: command.ownerFence });
             const modelConfigId = command.model && /^[0-9a-f-]{36}$/i.test(command.model) ? command.model : undefined;
             const turnPayload = { text: command.prompt, permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}),
                 ...(command.remixReferences?.length ? { context: { files: [], skills: [], remixReferences: command.remixReferences.map(reference => ({
@@ -110,16 +129,29 @@ export async function generateBatchMember(state, body) {
                 throw new Error('batch_command_conflict');
             const sourceCommit = existing?.sourceCommit ?? state.journal.getWorkspace(command.workspaceId)?.directories?.find(directory => directory.directoryName === command.directoryName)?.sourceCommit;
             const beforeTree = existing?.beforeTree ?? (prior ? sourceCommit : await snapshotWorkspaceTree(root));
-            let record = await writeMember(state, {
+            const scratchDir = existing?.scratchDir ?? await createMemberScratch(root);
+            const initial = {
                 runId: command.runId, ownerFence: command.ownerFence, occupancyId: command.occupancyId, workspaceId: command.workspaceId,
                 directoryName: command.directoryName, phase: 'generate', state: prior ? (prior.status === 'uncertain' ? 'unknown' : prior.status === 'completed' ? 'completed' : 'running') : 'running',
                 writersStopped: false, holding: true, stopRequested: false, processes: existing?.processes ?? [], sessionId,
                 operationId: prior?.operationId, commandHash: { ...existing?.commandHash, generate: hash },
                 snapshotDigest: existing?.snapshotDigest, branchName: existing?.branchName, headCommit: existing?.headCommit,
                 evidence: existing?.evidence,
-                sourceCommit, beforeTree,
+                sourceCommit, beforeTree, scratchDir,
                 updatedAt: new Date().toISOString(),
-            });
+            };
+            let record;
+            try {
+                const localChromiumAvailable = await access(LOCAL_CHROMIUM, constants.X_OK).then(() => true, () => false);
+                const policy = memberExecutionPolicy(root, scratchDir, localChromiumAvailable ? LOCAL_CHROMIUM : undefined);
+                await bindMemberPolicy(state, sessionId, policy, { runId: command.runId, ownerFence: command.ownerFence });
+                record = await writeMember(state, initial);
+            }
+            catch (error) {
+                if (!existing?.scratchDir)
+                    await rm(scratchDir, { recursive: true, force: true }).catch(() => undefined);
+                throw error;
+            }
             if (prior)
                 return memberStatus(await finishGenerate(state, record, prior, root));
             if (!state.native?.ready()) {
@@ -293,6 +325,6 @@ async function stoppedRecord(state, command, existing) {
         stopRequested: true, processes: existing?.processes ?? [], sessionId: existing?.sessionId, operationId: existing?.operationId,
         headCommit: existing?.headCommit, evidence: existing?.evidence, commandHash: existing?.commandHash, snapshotDigest: existing?.snapshotDigest,
         branchName: existing?.branchName, updatedAt: new Date().toISOString(),
-        sourceCommit: existing?.sourceCommit, beforeTree: existing?.beforeTree,
+        sourceCommit: existing?.sourceCommit, beforeTree: existing?.beforeTree, scratchDir: existing?.scratchDir,
     });
 }

package/dist/workspace-runtime/batch/policy.js

@@ -3,13 +3,15 @@ import { randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
 const memory = new WeakMap();
 /** Unattended member execution: workspace-write to the member directory and one controlled temp dir. */
-export function memberExecutionPolicy(cwd, tempDir) {
+export function memberExecutionPolicy(cwd, scratchDir, chromiumPath) {
     return {
         cwd,
+        scratchDir,
+        chromiumPath,
         approvalPolicy: 'never',
         sandboxPolicy: {
             type: 'workspaceWrite',
-            writableRoots: [cwd, tempDir],
+            writableRoots: [cwd, scratchDir],
             networkAccess: true,
             excludeTmpdirEnvVar: true,
             excludeSlashTmp: true,

package/dist/workspace-runtime/batch/processes.js

@@ -126,7 +126,7 @@ export async function runProcessGroup(cwd, command, role, onStart, options) {
                 tracked.stopped = true;
             }
             catch (error) {
-                collect(`\n[install] ${error instanceof Error ? error.message : String(error)}\n`);
+                collect(`\n[${role}] ${error instanceof Error ? error.message : String(error)}\n`);
                 // Keep the directory occupied until the launcher confirms stop.
             }
         }

package/dist/workspace-runtime/batch/records.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { batchSourceSnapshotRefSchema, normalizeLegacyBatchSourceSnapshot, sandboxBatchMemberStatusSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { releaseBatchDirectory } from '../server/directory-access.js';
@@ -68,6 +68,9 @@ export async function writeMember(state, record) {
     const next = { ...record, updatedAt: new Date().toISOString() };
     await writeAtomic(memberFile(state, record.runId), JSON.stringify(next));
     releaseBatchDirectory(state, next);
+    if (next.scratchDir && next.writersStopped && !next.holding) {
+        await rm(next.scratchDir, { recursive: true, force: true }).catch(() => undefined);
+    }
     return next;
 }
 export async function listMembers(state) {

package/dist/workspace-runtime/batch/source-capture.js

@@ -5,6 +5,8 @@ import { dirname, isAbsolute, join, relative } from 'node:path';
 import { gzip, gunzip } from 'node:zlib';
 import { promisify } from 'node:util';
 import { WORKSPACE_REMIX_REFERENCES_MANIFEST, starterTemplateTreeHashInput, remixReferenceContentHashInput, workspaceStarterTemplateSnapshotSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { buildLocalProjectSkillsSnapshot, canonicalProjectSkillsJson, declarationDigest, inspectProjectSkills, PROJECT_SKILLS_DECLARATION_PATH, PROJECT_SKILLS_LOCK_PATH, readProjectSkillSource, readProjectSkillsLockFile, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
+import { readLockedProjectSkillSnapshot } from '../../project-skills/discovery.js';
 import { excludeFromGit } from '../workspaces/dependencies.js';
 import { batchReferenceEnvExamples, batchReferenceMetadata, } from '../workspaces/remix-references.js';
 import { gitRead, gitWrite } from './git.js';
@@ -200,8 +202,11 @@ async function inspectSource(root, files) {
         ignoredDigest: createHash('sha256').update(JSON.stringify(ignored.sort())).digest('hex'),
     };
 }
-/** Merge only the trusted engine files. Workspace instructions, skills, references and configuration remain authoritative. */
-export function mergeStarterTemplate(files, template) {
+function templateSkillRoot(path) {
+    return /^(\.agents\/skills\/[^/]+)\//.exec(path)?.[1];
+}
+/** Merge starter files; only callers that lock repository skills should include them. */
+export function mergeStarterTemplate(files, template, { includeRepositorySkills = false } = {}) {
     if ('error' in template)
         throw new Error(template.error);
     const result = workspaceStarterTemplateSnapshotSchema.safeParse(template.snapshot);
@@ -216,6 +221,22 @@ export function mergeStarterTemplate(files, template) {
         throw new Error('starter_template_invalid');
     const sourcePaths = new Set([...files.keys()].map((path) => path.toLowerCase()));
     const added = [];
+    if (includeRepositorySkills) {
+        const templatePaths = new Set(snapshot.files.map(file => file.path));
+        const skillRoots = new Set(snapshot.files.flatMap(file => {
+            const root = templateSkillRoot(file.path);
+            return root ? [root] : [];
+        }));
+        for (const root of skillRoots) {
+            if (!templatePaths.has(`${root}/SKILL.md`))
+                throw new Error('starter_template_invalid');
+        }
+        for (const path of files.keys()) {
+            const root = templateSkillRoot(path);
+            if (root && skillRoots.has(root) && !templatePaths.has(path))
+                throw new Error('starter_template_path_conflict');
+        }
+    }
     for (const file of snapshot.files) {
         const { path } = file;
         const mode = file.mode;
@@ -231,13 +252,20 @@ export function mergeStarterTemplate(files, template) {
                 .startsWith('version https://git-lfs.github.com/spec/v1'))
             throw new Error('starter_template_invalid');
         const parts = path.split('/');
+        const skillRoot = includeRepositorySkills ? templateSkillRoot(path) : undefined;
+        if (skillRoot && !included(path, new Set()))
+            throw new Error('starter_template_invalid');
         if (path === 'AGENTS.md' ||
             parts[0] === '.claude' ||
-            parts[0] === '.agents' ||
+            (parts[0] === '.agents' && !skillRoot) ||
             parts[0] === '.playcraft' ||
             parts[0] === 'references' ||
             !included(path, new Set()))
             continue;
+        if (skillRoot && files.get(path)?.body.equals(body) && files.get(path)?.mode === (mode === '100755' ? 0o755 : 0o644)) {
+            added.push(path);
+            continue;
+        }
         if (path === '.gitignore' && files.has(path)) {
             files.set(path, {
                 body: Buffer.concat([files.get(path).body, Buffer.from('\n'), body]),
@@ -257,6 +285,68 @@ export function mergeStarterTemplate(files, template) {
         throw new Error('starter_template_invalid');
     return added;
 }
+async function lockStarterSkills(staging, roots) {
+    try {
+        const previous = (await readProjectSkillsLockFile(staging)) === null
+            ? undefined
+            : await readLockedProjectSkillSnapshot(staging);
+        const entries = [];
+        for (const root of roots) {
+            const existing = previous?.declaration.entries.find(entry => entry.source.kind === 'repository' && entry.source.root === root);
+            if (existing) {
+                const source = await readProjectSkillSource(staging, existing);
+                const locked = previous?.lock.entries.find(item => item.entryKey === existing.entryKey);
+                if (locked?.sourceTreeHash !== source.sourceTreeHash)
+                    throw new Error('starter_template_path_conflict');
+                continue;
+            }
+            const key = createHash('sha256').update(root).digest('hex').slice(0, 24);
+            entries.push({
+                entryKey: `repo-${key}`,
+                source: { kind: 'repository', root, skillRef: `local-template/repo-${key}` },
+                enabled: true,
+                surface: 'sandbox-agent',
+            });
+        }
+        if (!entries.length)
+            return;
+        const addition = previous
+            ? buildLocalProjectSkillsSnapshot({
+                declaration: { schemaVersion: 1, entries },
+                sources: await Promise.all(entries.map(entry => readProjectSkillSource(staging, entry))),
+                discovered: [],
+                issues: [],
+            }, undefined, { lockVersion: previous.lock.lockVersion })
+            : buildLocalProjectSkillsSnapshot(await inspectProjectSkills(staging));
+        const { declaration } = addition;
+        if (previous) {
+            declaration.entries.unshift(...previous.declaration.entries);
+        }
+        else {
+            for (const entry of declaration.entries) {
+                if (entry.source.kind === 'repository' && roots.includes(entry.source.root))
+                    entry.enabled = true;
+            }
+        }
+        const { lock } = validateProjectSkillsSnapshot(declaration, {
+            ...addition.lock,
+            declarationHash: declarationDigest(declaration),
+            entries: [...(previous?.lock.entries ?? []), ...addition.lock.entries],
+        });
+        await mkdir(join(staging, '.playcraft'), { recursive: true });
+        for (const [path, value] of [
+            [PROJECT_SKILLS_DECLARATION_PATH, declaration],
+            [PROJECT_SKILLS_LOCK_PATH, lock],
+        ]) {
+            await writeFile(join(staging, path), `${canonicalProjectSkillsJson(value)}\n`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'starter_template_path_conflict')
+            throw error;
+        throw new Error('starter_template_invalid', { cause: error });
+    }
+}
 /** Independent root commit. The source branch, index and config are never written. */
 export async function captureIndependentSource(source, destination, starterTemplate, identity) {
     const root = await realpath(source);
@@ -315,7 +405,9 @@ export async function captureIndependentSource(source, destination, starterTempl
             }
         }
     }
-    const templatePaths = starterTemplate && inspection?.empty ? mergeStarterTemplate(files, starterTemplate) : [];
+    const templatePaths = starterTemplate && inspection?.empty
+        ? mergeStarterTemplate(files, starterTemplate, { includeRepositorySkills: true })
+        : [];
     const staging = join(dirname(destination), `.batch-source-${randomUUID()}`);
     try {
         await mkdir(staging, { recursive: true });
@@ -327,6 +419,14 @@ export async function captureIndependentSource(source, destination, starterTempl
             await mkdir(dirname(full), { recursive: true });
             await writeFile(full, file.body, { mode: file.mode, flag: 'wx' });
         }
+        const skillRoots = templatePaths.flatMap(path => {
+            const root = templateSkillRoot(path);
+            return root && path === `${root}/SKILL.md` ? [root] : [];
+        });
+        if (skillRoots.length) {
+            await lockStarterSkills(staging, skillRoots);
+            templatePaths.push(PROJECT_SKILLS_DECLARATION_PATH, PROJECT_SKILLS_LOCK_PATH);
+        }
         if (headBefore !== (await gitRead(root, ['rev-parse', '--verify', 'HEAD']).catch(() => '')))
             throw new Error('batch_source_changed');
         const after = await filterUnstableFiles(root, await readSourceFiles(root));

package/dist/workspace-runtime/codex/app-server.js

@@ -42,6 +42,8 @@ const ENGINEERING_BATCH_INSTRUCTIONS = [
 const MEMBER_EXECUTION_INSTRUCTIONS = [
     'You are implementing one assigned variant in an independent Remix directory which the platform has already created.',
     'Apply the assigned changes directly to the current working directory. The originating source is a separate directory; source freezing, variant planning and directory creation have already been handled by the platform.',
+    'For browser validation, use the executable in PLAYCRAFT_CHROMIUM_PATH when set, and otherwise use the platform browser.',
+    'Complete the implementation and applicable checks in this turn. Leave the final playable build and preview registration to the platform after the turn ends. Do not run playcraft build or publish delivery in this turn. Report your changes and checks; the platform reports the delivery build result separately.',
 ].join('\n');
 function codexReasoningEffort(effort) {
     return effort === 'max' ? 'xhigh' : effort;
@@ -334,7 +336,7 @@ export function createCodexAppServerAdapter(options) {
             if (options.config.workspaceMode === 'multi')
                 throw new NativePreparationError('workspace_skills_unavailable');
             const execution = resolveSessionExecution(cwd, permissionMode, sessionId ? options.trustedExecution?.(sessionId) : undefined, options.fixedExecution);
-            const selected = threadExecutionParams(execution);
+            const selected = threadExecutionParams(execution, asRecord(asRecord(modelConfig.config)['shell_environment_policy.set']));
             return { params: { ...modelConfig, ...selected, config: withModelShell({ ...modelConfig.config, ...selected.config }, modelConfigId),
                     ...((unattended || options.workspaceUi) ? { developerInstructions: unattended ? MEMBER_EXECUTION_INSTRUCTIONS : WORKSPACE_UI_INSTRUCTIONS } : {}) },
                 execution, modelConfigId, activate, skillsHash: undefined, discoveryHash: undefined, mcpHash: mcp?.hash };
@@ -362,7 +364,7 @@ export function createCodexAppServerAdapter(options) {
             ].join('\n');
             const discoveryHash = createHash('sha256').update(JSON.stringify(listing.skills.map(skill => skill.path).sort())).digest('hex');
             const execution = resolveSessionExecution(cwd, permissionMode, sessionId ? options.trustedExecution?.(sessionId) : undefined, options.fixedExecution);
-            const selected = threadExecutionParams(execution);
+            const selected = threadExecutionParams(execution, asRecord(asRecord(config)['shell_environment_policy.set']));
             return { params: { ...modelConfig, ...selected, config: withModelShell({ ...config, ...selected.config }, modelConfigId), developerInstructions },
                 execution, modelConfigId, activate, skillsHash: frozen.lockHash, discoveryHash, mcpHash: mcp?.hash };
         }