@playcraft/cli 0.1.57-beta → 0.1.58-beta

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

@@ -3,7 +3,7 @@ import { observeWorkspaceDirectories } from '../workspaces/directory-revisions.j
 import { registerWorkspace, revisionScope, sessionWorkspaceRoot, workspaceRoot, WorkspaceContextError } from '../workspaces/registry.js';
 import { constants } from 'node:fs';
 import { access as accessDirectory, stat } from 'node:fs/promises';
-import { workspaceRegistrationRequestSchema, workspaceFileSearchQuerySchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, sourceAckSchema, operationAcceptRequestSchema, operationLogSchema, operationKindSchema, operationScopeKey, productionSessionAttemptId, takesWorkspaceDirectory, nativeHistoryReadSchema, runtimeError, runtimeConnectivityDocumentSchema, unavailableRuntimeCapabilities, workspaceUiResultSchema, workspaceRemixReferenceImportRequestSchema, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES, WORKSPACE_ASSET_LIBRARY_IMPORT_BODY_MAX_BYTES, workspaceSessionRestoreRequestSchema, workspaceSessionRestoreResponseSchema, deliveryValidatePayloadSchema, deliveryBuildListQuerySchema, deliveryBuildListSchema, deliveryBuildDetailSchema, deliveryBuildLogSchema, workspaceDirectoryNameSchema, attachmentIdsSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceRegistrationRequestSchema, workspaceFileSearchQuerySchema, HTTP_STATUS_BY_ERROR, assertLeaseFence, buildHandshakeDocument, capability, findUntrustedRuntimeFields, gitFileRefSchema, sourceAckSchema, operationAcceptRequestSchema, operationLogSchema, operationKindSchema, operationScopeKey, productionSessionAttemptId, takesWorkspaceDirectory, nativeHistoryReadSchema, runtimeError, runtimeConnectivityDocumentSchema, unavailableRuntimeCapabilities, workspaceUiResultSchema, workspaceRemixReferenceImportRequestSchema, WORKSPACE_REMIX_REFERENCE_BODY_MAX_BYTES, WORKSPACE_ASSET_LIBRARY_IMPORT_BODY_MAX_BYTES, workspaceSessionRestoreRequestSchema, workspaceSessionRestoreResponseSchema, deliveryValidatePayloadSchema, deliveryBuildListQuerySchema, deliveryBuildListSchema, deliveryBuildDetailSchema, deliveryBuildLogSchema, workspaceDirectoryNameSchema, workspaceDirectoryRegistrationSchema, attachmentIdsSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { controlTokenMatches, extractControlToken } from './auth.js';
 import { applyRuntimeEndpointPatch } from './endpoints.js';
 import { wakeSourceEventUploader } from './source-uploader.js';
@@ -12,6 +12,7 @@ import { GitWorkspaceError, readWorkspaceGitDiff, readWorkspaceGitFile, readWork
 import { readWorkspaceParameters } from '../workspaces/parameters.js';
 import { listParameterAgentTasks } from '../workspaces/parameter-agent.js';
 import { readDependencies } from '../workspaces/dependencies.js';
+import { permissionDriftFromError } from '../workspaces/workspace-shares.js';
 import { desktopHost, desktopRoute } from './desktop-host.js';
 import { ensureCliCredentials } from '../workspaces/cli-credentials.js';
 import { readAttachmentUpload, uploadWorkspaceAttachment, uploadWorkspaceVideoAttachment } from '../workspaces/attachments.js';
@@ -44,7 +45,31 @@ import { serveSessionImage } from '../workspaces/session-image.js';
 import { restoreNativeSession, SessionRestoreError } from './session-restore.js';
 import { handleAssetTransferRequest } from './asset-transfers.js';
 import { readWorktreeSource, registerChatWorktree } from '../workspaces/worktrees.js';
+import { withDirectoryWrite } from './directory-access.js';
 export async function handleRuntimeRequest(state, request, response) {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    const workspaceId = url.searchParams.get('workspaceId');
+    // Body-scoped operations, members and terminal control take their own lifetime-aware leases.
+    const ownLease = url.pathname.startsWith('/runtime/operations') || url.pathname.startsWith('/runtime/terminals/') ||
+        url.pathname.startsWith('/runtime/batch-') || /^\/runtime\/sessions\/[^/]+\/ui-results$/.test(url.pathname);
+    if (authorizeRuntime(state, request) === 'control' && workspaceId &&
+        (!['GET', 'HEAD', 'OPTIONS'].includes(request.method ?? 'GET') || url.pathname === '/runtime/git-bundle') && !ownLease) {
+        try {
+            return await withDirectoryWrite(state, { workspaceId, directoryName: url.searchParams.get('directoryName') ?? 'basic', wait: false,
+                sessionId: url.searchParams.get('sessionId') ?? undefined,
+                ...(url.pathname === '/runtime/git-bundle' ? { mode: 'exclusive' } : {}) }, () => dispatchRuntimeRequest(state, request, response));
+        }
+        catch (error) {
+            if (!response.headersSent)
+                writeJson(response, error instanceof Error && error.message === 'directory_busy' ? 409 : 500, { error: error instanceof Error && error.message === 'directory_busy' ? 'directory_busy' : 'runtime_request_failed' });
+            else
+                response.destroy(error instanceof Error ? error : undefined);
+            return;
+        }
+    }
+    return dispatchRuntimeRequest(state, request, response);
+}
+async function dispatchRuntimeRequest(state, request, response) {
     const url = new URL(request.url ?? '/', 'http://127.0.0.1');
     const directoryName = url.searchParams.get('directoryName') ?? 'basic';
     const access = authorizeRuntime(state, request);
@@ -104,6 +129,8 @@ export async function handleRuntimeRequest(state, request, response) {
                 permissionsVersion: 1,
                 composerContextVersion: 1,
                 parameterAgentVersion: 1,
+                directoryConcurrencyVersion: 1,
+                parameterInitializationVersion: 1,
                 remixReferencesVersion: 1,
                 batchSourceFreezeRevision: 2,
                 ...(state.native?.workspaceUi ? { workspaceUiVersion: 1 } : {}),
@@ -189,7 +216,7 @@ export async function handleRuntimeRequest(state, request, response) {
                 writeJson(response, 409, { error: 'invalid_workspace_registration' });
                 return;
             }
-            const binding = await registerWorkspace(state, parsed.data.binding, parsed.data.leaseFence, parsed.data.preparation, parsed.data.cliCredentials === false, parsed.data.sourceSnapshot);
+            const binding = await withDirectoryWrite(state, { workspaceId: parsed.data.binding.workspaceId, directoryName: 'basic', wait: false }, () => registerWorkspace(state, parsed.data.binding, parsed.data.leaseFence, parsed.data.preparation, parsed.data.cliCredentials === false, parsed.data.sourceSnapshot));
             if (parsed.data.cliCredentials)
                 await ensureCliCredentials(state);
             writeJson(response, 200, { workspaceId: binding.workspaceId, status: 'registered' });
@@ -210,10 +237,13 @@ export async function handleRuntimeRequest(state, request, response) {
                     writeJson(response, 400, { error: 'invalid_workspace_registration' });
                     return;
                 }
-                writeJson(response, 200, await registerChatWorktree(state, body.directory, Number(body.leaseFence), source.data, body.sourceBranchName, attachments.data));
+                const directory = workspaceDirectoryRegistrationSchema.parse(body.directory);
+                writeJson(response, 200, await withDirectoryWrite(state, { ...directory, mode: 'exclusive', wait: false }, () => withDirectoryWrite(state, { workspaceId: directory.workspaceId, directoryName: source.data, mode: 'exclusive', wait: false }, () => registerChatWorktree(state, directory, Number(body.leaseFence), source.data, body.sourceBranchName, attachments.data))));
+            }
+            else {
+                const directory = workspaceDirectoryRegistrationSchema.parse(body.directory);
+                writeJson(response, 200, await withDirectoryWrite(state, { ...directory, mode: 'exclusive', wait: false }, () => registerWorkspaceDirectory(state, directory, Number(body.leaseFence))));
             }
-            else
-                writeJson(response, 200, await registerWorkspaceDirectory(state, body.directory, Number(body.leaseFence)));
             return;
         }
         if (request.method === 'POST' && url.pathname === '/runtime/workspaces/directories/worktree-source') {
@@ -226,7 +256,7 @@ export async function handleRuntimeRequest(state, request, response) {
                 writeJson(response, 409, { error: 'invalid_workspace_registration' });
                 return;
             }
-            writeJson(response, 200, await readWorktreeSource(state, body.workspaceId, source.data, Number(body.leaseFence), body.sourceBranchName));
+            writeJson(response, 200, await withDirectoryWrite(state, { workspaceId: body.workspaceId, directoryName: source.data, mode: 'exclusive', wait: false }, () => readWorktreeSource(state, body.workspaceId, source.data, Number(body.leaseFence), body.sourceBranchName)));
             return;
         }
         const maintenance = /^\/runtime\/workspaces\/([a-f0-9-]{36})\/directories\/(cleanup|sync|stats)$/.exec(url.pathname);
@@ -763,6 +793,10 @@ export async function handleRuntimeRequest(state, request, response) {
         writeJson(response, 404, { error: 'not_found' });
     }
     catch (error) {
+        if (error instanceof Error && error.message === 'directory_busy') {
+            writeJson(response, 409, { error: 'directory_busy' });
+            return;
+        }
         if (request.method === 'GET' && ['/runtime/connectivity', '/runtime/files'].includes(url.pathname)) {
             const cause = error instanceof Error && error.cause ? error.cause : error;
             if (['EACCES', 'EPERM'].includes(String(cause?.code))) {
@@ -778,6 +812,12 @@ export async function handleRuntimeRequest(state, request, response) {
             writeJson(response, 413, { error: 'request_body_too_large' });
             return;
         }
+        // A shared path without development-group access is a repair, not an internal failure.
+        const drift = permissionDriftFromError(error);
+        if (drift) {
+            writeJson(response, 409, { error: 'workspace_permission_drift', ...drift });
+            return;
+        }
         if (error instanceof WorkspaceContextError) {
             writeJson(response, 409, { error: error.message });
             return;
@@ -858,7 +898,7 @@ async function acceptOperation(state, request, response) {
         return;
     }
     // leaseFence 由 Runtime Server 派发，本控制面单独校验；其余代次/身份/根目录字段仍只来自引导配置。
-    const untrusted = findUntrustedRuntimeFields(body).filter((field) => field !== 'leaseFence');
+    const untrusted = findUntrustedRuntimeFields(body).filter((field) => field !== 'leaseFence' && field !== 'gatewayOperationId');
     if (untrusted.length > 0) {
         writeError(response, runtimeError('untrusted_runtime_field', untrusted.join(',')));
         return;
@@ -896,7 +936,7 @@ async function acceptOperation(state, request, response) {
         return;
     }
     if (state.config.workspaceMode === 'multi' && parsed.data.kind === 'runtime.ensure' && parsed.data.workspaceId)
-        await restoreWorkspaceDirectory(state, parsed.data.workspaceId, parsed.data.directoryName);
+        await withDirectoryWrite(state, { workspaceId: parsed.data.workspaceId, directoryName: parsed.data.directoryName, mode: 'exclusive', wait: false }, () => restoreWorkspaceDirectory(state, parsed.data.workspaceId, parsed.data.directoryName));
     if (state.config.workspaceMode === 'multi')
         await sessionWorkspaceRoot(state, parsed.data.workspaceId, parsed.data.directoryName);
     // Shared classification: a new conversation writes no files, so a batch hold must not refuse it.
@@ -995,7 +1035,9 @@ async function acceptOperation(state, request, response) {
     };
     // Directory maintenance uses this same lock before checking durable occupancy.
     if (occupiesDirectory && state.config.workspaceMode === 'multi')
-        await state.journal.exclusive(`directory:${parsed.data.workspaceId}:${parsed.data.directoryName ?? 'basic'}`, acceptBound);
+        await state.journal.exclusive(parsed.data.kind.startsWith('session.') && parsed.data.sessionId
+            ? `session-admission:${parsed.data.sessionId}`
+            : `directory:${parsed.data.workspaceId}:${parsed.data.directoryName ?? 'basic'}`, acceptBound);
     else
         await acceptBound();
 }
@@ -1152,7 +1194,7 @@ async function readObservedParameters(state, workspaceId, directoryName = 'basic
     const scope = revisionScope(state, workspaceId, directoryName);
     return state.journal.exclusive(`workspace:${scope ?? 'single'}`, async () => {
         const first = await readWorkspaceParameters(root, state.journal.fileRevisions(scope));
-        for (const path of [first.schemaPath, first.dataPath]) {
+        for (const path of [first.schemaPath, first.dataPath, first.runtimeI18n?.globalPath, first.runtimeI18n?.themePath]) {
             if (path)
                 await withObservedFile(state, workspaceId, path, async () => undefined, directoryName);
         }

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

@@ -7,6 +7,8 @@ export function buildOperationRecord(state, parsed, payloadHash, leaseFence, exe
         : {};
     return {
         operationId: randomUUID(),
+        ...(parsed.gatewayOperationId ? { gatewayOperationId: parsed.gatewayOperationId } : {}),
+        ...(parsed.kind === 'session.turn' && payload.parameterTask !== undefined ? { directoryAccessMode: 'exclusive' } : {}),
         environment: state.config.environment,
         userId: state.config.userId,
         clientRequestId: parsed.clientRequestId,

package/dist/workspace-runtime/server/terminal-host.js

@@ -8,7 +8,9 @@ import { appendTerminalOutput, createTerminalOutputLog, decodeTerminalBytes, run
 import { resolveWorkspaceFile } from '../workspaces/files.js';
 import { sessionWorkspaceRoot } from '../workspaces/registry.js';
 import { startLauncherProcess } from '../codex/launcher-client.js';
+import { stopBackgroundWriter } from '../processes/managed-writes.js';
 import { controlTokenMatches, extractControlToken } from './auth.js';
+import { cancelPendingDirectoryAccess, holdDirectoryAccess } from './directory-access.js';
 const require = createRequire(import.meta.url);
 const commands = new WeakMap();
 const hosts = new WeakMap();
@@ -37,6 +39,7 @@ export class TerminalHost {
     closing = new Set();
     stops = new Map();
     confirmed = new Set();
+    directoryReleases = new Map();
     sockets = new WebSocketServer({ noServer: true });
     constructor(state) {
         this.state = state;
@@ -110,7 +113,14 @@ export class TerminalHost {
             return pending;
         this.closing.add(terminalId);
         const stopped = (async () => {
-            await this.spawning.get(terminalId);
+            await cancelPendingDirectoryAccess(this.state, `terminal:${terminalId}`);
+            try {
+                await this.spawning.get(terminalId);
+            }
+            catch (error) {
+                if (this.attempted.has(terminalId) && !this.confirmed.has(terminalId))
+                    throw error;
+            }
             const session = this.sessions.get(terminalId);
             if (session)
                 await session.stop();
@@ -123,6 +133,7 @@ export class TerminalHost {
                 ...terminal, status: 'destroyed', destroyedAt: new Date().toISOString(),
             });
             this.confirmed.add(terminalId);
+            this.releaseDirectory(terminalId);
             this.revoke(terminalId, 'terminal_destroyed');
             this.closing.delete(terminalId);
             return destroyed;
@@ -139,12 +150,7 @@ export class TerminalHost {
         for (const listener of session.listeners)
             listener(frame);
         session.listeners.clear();
-        try {
-            session.pty.kill();
-        }
-        catch {
-            /* the process may already have exited */
-        }
+        void session.stop().then(() => this.exited(terminalId, session, null)).catch(() => undefined);
     }
     dispose() {
         this.disposed = true;
@@ -153,6 +159,28 @@ export class TerminalHost {
         this.sockets.close();
     }
     async spawn(terminal, cwd) {
+        if (this.closing.has(terminal.terminalId) || this.disposed || this.state.journal.destroyed() ||
+            this.state.journal.getTerminal(terminal.terminalId)?.status === 'destroyed')
+            throw new Error('pty_unavailable');
+        const release = await holdDirectoryAccess(this.state, terminal, `terminal:${terminal.terminalId}`, 'shared');
+        this.directoryReleases.set(terminal.terminalId, release);
+        try {
+            if (this.closing.has(terminal.terminalId) || this.state.journal.destroyed() ||
+                this.state.journal.getTerminal(terminal.terminalId)?.status === 'destroyed')
+                throw new Error('pty_unavailable');
+            return await this.spawnProcess(terminal, cwd);
+        }
+        catch (error) {
+            if (!this.attempted.has(terminal.terminalId) || this.confirmed.has(terminal.terminalId))
+                this.releaseDirectory(terminal.terminalId);
+            throw error;
+        }
+    }
+    releaseDirectory(terminalId) {
+        this.directoryReleases.get(terminalId)?.();
+        this.directoryReleases.delete(terminalId);
+    }
+    async spawnProcess(terminal, cwd) {
         if (this.disposed)
             throw new Error('pty_unavailable');
         if (this.state.config.workspaceMode === 'multi' || process.env.PLAYCRAFT_LAUNCHER_SOCKET
@@ -167,6 +195,7 @@ export class TerminalHost {
                 runtimeEpoch: this.state.runtimeEpoch, cwd, argv: [], env: {}, terminal: { cols: 80, rows: 24 } });
             if (this.disposed) {
                 await child.stop();
+                this.confirmed.add(terminal.terminalId);
                 throw new Error('pty_unavailable');
             }
             const session = { terminalId: terminal.terminalId, streamId: randomUUID(), log: createTerminalOutputLog(), listeners: new Set(),
@@ -212,6 +241,8 @@ export class TerminalHost {
                     await Promise.race([knownExit, new Promise((_resolve, reject) => {
                             timer = setTimeout(() => reject(new Error('terminal_stop_unconfirmed')), 3000);
                         })]);
+                    if (!await stopBackgroundWriter(session.pty.pid))
+                        throw new Error('terminal_stop_unconfirmed');
                 }
                 finally {
                     clearTimeout(timer);
@@ -220,7 +251,10 @@ export class TerminalHost {
         };
         const local = session.pty;
         local.onData((data) => publish(session, data));
-        local.onExit(({ exitCode, signal }) => { finishExit(); void this.exited(terminal.terminalId, session, exitCode, signal).catch(() => undefined); });
+        local.onExit(({ exitCode, signal }) => {
+            finishExit();
+            void session.stop().then(() => this.exited(terminal.terminalId, session, exitCode, signal), () => this.exited(terminal.terminalId, session, undefined, signal)).catch(() => undefined);
+        });
         this.sessions.set(terminal.terminalId, session);
         return session;
     }
@@ -235,6 +269,7 @@ export class TerminalHost {
                     });
                 if (terminal)
                     this.confirmed.add(terminalId);
+                this.releaseDirectory(terminalId);
             }
         }
         finally {

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

@@ -105,7 +105,9 @@ export async function handleWorkspaceTransfer(state, request, response, url) {
                 lastProbe = size;
                 assertTransferDiskSpace(temporary, chunk.length).then(() => callback(null, chunk), error => callback(error));
             } });
-        await pipeline(Readable.from(request.iterator({ destroyOnReturn: false })), guard, createWriteStream(bundlePath, { flags: 'wx', mode: 0o600 }), { signal: controller.signal });
+        await pipeline(Readable.from(request.iterator({ destroyOnReturn: false })), guard, 
+        // private
+        createWriteStream(bundlePath, { flags: 'wx', mode: 0o600 }), { signal: controller.signal });
         if (!size || (declaredLength !== undefined && size !== declaredLength))
             throw new WorkspaceTransferError('invalid_workspace_transfer');
         const lockKeys = [...new Set([...directories.map(name => `directory:${workspaceId}:${name}`),

package/dist/workspace-runtime/workspaces/append-only-log.js

@@ -18,7 +18,9 @@ export class AppendOnlyLog {
     async append(chunk) {
         if (!chunk)
             return;
+        // private
         await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        // private
         const handle = await open(this.path, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW, 0o600);
         try {
             await handle.write(Buffer.from(chunk));
@@ -34,6 +36,7 @@ export class AppendOnlyLog {
         const tail = content.subarray(Math.max(0, content.length - (this.maxBytes - notice.length)));
         const temporary = `${this.path}.${randomUUID()}.tmp`;
         try {
+            // private
             await writeFile(temporary, Buffer.concat([notice, tail]), { mode: 0o600 });
             await rename(temporary, this.path);
         }

package/dist/workspace-runtime/workspaces/artifact-events.js

@@ -6,14 +6,17 @@ import { watch } from 'chokidar';
 import { join, relative, sep } from 'node:path';
 import { readdir } from 'node:fs/promises';
 import { generatedWorkspace } from './artifact-receipts.js';
+import { withShareRepair } from './workspace-shares.js';
 export async function refreshWorkspaceArtifacts(state, workspaceId, origin, directoryName = 'basic') {
     if (state.journal.destroyed())
         throw new Error('runtime_destroyed');
     const root = await workspaceRoot(state, workspaceId, directoryName);
     const active = state.journal.listSessions().some(session => session.workspaceId === workspaceId
         && (session.directoryName ?? 'basic') === directoryName && ['starting', 'running', 'waiting_for_user'].includes(session.turnStatus ?? ''));
-    const result = await new WorkspaceArtifactStore(state.config.stateDir, workspaceId, directoryName)
-        .discover(root, origin?.source, origin?.paths, origin?.playable ?? (active ? { mode: 'hold' } : {}));
+    const store = new WorkspaceArtifactStore(state.config.stateDir, workspaceId, directoryName);
+    // A scan that hits a drifted directory repairs it once as the owner and retries, so a transient
+    // EACCES never turns artifact discovery into a 500 for the session.
+    const result = await withShareRepair(state, root, () => store.discover(root, origin?.source, origin?.paths, origin?.playable ?? (active ? { mode: 'hold' } : {})));
     if (result.changed && !state.journal.destroyed()) {
         const event = await state.journal.allocateSourceEvent({
             runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,

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

@@ -3,6 +3,7 @@ import { constants } from 'node:fs';
 import { lstat, mkdir, open, readFile, realpath, link, unlink } from 'node:fs/promises';
 import { extname, join, posix, resolve, sep } from 'node:path';
 import { WORKSPACE_ARTIFACT_MAX_BYTES, isWorkspaceArtifactOutputPath, workspaceRelativePathSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { openSharedFile } from './shared-write.js';
 const formats = {
     '.png': ['image', 'image/png'], '.jpg': ['image', 'image/jpeg'], '.jpeg': ['image', 'image/jpeg'],
     '.webp': ['image', 'image/webp'], '.gif': ['image', 'image/gif'], '.avif': ['image', 'image/avif'], '.svg': ['image', 'image/svg+xml'],
@@ -34,10 +35,12 @@ export async function artifactPath(root, path) {
         throw new Error('invalid_artifact_path');
     return target;
 }
+/** Private catalog storage: only the controller reads the runtime state directory. */
 export async function artifactDirectory(root, relative) {
     let target = await realpath(root);
     for (const part of workspaceRelativePathSchema.parse(relative).split('/')) {
         target = join(target, part);
+        // private
         await mkdir(target, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
             throw error; });
         const stat = await lstat(target);
@@ -47,7 +50,7 @@ export async function artifactDirectory(root, relative) {
     return target;
 }
 /** Copies the exact bytes observed, and refuses a file changed while being copied. */
-export async function snapshotArtifactFile(root, path, objects, role = 'primary') {
+export async function snapshotArtifactFile(root, path, objects, role = 'primary', shared = false) {
     const target = await artifactPath(root, path);
     const source = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
     const temporary = join(objects, `${randomUUID()}.tmp`);
@@ -56,9 +59,12 @@ export async function snapshotArtifactFile(root, path, objects, role = 'primary'
         const before = await source.stat();
         if (!before.isFile() || before.nlink !== 1 || before.size > WORKSPACE_ARTIFACT_MAX_BYTES)
             throw new Error('artifact_file_unavailable');
-        // Objects are written by whichever identity generates the artifact and read by the other.
-        output = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o660);
-        await output.chmod(0o660);
+        // Workspace receipts are written by whichever identity generates the artifact and read by the
+        // other; the controller's own object store stays private.
+        output = shared
+            ? await openSharedFile(root, temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW)
+            // private
+            : await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
         const hash = createHash('sha256'), buffer = Buffer.allocUnsafe(64 * 1024);
         let size = 0;
         for (;;) {
@@ -176,16 +182,16 @@ export async function artifactResources(root, path) {
         throw new Error('artifact_too_many_resources');
     return [...resources].sort();
 }
-export async function snapshotArtifactBundle(root, path, objects, thumbnailPath) {
+export async function snapshotArtifactBundle(root, path, objects, thumbnailPath, shared = false) {
     if (!isWorkspaceArtifactOutputPath(path) || (thumbnailPath !== undefined && !isWorkspaceArtifactOutputPath(thumbnailPath)))
         throw new Error('invalid_artifact_path');
     const resources = await artifactResources(root, path);
-    const files = [await snapshotArtifactFile(root, path, objects)];
+    const files = [await snapshotArtifactFile(root, path, objects, 'primary', shared)];
     for (const resource of resources)
         if (resource !== path)
-            files.push(await snapshotArtifactFile(root, resource, objects, 'resource'));
+            files.push(await snapshotArtifactFile(root, resource, objects, 'resource', shared));
     if (thumbnailPath && !files.some(file => file.path === thumbnailPath))
-        files.push(await snapshotArtifactFile(root, thumbnailPath, objects, 'thumbnail'));
+        files.push(await snapshotArtifactFile(root, thumbnailPath, objects, 'thumbnail', shared));
     if (files.reduce((size, file) => size + file.size, 0) > WORKSPACE_ARTIFACT_MAX_BYTES)
         throw new Error('artifact_bundle_too_large');
     return files;

package/dist/workspace-runtime/workspaces/artifact-receipts.js

@@ -3,9 +3,9 @@ import { constants } from 'node:fs';
 import { lstat, open, rename, unlink } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { isWorkspaceArtifactOutputPath, workspaceArtifactReceiptSchema } from '@playcraft/common/cloud-workspace/runtime';
-import { artifactDirectory, artifactFormat, relativeArtifactPath, snapshotArtifactBundle } from './artifact-files.js';
-import { shareWorkspaceAssetDirectory } from './asset-publication-access.js';
+import { artifactFormat, relativeArtifactPath, snapshotArtifactBundle } from './artifact-files.js';
 import { excludeFromGit } from './dependencies.js';
+import { ensureSharedDirectory, openSharedFile } from './shared-write.js';
 export const ARTIFACT_RECEIPTS_DIRECTORY = '.playcraft/artifact-receipts';
 export const artifactReceiptSchema = workspaceArtifactReceiptSchema;
 export async function generatedWorkspace(cwd) {
@@ -33,21 +33,6 @@ export async function generatedWorkspace(cwd) {
             return undefined;
     }
 }
-/**
- * The receipt tree is written by the development identity and read by the controller. A directory
- * the other identity created cannot be re-shaped here; its owner repairs it on the next write and
- * readers keep working from whatever already carries the shared bits.
- */
-async function shareArtifactDirectory(root, directory) {
-    try {
-        await shareWorkspaceAssetDirectory(root, directory);
-    }
-    catch (error) {
-        const code = error.code;
-        if (code !== 'EACCES' && code !== 'EPERM')
-            throw error;
-    }
-}
 /** Preserve final outputs before another command overwrites them; intermediate project assets are not registered. */
 export async function captureGeneratedArtifact(output, tool, metadata = {}, cwd = process.cwd(), expectedDigest, origin) {
     const context = await generatedWorkspace(cwd);
@@ -63,13 +48,11 @@ export async function captureGeneratedArtifact(output, tool, metadata = {}, cwd
     }
     if (!isWorkspaceArtifactOutputPath(path) || !artifactFormat(path))
         return;
-    const receipts = await artifactDirectory(context.root, ARTIFACT_RECEIPTS_DIRECTORY);
-    const objects = await artifactDirectory(context.root, `${ARTIFACT_RECEIPTS_DIRECTORY}/objects`);
-    // Generations are written as the development identity while the controller scans this tree.
-    await shareArtifactDirectory(context.root, receipts);
-    await shareArtifactDirectory(context.root, objects);
+    // Generations are written by whichever identity runs the tool; the controller scans the same tree.
+    const receipts = await ensureSharedDirectory(context.root, join(context.root, ARTIFACT_RECEIPTS_DIRECTORY));
+    const objects = await ensureSharedDirectory(context.root, join(context.root, ARTIFACT_RECEIPTS_DIRECTORY, 'objects'));
     const thumbnailPath = metadata.thumbnailPath ? relativeArtifactPath(context.root, resolve(cwd, metadata.thumbnailPath)) : undefined;
-    const files = await snapshotArtifactBundle(context.root, path, objects, thumbnailPath);
+    const files = await snapshotArtifactBundle(context.root, path, objects, thumbnailPath, true);
     if (expectedDigest && files.find(file => file.role === 'primary')?.sha256 !== expectedDigest)
         throw new Error('artifact_file_changed');
     const receipt = artifactReceiptSchema.parse({
@@ -80,9 +63,8 @@ export async function captureGeneratedArtifact(output, tool, metadata = {}, cwd
         ...(metadata.duration !== undefined ? { duration: metadata.duration } : {}),
     });
     const temporary = join(receipts, `${receipt.id}.tmp`);
-    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o660);
+    const handle = await openSharedFile(context.root, temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW);
     try {
-        await handle.chmod(0o660);
         await handle.writeFile(`${JSON.stringify(receipt)}\n`);
         await handle.sync();
         await handle.close();

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

@@ -6,6 +6,7 @@ import sharp from 'sharp';
 import { WORKSPACE_ARTIFACT_OUTPUT_DIRECTORY, isWorkspaceArtifactOutputPath, isWorkspaceArtifactOutputVersion, workspaceArtifactContentQuerySchema, workspaceArtifactListSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { artifactBundleDigest, artifactDirectory, artifactFormat, artifactPath, artifactResources, snapshotArtifactBundle, snapshotArtifactFile } from './artifact-files.js';
 import { ARTIFACT_RECEIPTS_DIRECTORY, readArtifactReceipt } from './artifact-receipts.js';
+import { ensureSharedDirectory } from './shared-write.js';
 import { validateWorkspacePlayable } from '../previews/finalize.js';
 import { PREVIEW_HTML_MAX_BYTES, WORKSPACE_PLAYABLE_OUTPUT_PATH } from '@playcraft/common/cloud-workspace/runtime';
 const serial = new Map();
@@ -35,6 +36,7 @@ export class WorkspaceArtifactStore {
     }
     get scopeId() { return this.directoryName === 'basic' ? this.workspaceId : `${this.workspaceId}:${this.directoryName}`; }
     async directory() {
+        // private
         await mkdir(this.stateDir, { recursive: true, mode: 0o700 });
         return artifactDirectory(this.stateDir, `artifacts/${digest(this.scopeId)}`);
     }
@@ -64,6 +66,7 @@ export class WorkspaceArtifactStore {
     }
     async write(directory, catalog) {
         const temporary = join(directory, `${randomUUID()}.tmp`);
+        // private
         const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
         try {
             await handle.writeFile(JSON.stringify(catalog));
@@ -281,7 +284,7 @@ export class WorkspaceArtifactStore {
             const target = join(root, ARTIFACT_RECEIPTS_DIRECTORY);
             if (!(await lstat(target)).isDirectory())
                 return [];
-            directory = await artifactDirectory(root, ARTIFACT_RECEIPTS_DIRECTORY);
+            directory = await ensureSharedDirectory(root, target);
         }
         catch {
             return [];

package/dist/workspace-runtime/workspaces/asset-library-import.js

@@ -5,6 +5,7 @@ import { basename, dirname, extname, join, relative } from 'node:path';
 import { BINARY_WORKSPACE_FILE_MAX_BYTES, WORKSPACE_LIBRARY_ATTACHMENT_MAX_BYTES, WORKSPACE_LIBRARY_ATTACHMENT_MAX_FILES, workspaceAssetLibraryImportPayloadSchema, workspaceAssetLibraryImportResultSchema, workspaceAssetLibraryImportTransportSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { observeWorkspaceBinaryFile, writeWorkspaceBinaryFile } from './binary-write.js';
 import { shareWorkspaceAssetDirectory } from './asset-publication-access.js';
+import { ensureSharedDirectory } from './shared-write.js';
 const RESERVED = new Set(['.git', 'node_modules', '.playcraft-temp', '.tmp']);
 const digest = (value) => createHash('sha256').update(value).digest('hex');
 const missing = (error) => error?.code === 'ENOENT';
@@ -23,6 +24,7 @@ async function safeDirectory(root, path, create = false) {
     let current = root;
     for (const part of path.split('/').filter(Boolean)) {
         current = join(current, part);
+        // private
         if (create)
             await mkdir(current, { mode: 0o700 }).catch((error) => {
                 if (error.code !== 'EEXIST')
@@ -47,8 +49,7 @@ async function createPublicDirectory(root, path) {
             if (!missing(error))
                 throw error;
             await safeDirectory(root, parent);
-            await mkdir(join(root, current), { mode: 0o700 });
-            await shareWorkspaceAssetDirectory(root, join(root, current));
+            await ensureSharedDirectory(root, join(root, current));
             await safeDirectory(root, current);
         }
     }
@@ -127,6 +128,7 @@ async function syncDirectory(path) {
 async function saveTransaction(root, transaction, value) {
     await safeDirectory(root, relative(root, transaction));
     const temporary = join(transaction, 'manifest.next');
+    // private
     const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o600);
     try {
         await handle.writeFile(JSON.stringify(value));
@@ -181,6 +183,8 @@ export async function recoverInterruptedLibraryImports(root) {
             return result;
         throw error;
     }
+    // The shared scratch root is where both identities create their own private transactions.
+    await ensureSharedDirectory(rootReal, scratch);
     for (const entry of await readdir(scratch, { withFileTypes: true })) {
         if (!entry.isDirectory() || !entry.name.startsWith('library-import-'))
             continue;
@@ -239,9 +243,10 @@ async function publishBundle(root, target, asset, replace, assertCurrent, operat
     if (previous && (!replace || !previous.isDirectory() || previous.isSymbolicLink()))
         throw new AssetLibraryImportError('content_conflict');
     const originalHash = previous ? await directorySnapshot(join(root, target)) : undefined;
-    const scratch = await safeDirectory(root, '.playcraft-temp', true);
+    const scratch = await ensureSharedDirectory(root, join(root, '.playcraft-temp'));
     const transaction = await mkdtemp(join(scratch, 'library-import-'));
     const staged = join(transaction, 'incoming'), backup = join(transaction, 'previous');
+    // private
     await mkdir(staged, { mode: 0o700 });
     let moved = false, published = false, preserve = false;
     let reservation;
@@ -271,7 +276,7 @@ async function publishBundle(root, target, asset, replace, assertCurrent, operat
         }
         else if (current)
             throw new AssetLibraryImportError('content_conflict');
-        await mkdir(join(root, target), { mode: 0o700 });
+        await ensureSharedDirectory(root, join(root, target));
         reservation = await lstat(join(root, target));
         await saveTransaction(root, transaction, { ...manifest, phase: 'reserved', reservation: { dev: reservation.dev, ino: reservation.ino } });
         await assertCurrent();

package/dist/workspace-runtime/workspaces/asset-publication-access.js

@@ -1,19 +1,17 @@
 import { constants } from 'node:fs';
 import { lstat, open } from 'node:fs/promises';
+import { SHARED_DIRECTORY_MODE, SHARED_FILE_MODE, shareHandleWithGroup, } from './shared-write.js';
+/**
+ * Published workspace assets belong to the development group so both identities can read and edit
+ * them. Private transfers, chunks, transaction records and backups never use these helpers.
+ */
 async function shareWithWorkspaceGroup(root, handle, directory) {
     const workspace = await lstat(root), target = await handle.stat();
     if (!workspace.isDirectory() || workspace.isSymbolicLink()
         || (directory ? !target.isDirectory() : !target.isFile() || target.nlink !== 1))
         throw new Error('invalid_workspace_asset');
-    const shared = directory ? 0o2770 : 0o660;
-    // Already shared: the other identity owns this entry and cannot re-shape it from here.
-    if (target.gid === workspace.gid && (target.mode & 0o7777) === shared)
-        return;
-    if (target.gid !== workspace.gid)
-        await handle.chown(target.uid, workspace.gid);
-    // Match directory-access.ts: the development group can read and edit public project files.
-    // Private transfers, chunks, transaction records and backups never use these helpers.
-    await handle.chmod(shared);
+    // Already shared or owned by the other identity: shaping is a no-op, never a cross-owner EPERM.
+    await shareHandleWithGroup(handle, workspace.gid, directory ? SHARED_DIRECTORY_MODE : SHARED_FILE_MODE);
 }
 export async function shareWorkspaceAssetFile(root, handle) {
     await shareWithWorkspaceGroup(root, handle, false);

package/dist/workspace-runtime/workspaces/asset-transfer-publish.js

@@ -40,6 +40,7 @@ async function assemble(transfer) {
     const staged = [];
     for (const [index, file] of transfer.record.manifest.files.entries()) {
         const destination = join(transfer.directory, 'incoming', String(index));
+        // private
         const output = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
         const hash = createHash('sha256');
         try {
@@ -120,6 +121,7 @@ async function createDirectories(transfer, path) {
             if (!assetTransferMissing(error))
                 throw error;
             await safeAssetTransferDirectory(transfer.root, dirname(directory) === '.' ? '' : dirname(directory));
+            // private
             await mkdir(join(transfer.root, directory), { mode: 0o700 });
             await shareWorkspaceAssetDirectory(transfer.root, join(transfer.root, directory));
             const stat = await lstat(await safeAssetTransferDirectory(transfer.root, directory));
@@ -146,6 +148,7 @@ async function ensureDirectoryMarkers(transfer) {
         const parent = await safeAssetTransferDirectory(transfer.root, path);
         const marker = join(parent, '.gitkeep');
         try {
+            // private
             const handle = await open(marker, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
             try {
                 await shareWorkspaceAssetFile(transfer.root, handle);