@playcraft/cli 0.1.55-beta → 0.1.57-beta

package/dist/workspace-runtime/codex/model-broker.js

@@ -6,6 +6,7 @@ import { basename, dirname } from 'node:path';
 import { z } from 'zod';
 import { workspaceContextFromRoot } from '../workspaces/registry.js';
 import { PLATFORM_ROUTES, modelResponsesPath, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+import { WorkspaceGenerationProvenanceBroker } from './generation-provenance-broker.js';
 const credentialSchema = z.object({
     token: z.string().min(1), expiresAt: z.string().datetime(),
     configId: z.string().uuid(), model: z.string().min(1).max(128),
@@ -25,8 +26,10 @@ export class WorkspaceModelBroker {
     pending = new Map();
     requests = new Set();
     sessionRequests = new Map();
+    generation;
     constructor(state) {
         this.state = state;
+        this.generation = new WorkspaceGenerationProvenanceBroker(state);
     }
     async start() {
         if (this.server)
@@ -67,8 +70,10 @@ export class WorkspaceModelBroker {
         }
         // Resolve current model metadata and permission at every native turn boundary.
         const credential = await this.credential(entry, true);
+        const boundaryId = sessionId && clientRequestId ? await this.generation.prepare() : undefined;
         if (!route || route.epoch !== this.state.runtimeEpoch) {
-            route = { workspaceId, epoch: this.state.runtimeEpoch, capability: randomBytes(32).toString('base64url') };
+            route = { workspaceId, epoch: this.state.runtimeEpoch, capability: randomBytes(32).toString('base64url'),
+                generationCapability: randomBytes(32).toString('base64url') };
             this.routes.set(routeKey, route);
         }
         // Each session pins its prepared model; shared credential renewal cannot change an active turn.
@@ -77,12 +82,16 @@ export class WorkspaceModelBroker {
                 if (!this.valid(entry) || this.routes.get(routeKey) !== route)
                     throw new Error('model_access_denied');
                 route.selected = { entry, model: credential.model,
-                    ...(sessionId && clientRequestId ? { feedback: { sessionId, clientRequestId } } : {}) };
+                    ...(sessionId && clientRequestId ? { feedback: { sessionId, clientRequestId, cwd, boundaryId } } : {}) };
             },
             model: credential.model,
             modelConfigId: credential.configId,
             modelProvider: 'playcraft_workspace',
             config: {
+                ...(sessionId ? { 'shell_environment_policy.set': {
+                        PLAYCRAFT_AGENT_GENERATION_ENDPOINT: `${this.baseUrl}/${routeKey}/generation-provenance`,
+                        PLAYCRAFT_AGENT_GENERATION_CAPABILITY: route.generationCapability,
+                    } } : {}),
                 'model_providers.playcraft_workspace': {
                     name: 'PlayCraft Workspace', base_url: `${this.baseUrl}/${routeKey}`,
                     wire_api: 'responses', requires_openai_auth: false,
@@ -142,18 +151,28 @@ export class WorkspaceModelBroker {
         const cancel = () => abort.abort();
         response.once('close', cancel);
         try {
-            const match = /^\/([0-9a-f-]{36}(?:\/[0-9a-f]{32})?)\/responses$/.exec(request.url ?? '');
+            const match = /^\/([0-9a-f-]{36}(?:\/[0-9a-f]{32})?)\/(responses|generation-provenance)$/.exec(request.url ?? '');
             const route = match ? this.routes.get(match[1]) : undefined;
             const selected = route?.selected;
             const entry = selected?.entry;
             const presented = Buffer.from(request.headers.authorization ?? '');
-            const expected = Buffer.from(route ? `Bearer ${route.capability}` : '');
+            const generationRequest = match?.[2] === 'generation-provenance';
+            const expected = Buffer.from(route ? `Bearer ${generationRequest ? route.generationCapability : route.capability}` : '');
             if (request.method !== 'POST' || !entry || !expected.length || presented.length !== expected.length
                 || !timingSafeEqual(presented, expected) || !this.valid(entry)) {
                 response.writeHead(403);
                 response.end();
                 return;
             }
+            if (generationRequest) {
+                if (!selected?.feedback) {
+                    response.writeHead(403);
+                    response.end();
+                    return;
+                }
+                await this.generation.forward(request, response, selected.feedback, () => this.valid(entry) && route?.selected === selected);
+                return;
+            }
             activeRoute = route;
             const active = this.sessionRequests.get(route) ?? new Set();
             active.add(abort);

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/serve.js

@@ -2,7 +2,6 @@ import { closeCliCredentials } from './workspaces/cli-credentials.js';
 import { randomUUID } from 'node:crypto';
 import { mkdir, readdir } from 'node:fs/promises';
 import { createServer } from 'node:http';
-import { createPlatformAdapter } from '@playcraft/build';
 import { INCOMPATIBLE_EXIT_CODE, negotiateProtocol, transitionOperation, directoryMutationReceiptSchema, productionSessionAttemptId, } from '@playcraft/common/cloud-workspace/runtime';
 import { RuntimeJournal } from './persistence/journal.js';
 import { createCodexAppServerAdapter } from './codex/app-server.js';
@@ -32,7 +31,7 @@ import { revisionScope } from './workspaces/registry.js';
 import { observeWorkspaceArtifacts } from './workspaces/artifact-events.js';
 import { loadWorkspaceMcpConfig } from './codex/mcp-config.js';
 import { startSourceEventUploader, stopSourceEventUploader } from './server/source-uploader.js';
-import { submitTrustedOperation } from './server/submit-operation.js';
+import { platformExportTarget, readPlatformExport, startPlatformExport } from './workspaces/platform-export.js';
 export async function startWorkspaceRuntime(config, options = {}) {
     process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
     const negotiated = negotiateProtocol(config);
@@ -355,6 +354,7 @@ function closeServer(server) {
 function formatHost(host) {
     return host.includes(':') ? `[${host}]` : host;
 }
+const UUID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/i;
 function deliveryToolHandlers(state) {
     const contextFor = async (input) => {
         if (input.workspaceId)
@@ -368,37 +368,15 @@ function deliveryToolHandlers(state) {
             const { workspaceId, directoryName } = await contextFor(input);
             if (directoryName === 'root')
                 throw new Error('invalid_workspace_directory');
-            const builds = [];
-            for (const channel of input.channels) {
-                const operation = await submitTrustedOperation(state, {
-                    kind: 'delivery.build',
-                    workspaceId,
-                    directoryName,
-                    ...(input.sessionId ? { sessionId: input.sessionId } : {}),
-                    clientRequestId: `${input.clientRequestId.slice(0, 80)}:${channel}`,
-                    payload: {
-                        channel,
-                        format: input.format ?? createPlatformAdapter({ platform: channel, format: 'html' }).getDefaultFormat(),
-                        actor: 'agent',
-                    },
-                });
-                let record;
-                for (let attempt = 0; attempt < 40 && !record; attempt++) {
-                    record = await new DeliveryStore(state.config.stateDir, workspaceId).read(operation.operationId);
-                    if (!record)
-                        await new Promise(resolve => setTimeout(resolve, 25));
-                }
-                builds.push({
-                    buildId: operation.operationId,
-                    channel,
-                    status: record?.status ?? operation.status,
-                    ...(record?.queuePosition ? { queuePosition: record.queuePosition } : {}),
-                });
-            }
-            return { builds };
+            // Exports go through the platform; a standalone workspace becomes a project first.
+            return startPlatformExport(state, { ...input, workspaceId, directoryName });
         },
         async get(input) {
             const { workspaceId, directoryName } = await contextFor(input);
+            const sandboxBuild = input.buildId !== undefined && UUID.test(input.buildId);
+            if (!sandboxBuild && await platformExportTarget(state, { workspaceId, directoryName })) {
+                return readPlatformExport(state, { ...input, workspaceId, directoryName });
+            }
             const store = new DeliveryStore(state.config.stateDir, workspaceId);
             const record = input.buildId
                 ? await store.read(input.buildId)

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