@playcraft/cli 0.1.29 → 0.1.31

package/dist/workspace-runtime/workspaces/registry.js

@@ -0,0 +1,234 @@
+import { execFile } from 'node:child_process';
+import { lstat, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { promisify } from 'node:util';
+import { isLocalWorkspaceGitAuthMode, sameWorkspaceRegistration, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { prepareWorkspaceCheckout } from './prepare.js';
+import { WorkspaceContextError } from './context-error.js';
+import { scheduleDependencyInstall } from './dependencies.js';
+import { ensureWorkspaceSkills, readWorkspaceSkills } from './skills.js';
+import { loadWorkspaceSkillArtifact, workspacePlatformSkillAccess } from './skill-artifact-loader.js';
+import { writeWorkspaceCliContext } from './cli-context.js';
+import { attachWorkspaceRemote } from './git.js';
+export { WorkspaceContextError } from './context-error.js';
+const exec = promisify(execFile);
+export function revisionScope(state, workspaceId, directoryName = 'basic') {
+    return state.config.workspaceMode === 'multi' ? `${workspaceId}:${directoryName}` : undefined;
+}
+export function workspaceSessions(state, workspaceId, directoryName = 'basic') {
+    return state.journal
+        .listSessions()
+        .filter((item) => state.config.workspaceMode !== 'multi' || (item.workspaceId === workspaceId && (item.directoryName ?? 'basic') === directoryName));
+}
+export async function workspaceRoot(state, workspaceId, directoryName = 'basic') {
+    if (state.config.workspaceMode !== 'multi')
+        return state.config.workspaceRoot;
+    if (!workspaceId || !state.journal.getWorkspace(workspaceId))
+        throw new WorkspaceContextError('workspace_not_registered');
+    if (!/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/.test(directoryName))
+        throw new WorkspaceContextError('invalid_workspace_directory');
+    if (directoryName !== 'basic' && !state.journal.getWorkspace(workspaceId)?.directories?.some(directory => directory.directoryName === directoryName))
+        throw new WorkspaceContextError('workspace_directory_not_registered');
+    return checkedDirectory(state, workspaceId, directoryName);
+}
+async function checkedDirectory(state, workspaceId, directoryName = 'basic') {
+    if (!/^[0-9a-f-]{36}$/i.test(workspaceId))
+        throw new WorkspaceContextError('invalid_workspace');
+    const parent = await realpath(state.config.workspaceRoot);
+    const container = join(parent, workspaceId);
+    const containerStat = await lstat(container).catch(() => undefined);
+    if (!containerStat?.isDirectory() || containerStat.isSymbolicLink() || relative(parent, await realpath(container)) !== workspaceId)
+        throw new WorkspaceContextError('workspace_not_prepared');
+    const target = join(container, directoryName);
+    try {
+        const stat = await lstat(target);
+        if (!stat.isDirectory() ||
+            stat.isSymbolicLink() ||
+            relative(container, await realpath(target)) !== directoryName) {
+            throw new WorkspaceContextError('invalid_workspace_directory');
+        }
+        const stateDir = await realpath(state.config.stateDir);
+        if (stateDir === target || stateDir.startsWith(`${target}/`))
+            throw new WorkspaceContextError('invalid_workspace_directory');
+        return target;
+    }
+    catch (error) {
+        if (error instanceof WorkspaceContextError)
+            throw error;
+        throw new WorkspaceContextError('workspace_not_prepared');
+    }
+}
+/** Registers a fixed directory; optional first creation is restricted to its trusted binding. */
+export async function workspaceContainerRoot(state, workspaceId) {
+    if (state.config.workspaceMode !== 'multi')
+        return state.config.workspaceRoot;
+    if (!workspaceId || !state.journal.getWorkspace(workspaceId))
+        throw new WorkspaceContextError('workspace_not_registered');
+    if (!/^[0-9a-f-]{36}$/i.test(workspaceId))
+        throw new WorkspaceContextError('invalid_workspace');
+    const parent = await realpath(state.config.workspaceRoot);
+    const container = join(parent, workspaceId);
+    const stat = await lstat(container).catch(() => undefined);
+    if (!stat?.isDirectory() || stat.isSymbolicLink() || relative(parent, await realpath(container)) !== workspaceId)
+        throw new WorkspaceContextError('workspace_not_prepared');
+    const stateDir = await realpath(state.config.stateDir);
+    if (stateDir === container || stateDir.startsWith(`${container}/`))
+        throw new WorkspaceContextError('invalid_workspace_directory');
+    return container;
+}
+export async function sessionWorkspaceRoot(state, workspaceId, directoryName = 'basic') {
+    return directoryName === 'root' ? workspaceContainerRoot(state, workspaceId) : workspaceRoot(state, workspaceId, directoryName);
+}
+export async function workspaceContextFromRoot(state, cwd) {
+    const parent = await realpath(state.config.workspaceRoot);
+    const parts = relative(parent, cwd).split('/');
+    if (parts.length !== 1 && parts.length !== 2)
+        throw new WorkspaceContextError('workspace_not_registered');
+    const workspaceId = parts[0];
+    const directoryName = parts.length === 1 ? 'root' : parts[1];
+    if (await sessionWorkspaceRoot(state, workspaceId, directoryName) !== cwd)
+        throw new WorkspaceContextError('workspace_not_registered');
+    return { workspaceId, directoryName };
+}
+export async function registerWorkspace(state, input, leaseFence, preparation, readOnlyBasic = false) {
+    if (state.config.workspaceMode !== 'multi')
+        throw new WorkspaceContextError('multi_workspace_unavailable');
+    const parsed = workspaceRegistrationSchema.safeParse(input);
+    if (!parsed.success)
+        throw new WorkspaceContextError('invalid_workspace_registration');
+    const binding = parsed.data;
+    return state.journal.exclusive(`workspace:${binding.workspaceId}`, async () => {
+        if (state.journal.destroyed())
+            throw new WorkspaceContextError('runtime_destroyed');
+        if (leaseFence < state.acceptedLeaseFence)
+            throw new WorkspaceContextError('stale_lease');
+        state.acceptedLeaseFence = leaseFence;
+        await state.journal.setAcceptedLeaseFence(leaseFence);
+        const existing = state.journal.getWorkspace(binding.workspaceId);
+        const preservedLocalBasic = binding.targetKind !== 'standalone' && binding.preserveLocalBasic === true;
+        const localUpgrade = preservedLocalBasic && binding.targetKind === 'main' && existing?.targetKind === 'standalone';
+        // A standalone workspace promoted to a project's main keeps its checkout and gains that remote.
+        const remoteUpgrade = !preservedLocalBasic && binding.targetKind === 'main' && existing?.targetKind === 'standalone';
+        if (existing && !sameWorkspaceRegistration(existing, binding) && !localUpgrade && !remoteUpgrade)
+            throw new WorkspaceContextError('workspace_binding_conflict');
+        const attachMarker = join(state.config.stateDir, 'workspace-remote-attach', `${binding.workspaceId}.json`);
+        const existingByDir = new Map((existing?.directories ?? []).map(item => [item.directoryName, item]));
+        const directories = binding.directories
+            ? binding.directories.map(item => {
+                const local = existingByDir.get(item.directoryName);
+                return local && local.remixId === item.remixId && local.status === 'ready' && item.status === 'pending'
+                    ? { ...item, status: 'ready', sourceCommit: item.sourceCommit ?? local.sourceCommit }
+                    : item;
+            })
+            : existing?.directories;
+        if (directories?.some(directory => directory.directoryName === 'basic' && directory.status === 'reclaimed')) {
+            // Registration publishes trusted identity. Only an explicit basic ensure restores the checkout.
+            const parent = await realpath(state.config.workspaceRoot);
+            const container = join(parent, binding.workspaceId);
+            await mkdir(container, { mode: 0o2770 }).catch(error => { if (error.code !== 'EEXIST')
+                throw error; });
+            const registered = { ...binding, directories };
+            await state.journal.putWorkspace(registered);
+            await workspaceContainerRoot(state, binding.workspaceId);
+            return registered;
+        }
+        let root;
+        try {
+            root = await checkedDirectory(state, binding.workspaceId);
+        }
+        catch (error) {
+            if (existing && error instanceof WorkspaceContextError && error.message === 'workspace_not_prepared')
+                throw new WorkspaceContextError('workspace_recovery_required');
+            if (!preparation || !(error instanceof WorkspaceContextError) || error.message !== 'workspace_not_prepared')
+                throw error;
+            await prepareWorkspaceCheckout(state, binding, preparation, leaseFence);
+            root = await checkedDirectory(state, binding.workspaceId);
+        }
+        const git = async (...args) => (await exec('git', ['-C', root, ...args], {
+            timeout: 5000,
+            maxBuffer: 64 * 1024,
+            env: {
+                PATH: process.env.PATH,
+                HOME: process.env.HOME,
+                GIT_CONFIG_NOSYSTEM: '1',
+                GIT_CONFIG_GLOBAL: '/dev/null',
+            },
+        })).stdout.trim();
+        // Unfinished if it failed part way: the marker outlives the journal entry written below.
+        if (binding.targetKind === 'main' && !preservedLocalBasic && (remoteUpgrade || await lstat(attachMarker).then(() => true, () => false))) {
+            if (preparation?.mode !== 'clone' || !state.gitCredentials)
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            await mkdir(join(state.config.stateDir, 'workspace-remote-attach'), { recursive: true, mode: 0o700 });
+            await writeFile(attachMarker, JSON.stringify({ repositoryUrl: binding.repositoryUrl, branchName: binding.branchName }), { mode: 0o600 });
+            // The credential helper only serves a workspace the journal knows to be bound.
+            await state.journal.putWorkspace({ ...binding, directories });
+            try {
+                await state.gitCredentials.configure(binding, preparation);
+            }
+            catch {
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            }
+            try {
+                await attachWorkspaceRemote(root, binding.repositoryUrl, binding.branchName);
+            }
+            catch {
+                throw new WorkspaceContextError('workspace_remote_attach_failed');
+            }
+            await rm(attachMarker, { force: true });
+        }
+        try {
+            let checkoutMatches;
+            if (binding.targetKind === 'standalone' || preservedLocalBasic) {
+                const gitDirectory = await lstat(join(root, '.git'));
+                checkoutMatches = gitDirectory.isDirectory() && !gitDirectory.isSymbolicLink()
+                    && (await git('rev-parse', '--absolute-git-dir')) === join(root, '.git')
+                    && (await git('remote')) === '';
+            }
+            else {
+                checkoutMatches = (await git('config', '--get', 'remote.origin.url')) === binding.repositoryUrl
+                    && (await git('symbolic-ref', '--short', 'HEAD')) === binding.branchName;
+            }
+            if ((await realpath(await git('rev-parse', '--show-toplevel'))) !== root || !checkoutMatches) {
+                throw new WorkspaceContextError('workspace_checkout_mismatch');
+            }
+        }
+        catch (error) {
+            if (error instanceof WorkspaceContextError)
+                throw error;
+            throw new WorkspaceContextError('workspace_not_prepared');
+        }
+        if (state.journal.destroyed())
+            throw new WorkspaceContextError('runtime_destroyed');
+        if (leaseFence < state.acceptedLeaseFence)
+            throw new WorkspaceContextError('stale_lease');
+        if (readOnlyBasic || preservedLocalBasic) {
+            await state.journal.putWorkspace({ ...binding, directories });
+            return binding;
+        }
+        if (preparation?.mode === 'clone' && (preparation.transport?.kind === 'git-gateway-v2' || isLocalWorkspaceGitAuthMode(preparation.authMode))) {
+            if (!state.gitCredentials)
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            try {
+                await state.gitCredentials.configure(binding, preparation);
+            }
+            catch {
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            }
+        }
+        try {
+            await ensureWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'), workspacePlatformSkillAccess(state, binding.workspaceId));
+        }
+        catch {
+            throw new WorkspaceContextError('workspace_skills_unavailable');
+        }
+        await writeWorkspaceCliContext(root, binding.workspaceId);
+        await state.journal.putWorkspace({ ...binding, directories });
+        try {
+            await readWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'), entry => loadWorkspaceSkillArtifact(state, binding.workspaceId, entry));
+        }
+        catch { /* Skills reads and native turns diagnose missing artifacts; files and source repair remain available. */ }
+        // Runs in the background; every registration rechecks it, so reopening retries a failed install.
+        void scheduleDependencyInstall(state, revisionScope(state, binding.workspaceId), root);
+        return binding;
+    });
+}

package/dist/workspace-runtime/workspaces/revisions.js

@@ -0,0 +1,31 @@
+import { readWorkspaceFile } from './files.js';
+import { revisionScope, workspaceRoot } from './registry.js';
+/** Observe native/manual edits before checking an editor's conditional write. */
+export async function withObservedFile(state, workspaceId, path, action, directoryName = 'basic') {
+    const scope = revisionScope(state, workspaceId, directoryName);
+    return state.journal.exclusive(`file:${scope ?? 'single'}:${path}`, async () => {
+        const records = state.journal.fileRevisions(scope);
+        const previous = records[path];
+        let file;
+        try {
+            file = await readWorkspaceFile(await workspaceRoot(state, workspaceId, directoryName), path, records);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const hash = file?.contentHash ?? '';
+        const revision = previous ? previous.revision + (previous.contentHash === hash ? 0 : 1) : 0;
+        if ((!previous && file) || (previous && previous.contentHash !== hash)) {
+            await state.journal.putFileRevision(path, { revision, contentHash: hash }, scope);
+        }
+        return action({ file: file ? { ...file, revision } : undefined, revision });
+    });
+}
+export async function readObservedFile(state, workspaceId, path, directoryName = 'basic') {
+    return withObservedFile(state, workspaceId, path, async ({ file }) => {
+        if (!file)
+            throw Object.assign(new Error('file_not_found'), { code: 'ENOENT' });
+        return file;
+    }, directoryName);
+}

package/dist/workspace-runtime/workspaces/skill-artifact-loader.js

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+import { workspaceRoot } from './registry.js';
+import { PLATFORM_ROUTES, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+const MAX_ARTIFACT_BYTES = 80 * 1024 * 1024;
+/** Requests an exact locked artifact using control identity; no storage credentials reach Codex. */
+export async function loadWorkspaceSkillArtifact(state, workspaceId, entry, directoryName = 'basic') {
+    await workspaceRoot(state, workspaceId, directoryName);
+    return requestWorkspaceSkillArtifact(state, workspaceId, entry);
+}
+async function requestWorkspaceSkillArtifact(state, workspaceId, entry) {
+    const epoch = state.runtimeEpoch;
+    if (state.journal.destroyed())
+        throw new Error('workspace_skills_unavailable');
+    const endpoint = platformEndpoint(state.config.publicBaseUrl, PLATFORM_ROUTES.skillArtifacts);
+    const response = await fetch(endpoint, {
+        method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30_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: epoch, workspaceId, entryKey: entry.entryKey, revision: entry.revision }),
+    });
+    if (!response.ok || !response.body)
+        throw new Error('workspace_skills_artifact_unavailable');
+    const reader = response.body.getReader(), chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            total += chunk.value.byteLength;
+            if (total > Math.ceil(MAX_ARTIFACT_BYTES * 4 / 3) + 4096)
+                throw new Error('workspace_skills_artifact_too_large');
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (typeof result.content !== 'string' || result.artifactHash !== entry.revision.artifactHash
+        || result.content.length > Math.ceil(MAX_ARTIFACT_BYTES * 4 / 3) || result.content.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(result.content))
+        throw new Error('workspace_skills_digest_mismatch');
+    const archive = Buffer.from(result.content, 'base64');
+    if (archive.byteLength > MAX_ARTIFACT_BYTES || archive.toString('base64') !== result.content || createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+        throw new Error('workspace_skills_digest_mismatch');
+    if (state.journal.destroyed() || epoch !== state.runtimeEpoch)
+        throw new Error('workspace_skills_unavailable');
+    return archive;
+}
+/** The platform independently authorizes the trusted binding, including an unpublished checkout. */
+export function workspacePlatformSkillAccess(state, workspaceId) {
+    return {
+        resolve: async (skillRefs) => {
+            const epoch = state.runtimeEpoch;
+            if (state.journal.destroyed())
+                throw new Error('workspace_skills_unavailable');
+            const response = await fetch(`${platformEndpoint(state.config.publicBaseUrl, PLATFORM_ROUTES.skillArtifacts)}/resolve`, {
+                method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30_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: epoch, workspaceId, skillRefs }),
+            });
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new Error('workspace_skills_platform_unavailable');
+            }
+            if (!response.body)
+                throw new Error('workspace_skills_platform_unavailable');
+            const reader = response.body.getReader(), chunks = [];
+            let total = 0;
+            try {
+                while (true) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    total += part.value.byteLength;
+                    if (total > 1024 * 1024)
+                        throw new Error('workspace_skills_platform_unavailable');
+                    chunks.push(part.value);
+                }
+            }
+            finally {
+                await reader.cancel().catch(() => undefined);
+            }
+            if (state.journal.destroyed() || epoch !== state.runtimeEpoch)
+                throw new Error('workspace_skills_unavailable');
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        },
+        loadArtifact: entry => requestWorkspaceSkillArtifact(state, workspaceId, entry),
+    };
+}

package/dist/workspace-runtime/workspaces/skills.js

@@ -0,0 +1,189 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { load } from 'js-yaml';
+import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
+import { initializeLocalProjectSkills } from '../../project-skills/local-store.js';
+import { resolveCliPackageRoot } from '../../scaffold/compose.js';
+import { selectPlatformSkillSnapshot } from '../../project-skills/builtin-import.js';
+import { EMPTY_WORKSPACE_REPOSITORY_SKILLS, EMPTY_WORKSPACE_PLATFORM_SKILLS } from './empty-template.js';
+import { excludeFromGit } from './dependencies.js';
+/** Runtime availability is determined by the locked metadata, independent of unsynced source edits. */
+export async function readWorkspaceSkillSnapshot(root) {
+    const management = await lstat(join(root, '.playcraft'));
+    const declaration = join(root, '.playcraft/skills.json');
+    const stat = await lstat(declaration);
+    if (!management.isDirectory() || management.isSymbolicLink() || !stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+        throw new Error('workspace_skills_invalid');
+    return validateProjectSkillsSnapshot(await readFile(declaration, 'utf8'), await readProjectSkillsLockFile(root));
+}
+/** Existing managed projects keep their exact selection. Legacy source folders are adopted once. */
+export async function ensureWorkspaceSkills(root, cache, access) {
+    await excludeFromGit(root, '/.playcraft/skills/');
+    await excludeFromGit(root, '/.playcraft/skill-artifacts/');
+    const raw = await readProjectSkillsLockFile(root);
+    if (raw !== null) {
+        await readWorkspaceSkillSnapshot(root);
+        return;
+    }
+    const inventory = await inspectProjectSkills(root);
+    if (inventory.issues.length)
+        throw new Error('workspace_skills_invalid');
+    const names = new Set(inventory.discovered.map(entry => basename(entry.root)));
+    const platformNames = EMPTY_WORKSPACE_PLATFORM_SKILLS.filter(name => !names.has(name));
+    const selected = platformNames.length ? await selectPlatformSkillSnapshot(platformNames, access) : undefined;
+    const added = new Set();
+    await initializeLocalProjectSkills(root, cache, { enabledRoots: added, platform: selected,
+        prepareSources: async () => {
+            for (const name of EMPTY_WORKSPACE_REPOSITORY_SKILLS) {
+                if (names.has(name))
+                    continue;
+                await safeDirectory(root, '.agents/skills');
+                const source = `.agents/skills/${name}`;
+                await mkdir(join(root, source), { mode: 0o755 });
+                added.add(source);
+                const template = join(resolveCliPackageRoot(), 'project-template/.claude/skills', name);
+                for (const child of await readdir(template))
+                    await cp(join(template, child), join(root, source, child), {
+                        recursive: true, force: false, errorOnExist: true,
+                    });
+            }
+        },
+        rollbackSources: async () => {
+            for (const source of added)
+                await rm(join(root, source), { recursive: true, force: true });
+        },
+    });
+}
+async function safeDirectory(root, path) {
+    let current = root;
+    for (const segment of path.split('/')) {
+        current = join(current, segment);
+        await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        const stat = await lstat(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('workspace_skills_invalid');
+    }
+    return current;
+}
+/** Cache misses may reconstruct only the exact locked repository bytes, never a newer source. */
+async function lockedFiles(root, cache, entry, view, loadArtifact) {
+    const persistent = await safeDirectory(root, '.playcraft/skill-artifacts');
+    const saved = join(persistent, `${entry.revision.artifactHash}.tar.gz`);
+    const path = join(cache, `${entry.revision.artifactHash}.tar.gz`);
+    let archive;
+    try {
+        const stat = await lstat(saved);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 80 * 1024 * 1024)
+            throw new Error('workspace_skills_invalid_bundle');
+        archive = await readFile(saved);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        try {
+            archive = await readFile(path);
+        }
+        catch (cacheError) {
+            if (cacheError.code !== 'ENOENT')
+                throw cacheError;
+            const declaration = view.declaration.entries.find(item => item.entryKey === entry.entryKey);
+            if (entry.revision.kind === 'source' && declaration.source.kind === 'repository') {
+                const source = await readProjectSkillSource(root, declaration);
+                if (source.sourceTreeHash !== entry.sourceTreeHash)
+                    throw new Error('workspace_skills_source_changed');
+                archive = createCanonicalBundleArchive(source.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
+            }
+            else {
+                if (!loadArtifact)
+                    throw new Error('workspace_skills_artifact_unavailable');
+                archive = await loadArtifact(entry);
+            }
+        }
+    }
+    if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+        throw new Error('workspace_skills_digest_mismatch');
+    const extracted = extractBundleArchive(archive);
+    if (extracted.issues.length)
+        throw new Error('workspace_skills_invalid_bundle');
+    if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
+        throw new Error('workspace_skills_digest_mismatch');
+    const temporary = `${saved}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, archive, { flag: 'wx', mode: 0o644 });
+        await rename(temporary, saved);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return extracted.files;
+}
+function metadata(entryKey, content) {
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+    const parsed = frontmatter ? load(frontmatter[1]) : {};
+    const data = parsed && typeof parsed === 'object' ? parsed : {};
+    return { entryKey, name: typeof data.name === 'string' ? data.name : entryKey,
+        description: typeof data.description === 'string' ? data.description : '', content };
+}
+export async function readWorkspaceSkills(root, cache, loadArtifact) {
+    const snapshot = await readWorkspaceSkillSnapshot(root);
+    const skills = await Promise.all(snapshot.lock.entries.map(async (entry) => {
+        const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
+        const body = files.find(file => file.path === 'SKILL.md');
+        if (!body)
+            throw new Error('workspace_skills_body_missing');
+        return metadata(entry.entryKey, body.data.toString('utf8'));
+    }));
+    return { ...snapshot, lockHash: createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex'), skills };
+}
+/** Read-only task generation lives outside source discovery and is omitted from Git/snapshots. */
+export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
+    const snapshot = await readWorkspaceSkillSnapshot(root);
+    const entries = effectiveProjectSkills(snapshot.declaration, snapshot.lock, 'sandbox-agent');
+    const base = await safeDirectory(root, '.playcraft/skills');
+    const lockHash = createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex');
+    const generation = await safeDirectory(base, lockHash);
+    const skills = [];
+    const expectedFiles = new Set();
+    for (const entry of entries) {
+        const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
+        for (const file of files) {
+            const target = join(generation, entry.entryKey, file.path);
+            const relative = join(entry.entryKey, file.path);
+            expectedFiles.add(relative);
+            await safeDirectory(generation, dirname(relative));
+            await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(async (error) => {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                const stat = await lstat(target);
+                if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || !file.data.equals(await readFile(target)))
+                    throw new Error('workspace_skills_digest_mismatch');
+            });
+        }
+        const body = files.find(file => file.path === 'SKILL.md');
+        if (!body)
+            throw new Error('workspace_skills_body_missing');
+        const info = metadata(entry.entryKey, body.data.toString('utf8'));
+        skills.push({ name: info.name, description: info.description, skillRef: entry.revision.skillRef,
+            revision: entry.revision.kind === 'source' ? entry.revision.sourceRevision : entry.revision.version,
+            path: join(generation, entry.entryKey, 'SKILL.md') });
+    }
+    const verifyTree = async (directory, relative = '') => {
+        for (const item of await readdir(directory, { withFileTypes: true })) {
+            const path = join(relative, item.name);
+            if (item.isSymbolicLink())
+                throw new Error('workspace_skills_invalid_bundle');
+            if (item.isDirectory()) {
+                if (![...expectedFiles].some(file => file.startsWith(`${path}/`)))
+                    throw new Error('workspace_skills_invalid_bundle');
+                await verifyTree(join(directory, item.name), path);
+            }
+            else if (!item.isFile() || !expectedFiles.has(path))
+                throw new Error('workspace_skills_invalid_bundle');
+        }
+    };
+    await verifyTree(generation);
+    return { declarationHash: snapshot.lock.declarationHash,
+        lockHash, skills };
+}

package/dist/workspace-runtime/workspaces/video-attachments.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { WORKSPACE_VIDEO_ATTACHMENT_MAX_DURATION_MS, WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES } from '@playcraft/common/cloud-workspace/runtime';
+/** Probe the opened descriptor so replacing a pathname cannot redirect the media reader. */
+export async function probeAttachmentVideo(handle) {
+    const output = await new Promise((resolve, reject) => {
+        const child = spawn(process.env.PLAYCRAFT_FFPROBE_PATH ?? 'ffprobe', [
+            '-v', 'error', '-protocol_whitelist', 'file,pipe', '-show_entries',
+            'format=format_name,duration:stream=codec_type,width,height', '-of', 'json',
+            process.platform === 'linux' ? '/proc/self/fd/3' : '/dev/fd/3',
+        ], { stdio: ['ignore', 'pipe', 'ignore', handle.fd] });
+        let text = '';
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('invalid_attachment')); }, 15_000);
+        timer.unref();
+        child.stdout.on('data', (chunk) => {
+            text += chunk.toString('utf8');
+            if (text.length > 64 * 1024) {
+                child.kill('SIGKILL');
+                reject(new Error('invalid_attachment'));
+            }
+        });
+        child.once('error', () => { clearTimeout(timer); reject(new Error('video_probe_unavailable')); });
+        child.once('close', code => { clearTimeout(timer); code === 0 ? resolve(text) : reject(new Error('invalid_attachment')); });
+    });
+    const result = JSON.parse(output);
+    const stream = result.streams?.find(item => item.codec_type === 'video');
+    const durationMs = Math.round(Number(result.format?.duration) * 1000);
+    const formats = result.format?.format_name?.split(',') ?? [];
+    const mimeType = formats.includes('webm') ? 'video/webm' : formats.includes('mp4') ? 'video/mp4' : formats.includes('mov') ? 'video/quicktime' : undefined;
+    if (!stream || !mimeType || !Number.isFinite(durationMs) || durationMs <= 0 || durationMs > WORKSPACE_VIDEO_ATTACHMENT_MAX_DURATION_MS
+        || !Number.isSafeInteger(stream.width) || !Number.isSafeInteger(stream.height) || stream.width <= 0 || stream.height <= 0
+        || stream.width > 16384 || stream.height > 16384)
+        throw new Error('invalid_attachment');
+    return { mimeType, durationMs, width: stream.width, height: stream.height };
+}
+export async function hashAttachment(handle) {
+    const digest = createHash('sha256');
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let position = 0;
+    for (;;) {
+        const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
+        if (!bytesRead)
+            return digest.digest('hex');
+        digest.update(chunk.subarray(0, bytesRead));
+        position += bytesRead;
+        if (position > WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES)
+            throw new Error('invalid_attachment');
+    }
+}