@playcraft/cli 0.1.57-beta → 0.1.58-beta

package/dist/workspace-runtime/server/directory-access.js

@@ -0,0 +1,414 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { isTurnControl, takesWorkspaceDirectory, takesExecutionSlot, transitionOperation } from '@playcraft/common/cloud-workspace/runtime';
+import { listMembers, readSnapshot } from '../batch/records.js';
+const context = new AsyncLocalStorage();
+const gates = new WeakMap();
+const instances = new WeakMap();
+const executing = new WeakMap();
+const freezing = new WeakMap();
+const TERMINAL = new Set(['completed', 'failed', 'interrupted']);
+const EXCLUSIVE_OPERATIONS = new Set(['preview.publish', 'delivery.build', 'workspace.save', 'directory.create',
+    'directory.rename', 'directory.delete', 'workspace.references.import', 'skills.update', 'parameter.verify',
+    'checkpoint.create', 'checkpoint.restore']);
+export function managedDirectoryScope(state, value) {
+    if (state.config.workspaceMode !== 'multi')
+        return { directoryName: 'basic' };
+    const [workspaceId, directoryName = 'basic'] = value.split(':');
+    return { workspaceId, directoryName };
+}
+function overlaps(a, b) {
+    return (a.workspaceId ?? '') === (b.workspaceId ?? '') &&
+        ((a.directoryName ?? 'basic') === (b.directoryName ?? 'basic') || a.directoryName === 'root' || b.directoryName === 'root');
+}
+function covers(parent, child) {
+    return (parent.workspaceId ?? '') === (child.workspaceId ?? '') &&
+        (parent.directoryName === 'root' || (parent.directoryName ?? 'basic') === (child.directoryName ?? 'basic'));
+}
+export function operationDirectoryMode(operation) {
+    return operation.directoryAccessMode ?? (EXCLUSIVE_OPERATIONS.has(operation.kind) || operation.kind.startsWith('git.') ? 'exclusive' : 'shared');
+}
+function activeSessionOwner(state, gate, scope, sessionId, except) {
+    if (!sessionId)
+        return undefined;
+    const operation = state.journal.listOperations().map(item => item.operation).find(item => item.sessionId === sessionId &&
+        item.operationId !== except && ['session.turn', 'session.review', 'session.compact'].includes(item.kind) &&
+        ['dispatched', 'accepted', 'uncertain'].includes(item.status) && covers(item, scope) && gate.has(`operation:${item.operationId}`));
+    return operation ? `operation:${operation.operationId}` : undefined;
+}
+/** A directory has many ordinary writers, or one build, freeze, maintenance job or member Run. */
+export class DirectoryAccessGate {
+    normalize;
+    held = new Map();
+    pending = [];
+    constructor(normalize = claim => claim) {
+        this.normalize = normalize;
+    }
+    claim(input) {
+        const claim = this.normalize(input);
+        const held = this.held.get(claim.owner);
+        if (held) {
+            if (!covers(held, claim) || held.mode === 'shared' && claim.mode === 'exclusive')
+                return Promise.reject(new Error('directory_access_upgrade_forbidden'));
+            return Promise.resolve();
+        }
+        const existing = this.pending.find(item => item.owner === claim.owner);
+        if (existing) {
+            if (!covers(existing, claim) || existing.mode === 'shared' && claim.mode === 'exclusive')
+                return Promise.reject(new Error('directory_access_upgrade_forbidden'));
+            if (existing.paused && !claim.paused) {
+                existing.paused = false;
+                this.drain();
+            }
+            return existing.ready;
+        }
+        let resolve;
+        let reject;
+        const ready = new Promise((done, fail) => { resolve = done; reject = fail; });
+        this.pending.push({ ...claim, ready, resolve, reject });
+        this.drain();
+        return ready;
+    }
+    restore(claim) { this.held.set(claim.owner, this.normalize(claim)); }
+    has(owner) { return this.held.has(owner); }
+    permits(owner, scope, mode) {
+        const held = this.held.get(owner);
+        return Boolean(held && covers(held, this.normalize({ ...scope, owner, mode })) && (held.mode === 'exclusive' || mode === 'shared'));
+    }
+    tryClaim(claim) {
+        const ready = this.claim(claim);
+        if (this.has(claim.owner))
+            return true;
+        void ready.catch(() => undefined);
+        this.release(claim.owner);
+        return false;
+    }
+    adopt(owner, parentOwner) {
+        const child = this.pending.find(item => item.owner === owner);
+        const parent = this.held.get(parentOwner);
+        if (!child || !parent || parent.mode !== 'exclusive' || !covers(parent, child))
+            return;
+        child.parentOwner = parentOwner;
+        this.drain();
+    }
+    cancelPending(owner) {
+        if (this.held.has(owner) || !this.pending.some(item => item.owner === owner))
+            return false;
+        this.release(owner);
+        return true;
+    }
+    release(owner) {
+        this.held.delete(owner);
+        const pending = this.pending.find(item => item.owner === owner);
+        if (pending) {
+            this.pending.splice(this.pending.indexOf(pending), 1);
+            pending.reject(new Error('directory_access_cancelled'));
+        }
+        this.drain();
+    }
+    owners() { return [...this.held.keys(), ...this.pending.map(item => item.owner)]; }
+    drain() {
+        const earlier = [];
+        for (const item of [...this.pending]) {
+            if (item.paused) {
+                earlier.push(item);
+                continue;
+            }
+            const parent = item.parentOwner ? this.held.get(item.parentOwner) : undefined;
+            const family = parent && covers(parent, item) && (parent.mode === 'exclusive' || item.mode === 'shared');
+            const conflict = [...this.held.values()].some(held => !(family && (held.owner === parent.owner || held.parentOwner === parent.owner)) && overlaps(item, held) &&
+                (item.mode === 'exclusive' || held.mode === 'exclusive' || Boolean(item.sessionId && held.sessionId === item.sessionId)));
+            const queuedWriter = !family && earlier.some(prior => overlaps(item, prior) && (item.mode === 'exclusive' || prior.mode === 'exclusive'));
+            if (conflict || queuedWriter) {
+                earlier.push(item);
+                continue;
+            }
+            this.pending.splice(this.pending.indexOf(item), 1);
+            this.held.set(item.owner, item);
+            item.resolve();
+        }
+    }
+}
+async function gateFor(state) {
+    let pending = gates.get(state);
+    if (!pending) {
+        pending = (async () => {
+            const gate = new DirectoryAccessGate(claim => state.config.workspaceMode === 'multi'
+                ? claim : { ...claim, workspaceId: undefined, directoryName: 'basic' });
+            instances.set(state, gate);
+            const members = await listMembers(state);
+            for (const member of members)
+                if (member.holding)
+                    gate.restore({ ...member, owner: `run:${member.runId}`, mode: 'exclusive' });
+            for (const { operation } of state.journal.listOperations()) {
+                if (!takesWorkspaceDirectory(operation.kind) || isTurnControl(operation.kind) ||
+                    !['dispatched', 'accepted', 'uncertain'].includes(operation.status) ||
+                    members.some(member => member.holding && (member.operationId === operation.operationId || Boolean(member.sessionId && member.sessionId === operation.sessionId))))
+                    continue;
+                gate.restore({ ...operation, owner: `operation:${operation.operationId}`, mode: operationDirectoryMode(operation) });
+            }
+            for (const terminal of state.journal.listTerminals())
+                if (terminal.status !== 'destroyed')
+                    gate.restore({ ...terminal, owner: `terminal:${terminal.terminalId}`, mode: 'shared' });
+            for (const writer of state.journal.listManagedWrites())
+                if (!writer.stoppedAt) {
+                    gate.restore({ ...managedDirectoryScope(state, writer.workspaceId), owner: `managed:${writer.writeId}`, mode: 'shared' });
+                }
+            const waiting = [];
+            for (const barrier of state.journal.directoryBarriers()) {
+                const snapshot = barrier.owner.startsWith('freeze:')
+                    ? await readSnapshot(state, barrier.owner.slice('freeze:'.length)).catch(() => undefined) : undefined;
+                if (snapshot?.sourceWorkspaceId === barrier.workspaceId && snapshot.sourceDirectoryName === barrier.directoryName) {
+                    await state.journal.deleteDirectoryBarrier(barrier.owner);
+                    continue;
+                }
+                if (barrier.phase !== 'pending') {
+                    gate.restore({ ...barrier, mode: 'exclusive' });
+                    continue;
+                }
+                if (barrier.deadline && Date.parse(barrier.deadline) <= Date.now()) {
+                    await state.journal.deleteDirectoryBarrier(barrier.owner);
+                    continue;
+                }
+                waiting.push({ claim: { ...barrier, mode: 'exclusive', paused: true }, queuedAt: barrier.queuedAt ?? '' });
+                const timeout = setTimeout(() => {
+                    if (gate.cancelPending(barrier.owner))
+                        void state.journal.deleteDirectoryBarrier(barrier.owner).catch(() => undefined);
+                }, Math.max(0, Date.parse(barrier.deadline ?? new Date(Date.now() + 60_000).toISOString()) - Date.now()));
+                timeout.unref?.();
+            }
+            for (const pending of state.journal.deferredDirectoryOperations()) {
+                const operation = state.journal.getOperationById(pending.operationId);
+                if (operation?.status !== 'queued')
+                    continue;
+                waiting.push({ claim: { ...operation, owner: `operation:${operation.operationId}`, mode: operationDirectoryMode(operation),
+                        ...(operation.kind.startsWith('session.') ? { sessionId: operation.sessionId } : {}) }, queuedAt: pending.queuedAt ?? operation.createdAt });
+            }
+            for (const item of waiting.sort((a, b) => a.queuedAt.localeCompare(b.queuedAt)))
+                void gate.claim(item.claim).catch(() => undefined);
+            state.journal.onChange(() => reconcileDirectoryAccess(state));
+            return gate;
+        })();
+        gates.set(state, pending);
+    }
+    return pending;
+}
+/** The journal is the long-lived execution truth; only confirmed terminal writers release a lease. */
+export function reconcileDirectoryAccess(state) {
+    const gate = instances.get(state);
+    if (!gate)
+        return;
+    for (const owner of gate.owners()) {
+        if (owner.startsWith('operation:')) {
+            const operation = state.journal.getOperationById(owner.slice('operation:'.length));
+            if (operation && TERMINAL.has(operation.status))
+                gate.release(owner);
+        }
+        else if (owner.startsWith('terminal:')) {
+            if (state.journal.getTerminal(owner.slice('terminal:'.length))?.status === 'destroyed')
+                gate.release(owner);
+        }
+        else if (owner.startsWith('managed:')) {
+            if (state.journal.listManagedWrites().find(writer => writer.writeId === owner.slice('managed:'.length))?.stoppedAt)
+                gate.release(owner);
+        }
+    }
+}
+export async function holdDirectoryAccess(state, scope, owner, mode = 'shared') {
+    const gate = await gateFor(state);
+    const inherited = context.getStore();
+    await gate.claim({ ...scope, owner, mode,
+        ...(inherited?.state === state && gate.permits(inherited.claim.owner, scope, mode) ? { parentOwner: inherited.claim.owner } : {}) });
+    return () => gate.release(owner);
+}
+/** A build may join its known installer that was queued behind the build's own exclusive lease. */
+export async function adoptDirectoryAccess(state, owner) {
+    const inherited = context.getStore();
+    if (inherited?.state !== state || inherited.claim.mode !== 'exclusive')
+        return;
+    (await gateFor(state)).adopt(owner, inherited.claim.owner);
+}
+/** Cancelling a not-yet-spawned writer cannot release a process that is already running. */
+export async function cancelPendingDirectoryAccess(state, owner) {
+    return (await gateFor(state)).cancelPending(owner);
+}
+export async function withDirectoryOwner(state, scope, owner, action) {
+    if (!(await gateFor(state)).permits(owner, scope, 'exclusive'))
+        throw new Error('directory_owner_not_held');
+    return context.run({ state, claim: { ...scope, owner, mode: 'exclusive' } }, action);
+}
+export async function withDirectoryWrite(state, scope, action) {
+    const inherited = context.getStore();
+    const gate = await gateFor(state);
+    if (inherited?.state === state && gate.permits(inherited.claim.owner, scope, scope.mode ?? 'shared'))
+        return action();
+    if (inherited?.state === state && scope.mode === 'exclusive' && gate.permits(inherited.claim.owner, scope, 'shared'))
+        throw new Error('directory_busy');
+    const parentOwner = scope.mode !== 'exclusive' ? activeSessionOwner(state, gate, scope, scope.sessionId) : undefined;
+    const claim = { ...scope, sessionId: undefined, owner: scope.owner ?? `write:${randomUUID()}`, mode: scope.mode ?? 'shared',
+        ...(parentOwner ? { parentOwner } : {}) };
+    if (scope.wait === false && !gate.tryClaim(claim))
+        throw new Error('directory_busy');
+    if (scope.wait !== false)
+        await gate.claim(claim);
+    const release = () => gate.release(claim.owner);
+    try {
+        return await context.run({ state, claim }, action);
+    }
+    finally {
+        release();
+    }
+}
+export async function withOperationDirectoryAccess(state, operation, action, deferred) {
+    if (!takesWorkspaceDirectory(operation.kind) || isTurnControl(operation.kind) || operation.kind === 'runtime.destroy')
+        return action();
+    const inherited = context.getStore();
+    const mode = operationDirectoryMode(operation);
+    const gate = await gateFor(state);
+    if (inherited?.state === state && gate.permits(inherited.claim.owner, operation, mode))
+        return action();
+    const active = executing.get(state) ?? new Set();
+    executing.set(state, active);
+    if (active.has(operation.operationId))
+        return state.journal.getOperationById(operation.operationId) ?? operation;
+    active.add(operation.operationId);
+    const parentOwner = !takesExecutionSlot(operation.kind) && mode === 'shared'
+        ? activeSessionOwner(state, gate, operation, operation.sessionId, operation.operationId) : undefined;
+    const claim = { ...operation, owner: `operation:${operation.operationId}`, mode: operationDirectoryMode(operation),
+        ...(operation.kind.startsWith('session.') ? { sessionId: operation.sessionId } : {}),
+        ...(parentOwner ? { parentOwner } : {}) };
+    if (inherited?.state === state && mode === 'shared' && gate.permits(inherited.claim.owner, operation, mode))
+        claim.parentOwner = inherited.claim.owner;
+    const ready = gate.claim(claim);
+    const run = async () => {
+        try {
+            await ready;
+            const current = state.journal.getOperationById(operation.operationId);
+            if (current && TERMINAL.has(current.status))
+                return current;
+            return await context.run({ state, claim }, action);
+        }
+        finally {
+            active.delete(operation.operationId);
+            const current = state.journal.getOperationById(operation.operationId);
+            if (!current || current.status === 'queued' || TERMINAL.has(current.status))
+                gate.release(claim.owner);
+            if (deferred && current?.status !== 'queued')
+                await state.journal.deleteDeferredDirectoryOperation(operation.operationId);
+        }
+    };
+    if (gate.has(claim.owner))
+        return run();
+    if (!deferred)
+        return run();
+    try {
+        await state.journal.deferDirectoryOperation(deferred);
+    }
+    catch (error) {
+        active.delete(operation.operationId);
+        void ready.catch(() => undefined);
+        gate.release(claim.owner);
+        throw error;
+    }
+    void run().catch(async (error) => {
+        const current = state.journal.getOperationById(operation.operationId);
+        if (!current || TERMINAL.has(current.status))
+            return;
+        await state.journal.putOperation(deferred.scopeKey, transitionOperation(current, 'uncertain', {
+            error: error instanceof Error && error.message === 'directory_access_cancelled' ? 'cancelled' : 'native_receipt_lost',
+        }));
+    }).catch(() => undefined);
+    return state.journal.getOperationById(operation.operationId) ?? operation;
+}
+/** A queued command is replayed only if it never started; accepted or uncertain work is only observed. */
+export async function restoreDeferredDirectoryOperations(state, execute) {
+    for (const pending of state.journal.deferredDirectoryOperations()) {
+        const operation = state.journal.getOperationById(pending.operationId);
+        if (operation?.status === 'queued') {
+            if (operation.generation !== state.config.generation || operation.runtimeEpoch !== state.runtimeEpoch) {
+                await state.journal.putOperation(pending.scopeKey, transitionOperation(operation, 'failed', { error: 'generation_mismatch' }));
+                continue;
+            }
+            void execute(pending.scopeKey, operation, pending.payload, pending.recovery).catch(() => undefined);
+        }
+        else
+            await state.journal.deleteDeferredDirectoryOperation(pending.operationId);
+    }
+}
+export async function claimBatchDirectory(state, member) {
+    await holdDirectoryAccess(state, member, `run:${member.runId}`, 'exclusive');
+}
+export function releaseBatchDirectory(state, member) {
+    if (!member.holding && member.writersStopped)
+        instances.get(state)?.release(`run:${member.runId}`);
+}
+export async function withDirectoryFreeze(state, scope, action, quiesce, options) {
+    const pending = freezing.get(state) ?? new Map();
+    freezing.set(state, pending);
+    const existing = pending.get(scope.batchId);
+    if (existing) {
+        if (existing.scope.workspaceId !== scope.workspaceId || (existing.scope.directoryName ?? 'basic') !== (scope.directoryName ?? 'basic'))
+            throw new Error('batch_source_identity_mismatch');
+        return existing.task;
+    }
+    const task = performDirectoryFreeze(state, scope, action, quiesce, options);
+    pending.set(scope.batchId, { scope, task });
+    try {
+        return await task;
+    }
+    finally {
+        if (pending.get(scope.batchId)?.task === task)
+            pending.delete(scope.batchId);
+    }
+}
+async function performDirectoryFreeze(state, scope, action, quiesce, options) {
+    const deadline = options?.deadline ?? new Date(Date.now() + 60_000).toISOString();
+    const signal = AbortSignal.any([...(options?.signal ? [options.signal] : []), AbortSignal.timeout(Math.max(0, Date.parse(deadline) - Date.now()))]);
+    if (signal.aborted)
+        throw new Error('directory_access_cancelled');
+    const owner = `freeze:${scope.batchId}`;
+    const gate = await gateFor(state);
+    const previous = state.journal.directoryBarriers().find(barrier => barrier.owner === owner);
+    if (previous && (previous.workspaceId !== scope.workspaceId || previous.directoryName !== (scope.directoryName ?? 'basic')))
+        throw new Error('batch_source_identity_mismatch');
+    // A restored capture may still have writers. Retrying its publication is not a new admission,
+    // and a missing candidate or a lost request cannot provide the old capture's stop proof.
+    const restoredCapture = Boolean(previous && previous.phase !== 'pending');
+    const claimed = gate.claim({ ...scope, owner, mode: 'exclusive' });
+    void claimed.catch(() => undefined);
+    let started = restoredCapture;
+    const cancel = () => {
+        if (started)
+            return;
+        gate.release(owner);
+        void state.journal.deleteDirectoryBarrier(owner).catch(() => undefined);
+    };
+    signal.addEventListener('abort', cancel, { once: true });
+    try {
+        if (!restoredCapture)
+            await state.journal.putDirectoryBarrier({ owner, workspaceId: scope.workspaceId,
+                directoryName: scope.directoryName ?? 'basic', runtimeEpoch: state.runtimeEpoch, phase: 'pending', deadline });
+        await quiesce?.();
+        await claimed;
+        if (signal.aborted)
+            throw new Error('directory_access_cancelled');
+        started = true;
+        if (!restoredCapture)
+            await state.journal.putDirectoryBarrier({ owner, workspaceId: scope.workspaceId,
+                directoryName: scope.directoryName ?? 'basic', runtimeEpoch: state.runtimeEpoch, phase: 'capturing', deadline });
+        return await withDirectoryOwner(state, scope, owner, action);
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+        const snapshot = restoredCapture ? await readSnapshot(state, scope.batchId).catch(() => undefined) : undefined;
+        if (!restoredCapture || (snapshot?.sourceWorkspaceId === scope.workspaceId && snapshot.sourceDirectoryName === (scope.directoryName ?? 'basic'))) {
+            await state.journal.deleteDirectoryBarrier(owner);
+            gate.release(owner);
+        }
+    }
+}
+export async function clearDirectoryFreeze(state, batchId) {
+    const owner = `freeze:${batchId}`;
+    await state.journal.deleteDirectoryBarrier(owner);
+    instances.get(state)?.release(owner);
+}

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

@@ -2,6 +2,7 @@ import { withObservedFile } from '../workspaces/revisions.js';
 import { revisionScope, sessionWorkspaceRoot, workspaceRoot, workspaceSessions } from '../workspaces/registry.js';
 import { abandonTurnChanges, beginTurnChanges, finishTurnChanges } from '../workspaces/turn-changes.js';
 import { shareWorkspaceGit } from '../workspaces/shared-git.js';
+import { 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, parameterPatchPayloadSchema, parameterAgentTaskRequestSchema, parameterAgentVerifyPayloadSchema, productionSessionAttemptId, reasoningEffortSchema, workspacePermissionModeSchema, workspaceComposerSelectionSchema, workspaceReviewPayloadSchema, workspaceCompactPayloadSchema, workspaceSteerPayloadSchema, workspaceApprovalResponseSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, recoverUncertainOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, workspaceRemixReferenceImportPayloadSchema, deliveryBuildPayloadSchema, deliveryCancelPayloadSchema, } from '@playcraft/common/cloud-workspace/runtime';
@@ -11,6 +12,7 @@ import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
 import { resolveWorkspaceAttachments } from '../workspaces/attachments.js';
 import { importWorkspaceRemixReference, RemixReferenceError } from '../workspaces/remix-references.js';
 import { ComposerContextError, resolveComposerContext } from '../workspaces/composer-context.js';
+import { ensureParameterInitializationSkill } from '../workspaces/parameter-initialization-skill.js';
 import { readWorkspaceSkillSnapshot, readWorkspaceSkills } from '../workspaces/skills.js';
 import { loadWorkspaceSkillArtifact, workspacePlatformSkillAccess } from '../workspaces/skill-artifact-loader.js';
 import { enableLocalProjectSkill, syncLocalProjectSkills } from '../../project-skills/local-store.js';
@@ -28,7 +30,7 @@ import { ThemeAssetIndexError } from '../workspaces/theme-asset-index.js';
 import { patchWorkspaceParameters, readWorkspaceParameters } from '../workspaces/parameters.js';
 import { prepareParameterAgentTask, finishParameterAgentTask, verifyParameterAgentTask, } from '../workspaces/parameter-agent.js';
 import { previewFailureCode, previewWorkspaceRoot, runPreviewPublish, trackPreviewPublish, } from '../previews/publish.js';
-import { spawnBackgroundWriter, stopBackgroundWriter, } from '../processes/managed-writes.js';
+import { startManagedBackgroundWriter, stopBackgroundWriter, } from '../processes/managed-writes.js';
 import { wakeSourceEventUploader } from './source-uploader.js';
 import { batchDirectoryHeld } from '../batch/occupancy.js';
 import { BinaryWorkspaceWriteError, observeWorkspaceBinaryFile, writeWorkspaceBinaryFile } from '../workspaces/binary-write.js';
@@ -90,6 +92,8 @@ export async function recoverInterruptedParameterVerifications(journal) {
     for (const { scopeKey, operation } of journal.listOperations()) {
         if (operation.kind !== 'parameter.verify' || !['queued', 'dispatched', 'accepted', 'uncertain'].includes(operation.status))
             continue;
+        if (operation.status === 'queued' && journal.deferredDirectoryOperations().some(item => item.operationId === operation.operationId))
+            continue;
         await journal.putOperation(scopeKey, transitionOperation(operation, 'interrupted', { error: 'parameter_verification_interrupted' }));
     }
 }
@@ -105,12 +109,21 @@ export async function executeOperation(state, scopeKey, operation, payload, reco
         if ((operation.leaseFence ?? 0) < state.acceptedLeaseFence || state.journal.destroyed()) {
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: state.journal.destroyed() ? 'runtime_destroyed' : 'stale_lease' }));
         }
-        return executeScopedOperation(state, scopeKey, operation, payload, recovery);
+        if (operation.kind === 'session.turn' && !recovery && operation.sessionId &&
+            state.journal.getSession(operation.sessionId)?.recoverability === 'history_only')
+            return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'native_not_recoverable' }));
+        return withOperationDirectoryAccess(state, operation, () => {
+            if ((operation.leaseFence ?? 0) < state.acceptedLeaseFence || state.journal.destroyed())
+                return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: state.journal.destroyed() ? 'runtime_destroyed' : 'stale_lease' }));
+            return executeScopedOperation(state, scopeKey, operation, payload, recovery);
+        }, { operationId: operation.operationId, scopeKey, payload, ...(recovery ? { recovery } : {}) });
     };
     if (['runtime.destroy', 'session.interrupt', 'session.approval.respond', 'session.steer', 'preview.publish', 'delivery.build', 'delivery.cancel'].includes(operation.kind)) {
         return run();
     }
-    return state.journal.exclusive(`workspace:${revisionScope(state, operation.workspaceId, operation.directoryName) ?? 'single'}`, run);
+    return state.journal.exclusive(operation.kind.startsWith('session.') && operation.sessionId
+        ? `session-execution:${operation.sessionId}`
+        : `workspace:${revisionScope(state, operation.workspaceId, operation.directoryName) ?? 'single'}`, run);
 }
 async function executeScopedOperation(state, scopeKey, operation, payload, recovery) {
     let current = await persist(state, scopeKey, transitionOperation(operation, 'dispatched'));
@@ -381,12 +394,12 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
         }
         found = rebound;
     }
-    const binding = found;
     // Also covers a new thread whose first turn failed before starting: the next turn still carries it.
-    const context = recovery && binding?.recoveryContextPending ? recovery.context : '';
-    if (!binding) {
+    const context = recovery && found?.recoveryContextPending ? recovery.context : '';
+    if (!found) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'unknown_session' }));
     }
+    let binding = found;
     if ((binding.directoryName ?? 'basic') !== (operation.directoryName ?? 'basic')) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'context_directory_mismatch' }));
     }
@@ -398,17 +411,30 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
     }
     const root = await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName);
     let composer;
+    let initializationSkill;
     try {
+        let turnContext = selection.data.context;
+        if (parameterTask.data?.action === 'initialize') {
+            const selectedSkill = await ensureParameterInitializationSkill(root);
+            initializationSkill = { ...selectedSkill,
+                path: join(root, '.playcraft/skills', selectedSkill.lockHash, selectedSkill.entryKey, 'SKILL.md') };
+            turnContext = { ...turnContext, files: turnContext?.files ?? [], skills: [
+                    ...(turnContext?.skills ?? []).filter(skill => skill.entryKey !== selectedSkill.entryKey), selectedSkill,
+                ] };
+        }
         composer = await resolveComposerContext({
             root,
-            directoryName: binding.directoryName ?? 'basic', context: selection.data.context,
+            directoryName: binding.directoryName ?? 'basic', context: turnContext,
             skillCache: join(state.config.stateDir, 'skill-artifacts'),
             loadSkillArtifact: entry => loadWorkspaceSkillArtifact(state, operation.workspaceId ?? 'workspace', entry),
         });
     }
     catch (error) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', {
-            error: error instanceof ComposerContextError ? error.message : 'invalid_composer_context',
+            error: error instanceof ComposerContextError ? error.message : parameterTask.data?.action === 'initialize'
+                ? error instanceof Error && /^(?:workspace_skills_|skills_revision_conflict$)/.test(error.message)
+                    ? error.message : parameterAgentError(error)
+                : 'invalid_composer_context',
         }));
     }
     let attachments;
@@ -446,7 +472,7 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
     let parameterInstructions = '';
     if (parameterTask.data) {
         try {
-            parameterInstructions = (await prepareParameterAgentTask(state, operation, parameterTask.data, root)).instructions;
+            parameterInstructions = (await prepareParameterAgentTask(state, operation, parameterTask.data, root, { initializationSkill })).instructions;
         }
         catch (error) {
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: parameterAgentError(error) }));
@@ -458,7 +484,7 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
     });
     let result;
     try {
-        result = await native(state).startTurn({
+        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')),
@@ -490,6 +516,18 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
                 await state.journal.putSession({ ...binding, modelConfigId, reasoningEffort: selectedEffort, permissionMode: selectedMode, turnStatus: 'starting' });
             },
         });
+        result = await startTurn();
+        // The native runtime cannot persist an empty thread before its first turn. Adding the
+        // selected skill can therefore require replacing that empty thread, before any model work.
+        if (initializationSkill && result.outcome === 'failed' && result.error === 'workspace_skills_changed'
+            && !(state.journal.getOperation(scopeKey) ?? operation).nativeRequestId) {
+            const started = await native(state).startThread({ sessionId, cwd: root,
+                modelConfigId: selected.data ?? binding.modelConfigId, reasoningEffort: requestedEffort, permissionMode: requestedMode });
+            binding = { ...binding, threadId: started.threadId, modelConfigId: started.modelConfigId ?? binding.modelConfigId,
+                reasoningEffort: started.reasoningEffort ?? requestedEffort, permissionMode: started.permissionMode ?? requestedMode };
+            await state.journal.putSession(binding);
+            result = await startTurn();
+        }
     }
     catch (error) {
         if (!parameterTask.data)
@@ -1113,7 +1151,7 @@ async function executeFileWrite(state, scopeKey, operation, payload) {
             : 'invalid_workspace_path';
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error }));
     }
-    const workspaceId = operation.workspaceId ?? 'workspace';
+    const workspaceId = revisionScope(state, operation.workspaceId, operation.directoryName) ?? operation.workspaceId ?? 'workspace';
     const writer = parsed.data.writer ?? 'manual';
     if (parsed.data.release) {
         const lease = state.journal.getManagedWrite(parsed.data.writeId);
@@ -1147,17 +1185,14 @@ async function executeFileWrite(state, scopeKey, operation, payload) {
                 contentHash: written.contentHash,
             }, revisionScope(state, operation.workspaceId, operation.directoryName));
             if (parsed.data.hold && parsed.data.writeId) {
-                let pid;
+                const record = { writeId: parsed.data.writeId, workspaceId, source: writer, startedAt: new Date().toISOString() };
                 if (writer === 'background') {
-                    pid = spawnBackgroundWriter(await resolveWorkspaceFile(root, parsed.data.path));
+                    await startManagedBackgroundWriter(state, record, await resolveWorkspaceFile(root, parsed.data.path));
+                }
+                else {
+                    await holdDirectoryAccess(state, operation, `managed:${parsed.data.writeId}`, 'shared');
+                    await state.journal.putManagedWrite(record);
                 }
-                await state.journal.putManagedWrite({
-                    writeId: parsed.data.writeId,
-                    workspaceId,
-                    source: writer,
-                    startedAt: new Date().toISOString(),
-                    pid,
-                });
             }
             const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted', { expectedRevision: revision }));
             if (artifactFormat(parsed.data.path) && operation.workspaceId) {
@@ -1349,7 +1384,9 @@ async function executeParameterPatch(state, scopeKey, operation, payload) {
     if (document.status === 'missing' || document.status === 'schema_only' || !document.dataPath) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'parameter_data_missing' }));
     }
-    const dataPath = document.dataPath;
+    const dataPath = 'documentId' in parsed.data ? document.runtimeI18n?.themePath : document.dataPath;
+    if (!dataPath)
+        return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'parameter_i18n_global_invalid' }));
     return withObservedFile(state, operation.workspaceId, dataPath, async ({ revision: currentRevision, file }) => {
         if (parsed.data.expectedRevision !== currentRevision) {
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'revision_conflict' }));
@@ -1386,6 +1423,7 @@ async function executeParameterPatch(state, scopeKey, operation, payload) {
                         revision,
                         contentHash: written.contentHash,
                         size: written.size,
+                        ...('documentId' in parsed.data ? { documentId: parsed.data.documentId } : {}),
                         ...('changes' in parsed.data
                             ? { fieldPaths: parsed.data.changes.map((change) => change.fieldPath) }
                             : { fieldPath: parsed.data.fieldPath }),
@@ -1416,7 +1454,7 @@ async function executePreviewPublish(state, scopeKey, operation) {
     trackPreviewPublish(state, runPreviewPublish(state, accepted, root).then(async () => {
         await persist(state, scopeKey, transitionOperation(accepted, 'completed'));
     }, async (error) => {
-        await persist(state, scopeKey, transitionOperation(accepted, 'failed', { error: previewFailureCode(error) }));
+        await persist(state, scopeKey, transitionOperation(accepted, previewFailureCode(error) === 'preview_process_unknown' ? 'uncertain' : 'failed', { error: previewFailureCode(error) }));
     }).catch(() => undefined));
     return accepted;
 }
@@ -1438,7 +1476,7 @@ async function executeDeliveryBuild(state, scopeKey, operation, payload) {
     }).then(async (result) => {
         const error = result.record.error
             ?? (result.record.status === 'succeeded' ? undefined : 'delivery_build_failed');
-        await persist(state, scopeKey, transitionOperation(accepted, result.record.status === 'succeeded' ? 'completed' : 'failed', error ? { error } : {}));
+        await persist(state, scopeKey, transitionOperation(accepted, result.record.status === 'succeeded' ? 'completed' : error === 'delivery_process_unknown' ? 'uncertain' : 'failed', error ? { error } : {}));
     }, async (error) => {
         await persist(state, scopeKey, transitionOperation(accepted, 'failed', {
             error: error instanceof DeliveryBuildError ? error.code : 'delivery_build_failed',

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

@@ -12,6 +12,7 @@ export async function applyRuntimeEndpointPatch(state, patch) {
         throw new Error('endpoint_config_path_missing');
     }
     const temporary = `${state.configPath}.${process.pid}.tmp`;
+    // private
     await writeFile(temporary, `${JSON.stringify(next)}\n`, { mode: 0o600 });
     await chmod(temporary, 0o600);
     await rename(temporary, state.configPath);