@playcraft/cli 0.1.69 → 0.1.71

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

@@ -0,0 +1,87 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { remoteSkillMatchResultSchema } from '@playcraft/common/project-skills';
+import { RemoteSkillClient } from './remote-client.js';
+import { prepareRemoteSkillSelection } from './remote-prepare.js';
+import { findManagedSkillsRoot, normalizeSkillEngine } from './search.js';
+import { printSkillSearchError } from './search-command.js';
+import { projectSkillsMessage as t } from './messages.js';
+export async function matchRemoteSkills(options) {
+    const limit = Number(options.limit ?? 20);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new Error(t('searchInvalidLimit'));
+    const engine = options.engine ? normalizeSkillEngine(options.engine) : undefined;
+    if (engine !== undefined && engine !== 'phaser' && engine !== 'threejs')
+        throw new Error(t('remoteInvalidEngine'));
+    const result = await new RemoteSkillClient({ cwd: resolve(options.dir), url: options.url }).match({ query: options.intent, engine, limit });
+    if (options.json)
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    else {
+        console.log(t('remoteSource'));
+        console.log(result.total ? `${t('searchSummary')} ${result.total}` : t('remoteNoMatches'));
+        for (const skill of result.items) {
+            console.log(`  ${skill.skillRef}@${skill.version}  ${skill.name}`);
+            if (skill.description)
+                console.log(`    ${skill.description}`);
+            if (skill.matchedTerms.length)
+                console.log(`    ${skill.matchedTerms.join(', ')}`);
+        }
+        console.log(t('remotePrepareHint'));
+    }
+    return result;
+}
+async function readMatchReceipt(path) {
+    const file = await open(resolve(path), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > 4 * 1024 * 1024)
+            throw new Error(t('remoteInvalidMatchFile'));
+        return remoteSkillMatchResultSchema.parse(JSON.parse(await file.readFile('utf8')));
+    }
+    finally {
+        await file.close();
+    }
+}
+export function registerRemoteSkillPrepareCommand(skills) {
+    skills.command('prepare').description(t('remotePrepare'))
+        .requiredOption('--from-match <path>', t('remoteMatchFile'))
+        .requiredOption('--skills <refs>', t('remoteSelectedRefs'))
+        .option('--dir <path>', t('directory'), '.')
+        .option('--url <url>', t('remoteUrl'))
+        .option('--prepare-only', t('remotePrepareOnly'))
+        .option('--json', t('json'))
+        .action(async (options) => {
+        try {
+            const match = await readMatchReceipt(options.fromMatch);
+            const refs = [...new Set(options.skills.split(',').map(ref => ref.trim()).filter(Boolean))];
+            if (!refs.length || refs.length > 50)
+                throw new Error(t('remoteInvalidSelection'));
+            const selected = refs.map(ref => {
+                const candidates = match.items.filter(skill => skill.skillRef === ref || `${skill.skillRef}@${skill.version}` === ref);
+                if (candidates.length !== 1)
+                    throw new Error(`${t('remoteInvalidSelection')}: ${ref}`);
+                const skill = candidates[0];
+                return { skillRef: skill.skillRef, skillVersionId: skill.skillVersionId, version: skill.version, artifactHash: skill.artifactHash };
+            });
+            const engine = match.engine === 'phaser' || match.engine === 'threejs' ? match.engine : undefined;
+            const client = new RemoteSkillClient({ cwd: resolve(options.dir), url: options.url });
+            const selection = await client.select({ skills: selected, engine, catalogHash: match.catalogHash });
+            const root = client.hasExecutionBridge() ? await findManagedSkillsRoot(options.dir) ?? resolve(options.dir) : resolve(options.dir);
+            const prepared = await prepareRemoteSkillSelection(root, selection, entry => client.artifact(selection, entry));
+            const activation = options.prepareOnly ? undefined : await client.activate(selection.selectionId);
+            const result = activation ? { ...prepared, status: activation.status, activation } : prepared;
+            if (options.json)
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            else {
+                console.log(t('remotePrepared'));
+                console.log(result.directory);
+                console.log(t(activation?.status === 'activation_requested' ? 'remoteActivationRequested'
+                    : activation?.status === 'already_active' ? 'remoteAlreadyActive' : 'remoteActivationRequired'));
+            }
+        }
+        catch (error) {
+            printSkillSearchError(error, options.json);
+        }
+    });
+}

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

@@ -0,0 +1,223 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, open, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { canonicalProjectSkillsJson, parseRemoteSkillSelectionResult, projectSkillsDigest, } from '@playcraft/common/project-skills';
+import { ensureProjectSkillDirectory, readLockedProjectSkillCatalog } from './discovery.js';
+import { excludeFromGit } from '../workspace-runtime/workspaces/dependencies.js';
+const MAX_RECEIPT_BYTES = 16 * 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 64 * 1024 * 1024;
+const receiptName = 'selection.json';
+const PROCESS_STARTED_AT = Math.round(Date.now() - process.uptime() * 1000);
+async function readPreparationLease(path) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            throw error;
+        throw new Error('remote_skill_selection_lease_invalid');
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 2048)
+            throw new Error('remote_skill_selection_lease_invalid');
+        const bytes = await handle.readFile();
+        let record;
+        try {
+            record = JSON.parse(bytes.toString('utf8'));
+        }
+        catch {
+            throw new Error('remote_skill_selection_lease_invalid');
+        }
+        if (!record || record.version !== 1 || !/^[a-f0-9]{64}$/.test(record.selectionId)
+            || !Number.isSafeInteger(record.pid) || record.pid < 1 || record.pid > 2_147_483_647
+            || !Number.isSafeInteger(record.processStartedAt) || record.processStartedAt < 1
+            || typeof record.nonce !== 'string' || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(record.nonce))
+            throw new Error('remote_skill_selection_lease_invalid');
+        return { bytes, ino: stat.ino, dev: stat.dev, record };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function preparationOwnerExited(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+const samePreparationLease = (left, right) => left.ino === right.ino && left.dev === right.dev && left.bytes.equals(right.bytes);
+async function ownsPreparationLease(path, expected) {
+    try {
+        return samePreparationLease(await readPreparationLease(path), expected);
+    }
+    catch {
+        return false;
+    }
+}
+async function retirePreparationLease(path, expected, mayRemove = () => true) {
+    if (!await ownsPreparationLease(path, expected))
+        return false;
+    const retired = `${path}.${randomUUID()}.retired`;
+    try {
+        await rename(path, retired);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    if (await ownsPreparationLease(retired, expected) && mayRemove()) {
+        await rm(retired);
+        return true;
+    }
+    // Exclusive restoration never overwrites a concurrently created lease. If another
+    // owner claimed the original path, retain these unknown bytes under the retired name.
+    try {
+        await link(retired, path);
+        await rm(retired);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    return false;
+}
+async function acquirePreparationLease(path, selectionId) {
+    const create = async () => {
+        const handle = await open(path, 'wx', 0o600);
+        const record = { version: 1, selectionId, pid: process.pid,
+            processStartedAt: PROCESS_STARTED_AT, nonce: randomUUID() };
+        const bytes = Buffer.from(JSON.stringify(record));
+        try {
+            await handle.writeFile(bytes);
+            const stat = await handle.stat();
+            return { handle, bytes, record, ino: stat.ino, dev: stat.dev };
+        }
+        catch (error) {
+            await handle.close();
+            // A partially written lease has no proof of ownership and remains fail-closed.
+            throw error;
+        }
+    };
+    try {
+        return await create();
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const previous = await readPreparationLease(path);
+    if (previous.record.selectionId !== selectionId)
+        throw new Error('remote_skill_selection_lease_invalid');
+    if (!preparationOwnerExited(previous.record.pid))
+        throw new Error('remote_skill_selection_busy');
+    if (!await retirePreparationLease(path, previous, () => preparationOwnerExited(previous.record.pid)))
+        throw new Error('remote_skill_selection_lease_changed');
+    try {
+        return await create();
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error('remote_skill_selection_busy');
+        throw error;
+    }
+}
+async function exists(path) {
+    return lstat(path).then(stat => stat, (error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+}
+function identity(selection) {
+    return projectSkillsDigest({ declaration: selection.declaration, lock: selection.lock,
+        skills: selection.skills.map(({ skillRef, skillVersionId, version, artifactHash }) => ({ skillRef, skillVersionId, version, artifactHash })).sort((a, b) => a.skillRef.localeCompare(b.skillRef)) });
+}
+async function readReceipt(directory) {
+    const stat = await lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('remote_skill_selection_path_invalid');
+    const receipt = join(directory, receiptName);
+    const file = await lstat(receipt);
+    if (!file.isFile() || file.isSymbolicLink() || file.nlink !== 1 || file.size > MAX_RECEIPT_BYTES)
+        throw new Error('remote_skill_selection_path_invalid');
+    return parseRemoteSkillSelectionResult(JSON.parse(await readFile(receipt, 'utf8')));
+}
+async function prepared(directory, selection) {
+    const saved = await readReceipt(directory);
+    if (identity(saved) !== identity(selection))
+        throw new Error('remote_skill_selection_conflict');
+    const catalog = await readLockedProjectSkillCatalog(directory, join(directory, '.playcraft/skill-artifacts'));
+    if (catalog.lockHash !== selection.lockHash || catalog.skills.length !== selection.lock.entries.length)
+        throw new Error('remote_skill_selection_conflict');
+    return { status: 'prepared_requires_activation', executionReady: false,
+        selectionId: selection.selectionId, lockHash: selection.lockHash, directory,
+        skills: catalog.skills.map(({ entryKey, skillRef, revision, artifactHash, name, description, skillDir, path }) => ({ entryKey, skillRef, revision, artifactHash, name, description, skillDir, path })) };
+}
+/** Downloads a separate exact selection; never changes the project's active declaration or lock. */
+export async function prepareRemoteSkillSelection(directory, input, loadArtifact) {
+    const selection = parseRemoteSkillSelectionResult(input);
+    if (!selection.lock.entries.length || selection.declaration.entries.some(entry => entry.source.kind !== 'registry' || !entry.enabled || entry.surface !== 'sandbox-agent'))
+        throw new Error('invalid_remote_skill_selection');
+    const selectedBytes = canonicalProjectSkillsJson(selection);
+    if (Buffer.byteLength(selectedBytes) > MAX_RECEIPT_BYTES)
+        throw new Error('remote_skill_selection_too_large');
+    const suppliedRoot = resolve(directory);
+    const stat = await lstat(suppliedRoot);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('remote_skill_selection_path_invalid');
+    const root = await realpath(suppliedRoot);
+    await excludeFromGit(root, '/.playcraft/skill-selections/');
+    const parent = await ensureProjectSkillDirectory(root, '.playcraft/skill-selections', true);
+    const target = join(parent, selection.selectionId);
+    if (await exists(target))
+        return prepared(target, selection);
+    const leasePath = join(parent, `.${selection.selectionId}.prepare.lock`);
+    const lease = await acquirePreparationLease(leasePath, selection.selectionId);
+    const stageName = `.${selection.selectionId}.${randomUUID()}.tmp`;
+    const stage = join(parent, stageName);
+    let published = false;
+    try {
+        if (await exists(target))
+            return prepared(target, selection);
+        await ensureProjectSkillDirectory(parent, stageName);
+        const management = await ensureProjectSkillDirectory(stage, '.playcraft/skill-artifacts');
+        const snapshots = [
+            ['skills.json', selection.declaration], ['skills.lock.json', selection.lock],
+        ];
+        for (const [name, value] of snapshots) {
+            const bytes = canonicalProjectSkillsJson(value);
+            if (Buffer.byteLength(bytes) > 1024 * 1024)
+                throw new Error('remote_skill_selection_too_large');
+            await writeFile(join(stage, '.playcraft', name), bytes, { flag: 'wx', mode: 0o644 });
+        }
+        await readLockedProjectSkillCatalog(stage, management, async (entry) => {
+            const archive = await loadArtifact(entry);
+            if (!Buffer.isBuffer(archive) || archive.byteLength > MAX_ARTIFACT_BYTES
+                || createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+                throw new Error('remote_skill_artifact_digest_mismatch');
+            return archive;
+        });
+        await writeFile(join(stage, receiptName), selectedBytes, { flag: 'wx', mode: 0o644 });
+        // Nothing under the deterministic selection name is visible until every bundle is verified.
+        if (!await ownsPreparationLease(leasePath, lease))
+            throw new Error('remote_skill_selection_lease_changed');
+        if (await exists(target))
+            throw new Error('remote_skill_selection_conflict');
+        await rename(stage, target);
+        published = true;
+        return await prepared(target, selection);
+    }
+    finally {
+        if (!published)
+            await rm(stage, { recursive: true, force: true });
+        await lease.handle.close();
+        await retirePreparationLease(leasePath, lease);
+    }
+}

package/dist/project-skills/search-command.js

@@ -0,0 +1,47 @@
+import { resolve } from 'node:path';
+import { projectSkillsMessage as t } from './messages.js';
+import { searchProjectSkills } from './search.js';
+export function printLockedSkillSearch(skills, total) {
+    console.log(t('searchLockedSource'));
+    console.log(total ? `${t('searchSummary')} ${total}` : t('searchNoMatches'));
+    for (const skill of skills) {
+        console.log(`  ${skill.skillRef}@${skill.revision}  ${skill.name}`);
+        if (skill.description)
+            console.log(`    ${skill.description}`);
+        console.log(`    ${skill.path}`);
+    }
+    if (skills.length)
+        console.log(t('searchReadPath'));
+}
+export function printSkillSearchError(error, json) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : 'skill_search_failed';
+    if (json)
+        process.stdout.write(`${JSON.stringify({ error: { code, message } })}\n`);
+    else
+        console.error(`${t('searchFailed')}: ${message}`);
+    process.exitCode = 1;
+}
+export function registerSkillSearchCommand(skills) {
+    skills.command('search').description(t('search'))
+        .option('--query <text>', t('searchQuery'), '')
+        .option('--engine <name>', t('searchEngine'))
+        .option('--dir <path>', t('directory'), '.')
+        .option('--limit <count>', t('searchLimit'), '20')
+        .option('--json', t('json'))
+        .action(async (options) => {
+        try {
+            const limit = Number(options.limit);
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+                throw new Error(t('searchInvalidLimit'));
+            const result = await searchProjectSkills(resolve(options.dir), { ...options, limit });
+            if (options.json)
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            else
+                printLockedSkillSearch(result.skills, result.total);
+        }
+        catch (error) {
+            printSkillSearchError(error, options.json);
+        }
+    });
+}

package/dist/project-skills/search.js

@@ -0,0 +1,96 @@
+import { lstat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { readLockedProjectSkillCatalog } from './discovery.js';
+import { projectSkillsMessage as t } from './messages.js';
+/** A partial configuration is still managed and must fail validation, never fall through to scanning. */
+export async function findManagedSkillsRoot(directory) {
+    let root = resolve(directory);
+    const exists = async (file) => lstat(file).then(() => true, (error) => {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    });
+    while (true) {
+        if (await exists(join(root, '.playcraft/skills.json')) || await exists(join(root, '.playcraft/skills.lock.json')))
+            return root;
+        if (await exists(join(root, '.git')) || dirname(root) === root)
+            return null;
+        root = dirname(root);
+    }
+}
+const normalize = (value) => value.normalize('NFKC').toLowerCase();
+export const normalizeSkillEngine = (value) => normalize(value).replace(/[.\s-]/g, '');
+export function skillSearchTerms(query) {
+    const terms = new Set(normalize(query).split(/[\s,，、;；]+/u).filter(Boolean));
+    // Include words within natural-language Chinese queries and compound English tags.
+    const segmenter = new Intl.Segmenter('zh', { granularity: 'word' });
+    for (const { segment, isWordLike } of segmenter.segment(normalize(query))) {
+        if (isWordLike && segment.length > 1)
+            terms.add(segment);
+    }
+    return [...terms];
+}
+export function filterLockedSkillsByEngine(skills, target) {
+    if (!target)
+        return skills;
+    const engine = normalizeSkillEngine(target);
+    const byAtom = new Map(skills.filter(skill => skill.manifest).map(skill => [skill.manifest.atomId, skill]));
+    const rootEngine = (id) => /^(phaser|threejs)(?:\.aicomponent|-runtime)?$/.exec(id)?.[1];
+    const compatible = (skill, visited = new Set()) => {
+        if (visited.has(skill.entryKey))
+            return true;
+        visited.add(skill.entryKey);
+        const manifest = skill.manifest;
+        if (!manifest)
+            return true;
+        const ownEngine = rootEngine(manifest.atomId);
+        if (ownEngine && ownEngine !== engine)
+            return false;
+        const metadata = manifest;
+        const engines = [...(metadata.renderBackend ?? []), ...Object.keys(metadata.engineVariants ?? {})].map(normalize);
+        if (engines.length && !engines.includes(engine))
+            return false;
+        const pins = metadata.engineVariants?.[engine]?.imports ?? (manifest.imports ?? [])
+            .filter(item => item.edgeKind === 'requires' || item.slot === 'engine' || item.bindAs === 'engine')
+            .flatMap(item => item.pinAtomId ? [item.pinAtomId] : []);
+        return pins.every(id => {
+            const requiredEngine = rootEngine(id);
+            if (requiredEngine && requiredEngine !== engine)
+                return false;
+            const dependency = byAtom.get(id);
+            return !dependency || compatible(dependency, visited);
+        });
+    };
+    return skills.filter(skill => compatible(skill));
+}
+export function rankLockedProjectSkills(skills, options = {}) {
+    const terms = skillSearchTerms(options.query ?? '');
+    const ranked = filterLockedSkillsByEngine(skills, options.engine).flatMap((skill) => {
+        const manifest = skill.manifest;
+        const fields = [
+            [skill.name, 5], [skill.skillRef, 5],
+            [skill.triggers.join(' '), 4], [skill.tags.join(' '), 4], [skill.keywords.join(' '), 3],
+            [manifest?.label?.zh ?? '', 4], [manifest?.label?.en ?? '', 4], [skill.description, 1],
+        ];
+        let score = 0;
+        const matchedTerms = terms.filter(term => {
+            const weight = Math.max(0, ...fields.map(([value, boost]) => normalize(value).includes(term) ? boost : 0));
+            score += weight;
+            return weight > 0;
+        });
+        if (terms.length && !matchedTerms.length)
+            return [];
+        const { manifest: _manifest, ...metadata } = skill;
+        return [{ ...metadata, atomId: manifest?.atomId, score, matchedTerms }];
+    }).sort((a, b) => b.score - a.score || a.skillRef.localeCompare(b.skillRef));
+    return { total: ranked.length, skills: ranked.slice(0, options.limit ?? 20) };
+}
+export async function searchProjectSkills(directory, options = {}) {
+    const root = await findManagedSkillsRoot(directory);
+    if (!root)
+        throw new Error(t('searchRequiresLock'));
+    const catalog = await readLockedProjectSkillCatalog(root);
+    return { source: 'project-lock', lockHash: catalog.lockHash,
+        query: options.query ?? '', engine: options.engine ?? null,
+        ...rankLockedProjectSkills(catalog.skills, options) };
+}

package/dist/recording/project-digest.js

@@ -7,7 +7,7 @@ import { RecordingError } from './messages.js';
 const execute = promisify(execFile);
 const excludedNames = new Set(['.git', 'node_modules', '.DS_Store']);
 const excludedRoots = new Set(['.agents', '.claude', '.codex', '.next', '.vite', '.cache', '.tmp', 'tmp', 'temp', 'dist', 'build', 'coverage', '.playcraft-preview-out', '.playcraft-temp']);
-const excludedInternalPaths = ['.playcraft/video-replication', '.playcraft/skills', '.playcraft/skill-artifacts', '.playcraft/skills.json', '.playcraft/skills.lock.json', '.playcraft/workspace-context.json'];
+const excludedInternalPaths = ['.playcraft/video-replication', '.playcraft/skills', '.playcraft/skill-artifacts', '.playcraft/skill-selections', '.playcraft/skills.json', '.playcraft/skills.lock.json', '.playcraft/workspace-context.json'];
 const inside = (root, path) => path === root || path.startsWith(`${root}${sep}`);
 const canonicalPath = async (path) => {
     const absolute = resolve(path);

package/dist/workspace-runtime/batch/content-changes.js

@@ -1,8 +1,11 @@
+import { WORKSPACE_REMIX_REFERENCES_DIRECTORY } from '@playcraft/common/cloud-workspace/runtime';
 import { gitRead } from './git.js';
 const reference = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
 const excludedDirectories = new Set(['node_modules', 'dist', 'build', 'coverage', 'docs', 'test', 'tests', '__tests__']);
 const contentExtension = /\.(?:[cm]?[jt]sx?|vue|svelte|html?|css|s[ac]ss|less|json5?|ya?ml|xml|glsl|wgsl|vert|frag|lua|py|svg|png|jpe?g|webp|avif|gif|bmp|mp[34]|wav|ogg|m4a|webm|glb|gltf|fbx|obj|bin|atlas|woff2?|ttf|otf)$/i;
 function contentPath(path) {
+    if (path.startsWith(`${WORKSPACE_REMIX_REFERENCES_DIRECTORY}/`))
+        return false;
     const parts = path.split('/');
     if (parts.some(part => part.startsWith('.') || excludedDirectories.has(part)))
         return false;

package/dist/workspace-runtime/batch/generate.js

@@ -100,7 +100,10 @@ export async function generateBatchMember(state, body) {
             const policy = memberExecutionPolicy(root, tempDir);
             await bindMemberPolicy(state, sessionId, policy, { runId: command.runId, ownerFence: command.ownerFence });
             const modelConfigId = command.model && /^[0-9a-f-]{36}$/i.test(command.model) ? command.model : undefined;
-            const turnPayload = { text: command.prompt, permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}) };
+            const turnPayload = { text: command.prompt, permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}),
+                ...(command.remixReferences?.length ? { context: { files: [], skills: [], remixReferences: command.remixReferences.map(reference => ({
+                            ...reference, directoryName: command.directoryName,
+                        })) } } : {}) };
             const turnKey = operation(state, { kind: 'session.turn', clientRequestId: `batch-turn:${command.runId}`, sessionId, workspaceId: command.workspaceId, directoryName: command.directoryName, payload: turnPayload });
             const prior = state.journal.getOperation(turnKey.scopeKey);
             if (prior && prior.payloadHash !== turnKey.record.payloadHash)

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

@@ -14,6 +14,7 @@ import { processHasExited, runProcessGroup } from './processes.js';
 import { createInstallLog } from './install-log.js';
 import { stopMemberWriters } from './writer-proof.js';
 import { restoreBatchSkillArtifacts } from './skill-artifacts.js';
+import { rebindBatchRemixReferences } from '../workspaces/remix-references.js';
 import { filesystemObjectStore, memberStatus, readMember, readSnapshot, readStopMarker, serializeRun, sourceCacheDir, writeMember, } from './records.js';
 const BRANCH = /^remix\/draft-[a-f0-9]{16}$/;
 function hashCommand(value) {
@@ -191,11 +192,14 @@ export async function prepareBatchMember(state, body, options) {
                     const commit = command.resumeFromCommit ?? snapshot.commitHash;
                     await checkoutBranch(staging, command.branchName, commit, repositoryUrl);
                     await restoreBatchSkillArtifacts(sourceRoot, staging);
+                    await rebindBatchRemixReferences(staging, snapshot.sourceDirectoryName, command.directoryName, command.remixReferences ?? []);
                     const { rename } = await import('node:fs/promises');
                     await rename(staging, root);
                 }
-                else
+                else {
                     await restoreBatchSkillArtifacts(sourceRoot, root);
+                    await rebindBatchRemixReferences(root, snapshot.sourceDirectoryName, command.directoryName, command.remixReferences ?? []);
+                }
                 await registerWorkspaceDirectory(state, {
                     workspaceId: command.workspaceId,
                     directoryName: command.directoryName,

package/dist/workspace-runtime/batch/source-capture.js

@@ -4,16 +4,20 @@ import { lstat, mkdir, open, readFile, realpath, rename, rm, writeFile } from 'n
 import { dirname, isAbsolute, join, relative } from 'node:path';
 import { gzip, gunzip } from 'node:zlib';
 import { promisify } from 'node:util';
+import { WORKSPACE_REMIX_REFERENCES_MANIFEST } from '@playcraft/common/cloud-workspace/runtime';
 import { excludeFromGit } from '../workspaces/dependencies.js';
+import { batchReferenceEnvExamples, batchReferenceMetadata } from '../workspaces/remix-references.js';
 import { gitRead, gitWrite } from './git.js';
 const compress = promisify(gzip);
 const decompress = promisify(gunzip);
 const privateNames = new Set(['.git', 'node_modules', '.ssh', '.aws', '.azure', '.gnupg', '.codex', '.npm', '.pnpm-store',
     '.config', '.npmrc', '.yarnrc', '.yarnrc.yml', '.netrc', '.git-credentials', 'credentials.json', 'credentials', 'secrets',
     'id_rsa', 'id_ed25519', 'settings.local.json', '.playcraft.json', 'playcraft.config.json', '.playcraft-temp', '.playcraft-preview-out']);
-function included(path) {
-    return !path.split('/').some(name => privateNames.has(name) || /^\.env(?:$|\.)/.test(name) || /\.(?:pem|key|p12|pfx)$/.test(name))
-        && !path.startsWith('.playcraft/skills/');
+function included(path, referenceExamples) {
+    const parts = path.split('/');
+    return !parts.some((name, index) => privateNames.has(name) || (/^\.env(?:$|\.)/.test(name) &&
+        !(index === parts.length - 1 && referenceExamples.has(path))) || /\.(?:pem|key|p12|pfx)$/.test(name))
+        && !path.startsWith('.playcraft/skills/') && !path.startsWith('.playcraft/skill-selections/');
 }
 /** Git keeps only the executable bit, so the digest must not depend on umask or group-write bits. */
 function snapshotMode(mode) {
@@ -32,10 +36,12 @@ export function digestFiles(files) {
 /** Files Git will accept. Credentials, caches and node_modules are left out. */
 export async function readSourceFiles(root) {
     const source = await realpath(root);
+    const referenceExamples = await batchReferenceEnvExamples(source);
+    const referenceRecords = await batchReferenceMetadata(source);
     const paths = new Set((await gitRead(source, ['ls-files', '--cached', '--others', '--exclude-standard', '-z'])).split('\0').filter(Boolean));
     const files = new Map();
     for (const path of [...paths].sort()) {
-        if (!included(path))
+        if (!included(path, referenceExamples))
             continue;
         const full = join(source, path);
         const stat = await lstat(full).catch(error => {
@@ -55,6 +61,33 @@ export async function readSourceFiles(root) {
             await handle.close();
         }
     }
+    const manifestFile = files.get(WORKSPACE_REMIX_REFERENCES_MANIFEST);
+    if (manifestFile) {
+        try {
+            const manifest = JSON.parse(manifestFile.body.toString('utf8'));
+            if (manifest?.version === 1 && Array.isArray(manifest.items)) {
+                const withheld = [];
+                for (const record of referenceRecords) {
+                    for (const file of record.files) {
+                        const path = `${record.path}/${file.path}`;
+                        // A damaged reference may make an otherwise allowed example fail verification. That
+                        // is a reference-integrity error, not evidence that a protected path was withheld.
+                        const isExample = /^\.env\.(?:example|sample|template)$/i.test(path.split('/').pop() ?? '');
+                        if (paths.has(path) && !included(path, referenceExamples) &&
+                            (!isExample || !included(path, new Set([path]))) && (await lstat(join(source, path)).catch(() => undefined))?.isFile()) {
+                            withheld.push(record.referenceId);
+                            break;
+                        }
+                    }
+                }
+                delete manifest.batchPolicyWithheldReferenceIds;
+                if (withheld.length)
+                    manifest.batchPolicyWithheldReferenceIds = withheld;
+                files.set(WORKSPACE_REMIX_REFERENCES_MANIFEST, { ...manifestFile, body: Buffer.from(JSON.stringify(manifest)) });
+            }
+        }
+        catch { /* Preserve malformed legacy metadata without letting it block an unrelated batch. */ }
+    }
     return files;
 }
 /** A changing source must not silently lose files from the captured input. */
@@ -99,6 +132,12 @@ export async function captureIndependentSource(source, destination) {
         for (const entry of ['/.playcraft.json', '/playcraft.config.json', '/.playcraft/skills/', '/.playcraft-temp/'])
             await excludeFromGit(staging, entry);
         await gitWrite(staging, ['add', '-A', '.']);
+        // Imported reference files can be tracked in the source despite .gitignore. Preserve only
+        // their filtered staging paths, without changing ignore handling for other source files.
+        for (const path of ['.playcraft/remix-references.json', 'references/remixes']) {
+            if (await lstat(join(staging, path)).catch(() => undefined))
+                await gitWrite(staging, ['add', '--force', '-A', '--', path]);
+        }
         await gitWrite(staging, ['commit', '--allow-empty', '-m', 'Freeze batch source']);
         const commitHash = (await gitWrite(staging, ['rev-parse', 'HEAD'])).trim();
         await rename(staging, destination);