@playcraft/cli 0.1.21 → 0.1.22

package/dist/workspace-runtime/workspaces/directory-maintenance.js

@@ -0,0 +1,111 @@
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { promisify } from 'node:util';
+import { workspaceDirectoryNameSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { productionDirectoryBusy } from '../production/controller.js';
+import { workspaceRoot, workspaceSessions } from './registry.js';
+const execute = promisify(execFile);
+const git = async (state, root, ...args) => (await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root, ...args], {
+    timeout: 30_000, maxBuffer: 1024 * 1024, env: { PATH: process.env.PATH, HOME: state.config.stateDir, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' },
+})).stdout.trim();
+export async function workspaceDirectoryOccupied(state, workspaceId, directoryName) {
+    if (await productionDirectoryBusy(state, workspaceId, directoryName))
+        return true;
+    if (state.journal.listOperations().some(({ operation }) => operation.workspaceId === workspaceId
+        && (operation.directoryName ?? 'basic') === directoryName && ['queued', 'dispatched', 'accepted', 'uncertain'].includes(operation.status)))
+        return true;
+    if (workspaceSessions(state, workspaceId, directoryName).some(session => session.turnBlock === 'uncertain' || ['starting', 'running', 'waiting_for_user'].includes(session.turnStatus ?? '')))
+        return true;
+    if (state.journal.listTerminals().some(terminal => terminal.workspaceId === workspaceId && (terminal.directoryName ?? 'basic') === directoryName && terminal.status !== 'destroyed'))
+        return true;
+    return [workspaceId, `${workspaceId}:${directoryName}`].some(scope => state.journal.listManagedWrites(scope).some(write => !write.stoppedAt));
+}
+async function assertCleanAndPushed(state, root, allowedHead) {
+    if (await git(state, root, 'status', '--porcelain', '--untracked-files=all'))
+        throw new Error('workspace_directory_uncommitted');
+    const upstream = await git(state, root, 'rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}').catch(() => '');
+    if (!upstream || (Number(await git(state, root, 'rev-list', '--count', `${upstream}..HEAD`)) > 0 && await git(state, root, 'rev-parse', 'HEAD') !== allowedHead))
+        throw new Error('workspace_directory_unpushed');
+}
+/** Keep remote branches, published previews and all journal identities; only local checkouts are reclaimed. */
+export async function cleanupWorkspaceDirectories(state, workspaceId, directoryNames) {
+    if (!Array.isArray(directoryNames) || directoryNames.length === 0 || directoryNames.length > 64)
+        throw new Error('workspace_directories_invalid');
+    const names = [...new Set(directoryNames.map(name => workspaceDirectoryNameSchema.parse(name)))];
+    return state.journal.exclusive(`maintenance:${workspaceId}`, async () => {
+        const cleaned = [];
+        const blocked = [];
+        for (const directoryName of names) {
+            try {
+                await state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
+                    if (await workspaceDirectoryOccupied(state, workspaceId, directoryName))
+                        throw new Error('workspace_directory_occupied');
+                    const root = await workspaceRoot(state, workspaceId, directoryName);
+                    await assertCleanAndPushed(state, root);
+                    const binding = state.journal.getWorkspace(workspaceId);
+                    // Persist recoverable identity before removing the checkout; a retry cannot silently adopt another branch.
+                    const existing = binding.directories?.find(item => item.directoryName === directoryName);
+                    const directory = existing ?? { workspaceId, directoryName, remixId: binding.remixId, branchName: binding.branchName };
+                    await state.journal.putWorkspace({ ...binding, directories: [...(binding.directories ?? []).filter(item => item.directoryName !== directoryName), { ...directory, status: 'reclaimed' }] });
+                    await rm(root, { recursive: true });
+                    cleaned.push(directoryName);
+                });
+            }
+            catch (error) {
+                blocked.push({ directoryName, reason: error instanceof Error && /^[a-z0-9_]+$/.test(error.message) ? error.message : 'workspace_cleanup_failed' });
+            }
+        }
+        return { cleaned, blocked };
+    });
+}
+/** Conflicts remain isolated to their own engineering directory. Busy directories are skipped without deferred work. */
+export async function syncWorkspaceDirectories(state, workspaceId, commitHash, targetDirectoryNames) {
+    if (typeof commitHash !== 'string' || !/^[a-f0-9]{40,64}$/.test(commitHash) || !Array.isArray(targetDirectoryNames) || targetDirectoryNames.length === 0 || targetDirectoryNames.length > 64)
+        throw new Error('workspace_sync_invalid');
+    const basic = await workspaceRoot(state, workspaceId, 'basic');
+    await git(state, basic, 'merge-base', '--is-ancestor', commitHash, 'HEAD');
+    const synced = [], skipped = [], conflicts = [];
+    for (const directoryName of [...new Set(targetDirectoryNames.map(name => workspaceDirectoryNameSchema.parse(name)))]) {
+        if (directoryName === 'basic')
+            throw new Error('workspace_sync_target_invalid');
+        await state.journal.exclusive(`directory:${workspaceId}:${directoryName}`, async () => {
+            if (await workspaceDirectoryOccupied(state, workspaceId, directoryName)) {
+                skipped.push({ directoryName, reason: 'directory_busy' });
+                return;
+            }
+            const root = await workspaceRoot(state, workspaceId, directoryName);
+            const ledger = join(state.config.stateDir, 'directory-sync', workspaceId, `${directoryName}.json`);
+            const applied = await readFile(ledger, 'utf8').then(value => JSON.parse(value), () => undefined);
+            await assertCleanAndPushed(state, root, applied?.sourceCommit === commitHash ? applied.targetCommit : undefined);
+            if (applied?.sourceCommit === commitHash && await git(state, root, 'rev-parse', 'HEAD') === applied.targetCommit) {
+                synced.push(directoryName);
+                return;
+            }
+            const containing = await git(state, root, 'merge-base', '--is-ancestor', commitHash, 'HEAD').then(() => true, () => false);
+            if (containing) {
+                synced.push(directoryName);
+                return;
+            }
+            // Import the exact preserved basic commit, without fetching a moving remote branch.
+            await execute('git', ['-c', 'core.hooksPath=/dev/null', '-C', root, 'fetch', '--no-tags', '--', basic, commitHash], { timeout: 30_000, maxBuffer: 1024 * 1024 });
+            const equivalent = (await git(state, root, 'cherry', 'HEAD', commitHash)).split('\n').some(line => line === `- ${commitHash}`);
+            if (!equivalent) {
+                try {
+                    await git(state, root, '-c', 'user.name=PlayCraft', '-c', 'user.email=playcraft@localhost', 'cherry-pick', commitHash);
+                }
+                catch {
+                    conflicts.push(directoryName);
+                    return;
+                }
+            }
+            await mkdir(join(state.config.stateDir, 'directory-sync', workspaceId), { recursive: true, mode: 0o700 });
+            const temporary = `${ledger}.${randomUUID()}.tmp`;
+            await writeFile(temporary, JSON.stringify({ sourceCommit: commitHash, targetCommit: await git(state, root, 'rev-parse', 'HEAD') }), { mode: 0o600 });
+            await rename(temporary, ledger);
+            synced.push(directoryName);
+        });
+    }
+    return { synced, skipped, conflicts, previewStale: true };
+}

package/dist/workspace-runtime/workspaces/directory-stats.js

@@ -0,0 +1,49 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { workspaceRoot, WorkspaceContextError } from './registry.js';
+const execute = promisify(execFile);
+/** Measures registered checkouts only when requested; journal activity never scans private neighboring workspaces. */
+export async function readWorkspaceDirectoryStats(state, workspaceId) {
+    const binding = state.journal.getWorkspace(workspaceId);
+    if (!binding)
+        throw new WorkspaceContextError('workspace_not_registered');
+    const names = [...new Set(['basic', ...(binding.directories ?? []).map(directory => directory.directoryName)])];
+    const operations = state.journal.listOperations().map(item => item.operation).filter(operation => operation.workspaceId === workspaceId);
+    const events = state.journal.listEvents().flatMap(event => {
+        const payload = event.payload && typeof event.payload === 'object' ? event.payload : {};
+        const session = typeof payload.sessionId === 'string' ? state.journal.getSession(payload.sessionId) : undefined;
+        if ((payload.workspaceId ?? session?.workspaceId) !== workspaceId)
+            return [];
+        return [{ directoryName: String(payload.directoryName ?? session?.directoryName ?? 'basic'), occurredAt: event.occurredAt }];
+    });
+    const latest = (dates) => {
+        const timestamps = dates.map(value => Date.parse(value)).filter(Number.isFinite);
+        return timestamps.length ? new Date(Math.max(...timestamps)).toISOString() : null;
+    };
+    const directories = [];
+    for (const directoryName of names) {
+        const lastUsedAt = latest([...operations.filter(operation => (operation.directoryName ?? 'basic') === directoryName).map(operation => operation.updatedAt),
+            ...events.filter(event => event.directoryName === directoryName).map(event => event.occurredAt)]);
+        if (binding.directories?.some(directory => directory.directoryName === directoryName && directory.status === 'reclaimed')) {
+            directories.push({ directoryName, sizeBytes: 0, lastUsedAt, status: 'reclaimed' });
+            continue;
+        }
+        let root;
+        try {
+            root = await workspaceRoot(state, workspaceId, directoryName);
+        }
+        catch (error) {
+            if (!(error instanceof WorkspaceContextError) || error.message !== 'workspace_not_prepared')
+                throw error;
+            directories.push({ directoryName, sizeBytes: 0, lastUsedAt, status: 'missing' });
+            continue;
+        }
+        const output = await execute('du', ['-sk', root], { timeout: 30_000, maxBuffer: 4096 });
+        const blocks = Number(output.stdout.trim().split(/\s+/)[0]);
+        if (!Number.isSafeInteger(blocks) || blocks < 0 || !Number.isSafeInteger(blocks * 1024))
+            throw new Error('workspace_directory_stats_invalid');
+        directories.push({ directoryName, sizeBytes: blocks * 1024, lastUsedAt, status: 'present' });
+    }
+    return { workspaceId, sizeBytes: directories.reduce((sum, directory) => sum + directory.sizeBytes, 0),
+        lastUsedAt: latest([...operations.map(operation => operation.updatedAt), ...events.map(event => event.occurredAt)]), directories };
+}

package/dist/workspace-runtime/workspaces/git-credential-broker.js

@@ -6,7 +6,7 @@ import { createServer } from 'node:http';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { promisify } from 'node:util';
-import { isLocalWorkspaceGitAuthMode, isLocalWorkspaceGitEnvironment, matchWorkspaceGitGatewayCloneUrl, workspacePreparationSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { isLocalWorkspaceGitAuthMode, isLocalWorkspaceGitEnvironment, matchWorkspaceGitGatewayCloneUrl, workspacePreparationSchema, workspaceDirectoryNameSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceGitDirectStore } from './git-direct-store.js';
 import { PLATFORM_ROUTES, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
 const exec = promisify(execFile);
@@ -76,9 +76,17 @@ export class WorkspaceGitCredentialBroker {
             await unlink(this.socketPath).catch(() => undefined);
         }
     }
-    async configure(binding, preparation) {
+    async configure(binding, preparation, directoryName = 'basic') {
+        workspaceDirectoryNameSchema.parse(directoryName);
+        if (binding.targetKind === 'standalone')
+            throw new Error('git_access_denied');
+        if (directoryName !== 'basic')
+            binding = this.binding(binding.workspaceId, directoryName);
+        const { directories: _directories, ...stableBinding } = binding;
+        binding = stableBinding;
+        const scope = `${binding.workspaceId}:${directoryName}`;
         preparation = workspacePreparationSchema.parse(preparation);
-        if (binding.targetKind === 'standalone' || preparation.mode !== 'clone')
+        if (preparation.mode !== 'clone')
             throw new Error('git_access_denied');
         const transport = preparation.transport;
         const isDirect = isLocalWorkspaceGitAuthMode(preparation.authMode);
@@ -95,13 +103,13 @@ export class WorkspaceGitCredentialBroker {
         }
         // Revocation and switching to gateway invalidate first; direct rotation keeps the old file until rename.
         if (!isDirect)
-            await this.direct.remove(binding.workspaceId);
+            await this.direct.remove(binding.workspaceId, directoryName);
         else if (preparation.directAccess === null)
-            await this.direct.put(binding, null);
-        this.cache.delete(binding.workspaceId);
+            await this.direct.put(binding, null, undefined, directoryName);
+        this.cache.delete(scope);
         const cloneUrl = isDirect ? binding.repositoryUrl : transport.cloneUrl;
-        const root = join(this.state.config.workspaceRoot, binding.workspaceId);
-        const helper = `!${quote(process.execPath)} ${quote(fileURLToPath(new URL('./git-credential-helper.js', import.meta.url)))} ${quote(this.socketPath)} ${quote(binding.workspaceId)}`;
+        const root = join(this.state.config.workspaceRoot, binding.workspaceId, directoryName);
+        const helper = `!${quote(process.execPath)} ${quote(fileURLToPath(new URL('./git-credential-helper.js', import.meta.url)))} ${quote(this.socketPath)} ${quote(binding.workspaceId)} ${quote(directoryName)}`;
         await configureGitFile(root, this.state.config.stateDir, [
             ...(!isDirect ? [['--replace-all', `url.${cloneUrl}.insteadOf`, binding.repositoryUrl]] : []),
             ['--replace-all', `credential.${cloneUrl}.useHttpPath`, 'true'],
@@ -111,8 +119,8 @@ export class WorkspaceGitCredentialBroker {
             ['--replace-all', 'playcraft.gitAuthUrl', cloneUrl],
         ], binding.repositoryUrl);
         if (isDirect)
-            await this.direct.put(binding, preparation.directAccess);
-        this.cache.delete(binding.workspaceId);
+            await this.direct.put(binding, preparation.directAccess, undefined, directoryName);
+        this.cache.delete(scope);
     }
     async credential(input) {
         if (!this.ready || this.closed || this.state.journal.destroyed() || !input || !['get', 'erase'].includes(input.action)
@@ -120,17 +128,17 @@ export class WorkspaceGitCredentialBroker {
             || !['http', 'https'].includes(input.protocol) || typeof input.host !== 'string'
             || typeof input.path !== 'string')
             throw new Error('git_access_denied');
-        const binding = this.state.journal.getWorkspace(input.workspaceId);
-        if (!binding || binding.targetKind === 'standalone')
-            throw new Error('git_access_denied');
+        const directoryName = workspaceDirectoryNameSchema.parse(input.directoryName ?? 'basic');
+        const binding = this.binding(input.workspaceId, directoryName);
+        const scope = `${input.workspaceId}:${directoryName}`;
         const cloneUrl = `${input.protocol}://${input.host}/${input.path}`;
-        const direct = await this.direct.get(binding);
+        const direct = await this.direct.get(binding, directoryName);
         if (direct) {
             if (!direct.access || cloneUrl !== binding.repositoryUrl)
                 throw new Error('git_access_denied');
             if (input.action === 'erase') {
                 if (input.password === direct.access.password)
-                    await this.direct.put(binding, null, input.password);
+                    await this.direct.put(binding, null, input.password, directoryName);
                 return {};
             }
             return { username: direct.access.username, password: direct.access.password };
@@ -139,39 +147,57 @@ export class WorkspaceGitCredentialBroker {
         if (!matched.ok || matched.requestId !== `v2/${binding.workspaceId}`)
             throw new Error('git_access_denied');
         if (input.action === 'erase') {
-            if (this.cache.get(input.workspaceId)?.preparation.gitAccess?.password === input.password)
-                this.cache.delete(input.workspaceId);
+            if (this.cache.get(scope)?.preparation.gitAccess?.password === input.password)
+                this.cache.delete(scope);
             return {};
         }
         const key = JSON.stringify([binding, this.state.config.generation, this.state.runtimeEpoch]);
-        const cached = this.cache.get(input.workspaceId);
+        const cached = this.cache.get(scope);
         let preparation = cached?.key === key && Date.parse(cached.preparation.gitAccess.expiresAt) > Date.now() + 60_000
             ? cached.preparation : undefined;
         if (!preparation) {
-            const pendingKey = `${input.workspaceId}:${key}`;
+            const pendingKey = `${scope}:${key}`;
             let pending = this.pending.get(pendingKey);
             if (!pending) {
-                pending = this.refresh(binding, key).finally(() => this.pending.delete(pendingKey));
+                pending = this.refresh(binding, key, directoryName).finally(() => this.pending.delete(pendingKey));
                 this.pending.set(pendingKey, pending);
             }
             preparation = await pending;
         }
-        if (await this.direct.get(binding) || preparation.transport?.cloneUrl !== cloneUrl || !preparation.gitAccess)
+        if (await this.direct.get(binding, directoryName) || preparation.transport?.cloneUrl !== cloneUrl || !preparation.gitAccess)
             throw new Error('git_access_denied');
         return { username: preparation.gitAccess.username, password: preparation.gitAccess.password };
     }
+    async prepareDirectory(workspaceId, directoryName = 'basic') {
+        const binding = this.binding(workspaceId, directoryName, true);
+        return this.refresh(binding, JSON.stringify([binding, this.state.config.generation, this.state.runtimeEpoch]), directoryName);
+    }
+    binding(workspaceId, directoryName, recovering = false) {
+        workspaceDirectoryNameSchema.parse(directoryName);
+        const binding = this.state.journal.getWorkspace(workspaceId);
+        if (!binding || binding.targetKind === 'standalone')
+            throw new Error('git_access_denied');
+        const { directories: _directories, ...base } = binding;
+        if (directoryName === 'basic')
+            return base;
+        const directory = binding.directories?.find(item => item.directoryName === directoryName && (recovering || item.status !== 'reclaimed'));
+        if (!directory?.remixId)
+            throw new Error('git_access_denied');
+        return { ...base, targetKind: 'remix', remixId: directory.remixId, branchName: directory.branchName };
+    }
     async destroy() {
         await this.close();
         await this.direct.sweep(true);
     }
-    async refresh(binding, key) {
+    async refresh(binding, key, directoryName) {
+        const scope = `${binding.workspaceId}:${directoryName}`;
         const endpoint = platformEndpoint(this.state.config.publicBaseUrl, PLATFORM_ROUTES.gitCredentials);
         const epoch = this.state.runtimeEpoch;
         const response = await fetch(endpoint, {
             method: 'POST', redirect: 'error', signal: AbortSignal.timeout(10_000),
             headers: { authorization: `Bearer ${this.state.config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': this.state.config.environment },
             body: JSON.stringify({ runtimeId: this.state.config.runtimeId, generation: this.state.config.generation,
-                runtimeEpoch: epoch, workspaceId: binding.workspaceId }),
+                runtimeEpoch: epoch, workspaceId: binding.workspaceId, directoryName }),
         });
         if (!response.ok) {
             await response.body?.cancel();
@@ -182,14 +208,21 @@ export class WorkspaceGitCredentialBroker {
             throw new Error('git_access_denied');
         const matched = preparation.transport && matchWorkspaceGitGatewayCloneUrl(preparation.transport.cloneUrl, this.state.config.gitGatewayOrigins, binding.repositoryUrl);
         if (this.closed || this.state.journal.destroyed() || this.state.runtimeEpoch !== epoch
-            || JSON.stringify(this.state.journal.getWorkspace(binding.workspaceId)) !== JSON.stringify(binding)
-            || preparation.transport?.kind !== 'git-gateway-v2' || !matched?.ok || matched.requestId !== `v2/${binding.workspaceId}`
-            || !preparation.gitAccess || Date.parse(preparation.gitAccess.issuedAt) > Date.now()
-            || Date.parse(preparation.gitAccess.expiresAt) <= Date.now() + 10_000)
+            || JSON.stringify(this.binding(binding.workspaceId, directoryName, true)) !== JSON.stringify(binding))
             throw new Error('git_access_denied');
-        if (this.cache.size >= 128)
-            this.cache.clear();
-        this.cache.set(binding.workspaceId, { key, preparation });
+        if (isLocalWorkspaceGitAuthMode(preparation.authMode)) {
+            if (!isLocalWorkspaceGitEnvironment(this.state.config.environment) || !preparation.directAccess || preparation.directAccess.repositoryUrl !== binding.repositoryUrl)
+                throw new Error('git_access_denied');
+        }
+        else {
+            if (preparation.transport?.kind !== 'git-gateway-v2' || !matched?.ok || matched.requestId !== `v2/${binding.workspaceId}`
+                || !preparation.gitAccess || Date.parse(preparation.gitAccess.issuedAt) > Date.now()
+                || Date.parse(preparation.gitAccess.expiresAt) <= Date.now() + 10_000)
+                throw new Error('git_access_denied');
+            if (this.cache.size >= 128)
+                this.cache.clear();
+            this.cache.set(scope, { key, preparation });
+        }
         return preparation;
     }
 }

package/dist/workspace-runtime/workspaces/git-credential-helper.js

@@ -1,6 +1,8 @@
 import { request } from 'node:http';
 // Git invokes this executable directly. Keep standard output exclusively for the credential protocol.
-const [socketPath, workspaceId, action] = process.argv.slice(2);
+const [socketPath, workspaceId, third, fourth] = process.argv.slice(2);
+const directoryName = fourth === undefined ? 'basic' : third;
+const action = fourth ?? third;
 try {
     if (action === 'get' || action === 'erase') {
         const fields = {};
@@ -49,7 +51,7 @@ try {
                 }
             });
             client.once('error', reject);
-            client.end(JSON.stringify({ workspaceId, action, protocol: fields.protocol, host: fields.host,
+            client.end(JSON.stringify({ workspaceId, directoryName, action, protocol: fields.protocol, host: fields.host,
                 path: fields.path, ...(action === 'erase' ? { password: fields.password } : {}) }));
         });
         if (action === 'get') {

package/dist/workspace-runtime/workspaces/git-direct-store.js

@@ -2,7 +2,7 @@ import { constants } from 'node:fs';
 import { lstat, mkdir, open, realpath, readdir, rename, unlink } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { join, resolve, sep } from 'node:path';
-import { isLocalWorkspaceGitEnvironment, workspaceGitDirectAccessSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { isLocalWorkspaceGitEnvironment, workspaceGitDirectAccessSchema, workspaceDirectoryNameSchema, sameWorkspaceRegistration } from '@playcraft/common/cloud-workspace/runtime';
 /** Control-owned files only. Same-user processes are not an operating-system isolation boundary. */
 export class WorkspaceGitDirectStore {
     state;
@@ -19,10 +19,11 @@ export class WorkspaceGitDirectStore {
         const c = this.state.config;
         return JSON.stringify([c.environment, c.userId, c.runtimeId, c.generation]);
     }
-    name(id) {
+    name(id, directoryName = 'basic') {
         if (!/^[a-f0-9-]{36}$/.test(id))
             throw new Error('git_access_denied');
-        return `${id}.json`;
+        workspaceDirectoryNameSchema.parse(directoryName);
+        return `${id}${directoryName === 'basic' ? '' : `--${directoryName}`}.json`;
     }
     async directory(create, action) {
         const stateDir = resolve(this.state.config.stateDir);
@@ -76,12 +77,12 @@ export class WorkspaceGitDirectStore {
             await handle.close();
         }
     }
-    async get(binding) {
+    async get(binding, directoryName = 'basic') {
         return this.directory(false, async (path) => {
-            const stored = await this.read(join(path, this.name(binding.workspaceId)));
+            const stored = await this.read(join(path, this.name(binding.workspaceId, directoryName)));
             if (!stored)
                 return undefined;
-            if (stored.identity !== this.identity() || JSON.stringify(stored.binding) !== JSON.stringify(binding)
+            if (stored.identity !== this.identity() || !sameWorkspaceRegistration(stored.binding, binding)
                 || !isLocalWorkspaceGitEnvironment(this.state.config.environment))
                 throw new Error('git_access_denied');
             if (stored.access !== null) {
@@ -92,13 +93,13 @@ export class WorkspaceGitDirectStore {
             return stored;
         });
     }
-    async put(binding, access, rejectedPassword) {
+    async put(binding, access, rejectedPassword, directoryName = 'basic') {
         if (!isLocalWorkspaceGitEnvironment(this.state.config.environment) || this.state.journal.destroyed())
             throw new Error('git_access_denied');
         if (access && (workspaceGitDirectAccessSchema.parse(access).repositoryUrl !== binding.repositoryUrl))
             throw new Error('git_access_denied');
         await this.exclusive(() => this.directory(true, async (path) => {
-            const target = join(path, this.name(binding.workspaceId));
+            const target = join(path, this.name(binding.workspaceId, directoryName));
             // Refuse symlink/hardlink/permissive old files even though rename would replace them.
             const old = await this.read(target);
             if (rejectedPassword !== undefined && old?.access?.password !== rejectedPassword)
@@ -127,9 +128,9 @@ export class WorkspaceGitDirectStore {
             }
         }));
     }
-    async remove(workspaceId) {
+    async remove(workspaceId, directoryName = 'basic') {
         await this.exclusive(() => this.directory(false, async (path) => {
-            const target = join(path, this.name(workspaceId));
+            const target = join(path, this.name(workspaceId, directoryName));
             await this.read(target);
             await unlink(target).catch(error => { if (error.code !== 'ENOENT')
                 throw error; });
@@ -138,7 +139,7 @@ export class WorkspaceGitDirectStore {
     async sweep(destroy = false) {
         await this.exclusive(() => this.directory(false, async (path) => {
             for (const name of await readdir(path)) {
-                if (!/^[a-f0-9-]{36}\.(json|tmp)$/.test(name))
+                if (!/^[a-f0-9-]{36}(?:--remix-[a-z0-9][a-z0-9-]{3,63})?\.(json|tmp)$/.test(name))
                     throw new Error('git_credential_file_rejected');
                 const target = join(path, name);
                 if (name.endsWith('.tmp')) {

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

@@ -2,11 +2,11 @@ import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isLocalWorkspaceGitAuthMode, isLocalWorkspaceGitEnvironment, matchWorkspaceGitGatewayCloneUrl, sameWorkspaceRegistration, workspacePreparationSchema, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { isLocalWorkspaceGitAuthMode, isLocalWorkspaceGitEnvironment, matchWorkspaceGitGatewayCloneUrl, sameWorkspaceRegistration, workspacePreparationSchema, workspaceRegistrationSchema, workspaceDirectoryNameSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { WorkspaceContextError } from './context-error.js';
 import { scaffoldEmptyWorkspace } from './empty-template.js';
 /** The caller holds the Workspace lock. Only an absent, never-published directory may be prepared. */
-export async function prepareWorkspaceCheckout(state, binding, input, leaseFence) {
+export async function prepareWorkspaceCheckout(state, binding, input, leaseFence, directoryName = 'basic', recovery = false) {
     const preparation = workspacePreparationSchema.safeParse(input);
     if (!preparation.success)
         throw new WorkspaceContextError('invalid_workspace_preparation');
@@ -20,15 +20,24 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
         || clone.directAccess.repositoryUrl !== binding.repositoryUrl))
         throw new WorkspaceContextError('workspace_git_gateway_unavailable');
     const parent = await realpath(state.config.workspaceRoot);
-    const target = join(parent, binding.workspaceId);
+    const workspace = join(parent, binding.workspaceId);
+    workspaceDirectoryNameSchema.parse(directoryName);
+    const target = join(workspace, directoryName);
     const receiptDir = join(state.config.stateDir, 'workspace-preparations');
     await mkdir(receiptDir, { recursive: true, mode: 0o700 });
-    const receiptPath = join(receiptDir, `${binding.workspaceId}.json`);
-    const previous = await readReceipt(receiptPath, binding);
+    const receiptPath = join(receiptDir, `${binding.workspaceId}${directoryName === 'basic' ? '' : `--${directoryName}`}.json`);
+    let previous = await readReceipt(receiptPath, binding);
+    if (recovery && previous?.status === 'published')
+        previous = undefined;
     if (previous?.status === 'published')
         throw new WorkspaceContextError('workspace_recovery_required');
     if (await exists(target))
         throw new WorkspaceContextError('workspace_checkout_conflict');
+    if (await exists(workspace)) {
+        const stat = await lstat(workspace);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(workspace) !== workspace)
+            throw new WorkspaceContextError('invalid_workspace_directory');
+    }
     // An unfinished checkout recorded before the fork instructions were known must be cloned again.
     const forkMatches = !previous || samePendingFork(previous.binding, binding);
     if (previous && !forkMatches)
@@ -133,6 +142,12 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
     assertCurrent();
     if (await exists(target))
         throw new WorkspaceContextError('workspace_checkout_conflict');
+    if (await exists(workspace)) {
+        const stat = await lstat(workspace);
+        if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(workspace) !== workspace)
+            throw new WorkspaceContextError('invalid_workspace_directory');
+    }
+    await mkdir(workspace, { recursive: true, mode: 0o700 });
     await rename(staging, target);
     receipt.status = 'published';
     await writeReceipt(receiptPath, receipt);

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

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { lstat, realpath } from 'node:fs/promises';
+import { lstat, mkdir, realpath } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { promisify } from 'node:util';
 import { isLocalWorkspaceGitAuthMode, sameWorkspaceRegistration, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
@@ -10,31 +10,39 @@ import { ensureWorkspaceSkills, readWorkspaceSkills } from './skills.js';
 import { loadWorkspaceSkillArtifact } from './skill-artifact-loader.js';
 export { WorkspaceContextError } from './context-error.js';
 const exec = promisify(execFile);
-export function revisionScope(state, workspaceId) {
-    return state.config.workspaceMode === 'multi' ? workspaceId : undefined;
+export function revisionScope(state, workspaceId, directoryName = 'basic') {
+    return state.config.workspaceMode === 'multi' ? `${workspaceId}:${directoryName}` : undefined;
 }
-export function workspaceSessions(state, workspaceId) {
+export function workspaceSessions(state, workspaceId, directoryName = 'basic') {
     return state.journal
         .listSessions()
-        .filter((item) => state.config.workspaceMode !== 'multi' || item.workspaceId === workspaceId);
+        .filter((item) => state.config.workspaceMode !== 'multi' || (item.workspaceId === workspaceId && (item.directoryName ?? 'basic') === directoryName));
 }
-export async function workspaceRoot(state, workspaceId) {
+export async function workspaceRoot(state, workspaceId, directoryName = 'basic') {
     if (state.config.workspaceMode !== 'multi')
         return state.config.workspaceRoot;
     if (!workspaceId || !state.journal.getWorkspace(workspaceId))
         throw new WorkspaceContextError('workspace_not_registered');
-    return checkedDirectory(state, workspaceId);
+    if (!/^(basic|remix-[a-z0-9][a-z0-9-]{3,63})$/.test(directoryName))
+        throw new WorkspaceContextError('invalid_workspace_directory');
+    if (directoryName !== 'basic' && !state.journal.getWorkspace(workspaceId)?.directories?.some(directory => directory.directoryName === directoryName))
+        throw new WorkspaceContextError('workspace_directory_not_registered');
+    return checkedDirectory(state, workspaceId, directoryName);
 }
-async function checkedDirectory(state, workspaceId) {
+async function checkedDirectory(state, workspaceId, directoryName = 'basic') {
     if (!/^[0-9a-f-]{36}$/i.test(workspaceId))
         throw new WorkspaceContextError('invalid_workspace');
     const parent = await realpath(state.config.workspaceRoot);
-    const target = join(parent, workspaceId);
+    const container = join(parent, workspaceId);
+    const containerStat = await lstat(container).catch(() => undefined);
+    if (!containerStat?.isDirectory() || containerStat.isSymbolicLink() || relative(parent, await realpath(container)) !== workspaceId)
+        throw new WorkspaceContextError('workspace_not_prepared');
+    const target = join(container, directoryName);
     try {
         const stat = await lstat(target);
         if (!stat.isDirectory() ||
             stat.isSymbolicLink() ||
-            relative(parent, await realpath(target)) !== workspaceId) {
+            relative(container, await realpath(target)) !== directoryName) {
             throw new WorkspaceContextError('invalid_workspace_directory');
         }
         const stateDir = await realpath(state.config.stateDir);
@@ -49,6 +57,37 @@ async function checkedDirectory(state, workspaceId) {
     }
 }
 /** Registers a fixed directory; optional first creation is restricted to its trusted binding. */
+export async function workspaceContainerRoot(state, workspaceId) {
+    if (state.config.workspaceMode !== 'multi')
+        return state.config.workspaceRoot;
+    if (!workspaceId || !state.journal.getWorkspace(workspaceId))
+        throw new WorkspaceContextError('workspace_not_registered');
+    if (!/^[0-9a-f-]{36}$/i.test(workspaceId))
+        throw new WorkspaceContextError('invalid_workspace');
+    const parent = await realpath(state.config.workspaceRoot);
+    const container = join(parent, workspaceId);
+    const stat = await lstat(container).catch(() => undefined);
+    if (!stat?.isDirectory() || stat.isSymbolicLink() || relative(parent, await realpath(container)) !== workspaceId)
+        throw new WorkspaceContextError('workspace_not_prepared');
+    const stateDir = await realpath(state.config.stateDir);
+    if (stateDir === container || stateDir.startsWith(`${container}/`))
+        throw new WorkspaceContextError('invalid_workspace_directory');
+    return container;
+}
+export async function sessionWorkspaceRoot(state, workspaceId, directoryName = 'basic') {
+    return directoryName === 'root' ? workspaceContainerRoot(state, workspaceId) : workspaceRoot(state, workspaceId, directoryName);
+}
+export async function workspaceContextFromRoot(state, cwd) {
+    const parent = await realpath(state.config.workspaceRoot);
+    const parts = relative(parent, cwd).split('/');
+    if (parts.length !== 1 && parts.length !== 2)
+        throw new WorkspaceContextError('workspace_not_registered');
+    const workspaceId = parts[0];
+    const directoryName = parts.length === 1 ? 'root' : parts[1];
+    if (await sessionWorkspaceRoot(state, workspaceId, directoryName) !== cwd)
+        throw new WorkspaceContextError('workspace_not_registered');
+    return { workspaceId, directoryName };
+}
 export async function registerWorkspace(state, input, leaseFence, preparation) {
     if (state.config.workspaceMode !== 'multi')
         throw new WorkspaceContextError('multi_workspace_unavailable');
@@ -66,6 +105,18 @@ export async function registerWorkspace(state, input, leaseFence, preparation) {
         const existing = state.journal.getWorkspace(binding.workspaceId);
         if (existing && !sameWorkspaceRegistration(existing, binding))
             throw new WorkspaceContextError('workspace_binding_conflict');
+        const directories = binding.directories ?? existing?.directories;
+        if (directories?.some(directory => directory.directoryName === 'basic' && directory.status === 'reclaimed')) {
+            // Registration publishes trusted identity. Only an explicit basic ensure restores the checkout.
+            const parent = await realpath(state.config.workspaceRoot);
+            const container = join(parent, binding.workspaceId);
+            await mkdir(container, { mode: 0o2770 }).catch(error => { if (error.code !== 'EEXIST')
+                throw error; });
+            const registered = { ...binding, directories };
+            await state.journal.putWorkspace(registered);
+            await workspaceContainerRoot(state, binding.workspaceId);
+            return registered;
+        }
         let root;
         try {
             root = await checkedDirectory(state, binding.workspaceId);
@@ -129,13 +180,13 @@ export async function registerWorkspace(state, input, leaseFence, preparation) {
         catch {
             throw new WorkspaceContextError('workspace_skills_unavailable');
         }
-        await state.journal.putWorkspace(binding);
+        await state.journal.putWorkspace({ ...binding, directories });
         try {
             await readWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'), entry => loadWorkspaceSkillArtifact(state, binding.workspaceId, entry));
         }
         catch { /* Skills reads and native turns diagnose missing artifacts; files and source repair remain available. */ }
         // Runs in the background; every registration rechecks it, so reopening retries a failed install.
-        void scheduleDependencyInstall(state, binding.workspaceId, root);
+        void scheduleDependencyInstall(state, revisionScope(state, binding.workspaceId), root);
         return binding;
     });
 }