@playcraft/cli 0.1.55-beta → 0.1.56-beta

package/dist/commands/build.js

@@ -6,6 +6,10 @@ import { BaseBuilder, ViteBuilder, PlayableBuilder, PlayableAnalyzer, EngineDete
 import { loadBuildConfig } from '../build-config.js';
 import { cleanupBuildTempDirectory, createBuildTempDirectory } from './build-temp.js';
 import inquirer from 'inquirer';
+import { tmpdir } from 'node:os';
+import { generatedWorkspace } from '../workspace-runtime/workspaces/artifact-receipts.js';
+import { isolateWorkspaceForBuild } from '../workspace-runtime/workspaces/delivery-build.js';
+import { finalizeWorkspacePlayable, workspacePlayableSignature } from '../workspace-runtime/previews/finalize.js';
 /**
  * 类型守卫：检查对象是否符合 PlayableScriptsConfig 类型
  */
@@ -245,6 +249,38 @@ async function analyzeBaseBuild(baseBuildDir, ammoReplacement) {
 export async function buildCommand(projectPath, options) {
     // 解析项目路径 - 在 spinner 之前执行以便调试
     const resolvedProjectPath = path.resolve(projectPath);
+    const workspace = options.workspaceArtifact !== false && process.env.PLAYCRAFT_BUILD_ISOLATED !== '1' && options.mode === 'full' && options.platform === 'playcraft'
+        && (!options.format || options.format === 'html') ? await generatedWorkspace(resolvedProjectPath) : undefined;
+    const requestedOutput = options.output ? path.resolve(options.output) : path.join(resolvedProjectPath, 'dist');
+    const canonicalOutput = [path.join(resolvedProjectPath, 'dist'), path.join(resolvedProjectPath, 'dist/playable')].includes(requestedOutput);
+    if (workspace?.root === resolvedProjectPath) {
+        const prefix = requestedOutput.endsWith(path.sep) ? requestedOutput : `${requestedOutput}${path.sep}`;
+        if (requestedOutput === workspace.root || workspace.root.startsWith(prefix))
+            throw new Error('invalid_build_output');
+        const scratch = await fs.mkdtemp(path.join(tmpdir(), 'playcraft-workspace-build-'));
+        try {
+            const signature = canonicalOutput ? await workspacePlayableSignature(workspace.root) : undefined;
+            const project = path.join(scratch, 'project'), output = path.join(scratch, 'output');
+            await isolateWorkspaceForBuild(workspace.root, project);
+            await buildCommand(project, { ...options, workspaceArtifact: false, output });
+            if (canonicalOutput) {
+                const entries = await fs.readdir(output, { withFileTypes: true });
+                if (entries.length !== 1 || !entries[0].isFile() || !entries[0].name.endsWith('.html'))
+                    throw new Error('preview_not_single_file');
+                await finalizeWorkspacePlayable(workspace.root, await fs.readFile(path.join(output, entries[0].name)), 'playcraft build', { expectedSignature: signature });
+            }
+            else {
+                if (options.clean === true)
+                    await fs.rm(requestedOutput, { recursive: true, force: true });
+                await fs.cp(output, requestedOutput, { recursive: true });
+            }
+            console.log(canonicalOutput ? path.join(workspace.root, 'dist/playable/index.html') : requestedOutput);
+            return;
+        }
+        finally {
+            await fs.rm(scratch, { recursive: true, force: true });
+        }
+    }
     console.log(`[DEBUG] projectPath: ${projectPath}`);
     console.log(`[DEBUG] resolvedProjectPath: ${resolvedProjectPath}`);
     console.log(`[DEBUG] cwd: ${process.cwd()}`);
@@ -982,6 +1018,8 @@ export async function buildCommand(projectPath, options) {
         if (error.stack) {
             console.error(pc.dim(error.stack));
         }
+        if (options.workspaceArtifact === false)
+            throw error;
         process.exit(1);
     }
 }

package/dist/workspace-runtime/previews/finalize.js

@@ -0,0 +1,64 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { PREVIEW_HTML_MAX_BYTES, WORKSPACE_PLAYABLE_OUTPUT_PATH, readWorkspaceRuntimeProfile, } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactPath } from '../workspaces/artifact-files.js';
+import { captureGeneratedArtifact } from '../workspaces/artifact-receipts.js';
+import { injectPreviewDiagnostics } from './diagnostics.js';
+import { saveWorkspacePlayableOutput } from './output.js';
+import { findExternalLocalReferences } from './single-file.js';
+export function validateWorkspacePlayable(bytes) {
+    const html = bytes.toString('utf8');
+    if (!bytes.length || bytes.length > PREVIEW_HTML_MAX_BYTES || !/<(?:!doctype\s+html|html|head|title|body|script|canvas)\b/i.test(html)
+        || findExternalLocalReferences(html).length || readWorkspaceRuntimeProfile(html)) {
+        throw new Error('preview_not_single_file');
+    }
+}
+/** Reads one stable regular file, never a redirected path or a partially copied output. */
+export async function readWorkspacePlayable(root) {
+    const file = await open(await artifactPath(root, WORKSPACE_PLAYABLE_OUTPUT_PATH), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const before = await file.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > PREVIEW_HTML_MAX_BYTES)
+            throw new Error('preview_not_single_file');
+        const bytes = await file.readFile();
+        const after = await file.stat();
+        if (before.size !== bytes.length || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw new Error('artifact_file_changed');
+        return { bytes, signature: JSON.stringify([before.dev, before.ino, before.size, before.mtimeMs, before.ctimeMs]) };
+    }
+    finally {
+        await file.close();
+    }
+}
+export async function workspacePlayableSignature(root) {
+    try {
+        const file = await open(await artifactPath(root, WORKSPACE_PLAYABLE_OUTPUT_PATH), constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.nlink !== 1)
+                throw new Error('preview_not_single_file');
+            return JSON.stringify([stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs]);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** All build entry points retain the same validated bytes and an immutable generation receipt. */
+export async function finalizeWorkspacePlayable(root, built, tool, options = {}) {
+    validateWorkspacePlayable(built);
+    const bytes = injectPreviewDiagnostics(built);
+    validateWorkspacePlayable(bytes);
+    if ('expectedSignature' in options && await workspacePlayableSignature(root) !== options.expectedSignature)
+        throw new Error('preview_source_changed');
+    const current = await readWorkspacePlayable(root).catch(() => undefined);
+    if (!current?.bytes.equals(bytes))
+        await saveWorkspacePlayableOutput(root, bytes);
+    await captureGeneratedArtifact(WORKSPACE_PLAYABLE_OUTPUT_PATH, tool, {}, root, createHash('sha256').update(bytes).digest('hex'), options.source);
+}

package/dist/workspace-runtime/previews/publish.js

@@ -2,14 +2,18 @@ import { createHash } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
 import { constants } from 'node:fs';
-import { lstat, open, readdir, rm } from 'node:fs/promises';
+import { lstat, mkdtemp, open, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { PREVIEW_HTML_MAX_BYTES, PREVIEW_LOG_TAIL_MAX, WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, previewPublishResultSchema, previewReservationSchema, transitionOperation, } from '@playcraft/common/cloud-workspace/runtime';
 import { excludeFromGit, readDependencies, scheduleDependencyInstall, } from '../workspaces/dependencies.js';
 import { runDeveloperCommand } from '../workspaces/developer-command.js';
 import { revisionScope, workspaceRoot } from '../workspaces/registry.js';
 import { classifyPreviewOutput, findExternalLocalReferences } from './single-file.js';
-import { saveWorkspacePlayableOutput } from './output.js';
+import { finalizeWorkspacePlayable, workspacePlayableSignature } from './finalize.js';
+import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
+import { isolateWorkspaceForBuild } from '../workspaces/delivery-build.js';
+import { openScratchToDevelopment } from '../workspaces/directory-access.js';
 import { injectPreviewDiagnostics } from './diagnostics.js';
 import { OperationLogStore } from '../workspaces/operation-log.js';
 import { prepareRuntimePreview, RuntimePreviewBuildError } from './runtime-preview.js';
@@ -21,7 +25,7 @@ const BUILDER_TEMP_FOLDER = '.playcraft-temp';
  * The generic single-file build. `--mode full` keeps the builder from asking which stages to run.
  * Group-writable output lets the control user, a member of the development group, remove it.
  */
-const BUILD_COMMAND = 'umask 002 && playcraft build --mode full --platform playcraft --format html';
+const BUILD_COMMAND = 'umask 002 && PLAYCRAFT_BUILD_ISOLATED=1 playcraft build --mode full --platform playcraft --format html';
 class PreviewFailure extends Error {
     code;
     constructor(code) {
@@ -73,6 +77,8 @@ export async function runPreviewPublish(state, operation, root) {
     const output = { log: '' };
     const operationLog = new OperationLogStore(state.config.stateDir);
     let logChain = Promise.resolve();
+    let remotePreview = false;
+    let buildCopy;
     const appendLog = (text) => {
         logChain = logChain.then(() => operationLog.append(operation.operationId, text)).catch(() => undefined);
     };
@@ -80,12 +86,27 @@ export async function runPreviewPublish(state, operation, root) {
     try {
         await ensureDependencies(state, revisionScope(state, workspaceId, operation.directoryName) ?? workspaceId, root, output);
         const runtimePreview = await prepareRuntimePreview(state, operation, root);
+        remotePreview = Boolean(runtimePreview);
         if (runtimePreview)
             await excludeFromGit(root, '/.playcraft-editor-preview/');
         await excludeFromGit(root, `/${OUTPUT_FOLDER}/`);
         await excludeFromGit(root, `/${BUILDER_TEMP_FOLDER}/`);
         await excludeFromGit(root, `/${WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY}/`);
-        await buildPreview(state, root, outputDir, operation.operationId, output, appendLog, runtimePreview?.command);
+        if (!runtimePreview) {
+            const signature = await workspacePlayableSignature(root);
+            buildCopy = await mkdtemp(join(tmpdir(), 'playcraft-preview-build-'));
+            // The build runs as the development identity while this copy belongs to the controller.
+            await openScratchToDevelopment(buildCopy, (await lstat(root)).gid);
+            const project = join(buildCopy, 'project'), staged = join(buildCopy, 'output');
+            await isolateWorkspaceForBuild(root, project);
+            await buildPreview(state, project, staged, operation.operationId, output, appendLog);
+            await finalizeWorkspacePlayable(root, await readSingleHtml(staged), 'preview.publish', {
+                expectedSignature: signature, source: { operationId: operation.operationId, ...(operation.sessionId ? { sessionId: operation.sessionId } : {}) },
+            });
+            await refreshWorkspaceArtifacts(state, workspaceId, undefined, operation.directoryName ?? 'basic');
+            return;
+        }
+        await buildPreview(state, root, outputDir, operation.operationId, output, appendLog, runtimePreview.command);
         const runtimeBuild = runtimePreview ? await runtimePreview.finish() : undefined;
         const built = runtimeBuild?.bytes ?? await readSingleHtml(outputDir);
         const bytes = injectPreviewDiagnostics(built);
@@ -94,8 +115,6 @@ export async function runPreviewPublish(state, operation, root) {
         if (findExternalLocalReferences(bytes.toString('utf8')).length > 0) {
             throw new PreviewFailure('preview_not_single_file');
         }
-        if (!runtimePreview)
-            await saveWorkspacePlayableOutput(root, bytes);
         const contentDigest = createHash('sha256').update(bytes).digest('hex');
         const contentMd5 = createHash('md5').update(bytes).digest('base64');
         const source = await sourceRevision(root);
@@ -149,9 +168,11 @@ export async function runPreviewPublish(state, operation, root) {
         return published;
     }
     catch (error) {
-        const code = error instanceof PreviewFailure || error instanceof RuntimePreviewBuildError ? error.code : 'preview_build_failed';
+        const code = error instanceof RuntimePreviewBuildError ? error.code : previewFailureCode(error);
+        if (code === 'dependencies_not_ready' && output.log)
+            appendLog(`${output.log}\n`);
         appendLog(`\n[${code}] ${error instanceof Error ? error.message : code}\n`);
-        if (code !== 'publish_conflict') {
+        if (remotePreview && code !== 'publish_conflict') {
             await postControl(state, '/runtime/internal/preview-failures', {
                 workspaceId,
                 directoryName: operation.directoryName ?? 'basic',
@@ -166,6 +187,8 @@ export async function runPreviewPublish(state, operation, root) {
     finally {
         await logChain;
         await rm(outputDir, { recursive: true, force: true }).catch(() => undefined);
+        if (buildCopy)
+            await rm(buildCopy, { recursive: true, force: true }).catch(() => undefined);
     }
 }
 export function previewFailureCode(error) {

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

@@ -479,10 +479,10 @@ export async function handleRuntimeRequest(state, request, response) {
                 writeJson(response, 400, { error: 'invalid_workspace' });
                 return;
             }
-            await workspaceRoot(state, workspaceId);
+            await workspaceRoot(state, workspaceId, directoryName);
             writeJson(response, 200, url.searchParams.get('refresh') === 'false'
-                ? await new WorkspaceArtifactStore(state.config.stateDir, workspaceId).list()
-                : await refreshWorkspaceArtifacts(state, workspaceId));
+                ? await new WorkspaceArtifactStore(state.config.stateDir, workspaceId, directoryName).list()
+                : await refreshWorkspaceArtifacts(state, workspaceId, undefined, directoryName));
             return;
         }
         if (request.method === 'GET' && url.pathname === '/runtime/artifact-content') {
@@ -493,7 +493,7 @@ export async function handleRuntimeRequest(state, request, response) {
                 writeJson(response, 400, { error: 'invalid_workspace' });
                 return;
             }
-            await workspaceRoot(state, workspaceId);
+            await workspaceRoot(state, workspaceId, directoryName);
             const parsed = workspaceArtifactContentQuerySchema.safeParse({
                 artifactId: url.searchParams.get('artifactId'), versionId: url.searchParams.get('versionId'),
                 ...(url.searchParams.has('path') ? { path: url.searchParams.get('path') } : {}),
@@ -505,7 +505,7 @@ export async function handleRuntimeRequest(state, request, response) {
                 return;
             }
             try {
-                writeJson(response, 200, await new WorkspaceArtifactStore(state.config.stateDir, workspaceId).content(parsed.data));
+                writeJson(response, 200, await new WorkspaceArtifactStore(state.config.stateDir, workspaceId, directoryName).content(parsed.data));
             }
             catch (error) {
                 const reason = error instanceof Error ? error.message : 'artifact_unavailable';

package/dist/workspace-runtime/workspaces/artifact-events.js

@@ -1,16 +1,24 @@
 import { PLATFORM_ROUTES, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
 import { workspaceRoot } from './registry.js';
 import { WorkspaceArtifactStore } from './artifacts.js';
-export async function refreshWorkspaceArtifacts(state, workspaceId, origin) {
+import { finalizeWorkspacePlayable, readWorkspacePlayable, validateWorkspacePlayable, workspacePlayableSignature } from '../previews/finalize.js';
+import { watch } from 'chokidar';
+import { join, relative, sep } from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { generatedWorkspace } from './artifact-receipts.js';
+export async function refreshWorkspaceArtifacts(state, workspaceId, origin, directoryName = 'basic') {
     if (state.journal.destroyed())
         throw new Error('runtime_destroyed');
-    const root = await workspaceRoot(state, workspaceId);
-    const result = await new WorkspaceArtifactStore(state.config.stateDir, workspaceId).discover(root, origin?.source, origin?.paths);
+    const root = await workspaceRoot(state, workspaceId, directoryName);
+    const active = state.journal.listSessions().some(session => session.workspaceId === workspaceId
+        && (session.directoryName ?? 'basic') === directoryName && ['starting', 'running', 'waiting_for_user'].includes(session.turnStatus ?? ''));
+    const result = await new WorkspaceArtifactStore(state.config.stateDir, workspaceId, directoryName)
+        .discover(root, origin?.source, origin?.paths, origin?.playable ?? (active ? { mode: 'hold' } : {}));
     if (result.changed && !state.journal.destroyed()) {
         const event = await state.journal.allocateSourceEvent({
             runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,
             workspaceId, type: 'artifact.updated', occurredAt: result.list.scannedAt,
-            payload: { workspaceId, artifacts: result.list.artifacts.map(artifact => ({ id: artifact.id, currentVersionId: artifact.currentVersionId })) },
+            payload: { workspaceId, directoryName, artifacts: result.list.artifacts.map(artifact => ({ id: artifact.id, currentVersionId: artifact.currentVersionId })) },
         });
         // The durable source stream remains authoritative when the callback is temporarily unavailable.
         void fetch(platformEndpoint(state.config.publicBaseUrl, PLATFORM_ROUTES.events), {
@@ -23,33 +31,138 @@ export async function refreshWorkspaceArtifacts(state, workspaceId, origin) {
 }
 /** Completed commands and turns reconcile outputs, including work done before a failed turn. */
 export function observeWorkspaceArtifacts(state) {
-    const pending = new Map();
-    const running = new Set();
-    const reconcile = (workspaceId) => {
-        const task = refreshWorkspaceArtifacts(state, workspaceId).catch(() => undefined);
-        running.add(task);
-        void task.finally(() => running.delete(task));
-    };
+    const running = new Map();
+    const starts = new Map();
+    const deferred = new Map();
     const stop = state.journal.onSourceEvent((event) => {
-        if (!['file.written', 'files.changed', 'filesystem.changed', 'item/completed', 'turn.completed', 'turn/completed', 'turn.failed', 'turn.interrupted'].includes(event.type))
+        if (!['file.written', 'files.changed', 'filesystem.changed', 'item/started', 'item/completed', 'turn/started', 'turn.started', 'turn.completed', 'turn/completed', 'turn.failed', 'turn.interrupted'].includes(event.type))
             return;
         const payload = event.payload && typeof event.payload === 'object' ? event.payload : {};
         const sessionId = typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
-        const workspaceId = typeof payload.workspaceId === 'string' ? payload.workspaceId : sessionId ? state.journal.getSession(sessionId)?.workspaceId : undefined;
+        const session = sessionId ? state.journal.getSession(sessionId) : undefined;
+        const workspaceId = typeof payload.workspaceId === 'string' ? payload.workspaceId : session?.workspaceId;
         if (!workspaceId)
             return;
-        const timer = pending.get(workspaceId);
-        if (timer)
-            clearTimeout(timer);
-        pending.set(workspaceId, setTimeout(() => { pending.delete(workspaceId); reconcile(workspaceId); }, 200));
+        const directoryName = typeof payload.directoryName === 'string' ? payload.directoryName : session?.directoryName ?? 'basic';
+        if (directoryName === 'root')
+            return;
+        const scope = `${workspaceId}:${directoryName}`;
+        const item = payload.item && typeof payload.item === 'object' ? payload.item : undefined;
+        const turn = payload.turn && typeof payload.turn === 'object' ? payload.turn : undefined;
+        const turnId = String(payload.turnId ?? turn?.id ?? session?.activeTurnId ?? 'turn');
+        const turnKey = `${encodeURIComponent(String(payload.threadId ?? session?.threadId ?? sessionId))}/${encodeURIComponent(turnId)}`;
+        const command = item?.type === 'commandExecution';
+        if (event.type.startsWith('item/') && !command)
+            return;
+        const executionId = command ? `${turnKey}/${encodeURIComponent(String(item?.id))}` : turnKey;
+        const started = event.type.endsWith('started');
+        const terminal = command || event.type.startsWith('turn');
+        const success = command ? item?.status === 'completed' && item.exitCode === 0
+            : !['turn.failed', 'turn.interrupted'].includes(event.type) && (turn?.status ?? payload.status ?? 'completed') === 'completed';
+        const task = (running.get(scope) ?? Promise.resolve()).catch(() => undefined).then(async () => {
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            const store = new WorkspaceArtifactStore(state.config.stateDir, workspaceId, directoryName);
+            const source = { kind: 'generated', ...(sessionId ? { sessionId } : {}),
+                ...(typeof payload.operationId === 'string' ? { operationId: payload.operationId } : {}), tool: command ? 'agent command' : 'agent turn' };
+            if (started) {
+                await refreshWorkspaceArtifacts(state, workspaceId, { source, paths: [], playable: { mode: 'hold', executionId } }, directoryName);
+                starts.set(executionId, await workspacePlayableSignature(root).catch(() => undefined));
+                return;
+            }
+            let force = false;
+            let promote = terminal && success;
+            const candidate = terminal ? await readWorkspacePlayable(root).catch(() => undefined) : undefined;
+            if (terminal && success) {
+                force = command && starts.has(executionId) && starts.get(executionId) !== candidate?.signature;
+                const occupied = await store.hasPendingPlayableExecution(executionId);
+                promote = (!command || force) && !occupied;
+                if (command && force && occupied && candidate) {
+                    try {
+                        validateWorkspacePlayable(candidate.bytes);
+                        deferred.set(scope, { bytes: candidate.bytes, source });
+                    }
+                    catch { /* An incomplete output never becomes a deferred successful candidate. */ }
+                }
+                if (promote && candidate && (force || !await store.rejectedPlayable(candidate.bytes))) {
+                    await finalizeWorkspacePlayable(root, candidate.bytes, source.tool, { expectedSignature: candidate.signature, source }).catch(() => undefined);
+                }
+            }
+            const unrelatedFailure = terminal && !success && candidate && (starts.has(executionId) && starts.get(executionId) === candidate.signature
+                || await store.isCurrentPlayable(candidate.bytes));
+            starts.delete(executionId);
+            await refreshWorkspaceArtifacts(state, workspaceId, { source, paths: [], playable: {
+                    mode: terminal ? success ? promote ? 'success' : 'skip' : unrelatedFailure ? 'skip' : 'failure' : 'hold', ...(terminal ? { executionId } : {}), force,
+                } }, directoryName);
+            const waiting = deferred.get(scope);
+            if (waiting && !await store.hasPendingPlayableExecution(executionId)) {
+                deferred.delete(scope);
+                const current = await readWorkspacePlayable(root).catch(() => undefined);
+                if (current?.bytes.equals(waiting.bytes) && !await store.rejectedPlayable(current.bytes)) {
+                    await finalizeWorkspacePlayable(root, waiting.bytes, waiting.source.tool, { expectedSignature: current.signature, source: waiting.source });
+                    await refreshWorkspaceArtifacts(state, workspaceId, { source: waiting.source, paths: [], playable: { mode: 'success', force: true } }, directoryName);
+                }
+            }
+        }).catch(() => undefined);
+        running.set(scope, task);
     });
+    const receiptScope = (path) => {
+        const parts = relative(state.config.workspaceRoot, path).split(sep).filter(Boolean);
+        const offset = state.config.workspaceMode === 'multi' ? 2 : 0;
+        const directoryName = offset ? parts[1] : 'basic';
+        if (offset && (parts[0]?.startsWith('.') || parts.length > 1 && !/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/.test(directoryName)))
+            return undefined;
+        const tail = parts.slice(offset);
+        if (tail.some((part, index) => index === 0 ? part !== '.playcraft' : index === 1 ? part !== 'artifact-receipts' : index === 2 ? !/^[a-f0-9-]{36}\.json$/.test(part) : true))
+            return undefined;
+        return { parts, offset, directoryName: directoryName ?? 'basic' };
+    };
+    // Only completed generation receipts are observed; project files and build output are excluded.
+    const queueReceipt = (path) => {
+        const found = receiptScope(path);
+        if (!found || found.parts.length !== found.offset + 3)
+            return;
+        const scope = `${found.offset ? found.parts[0] : 'single'}:${found.directoryName}`;
+        const task = (running.get(scope) ?? Promise.resolve()).catch(() => undefined)
+            .then(async () => {
+            const workspaceId = found.offset ? found.parts[0] : (await generatedWorkspace(state.config.workspaceRoot))?.workspaceId;
+            if (workspaceId)
+                await refreshWorkspaceArtifacts(state, workspaceId, undefined, found.directoryName);
+        }).catch(() => undefined);
+        running.set(scope, task);
+    };
+    const receipts = watch(state.config.workspaceRoot, {
+        persistent: false, followSymlinks: false, depth: state.config.workspaceMode === 'multi' ? 5 : 3,
+        ignored: path => !receiptScope(path),
+    }).on('add', queueReceipt).on('ready', () => {
+        // Reconcile receipts created while the initial directory watches were being attached.
+        const task = (async () => {
+            let roots = [state.config.workspaceRoot];
+            if (state.config.workspaceMode === 'multi') {
+                roots = [];
+                for (const entry of await readdir(state.config.workspaceRoot, { withFileTypes: true })) {
+                    if (!entry.isDirectory() || entry.name.startsWith('.'))
+                        continue;
+                    const container = join(state.config.workspaceRoot, entry.name);
+                    for (const directory of await readdir(container, { withFileTypes: true })) {
+                        if (directory.isDirectory() && /^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/.test(directory.name))
+                            roots.push(join(container, directory.name));
+                    }
+                }
+            }
+            for (const root of roots) {
+                const directory = join(root, '.playcraft/artifact-receipts');
+                const names = await readdir(directory).catch(() => []);
+                for (const name of names)
+                    if (/^[a-f0-9-]{36}\.json$/.test(name))
+                        queueReceipt(join(directory, name));
+            }
+        })().catch(() => undefined);
+        running.set('receipt-startup', task);
+    }).on('error', () => undefined);
     return async () => {
         stop();
-        for (const [workspaceId, timer] of pending) {
-            clearTimeout(timer);
-            reconcile(workspaceId);
-        }
-        pending.clear();
-        await Promise.all([...running]);
+        await receipts.close();
+        await running.get('receipt-startup');
+        await Promise.all([...running.values()]);
     };
 }

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

@@ -56,7 +56,9 @@ export async function snapshotArtifactFile(root, path, objects, role = 'primary'
         const before = await source.stat();
         if (!before.isFile() || before.nlink !== 1 || before.size > WORKSPACE_ARTIFACT_MAX_BYTES)
             throw new Error('artifact_file_unavailable');
-        output = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        // Objects are written by whichever identity generates the artifact and read by the other.
+        output = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o660);
+        await output.chmod(0o660);
         const hash = createHash('sha256'), buffer = Buffer.allocUnsafe(64 * 1024);
         let size = 0;
         for (;;) {

package/dist/workspace-runtime/workspaces/artifact-receipts.js

@@ -4,10 +4,11 @@ import { lstat, open, rename, unlink } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { isWorkspaceArtifactOutputPath, workspaceArtifactReceiptSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { artifactDirectory, artifactFormat, relativeArtifactPath, snapshotArtifactBundle } from './artifact-files.js';
+import { shareWorkspaceAssetDirectory } from './asset-publication-access.js';
 import { excludeFromGit } from './dependencies.js';
 export const ARTIFACT_RECEIPTS_DIRECTORY = '.playcraft/artifact-receipts';
 export const artifactReceiptSchema = workspaceArtifactReceiptSchema;
-async function generatedWorkspace(cwd) {
+export async function generatedWorkspace(cwd) {
     for (let root = resolve(cwd);; root = dirname(root)) {
         const file = join(root, '.playcraft/workspace-context.json');
         try {
@@ -32,8 +33,23 @@ async function generatedWorkspace(cwd) {
             return undefined;
     }
 }
+/**
+ * The receipt tree is written by the development identity and read by the controller. A directory
+ * the other identity created cannot be re-shaped here; its owner repairs it on the next write and
+ * readers keep working from whatever already carries the shared bits.
+ */
+async function shareArtifactDirectory(root, directory) {
+    try {
+        await shareWorkspaceAssetDirectory(root, directory);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== 'EACCES' && code !== 'EPERM')
+            throw error;
+    }
+}
 /** Preserve final outputs before another command overwrites them; intermediate project assets are not registered. */
-export async function captureGeneratedArtifact(output, tool, metadata = {}, cwd = process.cwd()) {
+export async function captureGeneratedArtifact(output, tool, metadata = {}, cwd = process.cwd(), expectedDigest, origin) {
     const context = await generatedWorkspace(cwd);
     if (!context)
         return;
@@ -49,17 +65,24 @@ export async function captureGeneratedArtifact(output, tool, metadata = {}, cwd
         return;
     const receipts = await artifactDirectory(context.root, ARTIFACT_RECEIPTS_DIRECTORY);
     const objects = await artifactDirectory(context.root, `${ARTIFACT_RECEIPTS_DIRECTORY}/objects`);
+    // Generations are written as the development identity while the controller scans this tree.
+    await shareArtifactDirectory(context.root, receipts);
+    await shareArtifactDirectory(context.root, objects);
     const thumbnailPath = metadata.thumbnailPath ? relativeArtifactPath(context.root, resolve(cwd, metadata.thumbnailPath)) : undefined;
     const files = await snapshotArtifactBundle(context.root, path, objects, thumbnailPath);
+    if (expectedDigest && files.find(file => file.role === 'primary')?.sha256 !== expectedDigest)
+        throw new Error('artifact_file_changed');
     const receipt = artifactReceiptSchema.parse({
         id: randomUUID(), workspaceId: context.workspaceId, path,
-        source: { kind: 'generated', tool, generatedAt: new Date().toISOString() }, files,
+        source: { kind: 'generated', tool, generatedAt: new Date().toISOString(),
+            ...(origin?.sessionId ? { sessionId: origin.sessionId } : {}), ...(origin?.operationId ? { operationId: origin.operationId } : {}) }, files,
         ...(metadata.width ? { width: metadata.width } : {}), ...(metadata.height ? { height: metadata.height } : {}),
         ...(metadata.duration !== undefined ? { duration: metadata.duration } : {}),
     });
     const temporary = join(receipts, `${receipt.id}.tmp`);
-    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o660);
     try {
+        await handle.chmod(0o660);
         await handle.writeFile(`${JSON.stringify(receipt)}\n`);
         await handle.sync();
         await handle.close();