@playcraft/cli 0.1.56-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/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/workspaces/dependencies.js

@@ -15,16 +15,21 @@ const SHARE_WAIT_MS = 60_000;
  * prompts, and writes plain lines to the log. Package scripts run: the workspace is the user's own
  * sandbox and the install runs as the development user.
  */
-const INSTALL_COMMAND = 'pnpm install --no-frozen-lockfile --store-dir /var/cache/playcraft/pnpm-store --reporter=append-only --config.confirm-modules-purge=false';
-/** Installs whenever there is a package.json; the hash says whether a finished install is current. */
+export function dependencyInstallCommand(state, options = {}) {
+    const store = process.env.PLAYCRAFT_PNPM_STORE ?? (process.platform === 'linux' ? '/var/cache/playcraft/pnpm-store' : join(state.config.stateDir, 'pnpm-store'));
+    const quotedStore = `'${store.replaceAll("'", "'\\''")}'`;
+    return `pnpm install --${options.frozenLockfile ? 'frozen' : 'no-frozen'}-lockfile --store-dir ${quotedStore} --reporter=append-only --config.confirm-modules-purge=false`;
+}
+/** pnpm owns installation; other package managers' lockfiles remain untouched. */
 export async function planInstall(root) {
     const manifest = await readOptional(join(root, 'package.json'));
     if (manifest === undefined)
         return { kind: 'skip' };
-    const lock = (await readOptional(join(root, 'pnpm-lock.yaml'))) ?? '';
+    const lock = await readOptional(join(root, 'pnpm-lock.yaml'));
     return {
         kind: 'install',
-        lockHash: createHash('sha256').update(manifest).update('\0').update(lock).digest('hex'),
+        lockHash: createHash('sha256').update(manifest).update('\0').update(lock ?? '').digest('hex'),
+        hasLockfile: lock !== undefined,
     };
 }
 const running = new WeakMap();
@@ -108,7 +113,16 @@ export async function recoverInterruptedInstalls(journal) {
     }
 }
 async function installOnce(state, workspaceId, root) {
-    const plan = await planInstall(root);
+    let plan;
+    try {
+        plan = await planInstall(root);
+    }
+    catch {
+        await state.journal.putWorkspaceDependencies({
+            workspaceId, status: 'failed', error: 'dependency_inputs_unreadable', finishedAt: new Date().toISOString(),
+        });
+        return;
+    }
     const current = state.journal.getWorkspaceDependencies(workspaceId);
     if (plan.kind === 'skip') {
         if (current?.status !== 'none') {
@@ -174,9 +188,7 @@ async function installOnce(state, workspaceId, root) {
  */
 async function runInstall(state, workspaceId, root) {
     // Tests replace the install; a real registry is never reached from them.
-    const store = process.env.PLAYCRAFT_PNPM_STORE ?? (process.platform === 'linux' ? '/var/cache/playcraft/pnpm-store' : join(state.config.stateDir, 'pnpm-store'));
-    const quotedStore = `'${store.replaceAll("'", "'\\''")}'`;
-    const planned = process.env.PLAYCRAFT_DEPENDENCY_INSTALL_COMMAND || INSTALL_COMMAND.replace('/var/cache/playcraft/pnpm-store', quotedStore);
+    const planned = process.env.PLAYCRAFT_DEPENDENCY_INSTALL_COMMAND || dependencyInstallCommand(state);
     const logDir = join(state.config.stateDir, 'dependency-logs');
     await mkdir(logDir, { recursive: true, mode: 0o700 });
     const logPath = join(logDir, `${workspaceId}.log`);
@@ -265,8 +277,10 @@ async function readOptional(path) {
     try {
         return await readFile(path, 'utf8');
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
     }
 }
 async function isDirectory(path) {

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

@@ -0,0 +1,185 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { z } from 'zod';
+import { buildStageAt } from '@playcraft/common/build-progress';
+import { PLATFORM_ROUTES, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+import { submitTrustedOperation } from '../server/submit-operation.js';
+import { businessEndpoint } from '../../utils/environment-endpoints.js';
+import { ensureCliCredentials } from './cli-credentials.js';
+import { readWorkspaceGitStatus } from './git.js';
+import { sessionWorkspaceRoot } from './registry.js';
+const run = promisify(execFile);
+const REQUEST_TIMEOUT_MS = 60_000;
+/** Validation findings beyond this are summarized by count; the Agent fixes the first ones first. */
+const MAX_FINDINGS = 30;
+/** A tool error the Agent sees as its reason; `code` is stable, the detail explains it. */
+export class PlatformExportError extends Error {
+    code;
+    constructor(code, detail) {
+        super(detail ? `${code}: ${detail}` : code);
+        this.code = code;
+    }
+}
+/** The project and branch a workspace directory exports, or undefined when it has no project. */
+export async function platformExportTarget(state, scope) {
+    const binding = state.journal.getWorkspace(scope.workspaceId);
+    if (!binding?.projectId)
+        return undefined;
+    const root = await sessionWorkspaceRoot(state, scope.workspaceId, scope.directoryName);
+    return { projectId: binding.projectId, root };
+}
+/**
+ * A standalone workspace has no remote to export from. The platform gives it a project (as its
+ * first save does) and registers it again; the registration reaches this runtime before the reply.
+ */
+async function promoteStandalone(state, scope) {
+    if (state.journal.getWorkspace(scope.workspaceId)?.targetKind !== 'standalone' || scope.directoryName !== 'basic')
+        return;
+    const config = state.config;
+    const response = await fetch(platformEndpoint(config.publicBaseUrl, PLATFORM_ROUTES.workspacePromotions), {
+        method: 'POST',
+        redirect: 'error',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: { authorization: `Bearer ${config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': config.environment },
+        body: JSON.stringify({ runtimeId: config.runtimeId, generation: config.generation, runtimeEpoch: state.runtimeEpoch,
+            workspaceId: scope.workspaceId }),
+    });
+    if (!response.ok) {
+        const body = await response.json().catch(() => undefined);
+        throw new PlatformExportError('workspace_promotion_failed', typeof body?.reason === 'string' ? body.reason : String(response.status));
+    }
+    await response.body?.cancel().catch(() => undefined);
+}
+const credentialSchema = z.object({ apiUrl: z.string().url(), token: z.string().min(1) });
+async function request(state, path, init) {
+    await ensureCliCredentials(state).catch(() => { throw new PlatformExportError('cli_credentials_unavailable'); });
+    const credential = credentialSchema.parse(JSON.parse(await readFile(join(state.config.workspaceRoot, '.playcraft.json'), 'utf8')));
+    const response = await fetch(businessEndpoint(credential.apiUrl, path), {
+        method: init.method,
+        redirect: 'error',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'X-Sandbox-Token': credential.token,
+            'playcraft-env': state.config.environment,
+            ...(init.body !== undefined ? { 'content-type': 'application/json' } : {}),
+        },
+        ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+    });
+    const text = await response.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = undefined;
+    }
+    const error = body && typeof body === 'object' && 'error' in body ? body.error : undefined;
+    if (!response.ok || (typeof error === 'string' && !('id' in body))) {
+        const message = body && typeof body === 'object' && 'message' in body ? body.message : error;
+        throw new PlatformExportError('platform_export_rejected', `${response.status} ${typeof message === 'string' ? message : Array.isArray(message) ? message.join('; ') : text.slice(0, 300)}`);
+    }
+    return body;
+}
+/**
+ * Saves the directory (commit + push), then exports that commit for the channels through the
+ * platform, as the delivery panel's Export does. Each channel repeats its latest export of the
+ * branch, or uses the defaults without one. A standalone workspace first becomes a project.
+ */
+export async function startPlatformExport(state, input) {
+    await promoteStandalone(state, input);
+    const target = await platformExportTarget(state, input);
+    if (!target)
+        throw new PlatformExportError('platform_export_requires_project');
+    const saved = await submitTrustedOperation(state, {
+        kind: 'workspace.save',
+        workspaceId: input.workspaceId,
+        directoryName: input.directoryName,
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        clientRequestId: `${input.clientRequestId.slice(0, 80)}:export-save`,
+        payload: {},
+    });
+    if (saved.status !== 'completed')
+        throw new PlatformExportError('workspace_save_failed', saved.error);
+    const status = await readWorkspaceGitStatus(target.root);
+    // A save skips the push during a merge; with an upstream, `ahead` says the push did not land.
+    if (status.merging || (status.hasUpstream && status.ahead > 0))
+        throw new PlatformExportError('workspace_not_pushed');
+    if (status.branch === 'HEAD')
+        throw new PlatformExportError('workspace_detached_head');
+    const commit = (await run('git', ['-C', target.root, 'rev-parse', 'HEAD'])).stdout.trim();
+    const result = await request(state, '/api/builds/agent-exports', {
+        method: 'POST',
+        body: {
+            projectId: target.projectId,
+            branchName: status.branch,
+            commitHash: commit,
+            platforms: input.channels,
+            ...(input.format ? { format: input.format } : {}),
+            clientRequestId: input.clientRequestId,
+        },
+    });
+    return {
+        commit: commit.slice(0, 7),
+        branch: status.branch,
+        builds: result.builds.map((build) => ({
+            buildId: build.id,
+            channel: build.platform,
+            status: build.status,
+            ...(build.format ? { format: build.format } : {}),
+            ...(build.error ? { error: build.error } : {}),
+            ...(result.options?.[build.platform] ? { options: result.options[build.platform] } : {}),
+        })),
+    };
+}
+/** One platform export as the Agent reads it: status, the recorded failure and the checks. */
+export async function readPlatformExport(state, input) {
+    const target = await platformExportTarget(state, input);
+    if (!target)
+        throw new PlatformExportError('platform_export_requires_project');
+    let buildId = input.buildId;
+    if (!buildId) {
+        const { branch } = await readWorkspaceGitStatus(target.root);
+        const query = new URLSearchParams({ projectId: target.projectId, branchName: branch, limit: '1',
+            ...(input.channel ? { platform: input.channel } : {}) });
+        const list = await request(state, `/api/agent/tools/list-builds?${query}`, { method: 'GET' });
+        buildId = list.items[0]?.id;
+        if (!buildId)
+            throw new PlatformExportError('delivery_build_not_found');
+    }
+    const build = await request(state, `/api/agent/tools/get-build?${new URLSearchParams({ id: buildId })}`, { method: 'GET' });
+    const running = build.status === 'queued' || build.status === 'running';
+    const findings = (build.validationWarnings ?? []).map((warning) => ({
+        code: warning.code,
+        severity: warning.severity,
+        message: warning.message,
+        ...(typeof warning.details?.status === 'string' ? { status: warning.details.status } : {}),
+        ...(typeof warning.details?.recommendation === 'string' ? { recommendation: warning.details.recommendation } : {}),
+        ...(typeof warning.details?.file === 'string' ? { file: warning.details.file } : {}),
+        ...(typeof warning.details?.line === 'number' ? { line: warning.details.line } : {}),
+    }));
+    return {
+        build: {
+            buildId: build.id,
+            channel: build.platform,
+            format: build.format,
+            status: build.status,
+            ...(running ? { stage: buildStageAt(build.progress).stage } : {}),
+            ...(build.commitHash ? { commit: build.commitHash } : {}),
+            ...(build.error ? { error: build.error } : {}),
+            ...(build.previewUrl ? { previewUrl: build.previewUrl } : {}),
+            ...(build.downloadUrl ? { downloadUrl: build.downloadUrl } : {}),
+            ...(typeof build.outputSize === 'number' ? { sizeBytes: build.outputSize } : {}),
+            ...(typeof build.sizeLimit === 'number' ? { sizeLimitBytes: build.sizeLimit } : {}),
+        },
+        ...(build.artifacts?.failure ? { failure: build.artifacts.failure } : {}),
+        ...(!running && build.validationPassed !== null && build.validationPassed !== undefined ? {
+            validation: {
+                passed: build.validationPassed,
+                findings: findings.slice(0, MAX_FINDINGS),
+                ...(findings.length > MAX_FINDINGS ? { omitted: findings.length - MAX_FINDINGS } : {}),
+            },
+        } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.56-beta",
+  "version": "0.1.57-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -52,8 +52,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.56-beta",
-    "@playcraft/common": "0.1.56-beta",
+    "@playcraft/build": "0.1.57-beta",
+    "@playcraft/common": "0.1.57-beta",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",

package/project-template-v2/.playcraft/skills.lock.json

@@ -10,8 +10,8 @@
     },
     {
       "skillRef": "platform/playcraft-asset-management",
-      "version": "1.0.0",
-      "artifactHash": "27209dba24f6e1851dc83682fbd24165894c802794c797cac32d8871f740cf14",
+      "version": "1.1.0",
+      "artifactHash": "0b5408792edfeb7b852817bd76893b95738a0e161407f0b48c4b50161797ba3c",
       "surface": "portal-agent",
       "mountPath": ".playcraft/skills/platform__playcraft-asset-management"
     },
@@ -108,8 +108,8 @@
     },
     {
       "skillRef": "remix/playcraft-audio-generation",
-      "version": "1.0.0",
-      "artifactHash": "8d1b035b289545ca8fd6c247b9417bf34bddf5a26b31e114c35d001aa3a9ebf0",
+      "version": "1.1.1",
+      "artifactHash": "27661b1b52e7981a0b9cf5531f535fcf10928ea290348fcb469e35ad2082b437",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-audio-generation"
     },
@@ -122,15 +122,15 @@
     },
     {
       "skillRef": "remix/playcraft-image-generation",
-      "version": "1.0.0",
-      "artifactHash": "91bec2422c750d9d47d5be2796ec5aaffb48de561f2c2d8b92112f37d576f489",
+      "version": "1.1.2",
+      "artifactHash": "a006c96700f8dbfe4c34a31d0e1646620ca6148d319e59e7466d627fea1ca65e",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-image-generation"
     },
     {
       "skillRef": "remix/playcraft-image-processing",
-      "version": "1.0.0",
-      "artifactHash": "d845c067bed103c3d1d3f145b1cb8246ffbd6a9ae91efcfbce2eae456819212d",
+      "version": "1.1.1",
+      "artifactHash": "903f4efc14e2bb57403856edeca43146904ec64811cfd107b6ec76bb451842fd",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-image-processing"
     },
@@ -147,6 +147,13 @@
       "artifactHash": "e2a59c61ef5b094a821fbbab3b0f65f906bfc0dfda6f3d8c0b33a6f460dd0963",
       "surface": "sandbox-agent",
       "mountPath": ".playcraft/skills/remix__playcraft-remix-workflow"
+    },
+    {
+      "skillRef": "remix/playcraft-workspace-assets",
+      "version": "1.0.0",
+      "artifactHash": "f098949b043a229e561d92a34c3a65b44ffbd83d1758ef30ac09d2d0d5ea2570",
+      "surface": "sandbox-agent",
+      "mountPath": ".playcraft/skills/remix__playcraft-workspace-assets"
     }
   ]
 }

package/templates/preview-runtime/v1/README.md

@@ -22,6 +22,10 @@ Prepare all required images before changing visible objects, call `assertCurrent
 
 `ResourceLoadError` is exported from `runtime.mjs`. Live adapters let this error reach the runtime, which retains the last known installation and reports a recoverable, field-level resource failure. Do not catch an arbitrary update exception and claim successful fallback. During initial `createGame`, catch only this load error to start with an embedded default image or empty background; the runtime still reports the saved image as unapplied. A later patch of that field retries it; unrelated parameter updates can continue. `resourceErrors` and file-save receipts are independent. Save logical paths and let the original production asset registry include the file when building delivery output.
 
+The endpoint advertises `canRefreshImages: true` for explicit same-path content refresh. The host sends registered live-image fields and their expected file digests through a separate resource sequence; raw parameters and draft revisions remain unchanged. In `apply`, honor `context.fields` even when a logical path equals its previous value: request that field through `loadImage` and install the returned image after `assertCurrent()`. A local path-equality cache must not hide this explicit update. The runtime prepares new images without blocking unrelated live parameters, checks the expected content digest, rebases against the latest permitted configuration and records installed digests only after the real render acknowledgement. A matching installed digest is a no-op; a failed or superseded preparation leaves the old image available and can be retried. Older endpoints without this optional capability require the existing rebuild route.
+
+Content generations are independent per field. If an opening image and board image are being prepared together, a newer board-only refresh cancels only the old board read; the still-current opening image must finish and apply while preserving the newer board. Each application uses only the prepared fields that remain current and the latest permitted configuration. A preparation failure in a still-current batch retains the old images and marks all its unapplied fields as recoverable, so an explicit retry cannot silently forget a prepared sibling.
+
 ## Preview build
 
 The engineering project must install a compatible Vite as a development dependency. Set a separate package script:

package/templates/preview-runtime/v1/manifest.json

@@ -4,14 +4,14 @@
   "protocolVersion": 1,
   "files": {
     "build-preview.mjs": "2bd512675d829cc07ceddcb58365a6f74d36ff93690f8d72f4bbaa1d45511c91",
-    "README.md": "f104440b3acb23adb88bde0dff23840fa170a14f477d1d7338575eca75e73571",
+    "README.md": "3e35ca2ce6eab84ba8688b400aee8ee5e69458466a13f00e459fd630575d9cbd",
     "release-guard.mjs": "0c33d1559c68844f3760c3e754ee36ca70dc27151ef6f7ad62f29f95239679cc",
     "runtime.d.mts": "a366552166a4a93103306997058951416740eaf6d6f3d0a34854386b4f1e02f5",
     "runtime.d.ts": "a366552166a4a93103306997058951416740eaf6d6f3d0a34854386b4f1e02f5",
-    "runtime.mjs": "25b33218ff32dfeaaad7bcd69647cbf662fa4312d49b62724a2104fd27d9b001",
-    "types/adapters.d.ts": "29b5c18d4576ab00eca44875b5c4eae2fc0e0ed6ab5595dbbaf6ba9b9fd8beed",
-    "types/preview.d.ts": "19ea55ed6faf4faa4f4fc62a2d70309d7ba917fc165c2c149856798e1b4197f8",
-    "types/protocol.d.ts": "716e83802336c4e7377abc1b433c77045ed59997a45646fe2fdbe55cb82c5e62",
-    "types/runtime.d.ts": "efcd429b24d75b06afb3f05ec3f8134efc381ede0dd59cb43ec5770e2559c77b"
+    "runtime.mjs": "700c6cb0859ef4b4390d7a1dae41f7e8fa7be7c8dad90b5b48a7e7ee5f90a6a1",
+    "types/adapters.d.ts": "f5e70c4bb9043de1c590eada14266f613286360c809faf26680b0bbbd1cc7b2c",
+    "types/preview.d.ts": "db2e7eb1fa3406ca53fc7c3a4352da061c05af714ead978111ab5118de58db32",
+    "types/protocol.d.ts": "b298d1d35d6e261bbf6a0500f9029f38cad1532bb46475566180b3b92833c507",
+    "types/runtime.d.ts": "f52d08d7b53ff84394381f9d1741a624142f75fac468abf9a5029e98fe172ca4"
   }
 }