@playcraft/cli 0.1.69 → 0.1.71

package/dist/workspace-runtime/server/dispatch.js

@@ -9,7 +9,7 @@ import { remoteAttachPending } from '../workspaces/remote-attach-marker.js';
 import { cancelPendingDirectoryAccess, holdDirectoryAccess, withOperationDirectoryAccess, } from './directory-access.js';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { fileWritePayloadSchema, fileBinaryWritePayloadSchema, directoryCreatePayloadSchema, directoryRenamePayloadSchema, directoryDeletePayloadSchema, directoryMutationReceiptSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, gitPullPayloadSchema, gitMergeAbortPayloadSchema, hashOperationPayload, parameterPatchPayloadSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, levelEditorTaskRequestSchema, levelEditorVerifyPayloadSchema, levelEditorTransactionRequestSchema, productionSessionAttemptId, reasoningEffortSchema, workspacePermissionModeSchema, workspaceComposerSelectionSchema, workspaceReviewPayloadSchema, workspaceCompactPayloadSchema, workspaceSteerPayloadSchema, workspaceApprovalResponseSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, recoverUncertainOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, workspaceRemixReferenceImportPayloadSchema, workspaceModelPreviewBuildSchema, workspaceModelPreviewCancelSchema, isSoundDocumentPath, } from '@playcraft/common/cloud-workspace/runtime';
+import { fileWritePayloadSchema, fileBinaryWritePayloadSchema, directoryCreatePayloadSchema, directoryRenamePayloadSchema, directoryDeletePayloadSchema, directoryMutationReceiptSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, gitPullPayloadSchema, gitMergeAbortPayloadSchema, hashOperationPayload, parameterPatchPayloadSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, levelEditorTaskRequestSchema, skillActivationPayloadSchema, levelEditorVerifyPayloadSchema, levelEditorTransactionRequestSchema, productionSessionAttemptId, reasoningEffortSchema, workspacePermissionModeSchema, workspaceComposerSelectionSchema, workspaceReviewPayloadSchema, workspaceCompactPayloadSchema, workspaceSteerPayloadSchema, workspaceApprovalResponseSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, recoverUncertainOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, workspaceRemixReferenceImportPayloadSchema, workspaceModelPreviewBuildSchema, workspaceModelPreviewCancelSchema, isSoundDocumentPath, } from '@playcraft/common/cloud-workspace/runtime';
 import { closeCliCredentials, ensureCliCredentials } from '../workspaces/cli-credentials.js';
 import { artifactFormat } from '../workspaces/artifact-files.js';
 import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
@@ -52,6 +52,7 @@ import { prepareLevelEditorTask, finishLevelEditorTask, verifyLevelEditorTask, }
 import { readWorkspaceLevelEditor, transactWorkspaceLevelEditor, reconcileWorkspaceLevelEditorTransaction, } from '../workspaces/level-editor.js';
 import { readLevelEditorHistory } from '../workspaces/level-editor-history-store.js';
 import { wakeLevelEditorRequests, ensureLevelEditorTaskPipeline, retryLevelEditorRequest, assertLevelEditorRetryInput, } from '../workspaces/level-editor-requests.js';
+import { activateSkillSelectionForTurn, cancelSkillActivationPreparation, skillActivationRuntimeClosing, waitForSkillActivationIdle } from '../workspaces/skill-activation-requests.js';
 const CONVERSATION_KINDS = new Set([
     'session.create',
     'session.turn',
@@ -94,6 +95,7 @@ const LOCAL_KINDS = new Set([
 ]);
 const parameterVerifications = new WeakMap();
 const parameterVerificationClosing = new WeakSet();
+const nativePreparations = new WeakMap();
 export async function stopParameterVerifications(state) {
     parameterVerificationClosing.add(state);
     const tasks = parameterVerifications.get(state);
@@ -146,9 +148,30 @@ export async function executeOperation(state, scopeKey, operation, payload, reco
     if (['runtime.destroy', 'session.interrupt', 'session.approval.respond', 'session.steer', 'preview.publish', 'model.preview', 'model.preview.cancel', 'model.prepare'].includes(operation.kind)) {
         return run();
     }
-    return state.journal.exclusive(operation.kind.startsWith('session.') && operation.sessionId
+    const execute = () => state.journal.exclusive(operation.kind.startsWith('session.') && operation.sessionId
         ? `session-execution:${operation.sessionId}`
         : `workspace:${revisionScope(state, operation.workspaceId, operation.directoryName) ?? 'single'}`, run);
+    if (!['session.turn', 'session.review', 'session.compact'].includes(operation.kind))
+        return execute();
+    const pending = nativePreparations.get(state) ?? new Map();
+    nativePreparations.set(state, pending);
+    const entry = { scopeKey, operation, held: false, activation: operation.kind === 'session.turn'
+            && skillActivationPayloadSchema.safeParse(asRecord(payload).skillActivation).success };
+    pending.set(operation.operationId, entry);
+    try {
+        return await state.journal.exclusive('native-preparation', async () => {
+            entry.held = true;
+            const live = state.journal.getOperation(scopeKey) ?? operation;
+            if (['completed', 'failed', 'interrupted'].includes(live.status))
+                return live;
+            if (skillActivationRuntimeClosing(state))
+                return persist(state, scopeKey, transitionOperation(live, 'interrupted', { error: 'runtime_stopping' }));
+            return execute();
+        });
+    }
+    finally {
+        pending.delete(operation.operationId);
+    }
 }
 async function executeScopedOperation(state, scopeKey, operation, payload, recovery) {
     let current = await persist(state, scopeKey, transitionOperation(operation, 'dispatched'));
@@ -440,16 +463,39 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
     const levelEditorTask = levelEditorTaskRequestSchema.optional().safeParse(body.levelEditorTask);
     if (!levelEditorTask.success || levelEditorTask.data && (parameterTask.data || levelEditorTask.data.taskId !== operation.clientRequestId))
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'invalid_level_editor_task' }));
-    if (parameterTask.data || levelEditorTask.data) {
+    const skillActivation = skillActivationPayloadSchema.optional().safeParse(body.skillActivation);
+    if (!skillActivation.success || skillActivation.data && (parameterTask.data || levelEditorTask.data
+        || skillActivation.data.requestId !== operation.clientRequestId || skillActivation.data.sourceSessionId !== sessionId))
+        return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'skill_activation_request_invalid' }));
+    if (parameterTask.data || levelEditorTask.data || skillActivation.data) {
         if (operation.directoryName === 'root')
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'invalid_workspace_directory' }));
         if ((selection.data.workMode ?? 'execute') !== 'execute' || requestedMode === 'read-only')
-            return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: levelEditorTask.data ? 'level_editor_task_requires_execute' : 'parameter_task_readonly' }));
+            return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: skillActivation.data ? 'skill_activation_requires_execute' : levelEditorTask.data ? 'level_editor_task_requires_execute' : 'parameter_task_readonly' }));
         if (workspaceSessions(state, operation.workspaceId, operation.directoryName).some(sessionTurnBusy))
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'turn_already_active' }));
         if (await batchDirectoryHeld(state, operation.workspaceId, operation.directoryName))
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'batch_workspace_readonly' }));
     }
+    let activatedSkillSelection;
+    if (skillActivation.data) {
+        try {
+            if (!found || operation.directoryAccessMode !== 'exclusive' || selection.data.context?.skills.length)
+                throw new Error('skill_activation_request_invalid');
+            // Repair an interrupted activation pair before session recovery can read or freeze that pair.
+            await waitForSkillActivationIdle(state, operation, skillActivation.data);
+            activatedSkillSelection = await activateSkillSelectionForTurn(state, operation, skillActivation.data, await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName));
+        }
+        catch (error) {
+            const live = state.journal.getOperation(scopeKey);
+            if (live && ['failed', 'interrupted'].includes(live.status))
+                return live;
+            return persist(state, scopeKey, transitionOperation(operation, 'failed', {
+                error: error instanceof Error && /^(?:skill_activation_|skills_revision_conflict|workspace_skills_)/.test(error.message)
+                    ? error.message : 'skill_activation_failed',
+            }));
+        }
+    }
     const modelChanged = selected.data !== undefined && selected.data !== (found?.modelConfigId ?? recovery?.modelConfigId);
     const requestedEffort = effort.data ?? (modelChanged ? undefined : recovery?.reasoningEffort ?? found?.reasoningEffort);
     if (recovery && found?.recoverability !== 'native') {
@@ -476,11 +522,11 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
     }
     const root = await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName);
     try {
-        const policy = await preflightSkillExecution(state, { ...operation, payload });
+        const policy = skillActivation.data ? undefined : await preflightSkillExecution(state, { ...operation, payload });
         if (policy?.directoryAccessMode === 'exclusive' && operation.directoryAccessMode !== 'exclusive')
             throw new ComposerContextError('requires-exclusive-turn');
-        if (operation.skillExecutionPolicyVersion === 1 && (!policy ||
-            (parameterTask.data || levelEditorTask.data ? 'exclusive' : policy.directoryAccessMode) !== operation.directoryAccessMode))
+        if (!skillActivation.data && operation.skillExecutionPolicyVersion === 1 && (!policy ||
+            (parameterTask.data || levelEditorTask.data || skillActivation.data ? 'exclusive' : policy.directoryAccessMode) !== operation.directoryAccessMode))
             throw new ComposerContextError('context_skills_changed');
     }
     catch (error) {
@@ -490,9 +536,14 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
         }));
     }
     let composer;
+    let skillActivationInstructions = '';
     let initializationSkill;
     try {
         let turnContext = selection.data.context;
+        if (activatedSkillSelection) {
+            turnContext = { files: turnContext?.files ?? [], skills: activatedSkillSelection.entries };
+            skillActivationInstructions = activatedSkillSelection.instructions;
+        }
         if (parameterTask.data?.action === 'initialize' || levelEditorTask.data) {
             const selectedSkill = await ensureParameterInitializationSkill(root, levelEditorTask.data ? 'playcraft-level-editor' : 'playcraft-runtime-parameters', levelEditorTask.data ? { preserveExisting: true } : {});
             initializationSkill = { ...selectedSkill,
@@ -512,11 +563,16 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
         });
     }
     catch (error) {
+        const live = state.journal.getOperation(scopeKey);
+        if (skillActivation.data && live && ['failed', 'interrupted'].includes(live.status))
+            return live;
         return persist(state, scopeKey, transitionOperation(operation, 'failed', {
-            error: error instanceof ComposerContextError ? error.message : parameterTask.data?.action === 'initialize' || levelEditorTask.data
-                ? error instanceof Error && /^(?:workspace_skills_|skills_revision_conflict$)/.test(error.message)
-                    ? error.message : levelEditorTask.data ? 'level_editor_skill_unavailable' : parameterAgentError(error)
-                : 'invalid_composer_context',
+            error: skillActivation.data ? error instanceof Error && /^(?:skill_activation_|skills_revision_conflict|workspace_skills_)/.test(error.message)
+                ? error.message : 'skill_activation_failed'
+                : error instanceof ComposerContextError ? error.message : parameterTask.data?.action === 'initialize' || levelEditorTask.data
+                    ? error instanceof Error && /^(?:workspace_skills_|skills_revision_conflict$)/.test(error.message)
+                        ? error.message : levelEditorTask.data ? 'level_editor_skill_unavailable' : parameterAgentError(error)
+                    : 'invalid_composer_context',
         }));
     }
     let attachments;
@@ -567,6 +623,9 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
         }
     }
     // Taken before the native turn exists, so nothing the agent writes can precede it.
+    const beforeStart = state.journal.getOperation(scopeKey);
+    if (skillActivation.data && beforeStart && ['failed', 'interrupted'].includes(beforeStart.status))
+        return beforeStart;
     await beginTurnChanges(state, sessionId, {
         root, workspaceId: operation.workspaceId, directoryName: binding.directoryName ?? 'basic',
     });
@@ -575,7 +634,7 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
         const startTurn = () => native(state).startTurn({
             sessionId,
             threadId: binding.threadId,
-            text: composer.append(batchContext + context + String(body.text ?? '') + attachmentText, [engineeringBatchContext, parameterInstructions].filter(Boolean).join('\n\n')),
+            text: composer.append(batchContext + context + String(body.text ?? '') + attachmentText, [engineeringBatchContext, parameterInstructions, skillActivationInstructions].filter(Boolean).join('\n\n')),
             images: attachments.filter((file) => ['image/png', 'image/jpeg', 'image/gif', 'image/webp'].includes(file.mimeType)).map((file) => file.path),
             clientRequestId: operation.clientRequestId,
             modelConfigId: selected.data ?? binding.modelConfigId,
@@ -587,22 +646,30 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
             scheduledTaskProposalBridge: typeof body.scheduledTaskProposalBridge === 'string' ? body.scheduledTaskProposalBridge : undefined,
             simulateLostReceipt: body.simulateLostReceipt === true,
             persistReservation: async ({ nativeRequestId, modelConfigId, reasoningEffort, permissionMode }) => {
-                const selectedEffort = reasoningEffort ?? requestedEffort;
-                const selectedMode = permissionMode ?? requestedMode;
-                await persist(state, scopeKey, {
-                    ...operation,
-                    nativeRequestId,
-                    nativeThreadId: binding.threadId,
-                    modelConfigId,
-                    reasoningEffort: selectedEffort,
-                    permissionMode: selectedMode,
-                    workMode: selection.data.workMode ?? 'execute',
-                    context: composer.context,
-                    userText: selection.data.workMode !== undefined || composer.context !== undefined || parameterTask.data || levelEditorTask.data
-                        ? String(body.userText ?? body.text ?? '') : undefined,
-                    updatedAt: new Date().toISOString(),
+                await state.journal.exclusive(`native-reservation:${operation.operationId}`, async () => {
+                    const live = state.journal.getOperation(scopeKey) ?? operation;
+                    if (live.status !== 'dispatched' || skillActivationRuntimeClosing(state) || state.journal.destroyed())
+                        throw new NativePreparationError(skillActivation.data ? 'skill_activation_cancelled' : 'native_preparation_cancelled');
+                    if ((live.leaseFence ?? 0) < state.acceptedLeaseFence || live.generation !== state.config.generation || live.runtimeEpoch !== state.runtimeEpoch)
+                        throw new NativePreparationError('stale_lease');
+                    const selectedEffort = reasoningEffort ?? requestedEffort;
+                    const selectedMode = permissionMode ?? requestedMode;
+                    await persist(state, scopeKey, {
+                        ...live,
+                        nativeRequestId,
+                        nativeThreadId: binding.threadId,
+                        modelConfigId,
+                        reasoningEffort: selectedEffort,
+                        permissionMode: selectedMode,
+                        workMode: selection.data.workMode ?? 'execute',
+                        context: composer.context,
+                        ...(activatedSkillSelection ? { skillExecutionPolicyVersion: 1 } : {}),
+                        userText: selection.data.workMode !== undefined || composer.context !== undefined || parameterTask.data || levelEditorTask.data
+                            ? String(body.userText ?? body.text ?? '') : undefined,
+                        updatedAt: new Date().toISOString(),
+                    });
+                    await state.journal.putSession({ ...binding, modelConfigId, reasoningEffort: selectedEffort, permissionMode: selectedMode, turnStatus: 'starting' });
                 });
-                await state.journal.putSession({ ...binding, modelConfigId, reasoningEffort: selectedEffort, permissionMode: selectedMode, turnStatus: 'starting' });
             },
         });
         result = await startTurn();
@@ -619,9 +686,12 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
         }
     }
     catch (error) {
-        if (!parameterTask.data && !levelEditorTask.data)
+        if (!parameterTask.data && !levelEditorTask.data && !skillActivation.data)
             throw error;
         abandonTurnChanges(state, sessionId);
+        const live = state.journal.getOperation(scopeKey);
+        if (live && ['completed', 'failed', 'interrupted'].includes(live.status))
+            return live;
         if (error instanceof NativePreparationError) {
             await state.journal.putSession({ ...(state.journal.getSession(sessionId) ?? binding), turnStatus: undefined, turnBlock: undefined });
             return persist(state, scopeKey, transitionOperation(state.journal.getOperation(scopeKey) ?? operation, 'failed', { error: error.message }));
@@ -630,6 +700,10 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
         return persist(state, scopeKey, transitionOperation(state.journal.getOperation(scopeKey) ?? operation, 'uncertain', { error: 'native_receipt_lost' }));
     }
     const reserved = state.journal.getOperation(scopeKey) ?? operation;
+    if (['completed', 'failed', 'interrupted'].includes(reserved.status)) {
+        abandonTurnChanges(state, sessionId);
+        return reserved;
+    }
     if (result.outcome === 'uncertain' || result.outcome === 'failed' || !result.turnId) {
         abandonTurnChanges(state, sessionId);
         const failed = result.outcome === 'failed';
@@ -952,6 +1026,25 @@ async function executeInterrupt(state, scopeKey, operation, payload) {
     // A directory-gated turn has no native turn to interrupt. Cancel only a proven pending
     // claim; an admitted/racing claim still goes through the native interruption contract.
     if (expectedTurnId === undefined && !binding.activeTurnId) {
+        const preparations = [...(nativePreparations.get(state)?.values() ?? [])].filter(item => item.operation.sessionId === sessionId && item.operation.workspaceId === operation.workspaceId
+            && (item.operation.directoryName ?? 'basic') === (operation.directoryName ?? 'basic')
+            && (!item.held || item.activation)
+            && (cancelTarget === undefined || cancelTarget === item.operation.operationId || cancelTarget === item.operation.gatewayOperationId)
+            && !state.journal.getOperationById(item.operation.operationId)?.nativeRequestId);
+        if (preparations.length === 1) {
+            const preparation = preparations[0];
+            const cancelled = await state.journal.exclusive(`native-reservation:${preparation.operation.operationId}`, async () => {
+                const live = state.journal.getOperationById(preparation.operation.operationId) ?? preparation.operation;
+                if (!['queued', 'dispatched'].includes(live.status) || live.nativeTurnId || live.nativeRequestId)
+                    return false;
+                await persist(state, preparation.scopeKey, transitionOperation(live, 'interrupted', { error: 'cancelled' }));
+                cancelSkillActivationPreparation(state, live.operationId);
+                return true;
+            });
+            if (cancelled) {
+                return persist(state, scopeKey, transitionOperation(transitionOperation(operation, 'accepted'), 'completed'));
+            }
+        }
         const candidates = state.journal.deferredDirectoryOperations().flatMap(pending => {
             const queued = state.journal.getOperationById(pending.operationId);
             return queued?.status === 'queued' && ['session.turn', 'session.review', 'session.compact'].includes(queued.kind)

package/dist/workspace-runtime/server/http.js

@@ -15,6 +15,7 @@ import { listParameterAgentTasks } from '../workspaces/parameter-agent.js';
 import { readWorkspaceLevelEditor } from '../workspaces/level-editor.js';
 import { listLevelEditorTasks } from '../workspaces/level-editor-agent.js';
 import { listLevelEditorRequests } from '../workspaces/level-editor-requests.js';
+import { listSkillActivationRequests } from '../workspaces/skill-activation-requests.js';
 import { readDependencies } from '../workspaces/dependencies.js';
 import { permissionDriftFromError } from '../workspaces/workspace-shares.js';
 import { desktopHost, desktopRoute } from './desktop-host.js';
@@ -191,6 +192,7 @@ async function dispatchRuntimeRequest(state, request, response) {
                 parameterAgentVersion: 1,
                 directoryConcurrencyVersion: 1,
                 skillExecutionPolicyVersion: 1,
+                skillActivationVersion: 1,
                 parameterInitializationVersion: 1,
                 levelEditorVersion: 1,
                 levelEditorTaskVersion: 1,
@@ -201,6 +203,7 @@ async function dispatchRuntimeRequest(state, request, response) {
                 remixReferencesVersion: 1,
                 batchSourceFreezeRevision: 2,
                 batchSourcePublicationVersion: 1,
+                batchReferenceContextVersion: 1,
                 ...(state.native?.workspaceUi ? { workspaceUiVersion: 1 } : {}),
                 ...(state.native?.startReview && state.native?.steer ? { turnControlVersion: 1 } : {}),
                 ...(state.native?.startCompact ? { compactionVersion: 1 } : {}),
@@ -880,6 +883,18 @@ async function dispatchRuntimeRequest(state, request, response) {
             writeJson(response, 200, { tasks: await listLevelEditorTasks(state, workspaceId, directoryName, await workspaceRoot(state, workspaceId, directoryName)) });
             return;
         }
+        if (request.method === 'GET' && url.pathname === '/runtime/skill-activation-requests') {
+            if (writeDestroyed(state, response))
+                return;
+            if (directoryName === 'root') {
+                writeJson(response, 400, { error: 'invalid_workspace_directory' });
+                return;
+            }
+            const workspaceId = url.searchParams.get('workspaceId') ?? undefined;
+            await workspaceRoot(state, workspaceId, directoryName);
+            writeJson(response, 200, { requests: await listSkillActivationRequests(state, workspaceId, directoryName) });
+            return;
+        }
         if (request.method === 'GET' && url.pathname === '/runtime/level-editor/requests') {
             if (writeDestroyed(state, response))
                 return;

package/dist/workspace-runtime/server/operation-record.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { workspaceComposerSelectionSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { skillActivationPayloadSchema, workspaceComposerSelectionSchema } from '@playcraft/common/cloud-workspace/runtime';
 /** One construction point for operation records so HTTP and in-sandbox callers cannot drift. */
 export function buildOperationRecord(state, parsed, payloadHash, leaseFence, executable = true, policy) {
     const now = new Date().toISOString();
@@ -12,6 +12,8 @@ export function buildOperationRecord(state, parsed, payloadHash, leaseFence, exe
         ...(policy ? { skillExecutionPolicyVersion: policy.skillExecutionPolicyVersion, directoryAccessMode: policy.directoryAccessMode,
             ...workspaceComposerSelectionSchema.parse({ context: payload.context, workMode: payload.workMode }) } : {}),
         ...(parsed.kind === 'session.turn' && (payload.parameterTask !== undefined || payload.levelEditorTask !== undefined) ? { directoryAccessMode: 'exclusive' } : {}),
+        ...(parsed.kind === 'session.turn' && skillActivationPayloadSchema.safeParse(payload.skillActivation).success
+            ? { directoryAccessMode: 'exclusive', skillExecutionPolicyVersion: 1 } : {}),
         environment: state.config.environment,
         userId: state.config.userId,
         clientRequestId: parsed.clientRequestId,

package/dist/workspace-runtime/verify-artifact.js

@@ -48,6 +48,7 @@ export async function verifyRuntimeArtifact(expectedVersion) {
         assert.equal(identity.runtimeId, config.runtimeId);
         assert.equal(identity.batchSourceFreezeRevision, 2, 'built runtime lacks the required batch source freeze implementation');
         assert.equal(identity.batchSourcePublicationVersion, 1, 'built runtime lacks trusted batch source publication');
+        assert.equal(identity.batchReferenceContextVersion, 1, 'built runtime lacks batch reference context support');
     }
     finally {
         await runtime?.close();
@@ -56,5 +57,5 @@ export async function verifyRuntimeArtifact(expectedVersion) {
 }
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
     await verifyRuntimeArtifact(process.argv[2] ?? '');
-    console.log('Runtime artifact verified: batchSourceFreezeRevision=2, batchSourcePublicationVersion=1');
+    console.log('Runtime artifact verified: batchSourceFreezeRevision=2, batchSourcePublicationVersion=1, batchReferenceContextVersion=1');
 }

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

@@ -22,7 +22,7 @@ export async function resolveWorkspaceFile(root, relativePath) {
     const parsed = workspaceRelativePathSchema.safeParse(relativePath);
     if (!parsed.success)
         throw new InvalidWorkspacePathError(relativePath);
-    const rootReal = await ensureWorkspaceRoot(root);
+    const rootReal = await realpath(root);
     const target = resolve(rootReal, ...parsed.data.split('/'));
     assertInsideRoot(rootReal, target);
     try {
@@ -126,19 +126,25 @@ function isPermissionDenied(error) {
     return ['EACCES', 'EPERM'].includes(String(error?.code));
 }
 async function assertParentInsideRoot(rootReal, parent) {
-    if (parent === rootReal)
-        return;
-    try {
-        const parentReal = await realpath(parent);
-        assertInsideRoot(rootReal, parentReal);
-    }
-    catch (error) {
-        if (error.code !== 'ENOENT')
-            throw error;
-        // private
-        await mkdir(parent, { recursive: true, mode: 0o700 });
-        const parentReal = await realpath(parent);
-        assertInsideRoot(rootReal, parentReal);
+    while (parent !== rootReal) {
+        try {
+            const parentReal = await realpath(parent);
+            assertInsideRoot(rootReal, parentReal);
+            return;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            const entry = await lstat(parent).catch((error) => {
+                if (error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            });
+            if (entry?.isSymbolicLink())
+                throw new InvalidWorkspacePathError(parent);
+            // Resolve the nearest existing ancestor without creating anything during a read.
+            parent = dirname(parent);
+        }
     }
 }
 function assertInsideRoot(rootReal, target) {

package/dist/workspace-runtime/workspaces/remix-references.js

@@ -115,12 +115,18 @@ function validateRecord(record, directoryName) {
         originalFiles.reduce((sum, file) => sum + file.size, 0) > WORKSPACE_REMIX_REFERENCE_MAX_BYTES)
         throw new RemixReferenceError('remix_reference_manifest_invalid');
 }
-async function verifyReference(root, record, directoryName) {
+async function verifyReferenceMetadata(root, record, directoryName, alternateDirectory) {
     validateRecord(record, directoryName);
     const target = await safeDirectory(root, record.path);
     const receipt = JSON.parse((await readFileSafely(target, RECEIPT, MANIFEST_MAX_BYTES)).toString('utf8'));
-    if (JSON.stringify(workspaceRemixReferenceSchema.parse(receipt)) !== JSON.stringify(record))
+    const parsedReceipt = workspaceRemixReferenceSchema.parse(receipt);
+    if (JSON.stringify(parsedReceipt) !== JSON.stringify(record)
+        && (!alternateDirectory || JSON.stringify(parsedReceipt) !== JSON.stringify({ ...record, directoryName: alternateDirectory })))
         throw new RemixReferenceError('remix_reference_changed');
+    return target;
+}
+async function verifyReference(root, record, directoryName, alternateDirectory) {
+    const target = await verifyReferenceMetadata(root, record, directoryName, alternateDirectory);
     if ((await readFileSafely(target, ATTRIBUTES, 256)).toString('utf8') !== SNAPSHOT_ATTRIBUTES)
         throw new RemixReferenceError('remix_reference_changed');
     const expected = new Set([RECEIPT, ATTRIBUTES, ...record.files.map(file => file.path)]);
@@ -144,6 +150,117 @@ async function verifyReference(root, record, directoryName) {
             throw new RemixReferenceError('remix_reference_changed');
     }
 }
+/** Metadata-verified records identify files excluded by the batch source safety policy. */
+export async function batchReferenceMetadata(root) {
+    let items;
+    try {
+        items = await readManifest(root);
+    }
+    catch {
+        return [];
+    }
+    const verified = [];
+    for (const record of items) {
+        try {
+            await verifyReferenceMetadata(root, record, record.directoryName);
+            verified.push(record);
+        }
+        catch { /* An unrelated invalid reference cannot block source capture. */ }
+    }
+    return verified;
+}
+/** Only verified imported snapshots can retain credential-free .env examples in a batch freeze. */
+export async function batchReferenceEnvExamples(root) {
+    const examples = new Set();
+    let items;
+    try {
+        items = await readManifest(root);
+    }
+    catch {
+        return examples;
+    }
+    for (const record of items) {
+        const files = record.files.filter(file => /^\.env\.(?:example|sample|template)$/i.test(file.path.split('/').pop() ?? '')
+            && !isCredentialFile(file.sourcePath));
+        if (!files.length)
+            continue;
+        try {
+            await verifyReference(root, record, record.directoryName);
+            for (const file of files)
+                examples.add(`${record.path}/${file.path}`);
+        }
+        catch { /* An unselected damaged reference must not stop freezing the project. */ }
+    }
+    return examples;
+}
+/** Rebind frozen source references inside a member checkout; content and source identities remain immutable. */
+export async function rebindBatchRemixReferences(root, sourceDirectory, memberDirectory, selected) {
+    workspaceDirectoryNameSchema.parse(sourceDirectory);
+    workspaceDirectoryNameSchema.parse(memberDirectory);
+    const rootReal = await realpath(root);
+    let items;
+    try {
+        items = await readManifest(rootReal);
+    }
+    catch (error) {
+        if (!selected.length)
+            return;
+        throw error;
+    }
+    for (const reference of selected) {
+        const record = items.find(item => item.referenceId === reference.referenceId);
+        if (reference.directoryName !== sourceDirectory || !record || record.contentHash !== reference.snapshotHash)
+            throw new RemixReferenceError('context_remix_reference_changed');
+    }
+    if (selected.length) {
+        const manifest = JSON.parse((await readFileSafely(rootReal, WORKSPACE_REMIX_REFERENCES_MANIFEST, MANIFEST_MAX_BYTES)).toString('utf8'));
+        if (Array.isArray(manifest.batchPolicyWithheldReferenceIds) && selected.some(reference => manifest.batchPolicyWithheldReferenceIds.includes(reference.referenceId)))
+            throw new RemixReferenceError('batch_reference_files_withheld');
+    }
+    // Selected references must be complete. Other records need only valid metadata to be rebound;
+    // their contents remain subject to the normal checks when the user later lists or selects them.
+    const rebound = [];
+    const writable = [];
+    for (const record of items) {
+        const isSelected = selected.some(reference => reference.referenceId === record.referenceId);
+        try {
+            if (record.directoryName !== sourceDirectory && record.directoryName !== memberDirectory)
+                throw new RemixReferenceError('remix_reference_manifest_invalid');
+            const alternate = record.directoryName === sourceDirectory ? memberDirectory : sourceDirectory;
+            if (isSelected)
+                await verifyReference(rootReal, record, record.directoryName, alternate);
+            else
+                await verifyReferenceMetadata(rootReal, record, record.directoryName, alternate);
+            const next = { ...record, directoryName: memberDirectory };
+            rebound.push(next);
+            writable.push(next);
+        }
+        catch (error) {
+            if (isSelected)
+                throw error;
+            rebound.push(record);
+        }
+    }
+    if (!items.length)
+        return;
+    const metadata = await safeDirectory(rootReal, '.playcraft');
+    const atomicWrite = async (destination, body) => {
+        const temporary = join(metadata, `.batch-reference-${randomUUID()}.tmp`);
+        try {
+            // shared
+            await writeFile(temporary, body, { flag: 'wx', mode: 0o644 });
+            await rename(temporary, destination);
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    };
+    for (const record of writable) {
+        const target = await safeDirectory(rootReal, record.path);
+        await atomicWrite(join(target, RECEIPT), JSON.stringify(record));
+    }
+    await atomicWrite(join(metadata, 'remix-references.json'), JSON.stringify({ version: 1, items: rebound }));
+}
 /** Reads revalidate the snapshot, so changed/deleted files cannot silently remain attached to a turn. */
 export async function listWorkspaceRemixReferences(root, directoryName = 'basic') {
     workspaceDirectoryNameSchema.parse(directoryName);

package/dist/workspace-runtime/workspaces/skill-activation-recovery.js

@@ -0,0 +1,54 @@
+import { join } from 'node:path';
+import { lstat } from 'node:fs/promises';
+import { skillActivationBindingHash, transitionOperation } from '@playcraft/common/cloud-workspace/runtime';
+import { recoverPreparedSkillActivationTransactions } from '../../project-skills/remote-activation.js';
+import { workspaceRoot } from './registry.js';
+import { listSkillActivationRequests, reconcileSkillActivationRequestReceipts } from './skill-activation-requests.js';
+/** Runs before native startup: restore owned pairs and settle only provably unsent continuations. */
+export async function recoverInterruptedSkillActivations(state) {
+    if (state.config.workspaceMode !== 'multi' || !await lstat(join(state.config.stateDir, 'skill-activation-requests'))
+        .catch((error) => { if (error.code === 'ENOENT')
+        return undefined; throw error; }))
+        return;
+    const transactionDirectory = join(state.config.stateDir, 'skill-activation-requests/transactions');
+    const requests = await listSkillActivationRequests(state);
+    const unsentContinuations = (request) => {
+        const source = state.journal.getOperationById(request.sourceOperationId);
+        if (!source || source.kind !== 'session.turn' || source.sessionId !== request.sourceSessionId
+            || source.environment !== state.config.environment || source.userId !== state.config.userId
+            || source.workspaceId !== request.workspaceId || (source.directoryName ?? 'basic') !== request.directoryName
+            || source.generation !== request.generation || source.runtimeEpoch !== request.runtimeEpoch
+            || source.nativeThreadId !== request.sourceThreadId || source.nativeTurnId !== request.sourceTurnId)
+            return [];
+        return state.journal.listOperations().filter(({ operation }) => operation.kind === 'session.turn' && operation.clientRequestId === request.requestId
+            && operation.environment === state.config.environment && operation.userId === state.config.userId
+            && operation.sessionId === request.sourceSessionId && operation.workspaceId === request.workspaceId
+            && (operation.directoryName ?? 'basic') === request.directoryName && operation.generation === request.generation
+            && operation.runtimeEpoch === request.runtimeEpoch && operation.status === 'dispatched'
+            && !operation.nativeRequestId && !operation.nativeTurnId);
+    };
+    for (const workspaceId of new Set(requests.map(request => request.workspaceId))) {
+        const binding = state.journal.getWorkspace(workspaceId);
+        if (binding) {
+            for (const directoryName of new Set(['basic', ...(binding.directories ?? []).map(directory => directory.directoryName)])) {
+                const root = await workspaceRoot(state, binding.workspaceId, directoryName).catch(error => {
+                    if (error instanceof Error && error.message === 'workspace_not_prepared')
+                        return undefined;
+                    throw error;
+                });
+                if (root)
+                    await recoverPreparedSkillActivationTransactions(root, { transactionDirectory,
+                        orphanTransactionIds: requests.filter(request => request.workspaceId === workspaceId && request.directoryName === directoryName
+                            && request.registrationHash === skillActivationBindingHash(binding, directoryName) && unsentContinuations(request).length > 0)
+                            .map(request => request.requestId) });
+            }
+        }
+    }
+    for (const request of requests) {
+        for (const { scopeKey, operation } of unsentContinuations(request)) {
+            // Reservation is persisted before native send. Without it this interrupted preparation never sent a turn.
+            await state.journal.putOperation(scopeKey, transitionOperation(operation, 'failed', { error: 'skill_activation_interrupted' }));
+        }
+    }
+    await reconcileSkillActivationRequestReceipts(state);
+}