@playcraft/cli 0.1.10 → 0.1.12

package/dist/workspace-runtime/workspaces/file-snapshot.js

@@ -1,7 +1,77 @@
 import { chmod, lstat, mkdir, readdir, readFile, readlink, realpath, rm, symlink, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve, sep } from 'node:path';
-import { fileSnapshotDigest, fileSnapshotManifestKey, fileSnapshotManifestSchema, fileSnapshotObjectKey, hashSnapshotBytes, isDisposableBackupPath, putObjectBytes, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { fileSnapshotDigest, fileSnapshotManifestKey, fileSnapshotContentKey, nativeTranscriptKey, fileSnapshotManifestSchema, hashSnapshotBytes, isDisposableBackupPath, isWorkspaceAttachmentPath, putObjectBytes, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { UNPUSHED_BUNDLE, addBundleObjects, repositoryResolves } from './git.js';
 const SKIP_DIRECTORY_NAMES = new Set(['.git', 'node_modules']);
+/** Build output, caches and scratch folders, at any depth: regenerated, so not kept in storage. */
+const UNSTORED_DIRECTORY_NAMES = new Set([
+    'dist',
+    'dist-all',
+    'coverage',
+    '.vite',
+    '.cache',
+    '.turbo',
+    '.parcel-cache',
+    '.sass-cache',
+    '.next',
+    '.nuxt',
+    '.svelte-kit',
+    'tmp',
+    '.tmp',
+    '.temp',
+]);
+/** Scratch and cache files, at any depth. */
+const UNSTORED_FILE = /(?:\.tmp|\.log|\.tsbuildinfo|^\.eslintcache)$/;
+/**
+ * At the workspace root: the preview build's output, the builder's scratch folder, and skill
+ * artifacts the sandbox pulls from the registry by `.playcraft/skills.lock.json`.
+ */
+const UNSTORED_ROOT_DIRECTORIES = [
+    '.playcraft-preview-out/',
+    '.playcraft-temp/',
+    '.playcraft/skills/',
+    'ta-workspace/logs/',
+];
+/**
+ * Recordings, frames and reports the template's verify and record scripts write again on each run.
+ * The ring JSON evidence the build gate reads stays, as do the agent-edited profile and catalogs.
+ */
+const UNSTORED_RUN_OUTPUT = [
+    /^recordings\/(?:.+\.(?:mp4|webm)$|\.tmp-[^/]+\/|focus\/|clean\/)/,
+    /^validate\/(?:[^/]+\.md$|(?:ring\d+\/)?frames\/|ring\d+\/[^/]+\.mp4$)/,
+];
+/**
+ * Whether a path goes to checkpoint storage. Credentials, lock files, build output, caches and
+ * scratch files stay in the instance: its local copy keeps them, so restoring inside the instance
+ * does not remove them.
+ */
+export function keptInStorage(path) {
+    if (isWorkspaceAttachmentPath(path))
+        return true;
+    if (isDisposableBackupPath(path))
+        return false;
+    if (path.startsWith('.git/'))
+        return true;
+    if (UNSTORED_ROOT_DIRECTORIES.some((prefix) => path.startsWith(prefix)))
+        return false;
+    if (UNSTORED_RUN_OUTPUT.some((pattern) => pattern.test(path)))
+        return false;
+    const segments = path.split('/');
+    if (UNSTORED_FILE.test(segments[segments.length - 1]))
+        return false;
+    return !segments.slice(0, -1).some((segment) => UNSTORED_DIRECTORY_NAMES.has(segment));
+}
+/**
+ * Under `.git/`, what a `local` capture leaves to the remote: packs and their indexes, submodule
+ * repositories (`git submodule update` fetches them again), LFS objects, and template hooks.
+ */
+const REMOTE_GIT_DIRECTORIES = new Set([
+    '.git/objects/pack',
+    '.git/objects/info',
+    '.git/modules',
+    '.git/lfs',
+    '.git/hooks',
+]);
 const READ_ATTEMPTS = 3;
 const realIo = {
     async readdir(path) {
@@ -13,13 +83,28 @@ const realIo = {
     readFile,
     readlink,
 };
-export async function captureWorkspaceTree(root, previousPaths, revisions, io = realIo) {
+export async function captureWorkspaceTree(root, previousPaths, revisions, io = realIo, options = {}) {
     const entries = [];
     const files = [];
     const bodies = new Map();
     const seen = new Set();
     let status = 'complete';
-    await walk(root, root, io, revisions, entries, files, bodies, seen, () => {
+    const skip = (relativePath, name, directory) => {
+        if (name === '.' || name === '..')
+            return true;
+        if (directory && name === '.git')
+            return !(options.git && relativePath === '.git');
+        // A submodule's `.git` file points into `.git/modules`, which is not kept either.
+        if (!directory && name === '.git' && relativePath !== '.git')
+            return true;
+        if (directory && SKIP_DIRECTORY_NAMES.has(name))
+            return true;
+        if (directory && options.git === 'local' && REMOTE_GIT_DIRECTORIES.has(relativePath))
+            return true;
+        // Git's own lock files only exist while a command runs and must not come back with a restore.
+        return !directory && relativePath.startsWith('.git/') && name.endsWith('.lock');
+    };
+    await walk(root, root, io, revisions, entries, files, bodies, seen, skip, () => {
         status = 'incomplete';
     });
     for (const path of [...previousPaths].sort((left, right) => left.localeCompare(right))) {
@@ -62,6 +147,12 @@ export async function materializeRemoteSnapshot(root, entries) {
         if (hashSnapshotBytes(body) !== entry.contentHash)
             throw new Error('snapshot_mismatch');
     }
+    if (applicable.some((entry) => entry.path === '.git/HEAD')) {
+        const bundle = applicable.find((entry) => entry.path === UNPUSHED_BUNDLE && entry.kind === 'file');
+        if (bundle)
+            await addBundleObjects(rootReal, Buffer.from(bundle.contentBase64 ?? '', 'base64'));
+        await clearClonedGitMetadata(rootReal);
+    }
     for (const entry of applicable) {
         const target = resolve(rootReal, ...entry.path.split('/'));
         const rel = relative(rootReal, target);
@@ -72,7 +163,7 @@ export async function materializeRemoteSnapshot(root, entries) {
             await rm(target, { force: true });
             continue;
         }
-        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        await mkdir(dirname(target), { recursive: true, mode: isWorkspaceAttachmentPath(entry.path) ? 0o755 : 0o700 });
         if (entry.kind === 'symlink') {
             if (!entry.target)
                 throw new Error('snapshot_mismatch');
@@ -85,50 +176,100 @@ export async function materializeRemoteSnapshot(root, entries) {
         if (entry.mode !== undefined)
             await chmod(target, entry.mode);
     }
-    let repositoryReady = false;
-    try {
-        const git = await lstat(join(rootReal, '.git'));
-        repositoryReady = git.isDirectory() && !git.isSymbolicLink();
-    }
-    catch {
-        repositoryReady = false;
-    }
     return {
         skipped,
         directoryReady: true,
-        repositoryReady,
+        repositoryReady: await repositoryResolves(rootReal),
         environmentReady: false,
     };
 }
+/**
+ * The snapshot's `.git` replaces the one a new clone made, objects aside: a ref the clone wrote
+ * would otherwise outrank the snapshot's packed refs.
+ */
+async function clearClonedGitMetadata(rootReal) {
+    const gitDir = join(rootReal, '.git');
+    const info = await lstat(gitDir).catch(() => undefined);
+    if (!info?.isDirectory())
+        return;
+    for (const name of await readdir(gitDir)) {
+        if (name !== 'objects')
+            await rm(join(gitDir, name), { recursive: true, force: true });
+    }
+}
+/**
+ * Content goes to the workspace's shared objects, keyed by hash. A hash in `uploaded` was stored by
+ * this process before and is not sent again; hashes stored now are added to it. The manifest still
+ * lists every stored file, so each snapshot restores on its own. Paths not `keptInStorage` are left
+ * out of both the objects and the manifest.
+ */
 export async function publishFileSnapshot(input) {
-    for (const entry of input.tree.entries) {
+    const stored = new Set();
+    const entries = input.tree.entries.filter((entry) => keptInStorage(entry.path));
+    for (const entry of entries) {
         if (entry.kind !== 'file' || !entry.contentHash)
             continue;
+        if (input.uploaded?.has(entry.contentHash) || stored.has(entry.contentHash))
+            continue;
         const body = input.tree.bodies.get(entry.path);
         if (!body || hashSnapshotBytes(body) !== entry.contentHash)
             throw new Error('snapshot_body_missing');
-        await putObjectBytes(input.baseUrl, fileSnapshotObjectKey(input.workspaceId, input.generation, input.snapshotId, entry.contentHash), body, 'cli');
+        await putObjectBytes(input.baseUrl, fileSnapshotContentKey(input.workspaceId, entry.contentHash), body, 'cli', input.headers);
+        stored.add(entry.contentHash);
+    }
+    const native = [];
+    for (const transcript of input.native ?? []) {
+        const contentHash = hashSnapshotBytes(transcript.body);
+        if (input.uploadedTranscripts?.get(transcript.path) !== contentHash) {
+            await putObjectBytes(input.baseUrl, nativeTranscriptKey(input.workspaceId, transcript.path), transcript.body, 'cli', input.headers);
+            input.uploadedTranscripts?.set(transcript.path, contentHash);
+        }
+        native.push({
+            sessionId: transcript.sessionId,
+            threadId: transcript.threadId,
+            path: transcript.path,
+            contentHash,
+            size: transcript.body.byteLength,
+            capturedAt: transcript.capturedAt,
+        });
     }
-    const digest = fileSnapshotDigest(input.tree.entries);
+    const digest = fileSnapshotDigest(entries);
     const manifest = fileSnapshotManifestSchema.parse({
         snapshotId: input.snapshotId,
         workspaceId: input.workspaceId,
         generation: input.generation,
         status: input.tree.status,
-        entries: input.tree.entries,
+        entries,
         digest,
+        objectLayout: 'workspace',
+        ...(native.length > 0 ? { native } : {}),
     });
     const manifestKey = fileSnapshotManifestKey(input.workspaceId, input.generation, input.snapshotId);
-    await putObjectBytes(input.baseUrl, manifestKey, Buffer.from(JSON.stringify(manifest)), 'cli');
+    await putObjectBytes(input.baseUrl, manifestKey, Buffer.from(JSON.stringify(manifest)), 'cli', input.headers);
+    for (const hash of stored)
+        input.uploaded?.add(hash);
     return { manifestKey, checksum: digest, status: input.tree.status };
 }
-async function walk(rootReal, current, io, revisions, entries, files, bodies, seen, markIncomplete) {
+/**
+ * Digest of what is on disk now, without the deletions recorded against the previous snapshot.
+ * Transcripts count too: a turn that only talked still changes what a restore can resume.
+ */
+export function liveTreeDigest(tree, native = []) {
+    const files = fileSnapshotDigest(tree.entries.filter((entry) => entry.kind !== 'deleted'));
+    if (native.length === 0)
+        return files;
+    const transcripts = native
+        .map((item) => `${item.sessionId}:${item.threadId}:${item.path}:${hashSnapshotBytes(item.body)}`)
+        .sort();
+    return hashSnapshotBytes(Buffer.from([files, ...transcripts].join('\n')));
+}
+async function walk(rootReal, current, io, revisions, entries, files, bodies, seen, skip, markIncomplete) {
     const listed = await io.readdir(current);
     for (const entry of listed) {
-        if (entry.name === '.' || entry.name === '..' || SKIP_DIRECTORY_NAMES.has(entry.name))
-            continue;
         const child = join(current, entry.name);
         const relativePath = toPosixRelative(rootReal, child);
+        if (skip(relativePath, entry.name, entry.isDirectory()))
+            continue;
         if (!workspaceRelativePathSchema.safeParse(relativePath).success) {
             markIncomplete();
             continue;
@@ -145,7 +286,7 @@ async function walk(rootReal, current, io, revisions, entries, files, bodies, se
             continue;
         }
         if (entry.isDirectory()) {
-            await walk(rootReal, child, io, revisions, entries, files, bodies, seen, markIncomplete);
+            await walk(rootReal, child, io, revisions, entries, files, bodies, seen, skip, markIncomplete);
             continue;
         }
         if (!entry.isFile())

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

@@ -1,6 +1,6 @@
 import { mkdir, readdir, readFile, realpath, rm, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, resolve, sep } from 'node:path';
-import { hashWorkspaceFileContent, workspaceFileContentSchema, workspaceFileListSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { hashWorkspaceFileContent, hashSnapshotBytes, isWorkspaceAttachmentPath, workspaceFileContentSchema, workspaceFileListSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
 const SKIP_DIRECTORY_NAMES = new Set(['.git', 'node_modules']);
 export class InvalidWorkspacePathError extends Error {
     code = 'invalid_workspace_path';
@@ -71,11 +71,11 @@ export async function snapshotWorkspaceFiles(root, snapshotDir, revisions) {
     await rm(snapshotDir, { recursive: true, force: true });
     const records = [];
     for (const file of listed.files) {
-        const content = await readWorkspaceFile(root, file.path, revisions);
+        const content = await readFile(await resolveWorkspaceFile(root, file.path));
         const target = join(snapshotDir, ...file.path.split('/'));
         await mkdir(dirname(target), { recursive: true, mode: 0o700 });
-        await writeFile(target, content.content, { mode: 0o600 });
-        records.push({ path: file.path, contentHash: file.contentHash, revision: file.revision });
+        await writeFile(target, content, { mode: 0o600 });
+        records.push({ path: file.path, contentHash: hashSnapshotBytes(content), revision: file.revision });
     }
     return records;
 }
@@ -83,16 +83,17 @@ export async function restoreWorkspaceFiles(root, snapshotDir, files) {
     const rootReal = await ensureWorkspaceRoot(root);
     const keep = new Set(files.map((item) => item.path));
     for (const relativePath of await walkWorkspaceFiles(rootReal, rootReal)) {
-        if (!keep.has(relativePath)) {
+        if (!keep.has(relativePath) && !isWorkspaceAttachmentPath(relativePath)) {
             await rm(join(rootReal, ...relativePath.split('/')), { force: true });
         }
     }
     const next = {};
     for (const file of files) {
         const source = join(snapshotDir, ...file.path.split('/'));
-        const content = await readFile(source, 'utf8');
-        await writeWorkspaceFile(root, file.path, content);
-        next[file.path] = { revision: file.revision, contentHash: hashWorkspaceFileContent(content) };
+        const content = await readFile(source);
+        const target = await resolveWorkspaceFile(root, file.path);
+        await writeFile(target, content, { mode: isWorkspaceAttachmentPath(file.path) ? 0o644 : 0o600 });
+        next[file.path] = { revision: file.revision, contentHash: hashSnapshotBytes(content) };
     }
     return next;
 }

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

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
-import { lstat, readFile, realpath, stat, unlink } from 'node:fs/promises';
+import { excludeFromGit } from './dependencies.js';
+import { lstat, mkdir, readFile, realpath, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { WORKSPACE_FILE_CONTENT_MAX, gitDiffSchema, gitFileContentSchema, gitGraphSchema, gitStatusSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
@@ -245,6 +246,96 @@ export async function pushWorkspaceGit(root, boundBranch) {
     catch { /* Preserve uncertainty; never replay a write automatically. */ }
     throw new GitWorkspaceError('git_push_outcome_unknown', 'git_push_outcome_unknown');
 }
+const UNPUSHED_DIRECTORY = '.git/playcraft';
+export const UNPUSHED_BUNDLE = `${UNPUSHED_DIRECTORY}/unpushed.bundle`;
+const UNPUSHED_TIPS = `${UNPUSHED_DIRECTORY}/unpushed.tips`;
+/**
+ * Keeps a bundle of the commits on local branches and the latest stash that no remote-tracking
+ * branch holds, so a backup without the packs still has them. It is rewritten only when one of
+ * those refs moves, and removed when nothing is unpushed. Without remote-tracking refs there is no
+ * baseline, and the whole history is left out rather than bundled.
+ */
+export async function bundleUnpushedCommits(root) {
+    const rootReal = await realpath(root);
+    const marker = await lstat(join(rootReal, '.git')).catch(() => undefined);
+    if (!marker?.isDirectory())
+        return;
+    const tips = await git(rootReal, [
+        'for-each-ref', '--format=%(objectname) %(refname)', 'refs/heads', 'refs/remotes', 'refs/stash',
+    ]);
+    const tipsPath = join(rootReal, UNPUSHED_TIPS);
+    if ((await readFile(tipsPath, 'utf8').catch(() => undefined)) === tips)
+        return;
+    const refs = tips.split('\n').map((line) => line.split(' ')[1]).filter((ref) => Boolean(ref));
+    const local = ['--branches', ...(refs.includes('refs/stash') ? ['refs/stash'] : [])];
+    const unpushed = refs.some((ref) => ref.startsWith('refs/remotes/'))
+        ? Number.parseInt((await git(rootReal, ['rev-list', '--count', ...local, '--not', '--remotes'], 60000)).trim(), 10)
+        : 0;
+    const bundlePath = join(rootReal, UNPUSHED_BUNDLE);
+    await mkdir(join(rootReal, UNPUSHED_DIRECTORY), { recursive: true, mode: 0o700 });
+    if (unpushed > 0) {
+        // The `.lock` name keeps a half-written bundle out of any snapshot.
+        const temp = `${bundlePath}.lock`;
+        try {
+            await git(rootReal, ['bundle', 'create', temp, ...local, '--not', '--remotes'], 120000);
+            await rename(temp, bundlePath);
+        }
+        finally {
+            await rm(temp, { force: true });
+        }
+    }
+    else {
+        await rm(bundlePath, { force: true });
+    }
+    await writeFile(tipsPath, tips, { mode: 0o600 });
+}
+/**
+ * Adds a bundle's objects to the repository. `unbundle` walks history from the current refs, so this
+ * runs on the fresh clone before the snapshot's refs, which point at these very commits, replace its
+ * own. It fails when the remote lost the commits the bundle was built on; `repositoryResolves` then
+ * reports what is missing.
+ */
+export async function addBundleObjects(root, body) {
+    const rootReal = await realpath(root);
+    const marker = await lstat(join(rootReal, '.git')).catch(() => undefined);
+    if (!marker?.isDirectory())
+        return;
+    const temp = join(rootReal, '.git', 'playcraft-restore.bundle.lock');
+    try {
+        await writeFile(temp, body, { mode: 0o600 });
+        await gitAllowFail(rootReal, ['bundle', 'unbundle', temp], 120000);
+    }
+    catch {
+        /* Reported by repositoryResolves. */
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+/** Whether HEAD and the index resolve to objects the repository holds. */
+export async function repositoryResolves(root) {
+    const rootReal = await realpath(root);
+    const marker = await lstat(join(rootReal, '.git')).catch(() => undefined);
+    if (!marker?.isDirectory())
+        return false;
+    try {
+        // Snapshots hold files only; Git does not recognise a repository whose refs folder is gone.
+        for (const directory of ['refs/heads', 'refs/tags', 'objects']) {
+            await mkdir(join(rootReal, '.git', directory), { recursive: true, mode: 0o755 });
+        }
+        const head = await gitAllowFail(rootReal, ['rev-parse', '-q', '--verify', 'HEAD^{tree}']);
+        if (head.code === 0) {
+            const index = await gitAllowFail(rootReal, ['diff-index', '--cached', '--quiet', 'HEAD'], 60000);
+            return index.code === 0 || index.code === 1;
+        }
+        // Before the first commit there is no branch to resolve.
+        const branches = await gitAllowFail(rootReal, ['for-each-ref', '--count=1', 'refs/heads']);
+        return branches.code === 0 && branches.stdout.trim() === '';
+    }
+    catch {
+        return false;
+    }
+}
 export async function ensureWorkspaceGit(root) {
     const rootReal = await realpath(root);
     if (!(await gitMarkerExists(rootReal))) {
@@ -256,6 +347,7 @@ export async function ensureWorkspaceGit(root) {
         await git(rootReal, ['config', 'user.email', 'workspace@playcraft.local']);
     }
     await assertWorkspaceGitRoot(rootReal);
+    await excludeFromGit(rootReal, '/.tmp/user_uploads/');
     return rootReal;
 }
 async function gitMarkerExists(rootReal) {

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

@@ -4,6 +4,7 @@ import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs
 import { join } from 'node:path';
 import { isLocalWorkspaceGitAuthMode, isLocalWorkspaceGitEnvironment, matchWorkspaceGitGatewayCloneUrl, workspacePreparationSchema, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceContextError } from './context-error.js';
+import { scaffoldEmptyWorkspace } from './empty-template.js';
 /** The caller holds the Workspace lock. Only an absent, never-published directory may be prepared. */
 export async function prepareWorkspaceCheckout(state, binding, input, leaseFence) {
     const preparation = workspacePreparationSchema.safeParse(input);
@@ -82,22 +83,31 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
         try {
             if (standalone) {
                 await runGit(['init', '--initial-branch=main', staging], env, deadline);
+                await scaffoldEmptyWorkspace(staging, join(state.config.stateDir, 'skill-artifacts'));
             }
             else {
+                const fork = binding.pendingFork;
+                const cloneBranch = fork?.sourceBranchName ?? binding.branchName;
                 await runGit(['check-ref-format', '--branch', binding.branchName], env, deadline);
+                await runGit(['check-ref-format', '--branch', cloneBranch], env, deadline);
                 await runGit([
                     'clone',
                     '--no-checkout',
                     '--single-branch',
                     '--branch',
-                    binding.branchName,
+                    cloneBranch,
                     '--',
                     binding.repositoryUrl,
                     staging,
                 ], env, deadline);
                 // Checkout never receives the temporary credential and never invokes repository hooks or global filters.
                 clearCloneSecrets(env);
-                await runGit(['-C', staging, 'checkout', '--force', binding.branchName], env, deadline);
+                if (fork) {
+                    await runGit(['-C', staging, 'checkout', '-b', binding.branchName, fork.sourceCommit], env, deadline);
+                }
+                else {
+                    await runGit(['-C', staging, 'checkout', '--force', binding.branchName], env, deadline);
+                }
             }
             assertCurrent();
             receipt.status = 'ready';

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

@@ -6,6 +6,8 @@ import { isLocalWorkspaceGitAuthMode, workspaceRegistrationSchema, } from '@play
 import { prepareWorkspaceCheckout } from './prepare.js';
 import { WorkspaceContextError } from './context-error.js';
 import { scheduleDependencyInstall } from './dependencies.js';
+import { ensureWorkspaceSkills, readWorkspaceSkills } from './skills.js';
+import { loadWorkspaceSkillArtifact } from './skill-artifact-loader.js';
 export { WorkspaceContextError } from './context-error.js';
 const exec = promisify(execFile);
 export function revisionScope(state, workspaceId) {
@@ -121,7 +123,17 @@ export async function registerWorkspace(state, input, leaseFence, preparation) {
                 throw new WorkspaceContextError('workspace_git_gateway_unavailable');
             }
         }
+        try {
+            await ensureWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'));
+        }
+        catch {
+            throw new WorkspaceContextError('workspace_skills_unavailable');
+        }
         await state.journal.putWorkspace(binding);
+        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, binding.workspaceId, root);
         return binding;

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

@@ -0,0 +1,47 @@
+import { createHash } from 'node:crypto';
+import { workspaceRoot } from './registry.js';
+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) {
+    await workspaceRoot(state, workspaceId);
+    const epoch = state.runtimeEpoch;
+    if (state.journal.destroyed())
+        throw new Error('workspace_skills_unavailable');
+    const endpoint = new URL('/runtime/internal/skill-artifacts', state.config.callbackUrl);
+    if (endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(endpoint.hostname)))
+        throw new Error('workspace_skills_callback_insecure');
+    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;
+}