@playcraft/cli 0.1.58-beta → 0.1.59-beta

package/dist/workspace-runtime/codex/loopback.js

@@ -87,6 +87,8 @@ export function createLoopbackNativeAdapter() {
             if (!thread || thread.sessionId !== input.sessionId)
                 return { outcome: 'uncertain' };
             const turnId = thread.turnId;
+            if (input.expectedTurnId !== undefined && input.expectedTurnId !== turnId)
+                return { outcome: 'failed', error: 'turn_changed' };
             queueMicrotask(() => {
                 emit(collectedEvent('notification', 'turn/completed', {
                     threadId: input.threadId,

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

@@ -52,7 +52,7 @@ export class WorkspaceModelBroker {
         activate();
         return settings;
     }
-    async prepareThreadConfig(cwd, modelConfigId, sessionId, reasoningEffort, clientRequestId) {
+    async prepareThreadConfig(cwd, modelConfigId, sessionId, reasoningEffort, clientRequestId, originCwd) {
         if (!this.server)
             throw new Error('workspace_not_registered');
         const { workspaceId } = await workspaceContextFromRoot(this.state, cwd);
@@ -61,11 +61,12 @@ export class WorkspaceModelBroker {
         const routeKey = sessionId ? `${workspaceId}/${createHash('sha256').update(sessionId).digest('hex').slice(0, 32)}` : workspaceId;
         let route = this.routes.get(routeKey);
         const selected = modelConfigId ?? (route?.epoch === this.state.runtimeEpoch ? route.selected?.entry.modelConfigId : undefined);
-        const cacheKey = `${workspaceId}:${selected ?? 'default'}:${reasoningEffort ?? 'default'}`;
+        const cacheKey = `${workspaceId}:${selected ?? 'default'}:${reasoningEffort ?? 'default'}:${sessionId ?? ''}:${clientRequestId ?? ''}`;
         let entry = this.entries.get(cacheKey) ?? [...this.entries.values()].find(item => item.workspaceId === workspaceId && item.epoch === this.state.runtimeEpoch && item.modelConfigId === selected
+            && item.sessionId === sessionId && item.clientRequestId === clientRequestId
             && item.reasoningEffort === reasoningEffort);
         if (!entry || entry.epoch !== this.state.runtimeEpoch) {
-            entry = { workspaceId, epoch: this.state.runtimeEpoch, cacheKey, modelConfigId: selected, reasoningEffort };
+            entry = { workspaceId, epoch: this.state.runtimeEpoch, cacheKey, modelConfigId: selected, reasoningEffort, sessionId, clientRequestId };
             this.entries.set(cacheKey, entry);
         }
         // Resolve current model metadata and permission at every native turn boundary.
@@ -82,7 +83,7 @@ export class WorkspaceModelBroker {
                 if (!this.valid(entry) || this.routes.get(routeKey) !== route)
                     throw new Error('model_access_denied');
                 route.selected = { entry, model: credential.model,
-                    ...(sessionId && clientRequestId ? { feedback: { sessionId, clientRequestId, cwd, boundaryId } } : {}) };
+                    ...(sessionId && clientRequestId ? { feedback: { sessionId, clientRequestId, cwd, boundaryId, ...(originCwd ? { originCwd } : {}) } } : {}) };
             },
             model: credential.model,
             modelConfigId: credential.configId,
@@ -125,6 +126,8 @@ export class WorkspaceModelBroker {
             headers: { authorization: `Bearer ${config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': config.environment },
             body: JSON.stringify({ runtimeId: config.runtimeId, generation: config.generation,
                 runtimeEpoch: entry.epoch, workspaceId: entry.workspaceId,
+                ...(entry.sessionId ? { sessionId: entry.sessionId } : {}),
+                ...(entry.clientRequestId ? { clientRequestId: entry.clientRequestId } : {}),
                 ...(entry.modelConfigId ? { modelConfigId: entry.modelConfigId } : {}),
                 ...(entry.reasoningEffort ? { reasoningEffort: entry.reasoningEffort } : {}) }),
         });

package/dist/workspace-runtime/serve.js

@@ -12,7 +12,7 @@ import { attachNativeCollector, executeOperation, recoverInterruptedParameterVer
 import { restoreDeferredDirectoryOperations } from './server/directory-access.js';
 import { handleRuntimeRequest } from './server/http.js';
 import { desktopHost, disposeDesktopHost } from './server/desktop-host.js';
-import { disposeTerminalHost, terminalHost } from './server/terminal-host.js';
+import { disposeTerminalHost, retireStoppedTerminals, terminalHost } from './server/terminal-host.js';
 import { handleExecutionGroupCrash } from './server/execution-group.js';
 import { RuntimeProcessLock } from './server/lock.js';
 import { probeGitBinary } from './workspaces/git.js';
@@ -58,6 +58,7 @@ export async function startWorkspaceRuntime(config, options = {}) {
         await recoverInterruptedPreviews(journal);
         await recoverInterruptedParameterVerifications(journal);
         await recoverInterruptedDeliveries(config.stateDir);
+        await retireStoppedTerminals(journal, config.runtimeEpoch, previousEpoch);
         // shared: in multi-workspace mode this is /workspaces, the container both identities traverse.
         await mkdir(config.workspaceRoot, { recursive: true, mode: 0o2770 });
         const state = runtimeState = {

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

@@ -8,7 +8,7 @@ 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',
+const EXCLUSIVE_OPERATIONS = new Set(['preview.publish', 'delivery.build', 'directory.create',
     'directory.rename', 'directory.delete', 'workspace.references.import', 'skills.update', 'parameter.verify',
     'checkpoint.create', 'checkpoint.restore']);
 export function managedDirectoryScope(state, value) {

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

@@ -33,6 +33,7 @@ import { previewFailureCode, previewWorkspaceRoot, runPreviewPublish, trackPrevi
 import { startManagedBackgroundWriter, stopBackgroundWriter, } from '../processes/managed-writes.js';
 import { wakeSourceEventUploader } from './source-uploader.js';
 import { batchDirectoryHeld } from '../batch/occupancy.js';
+import { trustedMemberPolicy } from '../batch/policy.js';
 import { BinaryWorkspaceWriteError, observeWorkspaceBinaryFile, writeWorkspaceBinaryFile } from '../workspaces/binary-write.js';
 import { importWorkspaceLibraryAssets } from '../workspaces/asset-library-import.js';
 import { createWorkspaceDirectory, WorkspaceDirectoryCreateError } from '../workspaces/directory-create.js';
@@ -217,7 +218,7 @@ async function executeScopedOperation(state, scopeKey, operation, payload, recov
         if (operation.kind === 'session.steer')
             return executeSteer(state, scopeKey, current, payload);
         if (operation.kind === 'session.interrupt') {
-            return executeInterrupt(state, scopeKey, current);
+            return executeInterrupt(state, scopeKey, current, payload);
         }
         if (operation.kind === 'session.approval.respond') {
             return executeApproval(state, scopeKey, current, payload);
@@ -455,7 +456,7 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
             ...(typeof body.teamId === 'string' ? { teamId: body.teamId } : {}) })}\n\n`
         : '';
     const engineeringBatchContext = state.config.workspaceMode === 'multi' && operation.workspaceId
-        && operation.directoryName !== 'root' && !productionSessionAttemptId(sessionId)
+        && operation.directoryName !== 'root' && !productionSessionAttemptId(sessionId) && !trustedMemberPolicy(state, sessionId)
         ? `PlayCraft batch request context (trusted runtime identity): ${JSON.stringify({ workspaceId: operation.workspaceId,
             clientRequestId: operation.clientRequestId, sourceDirectoryName: binding.directoryName ?? 'basic',
             ...(typeof body.teamId === 'string' ? { teamId: body.teamId } : {}) })}`
@@ -849,13 +850,18 @@ async function executeSteer(state, scopeKey, operation, payload) {
             } }]);
     return persist(state, scopeKey, transitionOperation(accepted, 'completed'));
 }
-async function executeInterrupt(state, scopeKey, operation) {
+async function executeInterrupt(state, scopeKey, operation, payload) {
     const sessionId = required(operation.sessionId, 'sessionId');
     const binding = state.journal.getSession(sessionId);
     if (!binding) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'unknown_session' }));
     }
-    const result = await native(state).interrupt({ sessionId, threadId: binding.threadId });
+    const expectedTurnId = asRecord(payload).expectedTurnId;
+    if (expectedTurnId !== undefined && (typeof expectedTurnId !== 'string' || !expectedTurnId
+        || binding.activeTurnId !== expectedTurnId))
+        return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'turn_changed' }));
+    const result = await native(state).interrupt({ sessionId, threadId: binding.threadId,
+        ...(typeof expectedTurnId === 'string' ? { expectedTurnId } : {}) });
     if (result.outcome === 'failed') {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: result.error ?? 'turn_not_running' }));
     }
@@ -1273,11 +1279,12 @@ async function executeWorkspaceSave(state, scopeKey, operation, payload) {
     }
     const binding = operation.workspaceId ? state.journal.getWorkspace(operation.workspaceId) : undefined;
     try {
-        const saved = await saveWorkspaceGit(await gitWorkspaceRoot(state, operation), {
+        // Saves share the directory, and a deferred one runs outside the workspace queue; commit one at a time.
+        const saved = await state.journal.exclusive(`workspace-save:${revisionScope(state, operation.workspaceId, operation.directoryName) ?? 'single'}`, async () => saveWorkspaceGit(await gitWorkspaceRoot(state, operation), {
             message: parsed.data.trigger === 'auto' ? 'Autosave workspace' : 'Save workspace',
             push: savePushesBranch(binding?.targetKind, operation.directoryName),
             boundBranch: boundBranch(state, operation),
-        });
+        }));
         const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));
         await recordNativeEvents(state, accepted, [
             {

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

@@ -41,6 +41,7 @@ import { workspaceArtifactContentQuerySchema } from '@playcraft/common/cloud-wor
 import { searchWorkspaceFiles } from '../workspaces/files-search.js';
 import { serveWorkspaceArchive } from '../workspaces/archive.js';
 import { handleWorkspaceTransfer } from './workspace-transfer.js';
+import { handleWorkspaceStorage } from './workspace-storage.js';
 import { serveSessionImage } from '../workspaces/session-image.js';
 import { restoreNativeSession, SessionRestoreError } from './session-restore.js';
 import { handleAssetTransferRequest } from './asset-transfers.js';
@@ -51,7 +52,8 @@ export async function handleRuntimeRequest(state, request, response) {
     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);
+        url.pathname.startsWith('/runtime/batch-') || /^\/runtime\/sessions\/[^/]+\/ui-results$/.test(url.pathname) ||
+        /^\/runtime\/sessions\/[^/]+\/prediction$/.test(url.pathname);
     if (authorizeRuntime(state, request) === 'control' && workspaceId &&
         (!['GET', 'HEAD', 'OPTIONS'].includes(request.method ?? 'GET') || url.pathname === '/runtime/git-bundle') && !ownLease) {
         try {
@@ -82,6 +84,8 @@ async function dispatchRuntimeRequest(state, request, response) {
         return;
     }
     try {
+        if (await handleWorkspaceStorage(state, request, response, url))
+            return;
         const transfer = await handleAssetTransferRequest(state, request, url);
         if (transfer) {
             writeJson(response, transfer.status, transfer.body);
@@ -128,6 +132,8 @@ async function dispatchRuntimeRequest(state, request, response) {
                 instanceToken: state.instanceToken,
                 permissionsVersion: 1,
                 composerContextVersion: 1,
+                scheduledTaskIdentityVersion: 1,
+                scheduledTaskCancellationVersion: 1,
                 parameterAgentVersion: 1,
                 directoryConcurrencyVersion: 1,
                 parameterInitializationVersion: 1,
@@ -136,6 +142,7 @@ async function dispatchRuntimeRequest(state, request, response) {
                 ...(state.native?.workspaceUi ? { workspaceUiVersion: 1 } : {}),
                 ...(state.native?.startReview && state.native?.steer ? { turnControlVersion: 1 } : {}),
                 ...(state.native?.startCompact ? { compactionVersion: 1 } : {}),
+                ...(state.native?.startPrediction ? { predictionVersion: 1 } : {}),
                 sourceReadToken: state.journal.sourceReadToken(),
                 workspaceMode: state.config.workspaceMode,
                 executionGroup: {
@@ -208,6 +215,27 @@ async function dispatchRuntimeRequest(state, request, response) {
             writeJson(response, result.outcome === 'accepted' ? 200 : 409, result);
             return;
         }
+        const predictionRoute = /^\/runtime\/sessions\/([^/]+)\/prediction$/.exec(url.pathname);
+        if (request.method === 'POST' && predictionRoute) {
+            if (writeDestroyed(state, response))
+                return;
+            const sessionId = decodeURIComponent(predictionRoute[1]);
+            const session = state.journal.getSession(sessionId);
+            if (!session || productionSessionAttemptId(sessionId) || session.workspaceId !== url.searchParams.get('workspaceId')
+                || (session.directoryName ?? 'basic') !== directoryName) {
+                writeJson(response, 404, { error: 'session_not_found' });
+                return;
+            }
+            if (!state.native?.startPrediction) {
+                writeJson(response, 409, { error: 'prediction_unavailable' });
+                return;
+            }
+            // Best-effort and read-only: no instruction/journal reservation, and the ephemeral
+            // fork never becomes a user-visible thread.
+            const result = await state.native.startPrediction({ sessionId, threadId: session.threadId });
+            writeJson(response, result.outcome === 'ok' ? 200 : 409, result);
+            return;
+        }
         if (request.method === 'POST' && url.pathname === '/runtime/workspaces/register') {
             if (writeDestroyed(state, response))
                 return;

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';
@@ -12,11 +13,19 @@ 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) {
@@ -25,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);
@@ -41,10 +64,14 @@ export class TerminalHost {
     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');
@@ -152,7 +179,28 @@ export class TerminalHost {
         session.listeners.clear();
         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');
@@ -199,6 +247,7 @@ export class TerminalHost {
                 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); } } };
@@ -233,6 +282,8 @@ export class TerminalHost {
                 cwd,
                 env: shellEnv(command.file, cwd),
             }),
+            pid: 0,
+            lastActivity: Date.now(),
             stop: async () => {
                 if (!didExit)
                     session.pty.kill();
@@ -250,6 +301,7 @@ export class TerminalHost {
             },
         };
         const local = session.pty;
+        session.pid = local.pid;
         local.onData((data) => publish(session, data));
         local.onExit(({ exitCode, signal }) => {
             finishExit();
@@ -297,6 +349,7 @@ export class TerminalHost {
             send(frame);
         };
         session.listeners.add(listener);
+        session.lastActivity = Date.now();
         ws.on('message', (raw) => {
             let body;
             try {
@@ -332,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;
@@ -341,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);
@@ -361,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;
+}