@playcraft/cli 0.1.66 → 0.1.68

package/dist/utils/audio-export.js

@@ -0,0 +1,249 @@
+import path from 'node:path';
+import fsp from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import * as musicMetadata from 'music-metadata';
+export class AudioExportError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'AudioExportError';
+    }
+}
+function invalidOptions(message) {
+    throw new AudioExportError('audio_export_invalid_options', message);
+}
+const SAMPLE_RATES = [8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000];
+const OPUS_SAMPLE_RATES = [8000, 12000, 16000, 24000, 48000];
+const MP3_LOWEST_BITRATES = [8, 16, 24, 32, 40, 48, 56, 64];
+const MP3_LOW_BITRATES = [8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160];
+const MP3_HIGH_BITRATES = [32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320];
+const CODECS = {
+    mp3: 'libmp3lame',
+    ogg: 'libvorbis',
+    opus: 'libopus',
+    wav: 'pcm_s16le',
+};
+export async function getAudioInfo(inputPath) {
+    const resolvedPath = path.resolve(inputPath);
+    let stat;
+    try {
+        stat = await fsp.stat(resolvedPath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            throw new Error(`File not found: ${resolvedPath}`);
+        throw err;
+    }
+    const meta = await musicMetadata.parseFile(resolvedPath);
+    return {
+        duration: meta.format.duration ?? 0,
+        fileSize: stat.size,
+        format: meta.format.container ?? path.extname(resolvedPath).slice(1),
+        bitrate: Math.round((meta.format.bitrate ?? 0) / 1000),
+        sampleRate: meta.format.sampleRate ?? 44100,
+        channels: meta.format.numberOfChannels ?? 2,
+    };
+}
+function targetBytes(size) {
+    const match = size.trim().match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)?$/i);
+    const scales = { B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
+    const bytes = match
+        ? Math.floor(Number(match[1]) * scales[(match[2] ?? 'B').toUpperCase()])
+        : NaN;
+    if (!Number.isSafeInteger(bytes) || bytes <= 0)
+        invalidOptions('targetSize must be a positive size, such as 30KB');
+    return bytes;
+}
+function exportFormat(outputPath, explicit) {
+    const extension = path.extname(outputPath).slice(1).toLowerCase();
+    const format = explicit ?? extension;
+    if (!Object.hasOwn(CODECS, format))
+        invalidOptions(`Unsupported audio export format: ${format}`);
+    if (extension !== format)
+        invalidOptions(`Output extension must be .${format}`);
+    return format;
+}
+function validateOptions(format, options) {
+    if (options.channels !== undefined && options.channels !== 1 && options.channels !== 2) {
+        invalidOptions('channels must be 1 or 2');
+    }
+    const rates = format === 'opus' ? OPUS_SAMPLE_RATES : SAMPLE_RATES;
+    if (options.sampleRate !== undefined && !rates.includes(options.sampleRate)) {
+        invalidOptions(`Unsupported ${format} sampleRate: ${options.sampleRate}; supported: ${rates.join(', ')}`);
+    }
+    if (options.bitrate === undefined)
+        return;
+    const bitrate = options.bitrate;
+    if (format === 'wav')
+        invalidOptions('wav uses uncompressed 16-bit audio; set sampleRate and channels instead of bitrate');
+    const min = format === 'opus' ? 6 : format === 'ogg' ? 16 : 8;
+    const max = format === 'opus' ? 510 : format === 'ogg' ? 500 : 320;
+    if (!Number.isInteger(bitrate) || bitrate < min || bitrate > max) {
+        invalidOptions(`${format} bitrate must be an integer between ${min} and ${max}`);
+    }
+    if (format === 'mp3' && ![...MP3_LOW_BITRATES, ...MP3_HIGH_BITRATES].includes(bitrate)) {
+        invalidOptions(`Unsupported mp3 bitrate: ${bitrate}`);
+    }
+    if (format === 'mp3' && options.sampleRate !== undefined) {
+        const bitrates = mp3Bitrates(options.sampleRate);
+        if (!bitrates.includes(bitrate))
+            invalidOptions(`mp3 bitrate ${bitrate} is incompatible with sampleRate ${options.sampleRate}`);
+    }
+}
+function mp3Bitrates(rate) {
+    return rate <= 12000 ? MP3_LOWEST_BITRATES : rate < 32000 ? MP3_LOW_BITRATES : MP3_HIGH_BITRATES;
+}
+/** Run one bounded encoder process and terminate it immediately on cancellation. */
+export async function runAudioFfmpeg(args, signal) {
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        const child = spawn(process.env.FFMPEG_PATH || 'ffmpeg', ['-hide_banner', '-loglevel', 'error', '-nostdin', '-y', ...args], {
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        let stderr = '';
+        let cancelled = false;
+        const abort = () => {
+            cancelled = true;
+            child.kill('SIGKILL');
+        };
+        const timeout = setTimeout(abort, 120_000);
+        signal?.addEventListener('abort', abort, { once: true });
+        child.stderr.on('data', (chunk) => {
+            stderr = (stderr + String(chunk)).slice(-8192);
+        });
+        const cleanup = () => {
+            clearTimeout(timeout);
+            signal?.removeEventListener('abort', abort);
+        };
+        child.once('error', (err) => {
+            cleanup();
+            reject(err);
+        });
+        child.once('close', (code) => {
+            cleanup();
+            if (cancelled)
+                reject(signal?.reason ?? new AudioExportError('audio_export_failed', 'Audio encoding timed out'));
+            else if (code !== 0)
+                reject(new AudioExportError('audio_export_failed', `Audio encoding failed: ${stderr.trim() || `exit ${code}`}`));
+            else
+                resolve();
+        });
+        if (signal?.aborted)
+            abort();
+    });
+}
+/** Publish only a completed output; failed work never replaces an existing file. */
+export async function writeAudioOutput(outputPath, produce, signal) {
+    const output = path.resolve(outputPath);
+    await fsp.mkdir(path.dirname(output), { recursive: true });
+    const staging = await fsp.mkdtemp(path.join(path.dirname(output), '.playcraft-audio-'));
+    try {
+        const temporary = path.join(staging, path.basename(output));
+        const result = await produce(temporary);
+        signal?.throwIfAborted();
+        await fsp.rename(temporary, output);
+        return result;
+    }
+    finally {
+        await fsp.rm(staging, { recursive: true, force: true });
+    }
+}
+function encodingRate(format, bitrate, requested, sourceRate) {
+    if (requested !== undefined)
+        return requested;
+    if (format === 'opus')
+        return 48000;
+    let ceiling = sourceRate;
+    if (format === 'mp3') {
+        if (bitrate < 16)
+            ceiling = Math.min(ceiling, 8000);
+        else if (bitrate < 32 || bitrate === 144)
+            ceiling = Math.min(ceiling, 24000);
+        else if (bitrate > 160)
+            ceiling = Math.max(ceiling, 32000);
+        if (bitrate > 64)
+            ceiling = Math.max(ceiling, 16000);
+    }
+    if (format === 'ogg' && bitrate < 48)
+        ceiling = Math.min(ceiling, 16000);
+    return [...SAMPLE_RATES].reverse().find((rate) => rate <= ceiling) ?? SAMPLE_RATES[0];
+}
+function encodingBitrate(format, requested, rate) {
+    if (format === 'mp3') {
+        const supported = mp3Bitrates(rate);
+        return [...supported].reverse().find((value) => value <= requested) ?? supported[0];
+    }
+    return Math.max(format === 'opus' ? 6 : 16, Math.floor(requested));
+}
+/** Export from the original source on every attempt and verify the final byte budget. */
+export async function exportAudio(inputPath, outputPath, options = {}) {
+    try {
+        const format = exportFormat(outputPath, options.format);
+        validateOptions(format, options);
+        const budget = options.targetSize === undefined ? undefined : targetBytes(options.targetSize);
+        const signals = [options.signal, AbortSignal.timeout(120_000)].filter((signal) => !!signal);
+        const signal = AbortSignal.any(signals);
+        signal.throwIfAborted();
+        const source = await getAudioInfo(inputPath);
+        if (!Number.isFinite(source.duration) || source.duration <= 0)
+            invalidOptions('Input audio must have a positive duration');
+        const channels = options.channels ?? (source.channels === 1 ? 1 : 2);
+        let bitrate = options.bitrate ?? 128;
+        if (budget !== undefined && format !== 'wav')
+            bitrate = Math.min(bitrate, Math.floor((budget * 8) / source.duration / 1000));
+        return await writeAudioOutput(outputPath, async (temporary) => {
+            let previousBitrate = Infinity;
+            for (let attempt = 0; attempt < 8; attempt++) {
+                signal.throwIfAborted();
+                const rate = encodingRate(format, bitrate, options.sampleRate, source.sampleRate);
+                const actualBitrate = encodingBitrate(format, bitrate, rate);
+                if (format !== 'wav' && actualBitrate >= previousBitrate)
+                    break;
+                previousBitrate = actualBitrate;
+                const args = [
+                    '-i',
+                    path.resolve(inputPath),
+                    '-map',
+                    '0:a:0',
+                    '-vn',
+                    '-map_metadata',
+                    '-1',
+                    '-c:a',
+                    CODECS[format],
+                    '-ar',
+                    String(rate),
+                    '-ac',
+                    String(channels),
+                ];
+                if (format !== 'wav')
+                    args.push('-b:a', `${actualBitrate}k`);
+                if (format === 'mp3')
+                    args.push('-id3v2_version', '0');
+                if (format === 'opus')
+                    args.push('-vbr', 'off');
+                args.push('-f', format === 'opus' ? 'ogg' : format, temporary);
+                await runAudioFfmpeg(args, signal);
+                const result = await getAudioInfo(temporary);
+                signal.throwIfAborted();
+                const matchingRate = result.sampleRate === rate || (format === 'opus' && result.sampleRate === 48000);
+                if (!matchingRate ||
+                    result.channels !== channels ||
+                    (format === 'mp3' && result.bitrate !== actualBitrate)) {
+                    throw new AudioExportError('audio_export_failed', 'Encoder changed the requested sample rate, channels or bitrate');
+                }
+                if (budget === undefined || result.fileSize <= budget)
+                    return result;
+                if (format === 'wav')
+                    break;
+                bitrate = Math.min(actualBitrate - 1, Math.floor(((actualBitrate * budget) / result.fileSize) * 0.97));
+            }
+            throw new AudioExportError('audio_export_target_size_unreachable', `Cannot meet targetSize ${options.targetSize} with ${format} and the requested sample rate/channels; increase the budget or change export settings`);
+        }, signal);
+    }
+    catch (error) {
+        if (error instanceof AudioExportError || options.signal?.aborted)
+            throw error;
+        throw new AudioExportError('audio_export_failed', error instanceof Error ? error.message : String(error));
+    }
+}

package/dist/utils/audio-processor.js

@@ -2,32 +2,8 @@ import path from 'path';
 import os from 'os';
 import fsp from 'fs/promises';
 import ffmpeg from 'fluent-ffmpeg';
-import * as musicMetadata from 'music-metadata';
-/**
- * Parse a human-readable size string like "30KB", "1.5MB" into bytes.
- */
-function parseSizeToBytes(sizeStr) {
-    const match = sizeStr.trim().match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)?$/i);
-    if (!match)
-        throw new Error(`Invalid size format: ${sizeStr}. Use e.g. "30KB", "1.5MB"`);
-    const value = parseFloat(match[1]);
-    const unit = (match[2] ?? 'B').toUpperCase();
-    const multipliers = { B: 1, KB: 1024, MB: 1024 * 1024, GB: 1024 * 1024 * 1024 };
-    return Math.round(value * (multipliers[unit] ?? 1));
-}
-/**
- * Calculate the bitrate needed to hit a target file size for an audio file.
- * targetBytes: desired file size in bytes
- * durationSeconds: audio duration
- * Returns bitrate in kbps (clamped to 8-320).
- */
-function calcBitrateForSize(targetBytes, durationSeconds) {
-    if (durationSeconds <= 0)
-        return 64;
-    const targetBits = targetBytes * 8;
-    const bitrateKbps = Math.floor(targetBits / durationSeconds / 1000);
-    return Math.max(8, Math.min(320, bitrateKbps));
-}
+import { exportAudio, getAudioInfo, runAudioFfmpeg, writeAudioOutput } from './audio-export.js';
+export { exportAudio, getAudioInfo, AudioExportError } from './audio-export.js';
 /**
  * Wrap an ffmpeg command in a Promise.
  */
@@ -39,57 +15,14 @@ function runFfmpeg(cmd) {
             .run();
     });
 }
-/**
- * Get audio file metadata (duration, format, bitrate, sample rate, channels).
- */
-export async function getAudioInfo(inputPath) {
-    const resolvedPath = path.resolve(inputPath);
-    let stat;
-    try {
-        stat = await fsp.stat(resolvedPath);
-    }
-    catch (err) {
-        const code = err.code;
-        if (code === 'ENOENT') {
-            throw new Error(`File not found: ${resolvedPath}`);
-        }
-        throw err;
-    }
-    const meta = await musicMetadata.parseFile(resolvedPath);
-    return {
-        duration: meta.format.duration ?? 0,
-        fileSize: stat.size,
-        format: meta.format.container ?? path.extname(resolvedPath).replace('.', ''),
-        bitrate: Math.round((meta.format.bitrate ?? 0) / 1000),
-        sampleRate: meta.format.sampleRate ?? 44100,
-        channels: meta.format.numberOfChannels ?? 2,
-    };
-}
 /**
  * Compress audio file. Supports manual parameters or --target-size auto mode.
  */
 export async function compressAudio(inputPath, outputPath, options) {
-    const resolvedInput = path.resolve(inputPath);
-    const resolvedOutput = path.resolve(outputPath);
-    await ensureOutputDir(resolvedOutput);
-    let bitrate = options.bitrate ?? 128;
-    const sampleRate = options.sampleRate;
-    const mono = options.mono ?? false;
-    if (options.targetSize) {
-        const targetBytes = parseSizeToBytes(options.targetSize);
-        const info = await getAudioInfo(resolvedInput);
-        bitrate = calcBitrateForSize(targetBytes, info.duration);
-        console.log(`Auto bitrate for ${options.targetSize}: ${bitrate}kbps (duration=${info.duration.toFixed(1)}s)`);
-    }
-    const cmd = ffmpeg(resolvedInput).audioBitrate(bitrate);
-    if (sampleRate) {
-        cmd.audioFrequency(sampleRate);
-    }
-    if (mono) {
-        cmd.audioChannels(1);
+    if (options.mono && options.channels !== undefined && options.channels !== 1) {
+        throw new Error('mono cannot be combined with channels=2');
     }
-    cmd.output(resolvedOutput);
-    await runFfmpeg(cmd);
+    await exportAudio(inputPath, outputPath, { ...options, channels: options.mono ? 1 : options.channels });
 }
 /**
  * Trim audio to a specific time range.
@@ -183,7 +116,8 @@ export async function normalizeAudio(inputPath, outputPath, targetLoudness) {
 }
 /**
  * Create a seamless loop by crossfading the beginning and end of the audio.
- * Strategy: mix the faded-out tail over the faded-in beginning so the loop point is seamless.
+ * Crossfade the tail into the head, then append it after the unchanged middle.
+ * The output lasts one crossfade less than the input and is encoded only once.
  */
 export async function loopAudio(inputPath, outputPath, crossfadeDuration) {
     const resolvedInput = path.resolve(inputPath);
@@ -191,37 +125,26 @@ export async function loopAudio(inputPath, outputPath, crossfadeDuration) {
     await ensureOutputDir(resolvedOutput);
     const info = await getAudioInfo(resolvedInput);
     const duration = info.duration;
-    if (crossfadeDuration <= 0) {
+    if (!Number.isFinite(crossfadeDuration) || crossfadeDuration <= 0) {
         throw new Error('crossfade must be greater than 0');
     }
     if (crossfadeDuration * 2 >= duration) {
         throw new Error(`crossfade (${crossfadeDuration}s) is too long for audio duration (${duration.toFixed(1)}s)`);
     }
-    const ts = Date.now();
-    const tempMain = path.join(os.tmpdir(), `playcraft_loop_main_${ts}.mp3`);
-    const tempTail = path.join(os.tmpdir(), `playcraft_loop_tail_${ts}.mp3`);
-    const tempTailFaded = path.join(os.tmpdir(), `playcraft_loop_tailf_${ts}.mp3`);
-    try {
-        // Main: original without the last crossfade section, fade-out at end
-        await trimAudio(resolvedInput, tempMain, 0, duration - crossfadeDuration);
-        await fadeAudio(tempMain, tempMain, { fadeOut: crossfadeDuration });
-        // Tail: last crossfade seconds, fade-in
-        await trimAudio(resolvedInput, tempTail, duration - crossfadeDuration, duration);
-        await fadeAudio(tempTail, tempTailFaded, { fadeIn: crossfadeDuration });
-        // Mix: overlay tail (starts at t=0) on main beginning, output duration = main duration
-        const mixCmd = ffmpeg()
-            .input(tempMain)
-            .input(tempTailFaded)
-            .complexFilter([
-            `[0:a][1:a]amix=inputs=2:duration=first:dropout_transition=0[out]`,
-        ])
-            .outputOptions(['-map', '[out]'])
-            .output(resolvedOutput);
-        await runFfmpeg(mixCmd);
-    }
-    finally {
-        await Promise.all([tempMain, tempTail, tempTailFaded].map((tmp) => fsp.rm(tmp, { force: true }).catch(() => { })));
-    }
+    // The seam is built from two fades mixed with `amix` instead of `acrossfade`: acrossfade where
+    // both inputs are exactly the crossfade length is a degenerate case older FFmpeg releases
+    // resolve to an empty stream, which silently shortened the loop by the whole crossfade.
+    const graph = [
+        '[0:a:0]asplit=3[headsrc][midsrc][tailsrc]',
+        `[headsrc]atrim=start=0:end=${crossfadeDuration},asetpts=PTS-STARTPTS,afade=t=in:st=0:d=${crossfadeDuration}[head]`,
+        `[midsrc]atrim=start=${crossfadeDuration}:end=${duration - crossfadeDuration},asetpts=PTS-STARTPTS[mid]`,
+        `[tailsrc]atrim=start=${duration - crossfadeDuration}:end=${duration},asetpts=PTS-STARTPTS,afade=t=out:st=0:d=${crossfadeDuration}[tail]`,
+        '[tail][head]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[blend]',
+        '[mid][blend]concat=n=2:v=0:a=1[out]',
+    ].join(';');
+    await writeAudioOutput(resolvedOutput, temporary => runAudioFfmpeg([
+        '-i', resolvedInput, '-filter_complex', graph, '-map', '[out]', temporary,
+    ]));
 }
 /**
  * Mix multiple audio tracks together with optional volume and time offset per track.

package/dist/utils/execution-context-bridge.js

@@ -0,0 +1,28 @@
+import { workspaceExecutionContextReadSchema } from '@playcraft/common/cloud-workspace/runtime';
+/** A per-session broker capability supplies shell scope; its identity is never decoded in the command. */
+export async function readExecutionContextFromBridge(request, env = process.env) {
+    const endpoint = env.PLAYCRAFT_AGENT_GENERATION_ENDPOINT;
+    const capability = env.PLAYCRAFT_AGENT_GENERATION_CAPABILITY;
+    if (!endpoint && !capability)
+        return undefined;
+    if (!endpoint || endpoint.length > 1024 || !capability || !/^[A-Za-z0-9_-]{16,128}$/.test(capability))
+        throw new Error('execution_context_source_unavailable');
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error('execution_context_source_unavailable');
+    }
+    if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port || url.username || url.password
+        || url.search || url.hash || !/^\/[0-9a-f-]{36}\/[0-9a-f]{32}\/generation-provenance$/.test(url.pathname))
+        throw new Error('execution_context_source_unavailable');
+    url.pathname = url.pathname.replace(/generation-provenance$/, 'execution-context');
+    const response = await fetch(url, { method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15_000),
+        headers: { authorization: `Bearer ${capability}`, 'content-type': 'application/json' }, body: JSON.stringify(request) });
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(response.status === 403 ? 'execution_context_access_denied' : 'execution_context_unavailable');
+    }
+    return workspaceExecutionContextReadSchema.parse(await response.json());
+}

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

@@ -1,7 +1,7 @@
 import { setTimeout as delay } from 'node:timers/promises';
 import { sandboxBatchMemberStopSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { processHasExited, stopProcessGroup } from './processes.js';
-import { settleObservedGenerate } from './generate.js';
+import { reconcileFailedCreate, settleObservedGenerate } from './generate.js';
 import { memberStatus, readMember, serializeRun, writeMember, writeStopMarker } from './records.js';
 async function prove(record) {
     let stopped = true;
@@ -24,9 +24,20 @@ function sessionBusy(state, record) {
 }
 /** Read-only besides reconciling process proof. Does not start work or advance a phase. */
 export async function readBatchMemberStatus(state, runId) {
-    const record = await readMember(state, runId);
+    let record = await readMember(state, runId);
     if (!record)
         return undefined;
+    if (record.phase === 'generate' && record.state === 'stopping' && !record.stopRequested) {
+        const settled = await serializeRun(runId, async () => {
+            const latest = await readMember(state, runId);
+            return latest ? reconcileFailedCreate(state, latest) : undefined;
+        });
+        if (!settled)
+            return undefined;
+        record = settled;
+        if (record.state === 'failed')
+            return memberStatus(record);
+    }
     if (record.phase === 'generate' && record.state === 'running') {
         const settled = await settleObservedGenerate(state, record);
         if (settled.state !== 'running')

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

@@ -26,6 +26,18 @@ function operation(state, input) {
     };
     return { scopeKey: operationScopeKey(record), record };
 }
+function failedCreateWithoutNativeWork(state, record, created) {
+    if (!record.sessionId || state.journal.getSession(record.sessionId) || created.status !== 'failed' ||
+        created.nativeRequestId || created.nativeThreadId || created.nativeTurnId)
+        return false;
+    return state.journal.listOperations().every(({ operation: item }) => {
+        if (item.sessionId !== record.sessionId || !['session.create', 'session.turn'].includes(item.kind) ||
+            item.operationId === created.operationId)
+            return true;
+        return item.status === 'failed' && !item.nativeRequestId && !item.nativeThreadId && !item.nativeTurnId &&
+            (item.kind !== 'session.turn' || item.error === 'unknown_session');
+    });
+}
 function turnTerminal(event) {
     if (event.kind === 'approval_request')
         return 'needs_user';
@@ -124,8 +136,21 @@ export async function generateBatchMember(state, body) {
             try {
                 if (!state.journal.getSession(sessionId)) {
                     const created = operation(state, { kind: 'session.create', clientRequestId: `batch-create:${command.runId}`, sessionId, workspaceId: command.workspaceId, directoryName: command.directoryName, payload: { permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}) } });
-                    if (!state.journal.getOperation(created.scopeKey))
-                        await executeOperation(state, created.scopeKey, created.record, { permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}) });
+                    const result = state.journal.getOperation(created.scopeKey) ?? await executeOperation(state, created.scopeKey, created.record, { permissionMode: 'auto', ...(modelConfigId ? { modelConfigId } : {}) });
+                    if (failedCreateWithoutNativeWork(state, record, result)) {
+                        // A failed creation with no native receipt cannot have started a turn. Still prove all other writers stopped.
+                        const writersStopped = await stopMemberWriters(state, { ...record, sessionId: undefined });
+                        if (!failedCreateWithoutNativeWork(state, record, result)) {
+                            return memberStatus(await writeMember(state, { ...record, state: 'unknown', writersStopped: false,
+                                holding: true, operationId: result.operationId, error: 'native_receipt_lost' }));
+                        }
+                        return memberStatus(await writeMember(state, { ...record, state: writersStopped ? 'failed' : 'stopping',
+                            writersStopped, holding: !writersStopped, operationId: result.operationId, error: result.error ?? 'batch_session_create_failed' }));
+                    }
+                    if (result.status !== 'completed' || !state.journal.getSession(sessionId)) {
+                        return memberStatus(await writeMember(state, { ...record, state: 'unknown', writersStopped: false,
+                            holding: true, operationId: result.operationId, error: 'native_receipt_lost' }));
+                    }
                 }
                 if (await readStopMarker(state, command.runId))
                     return memberStatus(await stoppedRecord(state, command, record));
@@ -226,6 +251,22 @@ async function reconcileGenerate(state, record) {
     }
     return record;
 }
+/** Recover failures recorded by older runtimes which tried a turn after creation had failed. */
+export async function reconcileFailedCreate(state, record) {
+    if (record.phase !== 'generate' || record.state !== 'stopping' || record.stopRequested || !record.sessionId ||
+        state.journal.getSession(record.sessionId))
+        return record;
+    const operations = state.journal.listOperations().map(item => item.operation).filter(item => item.workspaceId === record.workspaceId && item.directoryName === record.directoryName && item.sessionId === record.sessionId);
+    const created = operations.find(item => item.kind === 'session.create' && item.clientRequestId === `batch-create:${record.runId}`);
+    if (!created || (record.error !== 'unknown_session' && record.error !== created.error) ||
+        !failedCreateWithoutNativeWork(state, record, created))
+        return record;
+    const writersStopped = await stopMemberWriters(state, { ...record, sessionId: undefined });
+    if (!writersStopped || !failedCreateWithoutNativeWork(state, record, created))
+        return record;
+    return writeMember(state, { ...record, state: 'failed', writersStopped: true, holding: false,
+        operationId: created.operationId, error: created.error ?? 'batch_session_create_failed' });
+}
 async function completeGeneration(state, record, root) {
     try {
         const afterTree = await snapshotWorkspaceTree(root);

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

@@ -13,6 +13,7 @@ import { restoreArchive } from './source-capture.js';
 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 { filesystemObjectStore, memberStatus, readMember, readSnapshot, readStopMarker, serializeRun, sourceCacheDir, writeMember, } from './records.js';
 const BRANCH = /^remix\/draft-[a-f0-9]{16}$/;
 function hashCommand(value) {
@@ -189,9 +190,12 @@ export async function prepareBatchMember(state, body, options) {
                         await materialize(state, snapshot, staging, options?.objectStore ?? filesystemObjectStore(state), sourceRoot);
                     const commit = command.resumeFromCommit ?? snapshot.commitHash;
                     await checkoutBranch(staging, command.branchName, commit, repositoryUrl);
+                    await restoreBatchSkillArtifacts(sourceRoot, staging);
                     const { rename } = await import('node:fs/promises');
                     await rename(staging, root);
                 }
+                else
+                    await restoreBatchSkillArtifacts(sourceRoot, root);
                 await registerWorkspaceDirectory(state, {
                     workspaceId: command.workspaceId,
                     directoryName: command.directoryName,

package/dist/workspace-runtime/batch/skill-artifacts.js

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { effectiveProjectSkills, extractBundleArchive, readProjectSkillsLockFile, sourceTreeDigest } from '@playcraft/common/project-skills';
+import { excludeFromGit } from '../workspaces/dependencies.js';
+import { ensureSharedDirectory, writeSharedFile } from '../workspaces/shared-write.js';
+import { readWorkspaceSkillSnapshot } from '../workspaces/skills.js';
+/** Copy only artifacts selected by the member's frozen lock; missing files retain the platform fallback. */
+export async function restoreBatchSkillArtifacts(source, member) {
+    if (await readProjectSkillsLockFile(member) === null)
+        return;
+    const snapshot = await readWorkspaceSkillSnapshot(member);
+    const entries = effectiveProjectSkills(snapshot.declaration, snapshot.lock, 'sandbox-agent');
+    const sourceRoot = await realpath(source).catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (!sourceRoot)
+        return;
+    const directories = [];
+    try {
+        let directory = sourceRoot;
+        for (const part of ['', '.playcraft', 'skill-artifacts']) {
+            if (part)
+                directory = join(directory, part);
+            const handle = await open(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW).catch((error) => {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            });
+            if (!handle)
+                return;
+            directories.push(handle);
+            // Pin the directory inode on Linux so concurrent changes cannot redirect the read.
+            if (process.platform === 'linux')
+                directory = `/proc/self/fd/${handle.fd}`;
+        }
+        for (const entry of entries) {
+            const hash = entry.revision.artifactHash;
+            let name = `${hash}.tar.gz`;
+            const openArtifact = (filename) => open(join(directory, filename), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch((error) => {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            });
+            let handle = await openArtifact(name);
+            if (!handle && snapshot.lock.lockVersion === 4) {
+                name = `content-${entry.revision.contentHash}.tar.gz`;
+                handle = await openArtifact(name);
+            }
+            if (!handle)
+                continue;
+            let body;
+            try {
+                const stat = await handle.stat({ bigint: true });
+                if (!stat.isFile() || stat.nlink !== 1n || stat.size > 80n * 1024n * 1024n)
+                    throw new Error('batch_snapshot_skill_artifact_invalid');
+                body = Buffer.alloc(Number(stat.size));
+                let offset = 0;
+                while (offset < body.length) {
+                    const { bytesRead } = await handle.read(body, offset, body.length - offset, offset);
+                    if (!bytesRead)
+                        throw new Error('batch_snapshot_skill_artifact_invalid');
+                    offset += bytesRead;
+                }
+                const probe = Buffer.alloc(1);
+                const extra = await handle.read(probe, 0, 1, offset);
+                const after = await handle.stat({ bigint: true });
+                if (extra.bytesRead || stat.dev !== after.dev || stat.ino !== after.ino || stat.size !== after.size ||
+                    stat.mtimeNs !== after.mtimeNs || stat.ctimeNs !== after.ctimeNs)
+                    throw new Error('batch_snapshot_skill_artifact_invalid');
+                if (name.startsWith('content-')) {
+                    const extracted = extractBundleArchive(body);
+                    if (extracted.issues.length || sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.revision.contentHash)
+                        throw new Error('batch_snapshot_skill_artifact_invalid');
+                }
+                else if (createHash('sha256').update(body).digest('hex') !== hash)
+                    throw new Error('batch_snapshot_skill_artifact_invalid');
+            }
+            finally {
+                await handle.close();
+            }
+            const targetDir = join(member, '.playcraft', 'skill-artifacts');
+            const target = join(targetDir, name);
+            const existing = await lstat(target).catch((error) => {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            });
+            if (existing)
+                continue; // The normal skill loader validates existing files before use.
+            await excludeFromGit(member, '/.playcraft/skill-artifacts/');
+            await ensureSharedDirectory(member, targetDir);
+            await writeSharedFile(member, target, body);
+        }
+    }
+    finally {
+        for (const handle of directories.reverse())
+            await handle.close();
+    }
+}