@playcraft/cli 0.1.59-beta → 0.1.61-beta

package/dist/workspace-runtime/workspaces/procedural-3d/render-worker.js

@@ -0,0 +1,159 @@
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { chromium } from 'playwright-core';
+import sharp from 'sharp';
+import { digest } from './files.js';
+import { canonicalJson, reviewProfileHash, validateRenderState, } from './review-contracts.js';
+/** Launched as the development user; Vite and Chromium die with the managed process group. */
+async function main() {
+    let raw = '';
+    for await (const chunk of process.stdin) {
+        raw += chunk;
+        if (raw.length > 64 * 1024)
+            throw new Error('render_input_limit');
+    }
+    const input = JSON.parse(raw);
+    if (input.reviewProfile &&
+        reviewProfileHash(input.reviewProfile.profile) !== input.reviewProfile.hash)
+        throw new Error('render_profile_mismatch');
+    const project = createRequire(join(input.projectRoot, 'package.json'));
+    const vite = await import(pathToFileURL(project.resolve('vite')).href);
+    const three = join(dirname(project.resolve('three')), 'three.module.js');
+    const threeVersion = JSON.parse(await readFile(join(dirname(three), '../package.json'), 'utf8')).version;
+    const server = await vite.createServer({
+        configFile: false,
+        root: input.sourceRoot,
+        logLevel: 'silent',
+        resolve: { alias: [{ find: /^three$/, replacement: three }] },
+        server: {
+            host: '127.0.0.1',
+            port: 0,
+            strictPort: false,
+            fs: { strict: true, allow: [input.sourceRoot, dirname(three)] },
+        },
+    });
+    let browser;
+    try {
+        await server.listen();
+        const address = server.httpServer.address();
+        const origin = `http://127.0.0.1:${address.port}`;
+        browser = await chromium.launch({
+            executablePath: process.env.PLAYCRAFT_CHROMIUM_PATH || '/usr/bin/chromium',
+            headless: true,
+            args: [
+                '--disable-dev-shm-usage',
+                '--enable-unsafe-swiftshader',
+                '--use-gl=angle',
+                '--use-angle=swiftshader',
+            ],
+        });
+        const context = await browser.newContext({
+            viewport: { width: 768, height: 768 },
+            deviceScaleFactor: 1,
+            serviceWorkers: 'block',
+        });
+        const errors = [];
+        await context.route('**/*', (route) => {
+            const url = route.request().url();
+            if (url === `${origin}/favicon.ico`)
+                return route.fulfill({ status: 204 });
+            return url.startsWith(`${origin}/`) || /^(data|blob):/.test(url)
+                ? route.continue()
+                : route.abort('blockedbyclient');
+        });
+        const page = await context.newPage();
+        page.on('pageerror', (error) => errors.push(error.message));
+        page.on('console', (message) => {
+            if (message.type() === 'error')
+                errors.push(message.text());
+        });
+        page.on('requestfailed', (request) => errors.push(`${request.url()}: ${request.failure()?.errorText}`));
+        await page.goto(`${origin}/${input.pagePath.split('/').map(encodeURIComponent).join('/')}`, {
+            waitUntil: 'networkidle',
+            timeout: 30_000,
+        });
+        await page.waitForFunction('Boolean(window.__PLAYCRAFT_SCULPT__?.ready)', undefined, {
+            timeout: 30_000,
+        });
+        await page.evaluate('Promise.resolve(window.__PLAYCRAFT_SCULPT__.ready)');
+        const renderer = await page.evaluate(`(() => {const c=document.querySelector('canvas'); const g=c?.getContext('webgl2')||c?.getContext('webgl'); if(!g) throw new Error('webgl_unavailable'); const e=g.getExtension('WEBGL_debug_renderer_info'); return {renderer:g.getParameter(e?e.UNMASKED_RENDERER_WEBGL:g.RENDERER),vendor:g.getParameter(e?e.UNMASKED_VENDOR_WEBGL:g.VENDOR)};})()`);
+        await mkdir(input.outputRoot, { recursive: true });
+        const captures = [];
+        const states = {};
+        const captureState = async (view, stripped = false) => {
+            if (!input.reviewProfile)
+                return;
+            states[view] = validateRenderState(await page.evaluate('window.__PLAYCRAFT_SCULPT__.getRenderState()'), input.reviewProfile.profile, view, stripped);
+        };
+        for (const view of input.views) {
+            await page.evaluate(`Promise.resolve(window.__PLAYCRAFT_SCULPT__.setView(${JSON.stringify(view)})).then(()=>new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r))))`);
+            await page.screenshot({
+                path: join(input.outputRoot, `${view}.png`),
+                animations: 'disabled',
+            });
+            await captureState(view);
+            captures.push({ view, file: `${view}.png` });
+        }
+        await page.evaluate(`Promise.resolve(window.__PLAYCRAFT_SCULPT__.setView('hero')).then(()=>window.__PLAYCRAFT_SCULPT__.setMapStripped(true)).then(()=>new Promise(r=>requestAnimationFrame(()=>requestAnimationFrame(r))))`);
+        await page.screenshot({
+            path: join(input.outputRoot, 'map-stripped.png'),
+            animations: 'disabled',
+        });
+        captures.push({ view: 'map-stripped', file: 'map-stripped.png' });
+        await captureState('map-stripped', true);
+        const reference = await sharp(input.referencePath)
+            .resize(768, 768, { fit: 'contain', background: '#e9e9e9' })
+            .png()
+            .toBuffer();
+        const hero = await sharp(join(input.outputRoot, `${input.views.includes('hero') ? 'hero' : input.views[0]}.png`))
+            .resize(768, 768)
+            .png()
+            .toBuffer();
+        await sharp({ create: { width: 1536, height: 768, channels: 3, background: '#e9e9e9' } })
+            .composite([
+            { input: reference, left: 0, top: 0 },
+            { input: hero, left: 768, top: 0 },
+        ])
+            .png()
+            .toFile(join(input.outputRoot, 'comparison.png'));
+        captures.push({ view: 'comparison', file: 'comparison.png' });
+        let renderReceipt;
+        if (input.reviewProfile) {
+            const bytes = canonicalJson({
+                schemaVersion: 1,
+                reviewProfileHash: input.reviewProfile.hash,
+                profile: input.reviewProfile.profile,
+                views: states,
+            });
+            await writeFile(join(input.outputRoot, 'render-state.json'), bytes, { flag: 'wx' });
+            renderReceipt = { file: 'render-state.json', hash: digest(bytes) };
+        }
+        await page.evaluate('window.__PLAYCRAFT_SCULPT__.dispose?.()');
+        if (errors.length)
+            throw new Error(`render_errors: ${errors.join('\n').slice(0, 4000)}`);
+        return {
+            captures,
+            renderer,
+            browser: browser.version(),
+            node: process.version,
+            three: threeVersion,
+            vite: vite.version,
+            viewport: { width: 768, height: 768, deviceScaleFactor: 1 },
+            ready: true,
+            ...(renderReceipt ? { renderReceipt } : {}),
+            errors,
+        };
+    }
+    finally {
+        await browser?.close();
+        await server.close();
+    }
+}
+main()
+    .then((result) => process.stdout.write(JSON.stringify({ ok: true, result })))
+    .catch((error) => {
+    process.stderr.write(String(error));
+    process.exitCode = 1;
+});

package/dist/workspace-runtime/workspaces/procedural-3d/review-contracts.js

@@ -0,0 +1,257 @@
+import { z } from 'zod';
+import { digest, relativeFile } from './files.js';
+export const REVIEW_DIRECTORY = '__playcraft-review';
+export const REVIEW_PAGE = `${REVIEW_DIRECTORY}/index.html`;
+export const REVIEW_VIEWS = ['front', 'right', 'back', 'left', 'hero'];
+const finite = z.number().finite();
+const coordinate = finite.min(-100000).max(100000);
+const vector = z.tuple([coordinate, coordinate, coordinate]);
+const projectedVector = z.tuple([finite, finite, finite]);
+const matrix = z.array(finite).length(16);
+export const reviewProfileSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    fovDegrees: finite.min(1).max(120),
+    near: finite.min(0.0001).max(1000),
+    far: finite.max(100000),
+    target: vector,
+    views: z
+        .object({ front: vector, right: vector, back: vector, left: vector, hero: vector })
+        .strict(),
+    background: z
+        .string()
+        .regex(/^#[a-fA-F0-9]{6}$/)
+        .transform((value) => value.toLowerCase()),
+    keyLightPosition: vector,
+    referenceCameraStatus: z.literal('estimated'),
+})
+    .strict()
+    .superRefine((profile, context) => {
+    if (profile.far < profile.near + 0.0001)
+        context.addIssue({ code: z.ZodIssueCode.custom, message: 'invalid camera range' });
+    for (const position of Object.values(profile.views)) {
+        const distance = Math.hypot(...position.map((value, index) => value - profile.target[index]));
+        if (distance <= profile.near || distance >= profile.far)
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'invalid camera target distance',
+            });
+    }
+});
+/** A bounded canonical JSON (JavaScript Object Notation, JavaScript对象表示法) encoding. */
+export function canonicalJson(value) {
+    let nodes = 0;
+    const normalize = (input, depth = 0) => {
+        if (++nodes > 4096 || depth > 12)
+            throw new Error('procedural_skill_invalid_review_json');
+        if (input === null || typeof input === 'string' || typeof input === 'boolean')
+            return input;
+        if (typeof input === 'number' && Number.isFinite(input))
+            return input;
+        if (Array.isArray(input))
+            return input.map((item) => normalize(item, depth + 1));
+        if (input && typeof input === 'object' && Object.getPrototypeOf(input) === Object.prototype)
+            return Object.fromEntries(Object.keys(input)
+                .sort()
+                .map((key) => [key, normalize(input[key], depth + 1)]));
+        throw new Error('procedural_skill_invalid_review_json');
+    };
+    const encoded = JSON.stringify(normalize(value));
+    if (Buffer.byteLength(encoded) > 64 * 1024)
+        throw new Error('procedural_skill_invalid_review_json');
+    return encoded;
+}
+export const reviewProfileHash = (profile) => digest(canonicalJson(profile));
+export const captureV2Schema = z
+    .object({
+    files: z.array(z.string()).min(1).max(252),
+    sourcePaths: z.array(z.string()).min(1).max(128),
+    views: z.array(z.enum(REVIEW_VIEWS)).min(3).max(5).default(['front', 'right', 'hero']),
+    review: z
+        .object({
+        factoryPath: z.string(),
+        exportName: z.string().regex(/^[A-Za-z_$][A-Za-z0-9_$]{0,79}$/),
+        parameters: z.record(z.unknown()).optional(),
+        profile: reviewProfileSchema,
+    })
+        .strict(),
+})
+    .strict()
+    .superRefine((input, context) => {
+    const invalid = () => context.addIssue({ code: z.ZodIssueCode.custom, message: 'invalid controlled review input' });
+    if (new Set(input.views).size !== input.views.length || !input.views.includes('hero'))
+        invalid();
+    if (!input.sourcePaths.includes(input.review.factoryPath) ||
+        !/\.(?:[cm]?[jt]sx?)$/.test(input.review.factoryPath))
+        invalid();
+    if (input.files.some((path) => path.toLowerCase() === REVIEW_DIRECTORY ||
+        path.toLowerCase().startsWith(`${REVIEW_DIRECTORY}/`)))
+        invalid();
+    try {
+        relativeFile(input.review.factoryPath);
+        if (input.review.parameters &&
+            Buffer.byteLength(canonicalJson(input.review.parameters)) > 16 * 1024)
+            invalid();
+    }
+    catch {
+        invalid();
+    }
+});
+const renderStateSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    view: z.enum(REVIEW_VIEWS),
+    mapStripped: z.boolean(),
+    profile: reviewProfileSchema,
+    viewport: z
+        .object({ width: z.literal(768), height: z.literal(768), deviceScaleFactor: z.literal(1) })
+        .strict(),
+    camera: z
+        .object({
+        position: vector,
+        target: vector,
+        fovDegrees: finite,
+        near: finite,
+        far: finite,
+        projectionMatrix: matrix,
+        matrixWorld: matrix,
+        matrixWorldInverse: matrix,
+    })
+        .strict(),
+    modelBounds: z.object({ min: vector, max: vector }).strict(),
+    projectedBounds: z
+        .object({ min: projectedVector, max: projectedVector, conservative: z.literal(true) })
+        .strict()
+        .nullable(),
+    framing: z.enum(['contained', 'bounds-overflow', 'unknown']),
+})
+    .strict();
+const close = (a, b) => Math.abs(a - b) <= 1e-7 * Math.max(1, Math.abs(a), Math.abs(b));
+const same = (a, b) => a.length === b.length && a.every((value, index) => close(value, b[index]));
+const cross = (a, b) => [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+];
+const norm = (a) => {
+    const length = Math.hypot(...a);
+    return a.map((value) => value / length);
+};
+const dot = (a, b) => a.reduce((sum, value, index) => sum + value * b[index], 0);
+/** Independently check the actual helper state against the fixed camera, never fit model bounds. */
+export function validateRenderState(value, profile, view, stripped = false) {
+    const state = renderStateSchema.parse(value);
+    const expectedView = stripped ? 'hero' : view;
+    const position = profile.views[expectedView];
+    const fail = () => {
+        throw new Error('procedural_skill_review_state_mismatch');
+    };
+    if (!position ||
+        state.view !== expectedView ||
+        state.mapStripped !== stripped ||
+        canonicalJson(state.profile) !== canonicalJson(profile) ||
+        !same(state.camera.position, position) ||
+        !same(state.camera.target, profile.target) ||
+        !close(state.camera.fovDegrees, profile.fovDegrees) ||
+        !close(state.camera.near, profile.near) ||
+        !close(state.camera.far, profile.far))
+        fail();
+    let zAxis = norm(position.map((value, index) => value - profile.target[index]));
+    if (Math.hypot(...cross([0, 1, 0], zAxis)) === 0) {
+        zAxis[2] += 0.0001;
+        zAxis = norm(zAxis);
+    }
+    const xAxis = norm(cross([0, 1, 0], zAxis)), yAxis = cross(zAxis, xAxis);
+    const world = [...xAxis, 0, ...yAxis, 0, ...zAxis, 0, ...position, 1];
+    const inverse = [
+        xAxis[0],
+        yAxis[0],
+        zAxis[0],
+        0,
+        xAxis[1],
+        yAxis[1],
+        zAxis[1],
+        0,
+        xAxis[2],
+        yAxis[2],
+        zAxis[2],
+        0,
+        -dot(xAxis, position),
+        -dot(yAxis, position),
+        -dot(zAxis, position),
+        1,
+    ];
+    const scale = 1 / Math.tan((profile.fovDegrees * Math.PI) / 360);
+    const projection = [
+        scale,
+        0,
+        0,
+        0,
+        0,
+        scale,
+        0,
+        0,
+        0,
+        0,
+        -(profile.far + profile.near) / (profile.far - profile.near),
+        -1,
+        0,
+        0,
+        (-2 * profile.far * profile.near) / (profile.far - profile.near),
+        0,
+    ];
+    if (!same(state.camera.matrixWorld, world) ||
+        !same(state.camera.matrixWorldInverse, inverse) ||
+        !same(state.camera.projectionMatrix, projection))
+        fail();
+    if (state.modelBounds.min.some((entry, index) => entry > state.modelBounds.max[index]))
+        fail();
+    const multiply = (m, p) => [0, 1, 2, 3].map((row) => p.reduce((sum, entry, column) => sum + m[column * 4 + row] * entry, 0));
+    const points = [];
+    for (const x of [state.modelBounds.min[0], state.modelBounds.max[0]])
+        for (const y of [state.modelBounds.min[1], state.modelBounds.max[1]])
+            for (const z of [state.modelBounds.min[2], state.modelBounds.max[2]]) {
+                const clip = multiply(projection, multiply(inverse, [x, y, z, 1]));
+                if (!clip.every(Number.isFinite) || clip[3] <= 1e-9) {
+                    if (state.projectedBounds !== null || state.framing !== 'unknown')
+                        fail();
+                    return state;
+                }
+                points.push(clip.slice(0, 3).map((entry) => entry / clip[3]));
+            }
+    const min = [0, 1, 2].map((axis) => Math.min(...points.map((point) => point[axis])));
+    const max = [0, 1, 2].map((axis) => Math.max(...points.map((point) => point[axis])));
+    const framing = min.every((value) => value >= -1) && max.every((value) => value <= 1)
+        ? 'contained'
+        : 'bounds-overflow';
+    if (!state.projectedBounds ||
+        !same(state.projectedBounds.min, min) ||
+        !same(state.projectedBounds.max, max) ||
+        state.framing !== framing)
+        fail();
+    return state;
+}
+export function validateRenderReceipt(value, profile, views) {
+    const receipt = z
+        .object({
+        schemaVersion: z.literal(1),
+        reviewProfileHash: z.string().regex(/^[a-f0-9]{64}$/),
+        profile: reviewProfileSchema,
+        views: z.record(z.unknown()),
+    })
+        .strict()
+        .parse(value);
+    const expected = [...views, 'map-stripped'];
+    if (receipt.reviewProfileHash !== reviewProfileHash(profile) ||
+        canonicalJson(receipt.profile) !== canonicalJson(profile) ||
+        Object.keys(receipt.views).length !== expected.length ||
+        expected.some((view) => !Object.hasOwn(receipt.views, view)))
+        throw new Error('procedural_skill_review_receipt_mismatch');
+    return {
+        ...receipt,
+        views: Object.fromEntries(expected.map((view) => [
+            view,
+            validateRenderState(receipt.views[view], profile, view, view === 'map-stripped'),
+        ])),
+    };
+}

package/dist/workspace-runtime/workspaces/procedural-3d/review-page.js

@@ -0,0 +1,26 @@
+import { canonicalJson, REVIEW_DIRECTORY, REVIEW_PAGE, } from './review-contracts.js';
+const literal = (value) => JSON.stringify(value)
+    .replace(/</g, '\\u003c')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
+/** Only locked helpers and declarative factory data enter the host-owned review page. */
+export function createHostReviewFiles(review, helpers) {
+    const factory = `/${review.factoryPath.split('/').map(encodeURIComponent).join('/')}`;
+    const profile = canonicalJson(review.profile);
+    const page = `<!doctype html><html><head><meta charset="utf-8"><base href="/"><style>html,body{margin:0;width:768px;height:768px;overflow:hidden}</style></head><body><script type="module">
+import { createReviewScene } from '/${REVIEW_DIRECTORY}/review-scene.mjs';
+import * as factory from ${literal(factory)};
+const createModel = factory[${literal(review.exportName)}];
+if (typeof createModel !== 'function') throw new Error('review_factory_missing');
+const parameters = JSON.parse(${literal(canonicalJson(review.parameters ?? {}))});
+const profile = JSON.parse(${literal(profile)});
+const api = createReviewScene(() => createModel(parameters), { profile });
+Object.defineProperty(window, '__PLAYCRAFT_SCULPT__', { value: api, writable: false, configurable: false });
+</script></body></html>`;
+    return [
+        { path: REVIEW_PAGE, bytes: Buffer.from(page) },
+        { path: `${REVIEW_DIRECTORY}/review-scene.mjs`, bytes: helpers.scene },
+        { path: `${REVIEW_DIRECTORY}/review-profile.mjs`, bytes: helpers.profile },
+        { path: `${REVIEW_DIRECTORY}/profile.json`, bytes: Buffer.from(profile) },
+    ];
+}

package/dist/workspace-runtime/workspaces/remix-reference-skill.js

@@ -0,0 +1,126 @@
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { buildLocalProjectSkillsSnapshot, canonicalProjectSkillsJson, createCanonicalBundleArchive, declarationDigest, PROJECT_SKILL_SOURCE_ROOTS, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
+import { resolveCliPackageRoot } from '../../scaffold/compose.js';
+import { ensureSharedDirectory, writeSharedFile } from './shared-write.js';
+export const WORKSPACE_REMIX_REFERENCES_SKILL = 'playcraft-remix-references';
+const ORIGINAL_BUNDLED_GUIDE = 'dbc89eb34ca8bc6a25c92d1cd83f6dcc4d8baddacaa7cb92aa8e5aad6986e8f6';
+/** Adds the bundled guide or upgrades its unchanged original revision, preserving user selection. */
+export async function ensureWorkspaceRemixReferenceSkill(root, cache) {
+    const management = await ensureSharedDirectory(root, join(root, '.playcraft'));
+    const lease = join(management, 'skills-write.lock');
+    // private: the write lease is controller coordination state, not workspace content.
+    await writeFile(lease, `${process.pid}\n`, { flag: 'wx', mode: 0o600 });
+    let ownedSource;
+    let replacedSource;
+    let committed = false;
+    try {
+        const declarationPath = join(management, 'skills.json');
+        const stat = await lstat(declarationPath);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+            throw new Error('workspace_skills_invalid');
+        const original = await readFile(declarationPath);
+        const previous = validateProjectSkillsSnapshot(original.toString('utf8'), await readProjectSkillsLockFile(root));
+        const name = WORKSPACE_REMIX_REFERENCES_SKILL;
+        const source = `.agents/skills/${name}`;
+        const matches = previous.declaration.entries.filter(entry => entry.entryKey === name || basename(entry.source.kind === 'repository'
+            ? entry.source.root : entry.source.skillRef) === name);
+        const existing = matches[0];
+        let oldContent;
+        if (existing) {
+            if (matches.length !== 1 || existing.source.kind !== 'repository' || existing.source.root !== source
+                || existing.projectFiles?.length || previous.lock.entries.some(entry => entry.dependencies.includes(existing.entryKey)))
+                return;
+            const locked = previous.lock.entries.find(entry => entry.entryKey === existing.entryKey);
+            if (locked.revision.kind !== 'source' || locked.dependencies.length)
+                return;
+            const current = await readProjectSkillSource(root, existing);
+            if (current.files.length !== 1 || current.files[0]?.path !== 'SKILL.md')
+                return;
+            oldContent = Buffer.from(current.files[0].content);
+            const archive = createCanonicalBundleArchive([{ path: 'SKILL.md', data: oldContent }]);
+            if (createHash('sha256').update(oldContent).digest('hex') !== ORIGINAL_BUNDLED_GUIDE
+                || current.sourceTreeHash !== locked.sourceTreeHash
+                || createHash('sha256').update(archive).digest('hex') !== locked.revision.artifactHash)
+                return;
+        }
+        else {
+            if (previous.declaration.entries.length >= 512 || previous.lock.entries.some(entry => basename(entry.revision.skillRef) === name))
+                return;
+            for (const sourceRoot of PROJECT_SKILL_SOURCE_ROOTS) {
+                const found = await lstat(join(root, sourceRoot, name)).catch(error => {
+                    if (error.code === 'ENOENT')
+                        return undefined;
+                    throw error;
+                });
+                if (found)
+                    return;
+            }
+        }
+        const entryKey = existing?.entryKey ?? `repo-${createHash('sha256').update(source).digest('hex').slice(0, 24)}`;
+        if (!existing && previous.declaration.entries.some(entry => entry.entryKey === entryKey))
+            return;
+        const content = await readFile(join(resolveCliPackageRoot(), 'project-template/.claude/skills', name, 'SKILL.md'));
+        const files = [{ path: 'SKILL.md', content }];
+        const addition = buildLocalProjectSkillsSnapshot({
+            declaration: { schemaVersion: 1, entries: [existing ?? { entryKey, source: { kind: 'repository', root: source }, enabled: true, surface: 'sandbox-agent' }] },
+            discovered: [], sources: [{ entryKey, root: source, files, sourceTreeHash: sourceTreeDigest(files) }], issues: [],
+        }, existing ? previous.lock : undefined);
+        const next = structuredClone(previous);
+        if (existing) {
+            next.declaration.entries[next.declaration.entries.findIndex(entry => entry.entryKey === entryKey)] = addition.declaration.entries[0];
+            next.lock.entries[next.lock.entries.findIndex(entry => entry.entryKey === entryKey)] = addition.lock.entries[0];
+        }
+        else {
+            next.declaration.entries.push(...addition.declaration.entries);
+            next.lock.entries.push(...addition.lock.entries);
+        }
+        next.lock.declarationHash = declarationDigest(next.declaration);
+        validateProjectSkillsSnapshot(next.declaration, next.lock);
+        // private: `cache` is the controller state dir, not the shared workspace tree.
+        await mkdir(cache, { recursive: true, mode: 0o700 });
+        for (const artifact of addition.artifacts) {
+            const target = join(cache, `${artifact.artifactHash}.tar.gz`);
+            // private
+            await writeFile(target, artifact.archive, { flag: 'wx', mode: 0o600 }).catch(async (error) => {
+                if (error.code !== 'EEXIST' || !(await readFile(target)).equals(artifact.archive))
+                    throw error;
+            });
+            await writeSharedFile(root, join(management, 'skill-artifacts', `${artifact.artifactHash}.tar.gz`), artifact.archive);
+        }
+        await ensureSharedDirectory(root, join(root, '.agents/skills'));
+        const destination = join(root, source);
+        if (oldContent) {
+            const current = await readProjectSkillSource(root, existing);
+            if (current.sourceTreeHash !== previous.lock.entries.find(entry => entry.entryKey === entryKey).sourceTreeHash)
+                return;
+            replacedSource = { path: join(destination, 'SKILL.md'), content: oldContent };
+        }
+        else {
+            await mkdir(destination);
+            ownedSource = destination;
+        }
+        await writeSharedFile(root, join(destination, 'SKILL.md'), content);
+        await writeSharedFile(root, declarationPath, `${canonicalProjectSkillsJson(next.declaration)}\n`);
+        try {
+            await writeSharedFile(root, join(management, 'skills.lock.json'), `${canonicalProjectSkillsJson(next.lock)}\n`);
+        }
+        catch (error) {
+            await writeSharedFile(root, declarationPath, original);
+            throw error;
+        }
+        committed = true;
+    }
+    finally {
+        try {
+            if (replacedSource && !committed)
+                await writeSharedFile(root, replacedSource.path, replacedSource.content);
+            if (ownedSource && !committed)
+                await rm(ownedSource, { recursive: true, force: true });
+        }
+        finally {
+            await rm(lease, { force: true });
+        }
+    }
+}

package/dist/workspace-runtime/workspaces/scheduled-task-proposals.js

@@ -0,0 +1,27 @@
+import { platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+import { SCHEDULED_TASK_TOOL_ERROR_CODES } from '../codex/scheduled-task-tools.js';
+/** This credential can only prepare a card; browser confirmation is a separate authority. */
+export function scheduledTaskProposalHandler(state) {
+    return async (action, source, args) => {
+        const deadline = Date.now() + 3_000;
+        for (;;) {
+            const response = await fetch(platformEndpoint(state.config.publicBaseUrl, `/runtime/internal/scheduled-task-proposals/${action}`), {
+                method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15_000),
+                headers: { authorization: `Bearer ${state.config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': state.config.environment },
+                body: JSON.stringify({ runtimeId: state.config.runtimeId, generation: state.config.generation,
+                    runtimeEpoch: state.runtimeEpoch, ...source, arguments: args }),
+            });
+            const result = await response.json().catch(() => undefined);
+            if (!response.ok) {
+                const code = typeof result?.code === 'string' ? result.code : result?.message;
+                if (response.status === 409 && code === 'scheduled_task_proposal_source_pending' && Date.now() < deadline
+                    && state.native?.scheduledTaskProposalSource?.(source)) {
+                    await new Promise(resolve => setTimeout(resolve, 50));
+                    continue;
+                }
+                throw new Error(typeof code === 'string' && SCHEDULED_TASK_TOOL_ERROR_CODES.has(code) ? code : 'scheduled_task_proposal_unavailable');
+            }
+            return result;
+        }
+    };
+}

package/dist/workspace-runtime/workspaces/skill-execution-context.js

@@ -0,0 +1,69 @@
+import { realpath } from 'node:fs/promises';
+import { PROCEDURAL_3D_SKILL_REF, resolveWorkspaceSkillExecutionPolicy, workspaceComposerSelectionSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { assertOperationDirectoryAccess } from '../server/directory-access.js';
+import { sessionWorkspaceRoot } from './registry.js';
+import { readWorkspaceSkillSnapshot } from './skills.js';
+/** Read-only preflight. It must precede the directory gate and cannot install or freeze files. */
+export async function preflightSkillExecution(state, request) {
+    if (request.kind !== 'session.turn')
+        return undefined;
+    const body = request.payload && typeof request.payload === 'object'
+        ? request.payload
+        : {};
+    if ('directoryAccessMode' in body || 'skillExecutionPolicyVersion' in body)
+        throw new Error('untrusted_runtime_field');
+    const selection = workspaceComposerSelectionSchema.safeParse({
+        context: body.context,
+        workMode: body.workMode,
+    });
+    if (!selection.success)
+        throw new Error('invalid_composer_context');
+    if (!selection.data.context?.skills.length)
+        return undefined;
+    if (request.directoryName === 'root')
+        throw new Error('context_directory_mismatch');
+    const root = await sessionWorkspaceRoot(state, request.workspaceId, request.directoryName);
+    return resolveWorkspaceSkillExecutionPolicy(await readWorkspaceSkillSnapshot(root), selection.data.context.skills);
+}
+/** Native tool callers supply the actual thread/turn binding, never shell-provided identity. */
+export async function resolveActiveSkillExecutionContext(state, input) {
+    const skillRef = input.skillRef ?? PROCEDURAL_3D_SKILL_REF;
+    if (state.journal.destroyed())
+        throw new Error('skill_execution_identity_mismatch');
+    if (skillRef !== PROCEDURAL_3D_SKILL_REF)
+        throw new Error('context_skill_unavailable');
+    const session = state.journal.getSession(input.sessionId);
+    const matches = state.journal
+        .listOperations()
+        .map((item) => item.operation)
+        .filter((operation) => operation.kind === 'session.turn' &&
+        ['dispatched', 'accepted'].includes(operation.status) &&
+        operation.sessionId === input.sessionId &&
+        operation.nativeThreadId === input.nativeThreadId &&
+        operation.nativeTurnId === input.nativeTurnId &&
+        operation.generation === state.config.generation &&
+        operation.runtimeEpoch === state.runtimeEpoch &&
+        operation.userId === state.config.userId &&
+        operation.environment === state.config.environment);
+    const operation = matches.length === 1 ? matches[0] : undefined;
+    if (!operation ||
+        !session ||
+        session.threadId !== input.nativeThreadId ||
+        (session.activeTurnId !== undefined && session.activeTurnId !== input.nativeTurnId) ||
+        session.workspaceId !== operation.workspaceId ||
+        (session.directoryName ?? 'basic') !== (operation.directoryName ?? 'basic'))
+        throw new Error('skill_execution_identity_mismatch');
+    if (operation.directoryAccessMode !== 'exclusive' || operation.skillExecutionPolicyVersion !== 1)
+        throw new Error('requires-exclusive-turn');
+    if (operation.workMode === 'plan' || operation.permissionMode === 'read-only')
+        throw new Error('skill_execution_readonly');
+    await assertOperationDirectoryAccess(state, operation, 'exclusive');
+    const root = await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName);
+    if ((await realpath(root)) !== (await realpath(input.root)))
+        throw new Error('skill_execution_identity_mismatch');
+    const policy = resolveWorkspaceSkillExecutionPolicy(await readWorkspaceSkillSnapshot(root), operation.context?.skills ?? []);
+    const entry = policy.entries.find((item) => item.revision.skillRef === skillRef);
+    if (!entry || policy.directoryAccessMode !== 'exclusive')
+        throw new Error('requires-exclusive-turn');
+    return { operation, entry, lockHash: policy.lockHash, declarationHash: policy.declarationHash };
+}