@playcraft/cli 0.1.42 → 0.1.44-beta

package/dist/workspace-runtime/workspaces/session-image.js

@@ -0,0 +1,104 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { WORKSPACE_ATTACHMENT_MAX_BYTES } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactPath } from './artifact-files.js';
+import { imageMime } from './attachments.js';
+import { sessionWorkspaceRoot } from './registry.js';
+/** Paths come from local history or an authenticated controller's archived conversation item. */
+export async function serveSessionImage(state, request, response, query, recordedPath) {
+    let handle;
+    try {
+        const workspaceId = query.get('workspaceId') ?? '', sessionId = query.get('sessionId') ?? '';
+        const itemId = query.get('itemId') ?? '', directoryName = query.get('directoryName') ?? 'basic';
+        if ([workspaceId, sessionId, itemId].some(id => !id || id.length > 128 || id.includes('\0'))
+            || query.has('path') || state.journal.destroyed())
+            throw new Error('image_not_found');
+        const archivedPath = request.method === 'POST' ? recordedPath : undefined;
+        const session = state.journal.getSession(sessionId);
+        if ((!session && archivedPath === undefined) || (session && (session.workspaceId !== workspaceId
+            || (session.directoryName ?? 'basic') !== directoryName)))
+            throw new Error('image_not_found');
+        const root = await sessionWorkspaceRoot(state, workspaceId, directoryName);
+        let imagePath = archivedPath;
+        for (const event of imagePath ? [] : state.journal.listEvents().reverse()) {
+            if (!['item/started', 'item/completed', 'item.started', 'item.completed'].includes(event.type))
+                continue;
+            const payload = record(event.payload), item = record(payload.item);
+            if (payload.sessionId === sessionId && payload.workspaceId === workspaceId
+                && (payload.directoryName === undefined || payload.directoryName === directoryName)
+                && item.type === 'imageView' && item.id === itemId && typeof item.path === 'string') {
+                imagePath = item.path;
+                break;
+            }
+        }
+        // Acknowledged source events can be reclaimed; native history remains the authority afterwards.
+        if (!imagePath && session && state.native?.readThreadImage) {
+            const threadIds = new Set([session.threadId]);
+            for (const { operation } of state.journal.listOperations()) {
+                if (operation.sessionId === sessionId && operation.workspaceId === workspaceId
+                    && (operation.directoryName ?? 'basic') === directoryName && operation.nativeThreadId)
+                    threadIds.add(operation.nativeThreadId);
+            }
+            for (const threadId of threadIds) {
+                imagePath = await state.native.readThreadImage({ threadId, itemId });
+                if (imagePath)
+                    break;
+            }
+        }
+        if (!imagePath || imagePath.length > 4096 || imagePath.includes('\0') || imagePath.includes('\\'))
+            throw new Error('image_not_found');
+        const temporaryRoot = await realpath('/tmp');
+        const target = imagePath.startsWith('/tmp/') ? resolve(temporaryRoot, imagePath.slice('/tmp/'.length))
+            : isAbsolute(imagePath) ? resolve(imagePath) : resolve(root, imagePath);
+        const stateRoot = await realpath(state.config.stateDir);
+        const workspaceParent = await realpath(state.config.workspaceRoot);
+        if (inside(stateRoot, target))
+            throw new Error('image_not_found');
+        const allowedRoot = inside(root, target) ? root
+            : inside(temporaryRoot, target) && !inside(workspaceParent, target) ? temporaryRoot : undefined;
+        if (!allowedRoot)
+            throw new Error('image_not_found');
+        const path = await artifactPath(allowedRoot, relative(allowedRoot, target).split(sep).join('/'));
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const before = await handle.stat();
+        const current = await lstat(await artifactPath(allowedRoot, relative(allowedRoot, target).split(sep).join('/')));
+        if (current.dev !== before.dev || current.ino !== before.ino)
+            throw new Error('image_not_found');
+        if (!before.isFile() || before.nlink !== 1 || before.size === 0 || before.size > WORKSPACE_ATTACHMENT_MAX_BYTES)
+            throw new Error('image_not_found');
+        const bytes = Buffer.alloc(before.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = await handle.read(bytes, offset, bytes.length - offset, offset);
+            if (!read.bytesRead)
+                throw new Error('image_not_found');
+            offset += read.bytesRead;
+        }
+        const after = await handle.stat(), mimeType = imageMime(bytes);
+        if (mimeType === 'application/octet-stream' || before.size !== after.size
+            || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw new Error('image_not_found');
+        response.writeHead(200, {
+            'content-type': mimeType,
+            'content-length': String(bytes.length),
+            'cache-control': 'private, no-store',
+            'x-content-type-options': 'nosniff',
+            'content-security-policy': "sandbox; default-src 'none'",
+            'referrer-policy': 'no-referrer',
+        });
+        response.end(request.method === 'HEAD' ? undefined : bytes);
+    }
+    catch {
+        response.writeHead(404, { 'content-type': 'application/json', 'cache-control': 'private, no-store',
+            'x-content-type-options': 'nosniff' });
+        response.end(request.method === 'HEAD' ? undefined : JSON.stringify({ error: 'image_not_found' }));
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function inside(root, target) { return target === root || target.startsWith(`${root}${sep}`); }
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}

package/dist/workspace-runtime/workspaces/shared-git.js

@@ -0,0 +1,40 @@
+import { lstat, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { launcherSocket, runDeveloperCommand } from './developer-command.js';
+import { shareWorkspaceRepository } from './git.js';
+/**
+ * Directories under `.git` this process cannot write: another user created them without group
+ * write. Only their owner can change that, so they are reported rather than fixed here.
+ */
+export async function foreignUnwritableGitDirectories(root) {
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined;
+    const found = [];
+    const visit = async (path) => {
+        const stat = await lstat(path).catch(() => undefined);
+        if (!stat?.isDirectory())
+            return;
+        if (stat.uid !== uid && (stat.mode & 0o020) === 0)
+            found.push(path);
+        for (const entry of await readdir(path).catch(() => []))
+            await visit(join(path, entry));
+    };
+    await visit(join(root, '.git'));
+    return found;
+}
+/**
+ * Prepares a workspace repository for a Git write by this process: new directories become group
+ * writable, and directories the development user already made without group write are opened by
+ * that user through the launcher. Without a launcher (local runs) both users are the same.
+ */
+export async function shareWorkspaceGit(state, root) {
+    await shareWorkspaceRepository(root).catch(() => undefined);
+    if (!launcherSocket(state) || !(await foreignUnwritableGitDirectories(root)).length)
+        return;
+    await runDeveloperCommand(state, {
+        processId: `git-share-${Date.now().toString(36)}`,
+        cwd: root,
+        command: 'find .git -type d -uid "$(id -u)" ! -perm -g+w -exec chmod g+ws {} +',
+        timeoutMs: 30_000,
+        onOutput: () => undefined,
+    }).catch(() => undefined);
+}

package/dist/workspace-runtime/workspaces/skill-artifact-loader.js

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { workspaceRoot } from './registry.js';
+import { PLATFORM_ROUTES, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+const MAX_ARTIFACT_BYTES = 80 * 1024 * 1024;
+/** Requests an exact locked artifact using control identity; no storage credentials reach Codex. */
+export async function loadWorkspaceSkillArtifact(state, workspaceId, entry, directoryName = 'basic') {
+    await workspaceRoot(state, workspaceId, directoryName);
+    return requestWorkspaceSkillArtifact(state, workspaceId, entry);
+}
+async function requestWorkspaceSkillArtifact(state, workspaceId, entry) {
+    const epoch = state.runtimeEpoch;
+    if (state.journal.destroyed())
+        throw new Error('workspace_skills_unavailable');
+    const endpoint = platformEndpoint(state.config.publicBaseUrl, PLATFORM_ROUTES.skillArtifacts);
+    const response = await fetch(endpoint, {
+        method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30_000),
+        headers: { authorization: `Bearer ${state.config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': state.config.environment },
+        body: JSON.stringify({ runtimeId: state.config.runtimeId, generation: state.config.generation,
+            runtimeEpoch: epoch, workspaceId, entryKey: entry.entryKey, revision: entry.revision }),
+    });
+    if (!response.ok || !response.body) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new Error(response.status === 401 || response.status === 403
+            ? 'workspace_skills_unavailable' : 'workspace_skills_artifact_unavailable');
+    }
+    const reader = response.body.getReader(), chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            total += chunk.value.byteLength;
+            if (total > Math.ceil(MAX_ARTIFACT_BYTES * 4 / 3) + 4096)
+                throw new Error('workspace_skills_artifact_too_large');
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (typeof result.content !== 'string' || result.artifactHash !== entry.revision.artifactHash
+        || result.content.length > Math.ceil(MAX_ARTIFACT_BYTES * 4 / 3) || result.content.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(result.content))
+        throw new Error('workspace_skills_digest_mismatch');
+    const archive = Buffer.from(result.content, 'base64');
+    if (archive.byteLength > MAX_ARTIFACT_BYTES || archive.toString('base64') !== result.content || createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+        throw new Error('workspace_skills_digest_mismatch');
+    if (state.journal.destroyed() || epoch !== state.runtimeEpoch)
+        throw new Error('workspace_skills_unavailable');
+    return archive;
+}
+/** The platform independently authorizes the trusted binding, including an unpublished checkout. */
+export function workspacePlatformSkillAccess(state, workspaceId) {
+    return {
+        resolve: async (skillRefs) => {
+            const epoch = state.runtimeEpoch;
+            if (state.journal.destroyed())
+                throw new Error('workspace_skills_unavailable');
+            const response = await fetch(`${platformEndpoint(state.config.publicBaseUrl, PLATFORM_ROUTES.skillArtifacts)}/resolve`, {
+                method: 'POST', redirect: 'error', signal: AbortSignal.timeout(30_000),
+                headers: { authorization: `Bearer ${state.config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': state.config.environment },
+                body: JSON.stringify({ runtimeId: state.config.runtimeId, generation: state.config.generation,
+                    runtimeEpoch: epoch, workspaceId, skillRefs }),
+            });
+            if (!response.ok) {
+                await response.body?.cancel().catch(() => undefined);
+                throw new Error(response.status === 401 || response.status === 403
+                    ? 'workspace_skills_unavailable' : 'workspace_skills_platform_unavailable');
+            }
+            if (!response.body)
+                throw new Error('workspace_skills_platform_unavailable');
+            const reader = response.body.getReader(), chunks = [];
+            let total = 0;
+            try {
+                while (true) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    total += part.value.byteLength;
+                    if (total > 1024 * 1024)
+                        throw new Error('workspace_skills_platform_unavailable');
+                    chunks.push(part.value);
+                }
+            }
+            finally {
+                await reader.cancel().catch(() => undefined);
+            }
+            if (state.journal.destroyed() || epoch !== state.runtimeEpoch)
+                throw new Error('workspace_skills_unavailable');
+            return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        },
+        loadArtifact: entry => requestWorkspaceSkillArtifact(state, workspaceId, entry),
+    };
+}

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

@@ -0,0 +1,191 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { load } from 'js-yaml';
+import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
+import { initializeLocalProjectSkills } from '../../project-skills/local-store.js';
+import { resolveCliPackageRoot } from '../../scaffold/compose.js';
+import { selectPlatformSkillSnapshot } from '../../project-skills/builtin-import.js';
+import { EMPTY_WORKSPACE_REPOSITORY_SKILLS, EMPTY_WORKSPACE_PLATFORM_SKILLS } from './empty-template.js';
+import { excludeFromGit } from './dependencies.js';
+import { selectOptionalPlatformSkills } from './optional-platform-skills.js';
+/** Runtime availability is determined by the locked metadata, independent of unsynced source edits. */
+export async function readWorkspaceSkillSnapshot(root) {
+    const management = await lstat(join(root, '.playcraft'));
+    const declaration = join(root, '.playcraft/skills.json');
+    const stat = await lstat(declaration);
+    if (!management.isDirectory() || management.isSymbolicLink() || !stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+        throw new Error('workspace_skills_invalid');
+    return validateProjectSkillsSnapshot(await readFile(declaration, 'utf8'), await readProjectSkillsLockFile(root));
+}
+/** Existing managed projects keep their exact selection. Legacy source folders are adopted once. */
+export async function ensureWorkspaceSkills(root, cache, access, options = {}) {
+    await excludeFromGit(root, '/.playcraft/skills/');
+    await excludeFromGit(root, '/.playcraft/skill-artifacts/');
+    const raw = await readProjectSkillsLockFile(root);
+    if (raw !== null) {
+        await readWorkspaceSkillSnapshot(root);
+        return;
+    }
+    const inventory = await inspectProjectSkills(root);
+    if (inventory.issues.length)
+        throw new Error('workspace_skills_invalid');
+    const names = new Set(inventory.discovered.map(entry => basename(entry.root)));
+    const platformNames = EMPTY_WORKSPACE_PLATFORM_SKILLS.filter(name => !names.has(name));
+    const select = options.optionalPlatformDefaults ? selectOptionalPlatformSkills : selectPlatformSkillSnapshot;
+    const selected = platformNames.length ? await select(platformNames, access) : undefined;
+    const added = new Set();
+    await initializeLocalProjectSkills(root, cache, { enabledRoots: added, platform: selected,
+        prepareSources: async () => {
+            for (const name of EMPTY_WORKSPACE_REPOSITORY_SKILLS) {
+                if (names.has(name))
+                    continue;
+                await safeDirectory(root, '.agents/skills');
+                const source = `.agents/skills/${name}`;
+                await mkdir(join(root, source), { mode: 0o755 });
+                added.add(source);
+                const template = join(resolveCliPackageRoot(), 'project-template/.claude/skills', name);
+                for (const child of await readdir(template))
+                    await cp(join(template, child), join(root, source, child), {
+                        recursive: true, force: false, errorOnExist: true,
+                    });
+            }
+        },
+        rollbackSources: async () => {
+            for (const source of added)
+                await rm(join(root, source), { recursive: true, force: true });
+        },
+    });
+}
+async function safeDirectory(root, path) {
+    let current = root;
+    for (const segment of path.split('/')) {
+        current = join(current, segment);
+        await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        const stat = await lstat(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('workspace_skills_invalid');
+    }
+    return current;
+}
+/** Cache misses may reconstruct only the exact locked repository bytes, never a newer source. */
+async function lockedFiles(root, cache, entry, view, loadArtifact) {
+    const persistent = await safeDirectory(root, '.playcraft/skill-artifacts');
+    const saved = join(persistent, `${entry.revision.artifactHash}.tar.gz`);
+    const path = join(cache, `${entry.revision.artifactHash}.tar.gz`);
+    let archive;
+    try {
+        const stat = await lstat(saved);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 80 * 1024 * 1024)
+            throw new Error('workspace_skills_invalid_bundle');
+        archive = await readFile(saved);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        try {
+            archive = await readFile(path);
+        }
+        catch (cacheError) {
+            if (cacheError.code !== 'ENOENT')
+                throw cacheError;
+            const declaration = view.declaration.entries.find(item => item.entryKey === entry.entryKey);
+            if (entry.revision.kind === 'source' && declaration.source.kind === 'repository') {
+                const source = await readProjectSkillSource(root, declaration);
+                if (source.sourceTreeHash !== entry.sourceTreeHash)
+                    throw new Error('workspace_skills_source_changed');
+                archive = createCanonicalBundleArchive(source.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
+            }
+            else {
+                if (!loadArtifact)
+                    throw new Error('workspace_skills_artifact_unavailable');
+                archive = await loadArtifact(entry);
+            }
+        }
+    }
+    if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+        throw new Error('workspace_skills_digest_mismatch');
+    const extracted = extractBundleArchive(archive);
+    if (extracted.issues.length)
+        throw new Error('workspace_skills_invalid_bundle');
+    if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
+        throw new Error('workspace_skills_digest_mismatch');
+    const temporary = `${saved}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, archive, { flag: 'wx', mode: 0o644 });
+        await rename(temporary, saved);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return extracted.files;
+}
+function metadata(entryKey, content) {
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+    const parsed = frontmatter ? load(frontmatter[1]) : {};
+    const data = parsed && typeof parsed === 'object' ? parsed : {};
+    return { entryKey, name: typeof data.name === 'string' ? data.name : entryKey,
+        description: typeof data.description === 'string' ? data.description : '', content };
+}
+export async function readWorkspaceSkills(root, cache, loadArtifact) {
+    const snapshot = await readWorkspaceSkillSnapshot(root);
+    const skills = await Promise.all(snapshot.lock.entries.map(async (entry) => {
+        const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
+        const body = files.find(file => file.path === 'SKILL.md');
+        if (!body)
+            throw new Error('workspace_skills_body_missing');
+        return metadata(entry.entryKey, body.data.toString('utf8'));
+    }));
+    return { ...snapshot, lockHash: createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex'), skills };
+}
+/** Read-only task generation lives outside source discovery and is omitted from Git/snapshots. */
+export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
+    const snapshot = await readWorkspaceSkillSnapshot(root);
+    const entries = effectiveProjectSkills(snapshot.declaration, snapshot.lock, 'sandbox-agent');
+    const base = await safeDirectory(root, '.playcraft/skills');
+    const lockHash = createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex');
+    const generation = await safeDirectory(base, lockHash);
+    const skills = [];
+    const expectedFiles = new Set();
+    for (const entry of entries) {
+        const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
+        for (const file of files) {
+            const target = join(generation, entry.entryKey, file.path);
+            const relative = join(entry.entryKey, file.path);
+            expectedFiles.add(relative);
+            await safeDirectory(generation, dirname(relative));
+            await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(async (error) => {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                const stat = await lstat(target);
+                if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || !file.data.equals(await readFile(target)))
+                    throw new Error('workspace_skills_digest_mismatch');
+            });
+        }
+        const body = files.find(file => file.path === 'SKILL.md');
+        if (!body)
+            throw new Error('workspace_skills_body_missing');
+        const info = metadata(entry.entryKey, body.data.toString('utf8'));
+        skills.push({ name: info.name, description: info.description, skillRef: entry.revision.skillRef,
+            revision: entry.revision.kind === 'source' ? entry.revision.sourceRevision : entry.revision.version,
+            path: join(generation, entry.entryKey, 'SKILL.md') });
+    }
+    const verifyTree = async (directory, relative = '') => {
+        for (const item of await readdir(directory, { withFileTypes: true })) {
+            const path = join(relative, item.name);
+            if (item.isSymbolicLink())
+                throw new Error('workspace_skills_invalid_bundle');
+            if (item.isDirectory()) {
+                if (![...expectedFiles].some(file => file.startsWith(`${path}/`)))
+                    throw new Error('workspace_skills_invalid_bundle');
+                await verifyTree(join(directory, item.name), path);
+            }
+            else if (!item.isFile() || !expectedFiles.has(path))
+                throw new Error('workspace_skills_invalid_bundle');
+        }
+    };
+    await verifyTree(generation);
+    return { declarationHash: snapshot.lock.declarationHash,
+        lockHash, skills };
+}

package/dist/workspace-runtime/workspaces/transfer-quota.js

@@ -0,0 +1,69 @@
+import { lstat, opendir, realpath, statfs } from 'node:fs/promises';
+import { join, sep } from 'node:path';
+import { WorkspaceTransferError } from './transfer.js';
+/** Includes dependencies and repository metadata; symbolic links never expand the charged tree. */
+export async function workspaceStorageBytes(root) {
+    const source = await realpath(root);
+    let bytes = 0;
+    const walk = async (directory) => {
+        const before = await lstat(directory), actual = await realpath(directory);
+        if (!before.isDirectory() || before.isSymbolicLink() || (actual !== source && !actual.startsWith(`${source}${sep}`)))
+            throw new WorkspaceTransferError('workspace_transfer_conflict');
+        for await (const entry of await opendir(directory)) {
+            const path = join(directory, entry.name);
+            const info = await lstat(path);
+            if (info.isSymbolicLink())
+                continue;
+            if (info.isDirectory())
+                await walk(path);
+            else if (info.isFile())
+                bytes += info.size;
+            if (!Number.isSafeInteger(bytes))
+                throw new WorkspaceTransferError('workspace_transfer_storage_unavailable');
+        }
+        const after = await lstat(directory);
+        if (after.isSymbolicLink() || after.dev !== before.dev || after.ino !== before.ino)
+            throw new WorkspaceTransferError('workspace_transfer_conflict');
+    };
+    await walk(source);
+    return bytes;
+}
+export async function transferDiskBudget(path) {
+    try {
+        const disk = await statfs(path);
+        const available = disk.bavail * disk.bsize;
+        const reserve = Math.ceil(disk.blocks * disk.bsize * 0.1);
+        if (disk.bsize <= 0 || disk.blocks <= 0 || available < 0 || reserve < 0 ||
+            !Number.isSafeInteger(available) || !Number.isSafeInteger(reserve))
+            throw new Error();
+        return { available, reserve, budget: Math.max(0, available - reserve) };
+    }
+    catch {
+        throw new WorkspaceTransferError('workspace_transfer_storage_unavailable');
+    }
+}
+export async function assertTransferDiskSpace(path, required) {
+    const disk = await transferDiskBudget(path);
+    if (required > disk.budget)
+        throw new WorkspaceTransferError('workspace_transfer_disk_full', {
+            metric: 'diskBytes', actual: required, limit: disk.budget,
+            availableBytes: disk.available, reserveBytes: disk.reserve,
+        });
+}
+export async function checkWorkspaceTransferQuota(workspaceRoot, current, incoming, limitBytes) {
+    const usedBytes = await workspaceStorageBytes(workspaceRoot);
+    const projectedBytes = Math.max(0, usedBytes - current.bytes) + incoming.bytes;
+    if (!Number.isSafeInteger(projectedBytes))
+        throw new WorkspaceTransferError('invalid_workspace_transfer');
+    if (limitBytes !== undefined && projectedBytes > limitBytes) {
+        throw new WorkspaceTransferError('workspace_transfer_quota_exceeded', {
+            metric: 'workspaceBytes', actual: projectedBytes, limit: limitBytes, usedBytes,
+            currentBytes: current.bytes, incomingBytes: incoming.bytes, fileCount: incoming.files,
+        });
+    }
+    const disk = await transferDiskBudget(workspaceRoot);
+    // The staged replacement may coexist with the old file until its atomic rename.
+    await assertTransferDiskSpace(workspaceRoot, incoming.bytes);
+    return { limitBytes: limitBytes ?? null, usedBytes, projectedBytes,
+        diskAvailableBytes: disk.available, diskReserveBytes: disk.reserve };
+}