@playcraft/cli 0.1.66 → 0.1.67

package/dist/project-skills/local-store.js

@@ -27,12 +27,34 @@ async function change(directory, action) {
         await rm(lease);
     }
 }
-async function writeSnapshot(directory, snapshot) {
+async function snapshotBytes(directory) {
+    const declaration = await readFile(join(directory, PROJECT_SKILLS_DECLARATION_PATH))
+        .catch((error) => { if (error.code === 'ENOENT')
+        return null; throw error; });
+    return { declaration, lock: await readProjectSkillsLockFile(directory) };
+}
+async function writeSnapshot(directory, snapshot, expected) {
     validateProjectSkillsSnapshot(snapshot.declaration, snapshot.lock);
-    for (const [file, value] of [[PROJECT_SKILLS_DECLARATION_PATH, snapshot.declaration], [PROJECT_SKILLS_LOCK_PATH, snapshot.lock]]) {
-        const target = join(directory, file), temporary = `${target}.${randomUUID()}.tmp`;
-        await writeFile(temporary, `${canonicalProjectSkillsJson(value)}\n`, { flag: 'wx', mode: 0o644 });
-        await rename(temporary, target);
+    const staged = [];
+    try {
+        for (const [file, value] of [[PROJECT_SKILLS_DECLARATION_PATH, snapshot.declaration], [PROJECT_SKILLS_LOCK_PATH, snapshot.lock]]) {
+            const target = join(directory, file), temporary = `${target}.${randomUUID()}.tmp`;
+            staged.push({ target, temporary });
+            await writeFile(temporary, `${canonicalProjectSkillsJson(value)}\n`, { flag: 'wx', mode: 0o644 });
+        }
+        if (expected) {
+            const current = await snapshotBytes(directory);
+            if ((current.declaration === null) !== (expected.declaration === null)
+                || current.declaration && expected.declaration && !current.declaration.equals(expected.declaration)
+                || current.lock !== expected.lock)
+                throw new Error('skills_revision_conflict');
+        }
+        for (const { temporary, target } of staged)
+            await rename(temporary, target);
+    }
+    finally {
+        for (const { temporary } of staged)
+            await rm(temporary, { force: true });
     }
 }
 /** Initializes an unmanaged checkout with one complete source and release snapshot under the existing writer lease. */
@@ -55,7 +77,7 @@ export async function initializeLocalProjectSkills(directory, cache, options) {
         let configurationWriteStarted = false;
         try {
             await options.prepareSources?.();
-            const snapshot = buildLocalProjectSkillsSnapshot(await inspectProjectSkills(directory));
+            const snapshot = buildLocalProjectSkillsSnapshot(await inspectProjectSkills(directory), undefined, { lockVersion: options.platform?.lock.lockVersion ?? 3 });
             for (const entry of snapshot.declaration.entries)
                 if (entry.source.kind === 'repository' && options.enabledRoots.has(entry.source.root))
                     entry.enabled = true;
@@ -64,7 +86,9 @@ export async function initializeLocalProjectSkills(directory, cache, options) {
                 if (platform.declaration.entries.some(entry => entry.source.kind !== 'registry'))
                     throw new Error('workspace_skills_invalid');
                 snapshot.declaration.entries.push(...platform.declaration.entries);
-                snapshot.lock.entries.push(...platform.lock.entries);
+                if (snapshot.lock.lockVersion !== platform.lock.lockVersion)
+                    throw new Error('workspace_skills_lock_version_mismatch');
+                snapshot.lock = { ...snapshot.lock, entries: [...snapshot.lock.entries, ...platform.lock.entries] };
             }
             snapshot.lock.declarationHash = declarationDigest(snapshot.declaration);
             validateProjectSkillsSnapshot(snapshot.declaration, snapshot.lock);
@@ -73,13 +97,16 @@ export async function initializeLocalProjectSkills(directory, cache, options) {
             for (const artifact of [...snapshot.artifacts, ...(options.platform?.artifacts ?? [])]) {
                 if (createHash('sha256').update(artifact.archive).digest('hex') !== artifact.artifactHash)
                     throw new Error('workspace_skills_digest_mismatch');
-                const target = join(cache, `${artifact.artifactHash}.tar.gz`), temporary = `${target}.${randomUUID()}.tmp`;
-                try {
-                    await writeFile(temporary, artifact.archive, { flag: 'wx', mode: 0o600 });
-                    await rename(temporary, target);
-                }
-                finally {
-                    await rm(temporary, { force: true });
+                const contentHash = 'contentHash' in artifact ? artifact.contentHash : undefined;
+                for (const name of [`${artifact.artifactHash}.tar.gz`, ...(contentHash ? [`content-${contentHash}.tar.gz`] : [])]) {
+                    const target = join(cache, name), temporary = `${target}.${randomUUID()}.tmp`;
+                    try {
+                        await writeFile(temporary, artifact.archive, { flag: 'wx', mode: 0o600 });
+                        await rename(temporary, target);
+                    }
+                    finally {
+                        await rm(temporary, { force: true });
+                    }
                 }
             }
             configurationWriteStarted = true;
@@ -107,8 +134,9 @@ export async function initializeLocalProjectSkills(directory, cache, options) {
         }
     });
 }
-export async function syncLocalProjectSkills(directory, cache = projectSkillsCache()) {
+export async function syncLocalProjectSkills(directory, cache = projectSkillsCache(), options = {}) {
     return change(directory, async () => {
+        const original = await snapshotBytes(directory);
         let previous;
         try {
             previous = await readProjectSkillsLockFile(directory) ?? undefined;
@@ -117,7 +145,7 @@ export async function syncLocalProjectSkills(directory, cache = projectSkillsCac
             if (error.code !== 'ENOENT')
                 throw error;
         }
-        const snapshot = buildLocalProjectSkillsSnapshot(await inspectProjectSkills(directory), previous);
+        const snapshot = buildLocalProjectSkillsSnapshot(await inspectProjectSkills(directory), previous, options);
         await mkdir(cache, { recursive: true, mode: 0o700 });
         for (const artifact of snapshot.artifacts) {
             const target = join(cache, `${artifact.artifactHash}.tar.gz`);
@@ -125,18 +153,19 @@ export async function syncLocalProjectSkills(directory, cache = projectSkillsCac
             await writeFile(temporary, artifact.archive, { flag: 'wx', mode: 0o600 });
             await rename(temporary, target);
         }
-        await writeSnapshot(directory, snapshot);
+        await writeSnapshot(directory, snapshot, original);
         return { declaration: snapshot.declaration, lock: snapshot.lock };
     });
 }
 export async function enableLocalProjectSkill(directory, entryKey, enabled) {
     return change(directory, async () => {
+        const original = await snapshotBytes(directory);
         const previous = await readLocalProjectSkillSnapshot(directory);
         const next = setProjectSkillEnabled(previous.declaration, previous.lock, entryKey, enabled);
         // Disabled required dependencies are shown immediately, before changing either file.
         for (const surface of ['portal-agent', 'sandbox-agent', 'build-time'])
             effectiveProjectSkills(next.declaration, next.lock, surface);
-        await writeSnapshot(directory, next);
+        await writeSnapshot(directory, next, original);
         return next;
     });
 }
@@ -150,27 +179,54 @@ export async function installFrozenProjectSkills(directory, cache = projectSkill
         for (const entry of effective) {
             const cached = join(cache, `${entry.revision.artifactHash}.tar.gz`);
             let archive;
+            let contentAddressed = false;
             try {
                 archive = await readFile(cached);
             }
             catch (error) {
-                if (error.code !== 'ENOENT' || entry.revision.kind !== 'source')
+                if (error.code !== 'ENOENT')
                     throw error;
-                const declaration = snapshot.declaration.entries.find(item => item.entryKey === entry.entryKey);
-                const source = await readProjectSkillSource(directory, declaration);
-                if (source.sourceTreeHash !== entry.sourceTreeHash)
-                    throw new Error(`Source digest mismatch: ${entry.entryKey}`);
-                archive = createCanonicalBundleArchive(source.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
-                if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
-                    throw new Error(`Artifact digest mismatch: ${entry.entryKey}`);
-                await writeFile(cached, archive, { flag: 'wx', mode: 0o600 }).catch(error => { if (error.code !== 'EEXIST')
-                    throw error; });
+                if (snapshot.lock.lockVersion === 4) {
+                    try {
+                        archive = await readFile(join(cache, `content-${entry.revision.contentHash}.tar.gz`));
+                        contentAddressed = true;
+                    }
+                    catch (contentError) {
+                        if (contentError.code !== 'ENOENT')
+                            throw contentError;
+                    }
+                }
+                if (!contentAddressed) {
+                    if (entry.revision.kind !== 'source')
+                        throw error;
+                    const declaration = snapshot.declaration.entries.find(item => item.entryKey === entry.entryKey);
+                    const source = await readProjectSkillSource(directory, declaration);
+                    if (source.sourceTreeHash !== entry.sourceTreeHash)
+                        throw new Error(`Source digest mismatch: ${entry.entryKey}`);
+                    if (snapshot.lock.lockVersion === 4) {
+                        if (source.sourceTreeHash !== entry.revision.contentHash)
+                            throw new Error(`Source digest mismatch: ${entry.entryKey}`);
+                        for (const file of source.files) {
+                            const target = join(generation, entry.entryKey, file.path);
+                            await mkdir(join(target, '..'), { recursive: true });
+                            await writeFile(target, file.content, { flag: 'wx', mode: 0o444 });
+                        }
+                        continue;
+                    }
+                    archive = createCanonicalBundleArchive(source.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
+                    if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+                        throw new Error(`Artifact digest mismatch: ${entry.entryKey}`);
+                    await writeFile(cached, archive, { flag: 'wx', mode: 0o600 }).catch(error => { if (error.code !== 'EEXIST')
+                        throw error; });
+                }
             }
-            if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+            if (!contentAddressed && createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
                 throw new Error(`Artifact digest mismatch: ${entry.entryKey}`);
             const extracted = extractBundleArchive(archive);
             if (extracted.issues.length)
                 throw new Error(JSON.stringify(extracted.issues));
+            if (snapshot.lock.lockVersion === 4 && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.revision.contentHash)
+                throw new Error(`Content digest mismatch: ${entry.entryKey}`);
             if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
                 throw new Error(`Source digest mismatch: ${entry.entryKey}`);
             for (const file of extracted.files) {
@@ -193,15 +249,18 @@ export async function explainLocalProjectSkills(directory) {
 export async function adoptServerProjectSkillSnapshot(directory, expected, response, checkpoint) {
     const next = validateProjectSkillsSnapshot(response.declaration, response.lock);
     const withoutIdentity = (snapshot) => ({
+        lockVersion: snapshot.lock.lockVersion,
         declaration: { ...snapshot.declaration, entries: snapshot.declaration.entries.map(entry => ({ ...entry,
                 source: entry.source.kind === 'repository' ? { kind: entry.source.kind, root: entry.source.root } : entry.source })) },
         entries: snapshot.lock.entries.map(entry => ({ entryKey: entry.entryKey, sourceTreeHash: entry.sourceTreeHash,
             dependencies: entry.dependencies,
-            revision: entry.revision.kind === 'source' ? { ...entry.revision, skillRef: undefined } : entry.revision })),
+            revision: { ...entry.revision, ...(entry.revision.kind === 'source' ? { skillRef: undefined } : {}),
+                ...(snapshot.lock.lockVersion === 4 ? { artifactHash: undefined } : {}) } })),
     });
     if (canonicalProjectSkillsJson(withoutIdentity(expected)) !== canonicalProjectSkillsJson(withoutIdentity(next)))
         throw new Error(t('reconcileChanged'));
     return change(directory, async () => {
+        const original = await snapshotBytes(directory);
         const current = await readLocalProjectSkillSnapshot(directory);
         if (canonicalProjectSkillsJson(current) !== canonicalProjectSkillsJson(expected))
             throw new Error(t('reconcileChanged'));
@@ -215,7 +274,7 @@ export async function adoptServerProjectSkillSnapshot(directory, expected, respo
         checkpoint();
         const changed = canonicalProjectSkillsJson(current) !== canonicalProjectSkillsJson(next);
         if (changed)
-            await writeSnapshot(directory, next);
+            await writeSnapshot(directory, next, original);
         return { changed };
     });
 }

package/dist/project-skills/messages.js

@@ -1,5 +1,13 @@
 const messages = {
     en: {
+        migrateLockV4: 'Upgrade a v3 lock using verified original artifacts and retain a backup',
+        migrationMissingArchive: 'Cannot upgrade: the exact locked artifact is missing',
+        migrationInvalidArchive: 'Cannot upgrade: the locked artifact is invalid or changed',
+        migrationSourceChanged: 'Cannot upgrade: the locked source files changed',
+        migrationConcurrentChanged: 'Concurrent lock change detected; original file preserved for recovery',
+        lockVersion: 'Lock format for a new project: 3 or 4 (existing locks require explicit migration)',
+        invalidLockVersion: 'Lock format must be 3 or 4',
+        migrateLockRequired: 'The existing lock cannot be converted by sync; use skills project migrate-lock-v4.',
         importBuiltins: 'Import published platform skills in Cloud Workspace; preserve exact existing revisions',
         platformRequired: 'Use Cloud Workspace’s Skills panel to import published platform skills. Local template import is unavailable.',
         expectedDeclarationHash: 'Expected declaration digest from the current skill lock',
@@ -37,6 +45,14 @@ const messages = {
         changed: 'Source files have changed since the saved revision',
     },
     zh: {
+        migrateLockV4: '使用已核验的原始技能包升级 v3 锁并保留备份',
+        migrationMissingArchive: '无法升级：缺少锁定的原始技能包',
+        migrationInvalidArchive: '无法升级：锁定的技能包无效或已更改',
+        migrationSourceChanged: '无法升级：锁定的技能源文件已更改',
+        migrationConcurrentChanged: '检测到技能锁并发变更，原文件已保留供恢复',
+        lockVersion: '新项目的技能锁格式：3 或 4（已有锁需要显式迁移）',
+        invalidLockVersion: '技能锁格式必须是 3 或 4',
+        migrateLockRequired: '不能通过 sync 转换已有技能锁，请使用 skills project migrate-lock-v4。',
         importBuiltins: '在云工作区导入已发布平台技能，保留已有精确修订',
         platformRequired: '请在云工作区的技能面板导入已发布平台技能；本地模板导入已停用。',
         expectedDeclarationHash: '当前技能锁中的声明摘要',

package/dist/project-skills/migrate-lock.js

@@ -0,0 +1,166 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalProjectSkillsJson, dependencyDigest, extractBundleArchive, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, PROJECT_SKILLS_DECLARATION_PATH, PROJECT_SKILLS_LOCK_PATH, } from '@playcraft/common/project-skills';
+import { projectSkillsCache } from './local-store.js';
+import { projectSkillsMessage as t } from './messages.js';
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const MAX_ARCHIVE = 80 * 1024 * 1024;
+async function readExactArchive(path, expectedHash) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch(error => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (!handle)
+        return undefined;
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > MAX_ARCHIVE)
+            throw new Error(t('migrationInvalidArchive'));
+        const bytes = await handle.readFile();
+        if (bytes.length !== stat.size || sha256(bytes) !== expectedHash)
+            throw new Error(t('migrationInvalidArchive'));
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Upgrade only from verified v3 bytes. No release is replaced based on name and version alone. */
+export async function migrateProjectSkillsLockV4(directory, cache = projectSkillsCache()) {
+    const management = join(directory, '.playcraft');
+    const managementStat = await lstat(management);
+    if (!managementStat.isDirectory() || managementStat.isSymbolicLink())
+        throw new Error('workspace_skills_invalid');
+    const lease = join(management, 'skills-write.lock');
+    await writeFile(lease, `${process.pid}\n`, { flag: 'wx', mode: 0o600 });
+    let temporary;
+    try {
+        const declarationPath = join(directory, PROJECT_SKILLS_DECLARATION_PATH);
+        const declarationStat = await lstat(declarationPath);
+        if (!declarationStat.isFile() || declarationStat.isSymbolicLink() || declarationStat.size > 1024 * 1024)
+            throw new Error('workspace_skills_invalid');
+        const declarationBytes = await readFile(declarationPath);
+        const lockPath = join(directory, PROJECT_SKILLS_LOCK_PATH);
+        const lockStat = await lstat(lockPath);
+        if (!lockStat.isFile() || lockStat.isSymbolicLink() || lockStat.nlink !== 1 || lockStat.size > 1024 * 1024)
+            throw new Error('workspace_skills_invalid');
+        const lockMode = lockStat.mode & 0o777;
+        const lockBytes = await readProjectSkillsLockFile(directory);
+        const { declaration, lock } = validateProjectSkillsSnapshot(declarationBytes.toString('utf8'), lockBytes);
+        if (lock.lockVersion === 4)
+            return { changed: false, lockVersion: 4 };
+        const artifactsDir = join(management, 'skill-artifacts');
+        await mkdir(artifactsDir, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        const artifactsStat = await lstat(artifactsDir);
+        if (!artifactsStat.isDirectory() || artifactsStat.isSymbolicLink())
+            throw new Error('workspace_skills_invalid');
+        const entries = [];
+        for (const entry of lock.entries) {
+            let contentHash;
+            if (entry.revision.kind === 'source') {
+                const declared = declaration.entries.find(item => item.entryKey === entry.entryKey);
+                const source = await readProjectSkillSource(directory, declared);
+                if (source.sourceTreeHash !== entry.sourceTreeHash)
+                    throw new Error(`${t('migrationSourceChanged')}: ${entry.entryKey}`);
+                contentHash = source.sourceTreeHash;
+            }
+            else {
+                const name = `${entry.revision.artifactHash}.tar.gz`;
+                const archive = await readExactArchive(join(artifactsDir, name), entry.revision.artifactHash)
+                    ?? await readExactArchive(join(cache, name), entry.revision.artifactHash);
+                if (!archive)
+                    throw new Error(`${t('migrationMissingArchive')}: ${entry.entryKey}`);
+                const extracted = extractBundleArchive(archive);
+                if (extracted.issues.length || !extracted.files.some(file => file.path === 'SKILL.md'))
+                    throw new Error(t('migrationInvalidArchive'));
+                contentHash = sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data })));
+            }
+            entries.push({ ...entry, revision: { ...entry.revision, contentHash } });
+        }
+        for (const entry of entries)
+            entry.dependencyLockHash = dependencyDigest(entries, entry.dependencies);
+        const next = validateProjectSkillsSnapshot(declaration, { ...lock, lockVersion: 4, entries }).lock;
+        const old = Buffer.from(lockBytes);
+        const backup = join(artifactsDir, `skills.lock.v3-${sha256(old)}.json`);
+        try {
+            await writeFile(backup, old, { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const saved = await readExactArchive(backup, sha256(old));
+            if (!saved || !saved.equals(old))
+                throw new Error('skills_revision_conflict');
+        }
+        temporary = `${lockPath}.${randomUUID()}.tmp`;
+        const staged = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, lockMode);
+        try {
+            await staged.writeFile(`${canonicalProjectSkillsJson(next)}\n`);
+            // The process umask may remove group write access on creation.
+            await staged.chmod(lockMode);
+        }
+        finally {
+            await staged.close();
+        }
+        for (const declared of declaration.entries) {
+            if (declared.source.kind !== 'repository')
+                continue;
+            const source = await readProjectSkillSource(directory, declared);
+            if (source.sourceTreeHash !== lock.entries.find(item => item.entryKey === declared.entryKey)?.sourceTreeHash) {
+                throw new Error(`${t('migrationSourceChanged')}: ${declared.entryKey}`);
+            }
+        }
+        if (!(await readFile(declarationPath)).equals(declarationBytes) || await readProjectSkillsLockFile(directory) !== lockBytes) {
+            throw new Error('skills_revision_conflict');
+        }
+        const target = lockPath;
+        const recovery = join(artifactsDir, `skills.lock.v3-recovery-${randomUUID()}.json`);
+        // Reserve a unique destination; a cross-device rename fails before the original is moved.
+        await writeFile(recovery, '', { flag: 'wx', mode: 0o600 });
+        try {
+            await rename(target, recovery);
+        }
+        catch (error) {
+            await rm(recovery, { force: true });
+            throw error;
+        }
+        let published = false;
+        try {
+            // A noncooperative writer may have changed the inode after our previous comparison.
+            const moved = await readExactArchive(recovery, sha256(old));
+            const movedStat = await lstat(recovery);
+            if (!moved?.equals(old) || (movedStat.mode & 0o777) !== lockMode)
+                throw new Error('skills_revision_conflict');
+            // Linking is atomic and cannot overwrite a concurrently created target.
+            await link(temporary, target);
+            published = true;
+        }
+        catch (error) {
+            // Restore only into an absent target; always keep the moved inode for recovery.
+            try {
+                const saved = await lstat(recovery);
+                if (saved.isFile() && !saved.isSymbolicLink())
+                    await link(recovery, target);
+            }
+            catch (restoreError) {
+                if (restoreError.code !== 'EEXIST')
+                    throw restoreError;
+            }
+            throw new Error(`${t('migrationConcurrentChanged')}: ${recovery}`, { cause: error });
+        }
+        if (published)
+            await rm(temporary, { force: true });
+        temporary = undefined;
+        // Keep the moved inode: a process that opened the old file may still write to it later.
+        return { changed: true, lockVersion: 4, backup, recovery };
+    }
+    finally {
+        if (temporary)
+            await rm(temporary, { force: true });
+        await rm(lease, { force: true });
+    }
+}

package/dist/project-skills/remote-cache.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, writeFile, rename, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { extractBundleArchive, sourceTreeDigest } from '@playcraft/common/project-skills';
 import { PlayCraftHttpClient } from '../utils/playcraft-http-client.js';
 import { readRemixLocalMeta } from '../remix/local-git.js';
 import { readLocalProjectSkillSnapshot, projectSkillsCache } from './local-store.js';
@@ -15,15 +16,39 @@ export async function downloadLocalProjectSkillArtifacts(directory, cache = proj
     let downloaded = 0;
     for (const locked of snapshot.lock.entries) {
         const file = join(cache, `${locked.revision.artifactHash}.tar.gz`);
+        const contentHash = snapshot.lock.lockVersion === 4 ? locked.revision.contentHash : undefined;
         try {
-            if (createHash('sha256').update(await readFile(file)).digest('hex') === locked.revision.artifactHash)
+            const bytes = await readFile(file);
+            if (createHash('sha256').update(bytes).digest('hex') === locked.revision.artifactHash) {
+                if (contentHash) {
+                    const extracted = extractBundleArchive(bytes);
+                    if (extracted.issues.length || sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== contentHash)
+                        throw new Error(t('downloadMismatch'));
+                }
                 continue;
+            }
         }
         catch (error) {
             if (error.code !== 'ENOENT')
                 throw error;
         }
-        const authorized = view.entries?.find(entry => entry.entryKey === locked.entryKey && entry.artifactHash === locked.revision.artifactHash);
+        const contentFile = contentHash ? join(cache, `content-${contentHash}.tar.gz`) : undefined;
+        if (contentFile) {
+            try {
+                const extracted = extractBundleArchive(await readFile(contentFile));
+                if (!extracted.issues.length && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) === contentHash)
+                    continue;
+                throw new Error(t('downloadMismatch'));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+        }
+        const authorized = view.entries?.find(entry => entry.entryKey === locked.entryKey && (contentHash
+            ? entry.skillRef === locked.revision.skillRef && entry.revisionKind === locked.revision.kind &&
+                (locked.revision.kind === 'release' ? entry.version === locked.revision.version : entry.sourceRevision === locked.revision.sourceRevision)
+            : entry.artifactHash === locked.revision.artifactHash));
         if (!authorized)
             throw new Error(t('downloadMismatch'));
         const response = await fetch(client.url(`/projects/${encodeURIComponent(meta.projectId)}/skills/versions/${authorized.versionId}/archive?${query}`), {
@@ -40,11 +65,17 @@ export async function downloadLocalProjectSkillArtifacts(directory, cache = proj
             parts.push(Buffer.from(chunk));
         }
         const archive = Buffer.concat(parts);
-        if (createHash('sha256').update(archive).digest('hex') !== locked.revision.artifactHash)
+        if (!/^[a-f0-9]{64}$/.test(authorized.artifactHash) || createHash('sha256').update(archive).digest('hex') !== authorized.artifactHash)
             throw new Error(t('downloadMismatch'));
-        const temporary = `${file}.${randomUUID()}.tmp`;
+        if (contentHash) {
+            const extracted = extractBundleArchive(archive);
+            if (extracted.issues.length || sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== contentHash)
+                throw new Error(t('downloadMismatch'));
+        }
+        const target = contentFile ?? file;
+        const temporary = `${target}.${randomUUID()}.tmp`;
         await writeFile(temporary, archive, { mode: 0o600, flag: 'wx' });
-        await rename(temporary, file);
+        await rename(temporary, target);
         downloaded++;
     }
     return { downloaded };

package/dist/utils/agent-api-client.js

@@ -11,7 +11,7 @@ import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
 import { AGENT_TOOL_OPERATION_PROTOCOL, AGENT_TOOL_OPERATION_HEADERS, AGENT_TOOL_OPERATION_CAPABILITIES_PATH, } from '@playcraft/common/agent-tools';
 import { beginToolOperation, findToolOperation } from './tool-operation-journal.js';
 import { businessEndpoint } from './environment-endpoints.js';
-import { PLATFORM_ROUTES } from '@playcraft/common/cloud-workspace/runtime';
+import { PLATFORM_ROUTES, workspaceExecutionContextQuerySchema, workspaceExecutionContextReadSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { cloudRuntimeCredentialHint, isWorkspaceGenerationPath, withGenerationWorkspaceScope } from './generation-workspace-scope.js';
 import { agentGenerationProvenanceHeaders } from './agent-generation-provenance.js';
 import { redactDiagnosticText } from './error-diagnostics.js';
@@ -245,6 +245,23 @@ export class AgentApiClient {
         }
         return res.json();
     }
+    /** Context reads are fresh authenticated queries and never durable mutation receipts. */
+    async readWorkspaceExecutionContext(scope, request, signal = AbortSignal.timeout(15_000)) {
+        const query = workspaceExecutionContextQuerySchema.parse(request);
+        const response = await fetch(this.toolsRequestUrl('/execution-context'), {
+            method: 'POST', redirect: 'error', signal,
+            headers: { ...this.authHeaders(), 'content-type': 'application/json' },
+            body: JSON.stringify({ workspaceId: scope.workspaceId, directoryName: scope.directoryName, request: query }),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => '');
+            const pending = pendingAccountActivationError(response.status, parseErrorPayload(text));
+            if (pending)
+                throw pending;
+            throw new Error(`execution_context_read_failed:${response.status}: ${responseErrorReason(text)}`);
+        }
+        return workspaceExecutionContextReadSchema.parse(await response.json());
+    }
     /** Stream authenticated tool content to a new file; credentials never follow redirects. */
     async download(path, destination, options) {
         const url = this.toolsRequestUrl(path);

package/dist/utils/agent-generation-provenance.js

@@ -13,7 +13,13 @@ export async function agentGenerationProvenanceHeaders(path, body, requestId, cl
         return {};
     }
     const assetCreate = normalized === '/workspace-assets' && payload?.action === 'create';
-    if (!isWorkspaceGenerationPath(normalized) && !assetCreate && normalized !== '/create-batch')
+    const audioWrite = normalized === '/workspace-audio';
+    const audioRequest = payload?.request;
+    const audioRequestId = audioRequest && typeof audioRequest === 'object' && !Array.isArray(audioRequest)
+        ? audioRequest.requestId : undefined;
+    if (audioWrite && (typeof audioRequestId !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(audioRequestId)))
+        return {};
+    if (!isWorkspaceGenerationPath(normalized) && !assetCreate && !audioWrite && normalized !== '/create-batch')
         return {};
     const endpoint = process.env.PLAYCRAFT_AGENT_GENERATION_ENDPOINT;
     const capability = process.env.PLAYCRAFT_AGENT_GENERATION_CAPABILITY;
@@ -29,7 +35,7 @@ export async function agentGenerationProvenanceHeaders(path, body, requestId, cl
             signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000),
             headers: { 'content-type': 'application/json', authorization: `Bearer ${capability}` },
             body: JSON.stringify({ toolPath: `/agent/tools${normalized}`,
-                toolRequestId: assetCreate ? payload.clientRequestId : requestId, payloadHash: hashOperationPayload(payload) }),
+                toolRequestId: audioWrite ? audioRequestId : assetCreate ? payload.clientRequestId : requestId, payloadHash: hashOperationPayload(payload) }),
         });
         if (!response.ok) {
             await response.body?.cancel();