@playcraft/cli 0.1.59-beta → 0.1.61-beta

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

@@ -2,6 +2,8 @@ import { execFile, spawn } from 'node:child_process';
 import { readFile } from 'node:fs/promises';
 import { promisify } from 'node:util';
 import { setTimeout as delay } from 'node:timers/promises';
+import { startLauncherProcess, stopLauncherProcess } from '../codex/launcher-client.js';
+import { launcherSocket } from '../workspaces/developer-command.js';
 export async function processBirth(pid) {
     if (process.platform !== 'linux') {
         return promisify(execFile)('ps', ['-p', String(pid), '-o', 'lstart='], { timeout: 2000 }).then(value => value.stdout.trim() || undefined, () => undefined);
@@ -23,12 +25,27 @@ export function groupExited(pid) {
         return error.code === 'ESRCH';
     }
 }
+/** A missing local process cannot replace the launcher's proof for a development-user group. */
+export function processHasExited(record) {
+    return record.stopped || (!record.launcher && groupExited(record.pid));
+}
 /**
  * Stops one run's process group. A mismatched birth means the pid was reused, which is not proof
  * that the original writers exited, so the caller must not report writersStopped.
  */
 export async function stopProcessGroup(record) {
-    if (record.stopped || groupExited(record.pid))
+    if (record.stopped)
+        return true;
+    if (record.launcher) {
+        try {
+            await stopLauncherProcess(record.launcher);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (groupExited(record.pid))
         return true;
     if (record.birth && await processBirth(record.pid) !== record.birth)
         return false;
@@ -46,27 +63,82 @@ export async function stopProcessGroup(record) {
     }
     return groupExited(record.pid);
 }
-export async function runProcessGroup(cwd, command, role, onStart) {
-    const child = spawn('bash', ['-lc', command], {
+export async function runProcessGroup(cwd, command, role, onStart, options) {
+    const socketPath = options && launcherSocket(options.state);
+    if (options && options.state.config.workspaceMode === 'multi' &&
+        options.state.config.environment !== 'local' && !socketPath)
+        throw new Error('development_launcher_unavailable');
+    let launched;
+    let tracked;
+    if (socketPath) {
+        // Persist uncertainty before sending start: a lost acknowledgement is not a rejected launch.
+        tracked = { pid: 0, role, stopped: false, launcher: {
+                socketPath, processId: options.processId, runtimeEpoch: options.state.runtimeEpoch, instanceId: '',
+            } };
+        await onStart(tracked);
+        try {
+            launched = await startLauncherProcess({
+                socketPath, processId: options.processId, runtimeEpoch: options.state.runtimeEpoch,
+                argv: ['/usr/bin/bash', '-lc', `{ ${command}; } </dev/null 2>&1`], cwd, env: {},
+            });
+        }
+        catch (error) {
+            if (error.launchRejected) {
+                tracked.stopped = true;
+                await onStart(tracked);
+            }
+            throw error;
+        }
+    }
+    launched?.stdin?.end();
+    const child = launched ? undefined : spawn('bash', ['-lc', command], {
         cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'],
         env: { PATH: process.env.PATH, HOME: cwd, GIT_TERMINAL_PROMPT: '0' },
     });
-    const pid = child.pid;
+    const pid = launched?.pid ?? child?.pid;
     if (!pid)
         throw new Error('batch_process_not_started');
     let output = '';
-    const collect = (chunk) => { output = (output + String(chunk)).slice(-64 * 1024); };
-    child.stdout?.on('data', collect);
-    child.stderr?.on('data', collect);
+    const collect = (chunk) => {
+        output = (output + String(chunk)).slice(-64 * 1024);
+        options?.onOutput?.(chunk);
+    };
+    (launched?.stdout ?? child?.stdout)?.on('data', collect);
+    (launched?.stderr ?? child?.stderr)?.on('data', collect);
     // Subscribe before any await. A short command can exit during processBirth or onStart,
     // and a late listener never sees that close event.
     const finished = new Promise((resolve) => {
-        child.once('error', () => resolve(null));
-        child.once('close', resolve);
+        if (launched)
+            launched.onExit(code => resolve(code ?? null));
+        else {
+            child.once('error', () => resolve(null));
+            child.once('close', resolve);
+        }
     });
-    const tracked = { pid, birth: await processBirth(pid), stopped: false, role };
-    await onStart(tracked);
-    const code = await finished;
-    tracked.stopped = groupExited(pid);
-    return { code, output, process: tracked };
+    tracked = { pid, birth: await processBirth(pid), stopped: false, role,
+        ...(launched ? { launcher: launched.identity } : {}) };
+    try {
+        await onStart(tracked);
+        const code = await finished;
+        if (launched) {
+            try {
+                await launched.stop();
+                tracked.stopped = true;
+            }
+            catch (error) {
+                collect(`\n[install] ${error instanceof Error ? error.message : String(error)}\n`);
+                // Keep the directory occupied until the launcher confirms stop.
+            }
+        }
+        else
+            tracked.stopped = groupExited(pid);
+        return { code, output, process: tracked };
+    }
+    catch (error) {
+        if (launched)
+            await launched.stop().catch(() => undefined);
+        else
+            await stopProcessGroup(tracked);
+        throw error;
+    }
 }

package/dist/workspace-runtime/batch/writer-proof.js

@@ -1,12 +1,12 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { groupExited, stopProcessGroup } from './processes.js';
+import { processHasExited, stopProcessGroup } from './processes.js';
 /** An interrupt acknowledgement is not proof that the native turn and its writers have stopped. */
 export async function stopMemberWriters(state, record) {
     if (!record)
         return true;
     let stopped = true;
     for (const process of record.processes) {
-        if (process.stopped || groupExited(process.pid))
+        if (processHasExited(process))
             process.stopped = true;
         else
             process.stopped = await stopProcessGroup(process);

package/dist/workspace-runtime/codex/app-server.js

@@ -19,6 +19,8 @@ import { readNativeThreadImage } from './thread-image.js';
 import { WORKSPACE_UI_TOOLS, WorkspaceUiTools } from './ui-tools.js';
 import { WORKSPACE_DELIVERY_TOOLS, WorkspaceDeliveryTools, isWorkspaceDeliveryTool } from './delivery-tools.js';
 import { WORKSPACE_UI_INSTRUCTIONS } from './ui-instructions.js';
+import { WORKSPACE_SCHEDULED_TASK_TOOLS, WorkspaceScheduledTaskTools, isWorkspaceScheduledTaskTool } from './scheduled-task-tools.js';
+import { PROCEDURAL_3D_TOOL, ProductionSkillTools } from './production-skill-tools.js';
 function withModelShell(config, modelConfigId) {
     if (!modelConfigId || !/^[0-9a-f-]{36}$/i.test(modelConfigId))
         return config;
@@ -191,9 +193,15 @@ export function createCodexAppServerAdapter(options) {
     const coordinatorDirectories = new Map();
     const uiTools = new WorkspaceUiTools(emitCollected, options.uiToolTimeoutMs);
     const deliveryTools = options.deliveryTools ? new WorkspaceDeliveryTools(options.deliveryTools) : undefined;
+    const scheduledTaskTools = options.scheduledTaskProposals ? new WorkspaceScheduledTaskTools(options.scheduledTaskProposals, (proposalId, source) => emitCollected(collectedEvent('notification', 'scheduled-task.proposal.changed', {
+        proposalId, sessionId: threads.get(source.threadId)?.sessionId, threadId: source.threadId, turnId: source.turnId,
+    }))) : undefined;
+    const productionSkill = options.productionSkill ? new ProductionSkillTools(options.productionSkill) : undefined;
     const dynamicTools = [
         ...(options.workspaceUi ? WORKSPACE_UI_TOOLS : []),
         ...(deliveryTools ? WORKSPACE_DELIVERY_TOOLS : []),
+        ...(scheduledTaskTools ? WORKSPACE_SCHEDULED_TASK_TOOLS : []),
+        ...(productionSkill ? [PROCEDURAL_3D_TOOL] : []),
     ];
     function emitCollected(event) {
         for (const listener of collected)
@@ -594,7 +602,13 @@ export function createCodexAppServerAdapter(options) {
                         approvals.delete(key);
                 }
             }
-            emitCollected(collectedEvent('notification', method, payload));
+            if (method === 'turn/completed' && typeof payload.threadId === 'string'
+                && productionSkill?.hasActive(payload.threadId, String(asRecord(payload.turn).id))) {
+                // Keep the operation's directory lease until the tool's writer has stopped.
+                void productionSkill.cancel(payload.threadId, String(asRecord(payload.turn).id)).then(() => emitCollected(collectedEvent('notification', method, payload)));
+            }
+            else
+                emitCollected(collectedEvent('notification', method, payload));
         });
         rpc.onServerRequest((id, method, params) => {
             const payload = asRecord(params);
@@ -609,6 +623,36 @@ export function createCodexAppServerAdapter(options) {
             }
             if (method === 'item/tool/call') {
                 const thread = typeof payload.threadId === 'string' ? threads.get(payload.threadId) : undefined;
+                if (scheduledTaskTools && isWorkspaceScheduledTaskTool(payload.tool)) {
+                    const threadId = String(payload.threadId ?? ''), turnId = String(payload.turnId ?? '');
+                    const current = () => {
+                        try {
+                            return Boolean(thread && threads.get(threadId) === thread && thread.turnActive
+                                && thread.lastTurnId === turnId && !childParents.has(threadId)
+                                && ['execute', 'plan'].includes(thread.activeMode ?? '') && !options.fixedExecution
+                                && !options.trustedExecution?.(thread.sessionId));
+                        }
+                        catch {
+                            return false;
+                        }
+                    };
+                    setTimeout(() => {
+                        void scheduledTaskTools.request(id, payload, nativeClient, thread ? {
+                            bridge: thread.scheduledTaskProposalBridge, threadId, turnId, current,
+                        } : undefined);
+                    }, 0);
+                    return;
+                }
+                if (productionSkill && payload.tool === PROCEDURAL_3D_TOOL.name) {
+                    const trusted = thread?.turnActive && thread.cwd && thread.activeMode === 'execute'
+                        && thread.permissionMode !== 'read-only' && thread.readOnlyConfirmed !== true
+                        && payload.turnId === thread.lastTurnId && typeof payload.threadId === 'string' && typeof payload.turnId === 'string';
+                    void productionSkill.request(id, payload, nativeClient, trusted ? {
+                        sessionId: thread.sessionId, root: thread.cwd,
+                        nativeThreadId: payload.threadId, nativeTurnId: payload.turnId,
+                    } : undefined);
+                    return;
+                }
                 if (deliveryTools && isWorkspaceDeliveryTool(payload.tool)) {
                     void deliveryTools.request(id, payload, nativeClient, {
                         sessionId: thread?.sessionId,
@@ -653,6 +697,7 @@ export function createCodexAppServerAdapter(options) {
             if (live === current) {
                 readyFlag = false;
                 void uiTools.cancel(undefined, 'ui_runtime_disconnected');
+                void productionSkill?.cancel();
                 approvals.clear();
                 // Retain the old handle until its entire execution group is confirmed stopped.
                 rpc = undefined;
@@ -734,6 +779,7 @@ export function createCodexAppServerAdapter(options) {
         name: 'codex-app-server',
         workspaceUi: options.workspaceUi === true,
         ready: () => readyFlag && !closed,
+        ...(scheduledTaskTools ? { scheduledTaskProposalSource: (source) => scheduledTaskTools.isActive(source) } : {}),
         executionProcess() {
             if (!live)
                 return undefined;
@@ -755,6 +801,7 @@ export function createCodexAppServerAdapter(options) {
                 previous.superseded = true;
             readyFlag = false;
             await uiTools.cancel(undefined, 'ui_runtime_disconnected');
+            await productionSkill?.cancel();
             startPromise = undefined;
             threads.clear();
             approvals.clear();
@@ -927,7 +974,7 @@ export function createCodexAppServerAdapter(options) {
                 selectedModel ??= thread.resolvedModel ?? model;
                 const requestId = rpc.reserveRequest();
                 await input.persistReservation({ nativeRequestId: String(requestId), modelConfigId, reasoningEffort, permissionMode });
-                activateModel();
+                activateModel(execution.sandboxPolicy.type === 'readOnly');
                 thread.modelConfigId = modelConfigId;
                 thread.reasoningEffort = reasoningEffort;
                 thread.permissionMode = permissionMode;
@@ -941,6 +988,7 @@ export function createCodexAppServerAdapter(options) {
                     return { outcome: 'uncertain', threadId: input.threadId };
                 try {
                     thread.turnActive = true;
+                    thread.scheduledTaskProposalBridge = input.scheduledTaskProposalBridge;
                     thread.uiSnapshot = options.workspaceUi && input.uiSnapshot?.sessionId === input.sessionId ? input.uiSnapshot : undefined;
                     const started = await rpc.sendReserved(requestId, 'turn/start', { threadId: input.threadId, input: [
                             { type: 'text', text: input.text },
@@ -1240,6 +1288,7 @@ export function createCodexAppServerAdapter(options) {
                 return { outcome: 'failed', error: 'turn_changed' };
             try {
                 await uiTools.cancel(input.threadId);
+                await productionSkill?.cancel(input.threadId, turnId);
                 await rpc.request('turn/interrupt', { threadId: input.threadId, turnId });
                 const cwd = threads.get(input.threadId)?.cwd;
                 if (cwd && (input.expectedTurnId === undefined || threads.get(input.threadId)?.lastTurnId === turnId))
@@ -1300,6 +1349,7 @@ export function createCodexAppServerAdapter(options) {
                 closed = true;
                 readyFlag = false;
                 await uiTools.cancel(undefined, 'ui_runtime_disconnected');
+                await productionSkill?.cancel();
                 approvals.clear();
                 if (live)
                     live.superseded = true;

package/dist/workspace-runtime/codex/config-toml.js

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 const exec = promisify(execFile);
@@ -77,13 +77,17 @@ export async function writePortableCodexCatalog(input) {
     }
     await mkdir(input.directory, { recursive: true });
     const path = join(input.directory, 'portable-models.json');
-    // private
-    await writeFile(path, body, { encoding: 'utf8', mode: 0o644 });
-    // private
-    await writeFile(join(input.directory, 'portable-models.version.json'), JSON.stringify({
+    // shared: public model metadata crosses from the control user to the development user.
+    // Explicit permissions also repair existing files and override a private process umask.
+    await writeFile(path, body, { encoding: 'utf8', mode: 0o644 }); // shared
+    await chmod(path, 0o644);
+    const versionPath = join(input.directory, 'portable-models.version.json');
+    await writeFile(// shared
+    versionPath, JSON.stringify({
         version,
         sha256: createHash('sha256').update(body).digest('hex'),
     }), { encoding: 'utf8', mode: 0o644 });
+    await chmod(versionPath, 0o644);
     return path;
 }
 export async function writePlaycraftCodexConfig(input) {

package/dist/workspace-runtime/codex/delivery-tools.js

@@ -1,11 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { DELIVERY_CHANNELS, deliveryFormatSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { DELIVERY_CHANNELS, } from '@playcraft/common/cloud-workspace/runtime';
 import { rejectTool, toolContent } from './tool-response.js';
 export const WORKSPACE_DELIVERY_TOOLS = [
     {
         type: 'function',
         name: 'playcraft_build_delivery',
-        description: 'Export channel packages through the PlayCraft platform. This first saves the workspace (commit and push), then exports that commit; each channel reuses the options of its latest export on this branch, or the defaults when it has none. A workspace without a project first gets one, with a private repository, as its first save would. If the result is pending at workspace.save, finish the current turn without polling so the save can run, then continue the export in a later turn. Once build ids are returned, poll playcraft_get_delivery for status, checks and failure details.',
+        description: 'Export channel packages through the PlayCraft platform. This first saves the workspace (commit and push), then exports that commit. Each channel uses the same fixed HTML or ZIP choice as the Export button for that channel and the project engine. Other options reuse the channel\'s latest export on this branch, or the defaults when it has none. A workspace without a project first gets one, with a private repository, as its first save would. If the result is pending at workspace.save, finish the current turn without polling so the save can run, then continue the export in a later turn. Once build ids are returned, poll playcraft_get_delivery for status, checks and failure details.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -16,7 +16,6 @@ export const WORKSPACE_DELIVERY_TOOLS = [
                     maxItems: 8,
                     uniqueItems: true,
                 },
-                format: { type: 'string', enum: ['html', 'zip'] },
             },
             additionalProperties: false,
         },
@@ -71,7 +70,7 @@ export class WorkspaceDeliveryTools {
             await this.reject(client, requestId, 'permission_denied');
             return;
         }
-        const unknown = Object.keys(input).filter(key => key !== 'channels' && key !== 'format');
+        const unknown = Object.keys(input).filter(key => key !== 'channels');
         if (unknown.length) {
             await this.reject(client, requestId, 'invalid_delivery_tool_arguments');
             return;
@@ -83,11 +82,6 @@ export class WorkspaceDeliveryTools {
             await this.reject(client, requestId, 'invalid_delivery_tool_arguments');
             return;
         }
-        const format = input.format === undefined ? undefined : deliveryFormatSchema.safeParse(input.format);
-        if (format && !format.success) {
-            await this.reject(client, requestId, 'invalid_delivery_tool_arguments');
-            return;
-        }
         try {
             const result = await this.handlers.build({
                 ...context,
@@ -95,7 +89,6 @@ export class WorkspaceDeliveryTools {
                     ? payload.callId
                     : randomUUID(),
                 channels: channels,
-                ...(format && format.success ? { format: format.data } : {}),
             });
             await this.respond(client, requestId, result);
         }

package/dist/workspace-runtime/codex/launcher-client.js

@@ -33,6 +33,13 @@ function request(socketPath, message) {
         });
     });
 }
+/** A persisted identity lets the controller stop development-user writers after a request ends. */
+export async function stopLauncherProcess(input) {
+    if (!input.instanceId)
+        throw new Error('launcher_start_unconfirmed');
+    const { socketPath, ...identity } = input;
+    await stopLauncherExecution(socketPath, identity);
+}
 /** The private launcher owns the boundary; development shells never receive its identity. */
 export async function prepareLauncherOrigin(input) {
     try {
@@ -51,6 +58,24 @@ export async function verifyLauncherOrigin(input) {
         return false;
     }
 }
+/** Recovered writers need a receipt from the same launcher, not just an absent process id. */
+export async function stopLauncherExecution(socketPath, identity) {
+    if (!identity || typeof identity.processId !== 'string' || !identity.processId ||
+        typeof identity.instanceId !== 'string' || !identity.instanceId ||
+        !Number.isSafeInteger(identity.runtimeEpoch) || identity.runtimeEpoch < 0)
+        throw new Error('launcher_execution_identity_invalid');
+    for (const signal of ['SIGTERM', 'SIGKILL']) {
+        await request(socketPath, { ...identity, action: 'stop', signal });
+        const deadline = Date.now() + 3000;
+        while (Date.now() < deadline) {
+            const status = await request(socketPath, { ...identity, action: 'status' });
+            if (status.running === false)
+                return;
+            await delay(50);
+        }
+    }
+    throw new Error('codex_group_stop_unconfirmed');
+}
 export async function startLauncherProcess(input) {
     const socket = createConnection(input.socketPath);
     const stdout = new PassThrough();
@@ -98,9 +123,12 @@ export async function startLauncherProcess(input) {
                 try {
                     const frame = JSON.parse(line);
                     if (!started) {
+                        if (frame.ok === false)
+                            throw Object.assign(new Error(frame.error || 'launcher_start_failed'), { launchRejected: true });
                         if (!frame.ok || !frame.pid || !frame.instanceId)
                             throw new Error(frame.error || 'launcher_start_failed');
                         identity = {
+                            socketPath: input.socketPath,
                             processId: input.processId,
                             runtimeEpoch: input.runtimeEpoch,
                             instanceId: frame.instanceId,
@@ -146,7 +174,13 @@ export async function startLauncherProcess(input) {
         });
     });
     return {
+        identity,
         pid,
+        executionIdentity: {
+            processId: identity.processId,
+            runtimeEpoch: identity.runtimeEpoch,
+            instanceId: identity.instanceId,
+        },
         stdin,
         stdout,
         stderr,
@@ -163,31 +197,19 @@ export async function startLauncherProcess(input) {
         },
         stop() {
             stopPromise ??= (async () => {
-                // A new launcher's empty registry cannot confirm an old group's exit.
-                for (const signal of ['SIGTERM', 'SIGKILL']) {
-                    await request(input.socketPath, { ...identity, action: 'stop', signal });
-                    const deadline = Date.now() + 3000;
-                    while (Date.now() < deadline) {
-                        const status = await request(input.socketPath, { ...identity, action: 'status' });
-                        if (status.running === false) {
-                            let timeout;
-                            try {
-                                await Promise.race([transportClosed, new Promise((_resolve, reject) => {
-                                        timeout = setTimeout(() => {
-                                            socket.destroy();
-                                            reject(new Error('launcher_output_drain_unconfirmed'));
-                                        }, 3000);
-                                    })]);
-                            }
-                            finally {
-                                clearTimeout(timeout);
-                            }
-                            return;
-                        }
-                        await delay(50);
-                    }
+                await stopLauncherProcess(identity);
+                let timeout;
+                try {
+                    await Promise.race([transportClosed, new Promise((_resolve, reject) => {
+                            timeout = setTimeout(() => {
+                                socket.destroy();
+                                reject(new Error('launcher_output_drain_unconfirmed'));
+                            }, 3000);
+                        })]);
+                }
+                finally {
+                    clearTimeout(timeout);
                 }
-                throw new Error('codex_group_stop_unconfirmed');
             })();
             return stopPromise;
         },

package/dist/workspace-runtime/codex/model-broker.js

@@ -7,6 +7,7 @@ import { z } from 'zod';
 import { workspaceContextFromRoot } from '../workspaces/registry.js';
 import { PLATFORM_ROUTES, modelResponsesPath, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceGenerationProvenanceBroker } from './generation-provenance-broker.js';
+import { WorkspaceRemixReferencesBroker } from './remix-references-broker.js';
 const credentialSchema = z.object({
     token: z.string().min(1), expiresAt: z.string().datetime(),
     configId: z.string().uuid(), model: z.string().min(1).max(128),
@@ -27,9 +28,11 @@ export class WorkspaceModelBroker {
     requests = new Set();
     sessionRequests = new Map();
     generation;
+    references;
     constructor(state) {
         this.state = state;
         this.generation = new WorkspaceGenerationProvenanceBroker(state);
+        this.references = new WorkspaceRemixReferencesBroker(state);
     }
     async start() {
         if (this.server)
@@ -74,16 +77,37 @@ export class WorkspaceModelBroker {
         const boundaryId = sessionId && clientRequestId ? await this.generation.prepare() : undefined;
         if (!route || route.epoch !== this.state.runtimeEpoch) {
             route = { workspaceId, epoch: this.state.runtimeEpoch, capability: randomBytes(32).toString('base64url'),
-                generationCapability: randomBytes(32).toString('base64url') };
+                generationCapability: randomBytes(32).toString('base64url'), referencesCapability: randomBytes(32).toString('base64url') };
             this.routes.set(routeKey, route);
         }
         // Each session pins its prepared model; shared credential renewal cannot change an active turn.
         return {
-            activate: () => {
+            activate: (readOnly = false) => {
                 if (!this.valid(entry) || this.routes.get(routeKey) !== route)
                     throw new Error('model_access_denied');
+                const priorFeedback = route.selected?.feedback;
+                let refsBlocked = Boolean(entry.refsBlocked || priorFeedback?.refsBlocked && priorFeedback.clientRequestId === clientRequestId);
+                if (sessionId && clientRequestId) {
+                    const overlaps = (this.state.journal.listOperations?.() ?? []).some(({ operation }) => ['session.turn', 'session.review', 'session.compact'].includes(operation.kind)
+                        && ['dispatched', 'accepted', 'uncertain'].includes(operation.status)
+                        && operation.generation === this.state.config.generation && operation.runtimeEpoch === this.state.runtimeEpoch
+                        && (operation.sessionId !== sessionId || operation.clientRequestId !== clientRequestId));
+                    if (overlaps) {
+                        refsBlocked = true;
+                        // A completed overlapping turn may leave shells alive. Only a later turn gets a new safe boundary.
+                        for (const prepared of this.entries.values()) {
+                            if (prepared.epoch === this.state.runtimeEpoch)
+                                prepared.refsBlocked = true;
+                        }
+                        for (const existing of this.routes.values()) {
+                            if (existing.epoch === this.state.runtimeEpoch && existing.selected?.feedback)
+                                existing.selected.feedback.refsBlocked = true;
+                        }
+                    }
+                }
                 route.selected = { entry, model: credential.model,
-                    ...(sessionId && clientRequestId ? { feedback: { sessionId, clientRequestId, cwd, boundaryId, ...(originCwd ? { originCwd } : {}) } } : {}) };
+                    ...(sessionId && clientRequestId ? { feedback: { sessionId, clientRequestId, cwd, boundaryId, readOnly, refsBlocked,
+                            ...(originCwd ? { originCwd } : {}) } } : {}) };
             },
             model: credential.model,
             modelConfigId: credential.configId,
@@ -92,6 +116,8 @@ export class WorkspaceModelBroker {
                 ...(sessionId ? { 'shell_environment_policy.set': {
                         PLAYCRAFT_AGENT_GENERATION_ENDPOINT: `${this.baseUrl}/${routeKey}/generation-provenance`,
                         PLAYCRAFT_AGENT_GENERATION_CAPABILITY: route.generationCapability,
+                        PLAYCRAFT_REMIX_REFERENCES_ENDPOINT: `${this.baseUrl}/${routeKey}/remix-references`,
+                        PLAYCRAFT_REMIX_REFERENCES_CAPABILITY: route.referencesCapability,
                     } } : {}),
                 'model_providers.playcraft_workspace': {
                     name: 'PlayCraft Workspace', base_url: `${this.baseUrl}/${routeKey}`,
@@ -154,13 +180,15 @@ export class WorkspaceModelBroker {
         const cancel = () => abort.abort();
         response.once('close', cancel);
         try {
-            const match = /^\/([0-9a-f-]{36}(?:\/[0-9a-f]{32})?)\/(responses|generation-provenance)$/.exec(request.url ?? '');
+            const match = /^\/([0-9a-f-]{36}(?:\/[0-9a-f]{32})?)\/(responses|generation-provenance|remix-references)$/.exec(request.url ?? '');
             const route = match ? this.routes.get(match[1]) : undefined;
             const selected = route?.selected;
             const entry = selected?.entry;
             const presented = Buffer.from(request.headers.authorization ?? '');
             const generationRequest = match?.[2] === 'generation-provenance';
-            const expected = Buffer.from(route ? `Bearer ${generationRequest ? route.generationCapability : route.capability}` : '');
+            const referencesRequest = match?.[2] === 'remix-references';
+            const expected = Buffer.from(route ? `Bearer ${generationRequest ? route.generationCapability
+                : referencesRequest ? route.referencesCapability : route.capability}` : '');
             if (request.method !== 'POST' || !entry || !expected.length || presented.length !== expected.length
                 || !timingSafeEqual(presented, expected) || !this.valid(entry)) {
                 response.writeHead(403);
@@ -176,6 +204,15 @@ export class WorkspaceModelBroker {
                 await this.generation.forward(request, response, selected.feedback, () => this.valid(entry) && route?.selected === selected);
                 return;
             }
+            if (referencesRequest) {
+                if (!selected?.feedback) {
+                    response.writeHead(403);
+                    response.end();
+                    return;
+                }
+                await this.references.forward(request, response, selected.feedback, () => this.valid(entry) && route?.selected === selected);
+                return;
+            }
             activeRoute = route;
             const active = this.sessionRequests.get(route) ?? new Set();
             active.add(abort);