@playcraft/cli 0.1.57-beta → 0.1.59-beta

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

@@ -1,6 +1,7 @@
 import { batchDirectoryHeld } from '../batch/occupancy.js';
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
+import { readdirSync, readFileSync } from 'node:fs';
 import { lstat } from 'node:fs/promises';
 import { StringDecoder } from 'node:string_decoder';
 import { WebSocketServer } from 'ws';
@@ -8,13 +9,23 @@ 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);
+/** A shell nobody views, silent this long and running nothing besides itself, is closed. */
+const IDLE_RECLAIM_MS = 30 * 60_000;
+const IDLE_SWEEP_MS = 120_000;
 const commands = new WeakMap();
+const sessionProbes = new WeakMap();
 const hosts = new WeakMap();
 export function setTerminalCommand(state, command) {
     commands.set(state, command);
 }
+/** Replaces the /proc session scan, for platforms without /proc. */
+export function setTerminalSessionProbe(state, probe) {
+    sessionProbes.set(state, probe);
+}
 export function terminalHost(state) {
     let host = hosts.get(state);
     if (!host) {
@@ -23,6 +34,20 @@ export function terminalHost(state) {
     }
     return host;
 }
+/**
+ * The supervisor advances the runtime epoch only after the launcher confirms that every process it
+ * started, terminals included, has exited. A terminal from an earlier epoch is gone whatever its record says.
+ */
+export async function retireStoppedTerminals(journal, runtimeEpoch, previousEpoch) {
+    if (previousEpoch === undefined || runtimeEpoch <= previousEpoch)
+        return;
+    const destroyedAt = new Date().toISOString();
+    for (const terminal of journal.listTerminals()) {
+        if (terminal.status === 'destroyed' || (terminal.runtimeEpoch ?? 0) >= runtimeEpoch)
+            continue;
+        await journal.putTerminal({ ...terminal, status: 'destroyed', destroyedAt });
+    }
+}
 export function disposeTerminalHost(state) {
     hosts.get(state)?.dispose();
     hosts.delete(state);
@@ -37,11 +62,16 @@ export class TerminalHost {
     closing = new Set();
     stops = new Map();
     confirmed = new Set();
+    directoryReleases = new Map();
     sockets = new WebSocketServer({ noServer: true });
+    idleSweep;
     constructor(state) {
         this.state = state;
+        this.idleSweep = setInterval(() => void this.reclaimIdle(), IDLE_SWEEP_MS);
+        this.idleSweep.unref?.();
         // An absent in-memory session cannot prove a restored terminal's old process group stopped.
-        this.restored = new Set((state.journal?.listTerminals?.() ?? []).map(terminal => terminal.terminalId));
+        this.restored = new Set((state.journal?.listTerminals?.() ?? [])
+            .filter(terminal => terminal.status !== 'destroyed').map(terminal => terminal.terminalId));
     }
     async handleUpgrade(request, socket, head) {
         const url = new URL(request.url ?? '/', 'http://127.0.0.1');
@@ -110,7 +140,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 +160,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,20 +177,58 @@ 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);
+    }
+    /** Closes shells with no browser, no input or output for the idle window, and nothing else running. */
+    async reclaimIdle(now = Date.now()) {
+        const reclaimed = [];
+        for (const [terminalId, session] of [...this.sessions]) {
+            if (session.exited || session.listeners.size > 0 || this.closing.has(terminalId)
+                || now - session.lastActivity < IDLE_RECLAIM_MS)
+                continue;
+            // A background job keeps the shell; a session that cannot be inspected is kept too.
+            if (!session.pid || (sessionProbes.get(this.state) ?? runsOtherProcesses)(session.pid) !== false)
+                continue;
+            try {
+                await this.destroy(terminalId);
+                reclaimed.push(terminalId);
+            }
+            catch {
+                // The next sweep tries again.
+            }
         }
+        return reclaimed;
     }
     dispose() {
+        clearInterval(this.idleSweep);
         this.disposed = true;
         for (const terminalId of [...this.sessions.keys()])
             this.revoke(terminalId, 'runtime_destroyed');
         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,9 +243,11 @@ 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(),
+                pid: child.pid ?? 0, lastActivity: Date.now(),
                 stop: () => child.stop(),
                 pty: { write: (data) => { child.stdin?.write(data); }, resize: child.resize,
                     kill: () => { void child.stop().catch(() => undefined); } } };
@@ -204,6 +282,8 @@ export class TerminalHost {
                 cwd,
                 env: shellEnv(command.file, cwd),
             }),
+            pid: 0,
+            lastActivity: Date.now(),
             stop: async () => {
                 if (!didExit)
                     session.pty.kill();
@@ -212,6 +292,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);
@@ -219,8 +301,12 @@ export class TerminalHost {
             },
         };
         const local = session.pty;
+        session.pid = local.pid;
         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 +321,7 @@ export class TerminalHost {
                     });
                 if (terminal)
                     this.confirmed.add(terminalId);
+                this.releaseDirectory(terminalId);
             }
         }
         finally {
@@ -262,6 +349,7 @@ export class TerminalHost {
             send(frame);
         };
         session.listeners.add(listener);
+        session.lastActivity = Date.now();
         ws.on('message', (raw) => {
             let body;
             try {
@@ -297,6 +385,7 @@ export class TerminalHost {
             }
             if (!resumed)
                 return;
+            session.lastActivity = Date.now();
             if (frame.type === 'resize') {
                 session.pty.resize(frame.cols, frame.rows);
                 return;
@@ -306,12 +395,14 @@ export class TerminalHost {
         const detach = () => {
             open = false;
             session.listeners.delete(listener);
+            session.lastActivity = Date.now();
         };
         ws.on('close', detach);
         ws.on('error', detach);
     }
 }
 function publish(session, text) {
+    session.lastActivity = Date.now();
     const before = session.log.end;
     session.log = appendTerminalOutput(session.log, text);
     const since = terminalOutputSince(session.log, before);
@@ -326,6 +417,31 @@ function publish(session, text) {
             listener(frame);
     }
 }
+/** `true` while a process other than the shell runs in its session; `undefined` when /proc cannot tell. */
+function runsOtherProcesses(shellPid) {
+    let names;
+    try {
+        names = readdirSync('/proc');
+    }
+    catch {
+        return undefined;
+    }
+    for (const name of names) {
+        if (!/^\d+$/.test(name) || Number(name) === shellPid)
+            continue;
+        try {
+            const stat = readFileSync(`/proc/${name}/stat`, 'utf8');
+            const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+            if (Number(fields[3]) === shellPid && !['Z', 'X'].includes(fields[0] ?? ''))
+                return true;
+        }
+        catch (error) {
+            if (!['ENOENT', 'ESRCH'].includes(error.code ?? ''))
+                return undefined;
+        }
+    }
+    return false;
+}
 function exitFrame(session) {
     return {
         type: 'exit',

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

@@ -0,0 +1,193 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { workspaceDirectoryOccupied } from '../workspaces/directory-maintenance.js';
+import { openDirectoryToDevelopment } from '../workspaces/directory-access.js';
+import { createStorageSnapshot, extractStorageSnapshot, STORAGE_SNAPSHOT_MAX_BYTES } from '../workspaces/storage-snapshot.js';
+import { withDirectoryWrite } from './directory-access.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+/** Private control routes. Workspace identity survives disk eviction in the runtime journal. */
+export async function handleWorkspaceStorage(state, request, response, url) {
+    const route = /^\/runtime\/workspaces\/([^/]+)\/storage-(status|snapshot|evict|restore)$/.exec(url.pathname);
+    if (!route)
+        return false;
+    const [, workspaceId, action] = route;
+    const json = (status, body) => { response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'private, no-store' }); response.end(JSON.stringify(body)); };
+    const controller = new AbortController(), abort = () => controller.abort();
+    let download;
+    let result;
+    const closed = () => { if (!response.writableEnded)
+        abort(); };
+    request.once('aborted', abort);
+    response.once('close', closed);
+    try {
+        if (state.config.workspaceMode !== 'multi' || !/^[0-9a-f-]{36}$/i.test(workspaceId))
+            throw new Error('storage_snapshot_invalid');
+        if (state.journal.destroyed())
+            throw new Error('runtime_destroyed');
+        if ((action === 'status' || action === 'snapshot') ? request.method !== 'GET' : request.method !== 'POST') {
+            json(405, { error: 'method_not_allowed' });
+            return true;
+        }
+        for (const [name, expected] of [['x-playcraft-generation', state.config.generation], ['x-playcraft-runtime-epoch', state.runtimeEpoch]]) {
+            const value = request.headers[name];
+            if (value !== undefined && value !== String(expected))
+                throw new Error('generation_mismatch');
+        }
+        const parent = await realpath(state.config.workspaceRoot), root = join(parent, workspaceId);
+        const stateRoot = await realpath(state.config.stateDir);
+        if (stateRoot === root || stateRoot.startsWith(`${root}${sep}`))
+            throw new Error('storage_snapshot_invalid');
+        const present = async () => {
+            const info = await lstat(root).catch(error => { if (error.code === 'ENOENT')
+                return undefined; throw error; });
+            if (!info)
+                return false;
+            if (!info.isDirectory() || info.isSymbolicLink() || relative(parent, await realpath(root)) !== workspaceId)
+                throw new Error('storage_snapshot_invalid');
+            return (await readdir(root)).length > 0;
+        };
+        if (action === 'status') {
+            json(200, { present: await present() });
+            return true;
+        }
+        if ((action === 'snapshot' || action === 'evict') && !state.journal.getWorkspace(workspaceId))
+            throw new Error('workspace_not_registered');
+        const directories = [...new Set(['root', 'basic', ...(state.journal.getWorkspace(workspaceId)?.directories ?? []).map(item => item.directoryName)])];
+        const assertIdle = async () => {
+            controller.signal.throwIfAborted();
+            if (state.journal.destroyed())
+                throw new Error('runtime_destroyed');
+            for (const directory of directories)
+                if (await workspaceDirectoryOccupied(state, workspaceId, directory))
+                    throw new Error('workspace_directory_occupied');
+        };
+        await withDirectoryWrite(state, { workspaceId, directoryName: 'root', mode: 'exclusive', wait: false }, async () => {
+            await assertIdle();
+            const markerDir = join(state.config.stateDir, 'workspace-storage'), marker = join(markerDir, `${workspaceId}.json`);
+            if (action === 'snapshot') {
+                if (!(await present()))
+                    throw new Error('workspace_not_prepared');
+                const snapshot = await createStorageSnapshot(root, { signal: controller.signal, excludedRoots: [state.config.stateDir] });
+                try {
+                    await assertIdle();
+                    download = snapshot;
+                }
+                catch (error) {
+                    await snapshot.cleanup();
+                    throw error;
+                }
+                return;
+            }
+            if (action === 'evict') {
+                let body = '';
+                for await (const part of request) {
+                    body += part.toString();
+                    if (body.length > 1024)
+                        throw new Error('storage_snapshot_invalid');
+                }
+                const sha256 = JSON.parse(body).sha256;
+                if (typeof sha256 !== 'string' || !SHA256.test(sha256))
+                    throw new Error('storage_snapshot_invalid');
+                const removed = join(parent, `.storage-evicted-${workspaceId}-${sha256}`);
+                if (!(await present())) {
+                    const saved = await readFile(marker, 'utf8').then(value => JSON.parse(value), () => undefined);
+                    if (saved?.sha256 !== sha256)
+                        throw new Error('storage_snapshot_conflict');
+                    await rm(removed, { recursive: true, force: true });
+                    result = { evicted: true };
+                    return;
+                }
+                const snapshot = await createStorageSnapshot(root, { signal: controller.signal, excludedRoots: [state.config.stateDir] });
+                try {
+                    if (snapshot.sha256 !== sha256)
+                        throw new Error('storage_snapshot_conflict');
+                    await assertIdle();
+                    // private
+                    await mkdir(markerDir, { recursive: true, mode: 0o700 });
+                    const temporary = `${marker}.${randomUUID()}.tmp`;
+                    // private
+                    await writeFile(temporary, JSON.stringify({ sha256 }), { flag: 'wx', mode: 0o600 });
+                    await rename(temporary, marker);
+                    // Moving first makes a partially-deleted directory invisible to readers and safe to retry.
+                    await rename(root, removed);
+                    await rm(removed, { recursive: true, force: true });
+                    result = { evicted: true };
+                }
+                finally {
+                    await snapshot.cleanup();
+                }
+                return;
+            }
+            if (await present())
+                throw new Error('storage_snapshot_destination_exists');
+            const sha256 = request.headers['x-playcraft-snapshot-sha256'];
+            if (typeof sha256 !== 'string' || !SHA256.test(sha256))
+                throw new Error('storage_snapshot_invalid');
+            const rawLength = request.headers['content-length'];
+            if (rawLength !== undefined && (typeof rawLength !== 'string' || !/^\d+$/.test(rawLength) || !Number.isSafeInteger(Number(rawLength)) || Number(rawLength) > STORAGE_SNAPSHOT_MAX_BYTES))
+                throw new Error('storage_snapshot_too_large');
+            const temporary = await mkdtemp(join(parent, '.storage-restore-'));
+            try {
+                const incoming = join(temporary, 'incoming.gz'), staged = join(temporary, 'workspace');
+                const hash = createHash('sha256');
+                let size = 0;
+                await pipeline(Readable.from(request.iterator({ destroyOnReturn: false })), new Transform({ transform(chunk, _encoding, done) {
+                        size += chunk.length;
+                        hash.update(chunk);
+                        done(size > STORAGE_SNAPSHOT_MAX_BYTES ? new Error('storage_snapshot_too_large') : null, chunk);
+                    } }), createWriteStream(incoming, { flags: 'wx', mode: 0o600 }), { signal: controller.signal }); // private
+                if (hash.digest('hex') !== sha256 || rawLength !== undefined && size !== Number(rawLength))
+                    throw new Error('storage_snapshot_checksum_mismatch');
+                // private
+                await mkdir(staged, { mode: 0o700 });
+                await extractStorageSnapshot(incoming, staged, { signal: controller.signal });
+                await openDirectoryToDevelopment(staged, (await lstat(parent)).gid);
+                await assertIdle();
+                if (await present())
+                    throw new Error('storage_snapshot_destination_exists');
+                const evicted = await readFile(marker, 'utf8').then(value => JSON.parse(value), () => undefined);
+                if (typeof evicted?.sha256 === 'string' && SHA256.test(evicted.sha256))
+                    await rm(join(parent, `.storage-evicted-${workspaceId}-${evicted.sha256}`), { recursive: true, force: true });
+                await rmdir(root).catch(error => { if (error.code !== 'ENOENT')
+                    throw error; });
+                await rename(staged, root);
+                await rm(marker, { force: true });
+                result = { restored: true };
+            }
+            finally {
+                await rm(temporary, { recursive: true, force: true });
+            }
+        });
+        if (result)
+            json(200, result);
+        if (download) {
+            const snapshot = download;
+            try {
+                response.writeHead(200, { 'content-type': 'application/octet-stream', 'content-length': snapshot.bytes,
+                    'cache-control': 'private, no-store', 'x-content-type-options': 'nosniff', 'x-playcraft-snapshot-sha256': snapshot.sha256 });
+                await pipeline(createReadStream(snapshot.path), response, { signal: controller.signal });
+            }
+            finally {
+                await snapshot.cleanup();
+            }
+        }
+    }
+    catch (error) {
+        if (response.headersSent)
+            response.destroy(error instanceof Error ? error : undefined);
+        else if (!controller.signal.aborted) {
+            const reason = error instanceof Error ? error.message : '';
+            const code = /^(?:storage_snapshot_[a-z_]+|workspace_(?:not_registered|not_prepared|directory_occupied)|directory_busy|runtime_destroyed|generation_mismatch)$/.test(reason) ? reason : 'storage_snapshot_failed';
+            json(code === 'storage_snapshot_too_large' ? 413 : code === 'storage_snapshot_invalid' ? 400 : 409, { error: code });
+        }
+    }
+    finally {
+        request.off('aborted', abort);
+        response.off('close', closed);
+    }
+    return true;
+}

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();