@playcraft/cli 0.1.21 → 0.1.22

package/dist/workspace-runtime/production/processes.js

@@ -0,0 +1,86 @@
+import { spawn, execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { startLauncherProcess } from '../codex/launcher-client.js';
+export async function processBirth(pid) {
+    if (process.platform !== 'linux') {
+        return promisify(execFile)('ps', ['-p', String(pid), '-o', 'lstart='], { timeout: 2000 }).then(value => value.stdout.trim() || undefined, () => undefined);
+    }
+    try {
+        const stat = await readFile(`/proc/${pid}/stat`, 'utf8');
+        return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function groupExited(pid) {
+    try {
+        process.kill(-pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+export async function stopProductionGroup(record) {
+    if (record.stopped || groupExited(record.pid))
+        return true;
+    if (record.birth && await processBirth(record.pid) !== record.birth)
+        return false;
+    for (const signal of ['SIGTERM', 'SIGKILL']) {
+        try {
+            process.kill(-record.pid, signal);
+        }
+        catch { /* Recheck whether the whole group exited. */ }
+        const deadline = Date.now() + 2000;
+        while (Date.now() < deadline) {
+            if (groupExited(record.pid))
+                return true;
+            await delay(25);
+        }
+    }
+    return groupExited(record.pid);
+}
+/** Only the save stage receives repository credentials; build and install receive none. */
+export async function runProductionCommand(state, input) {
+    const launcher = !input.trusted ? process.env.PLAYCRAFT_LAUNCHER_SOCKET : undefined;
+    const launched = launcher ? await startLauncherProcess({ socketPath: launcher, processId: input.processId,
+        runtimeEpoch: state.runtimeEpoch, argv: ['/usr/bin/bash', '-lc', input.command], cwd: input.cwd, env: input.env ?? {} }) : undefined;
+    const local = launched ? undefined : spawn('bash', ['-lc', input.command], { cwd: input.cwd,
+        env: { PATH: process.env.PATH, HOME: state.config.stateDir, ...input.env }, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const pid = launched?.pid ?? local?.pid;
+    if (!pid)
+        throw new Error('production_process_not_started');
+    const record = { pid, birth: await processBirth(pid), stopped: false };
+    try {
+        await input.record(record);
+    }
+    catch (error) {
+        await stopProductionGroup(record);
+        throw error;
+    }
+    let output = '';
+    const collect = (chunk) => { output = (output + String(chunk)).slice(-64 * 1024); };
+    (launched?.stdout ?? local.stdout).on('data', collect);
+    (launched?.stderr ?? local.stderr).on('data', collect);
+    launched?.stdin?.end();
+    let timedOut = false;
+    const code = await new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            void (launched ? launched.stop() : stopProductionGroup(record)).catch(() => undefined).finally(() => resolve(undefined));
+        }, input.timeoutMs);
+        const finish = (code) => { clearTimeout(timeout); resolve(code); };
+        if (launched)
+            launched.onExit(finish);
+        else {
+            local.once('error', () => finish(undefined));
+            local.once('close', finish);
+        }
+    });
+    const stopped = await stopProductionGroup(record);
+    await input.record({ ...record, stopped });
+    return { code: timedOut ? undefined : code, output, stopped };
+}

package/dist/workspace-runtime/production/save-command.js

@@ -0,0 +1,20 @@
+export function productionSaveCommand() {
+    return `set -eu
+status=0
+remote=$(git -c protocol.version=0 -c core.hooksPath=/dev/null ls-remote --exit-code --heads "$PRODUCTION_REPOSITORY" "refs/heads/$PRODUCTION_BRANCH") || status=$?
+if [ "$status" != 0 ] && [ "$status" != 2 ]; then exit "$status"; fi
+if [ "\${PRODUCTION_EXPECTED_PARENT+x}" = x ]; then
+  actual=$(printf '%s' "$remote" | cut -f1)
+  test "$actual" = "$PRODUCTION_EXPECTED_PARENT" || { printf 'production_git_parent_changed\\n' >&2; exit 1; }
+fi
+if [ -n "$remote" ]; then
+  parent=$(printf '%s' "$remote" | cut -f1)
+  git -c protocol.version=0 -c core.hooksPath=/dev/null fetch --no-tags --no-recurse-submodules "$PRODUCTION_REPOSITORY" "refs/heads/$PRODUCTION_BRANCH"
+  test "$(git rev-parse FETCH_HEAD)" = "$parent"
+  git -c core.hooksPath=/dev/null -c core.fsmonitor=false reset --soft FETCH_HEAD
+fi
+git -c core.hooksPath=/dev/null -c core.fsmonitor=false add -A .
+git diff --cached --quiet || git -c core.hooksPath=/dev/null commit -m "Save generated engineering"
+git -c protocol.version=0 -c core.hooksPath=/dev/null push "$PRODUCTION_REPOSITORY" HEAD:"refs/heads/$PRODUCTION_BRANCH"
+git rev-parse HEAD`;
+}

package/dist/workspace-runtime/production/stages.js

@@ -0,0 +1,175 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { batchBaselineSnapshotSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { checkoutBatchCommit, freezeBatchCommit } from '../workspaces/batch-commit.js';
+import { openDirectoryToDevelopment } from '../workspaces/directory-access.js';
+import { registerWorkspaceDirectory } from '../workspaces/directories.js';
+import { workspaceRoot, workspaceSessions } from '../workspaces/registry.js';
+import { excludeFromGit, settleDependencyInstalls } from '../workspaces/dependencies.js';
+import { resolveProductionDependencies, verifyProductionDependencyLocks } from './dependencies.js';
+import { productionSaveCommand } from './save-command.js';
+import { productionOutputStore, verifyProductionLease } from './storage.js';
+import { runProductionCommand } from './processes.js';
+import { runProductionNative } from './native.js';
+import { classifyPreviewOutput, findExternalLocalReferences } from '../previews/single-file.js';
+const execute = promisify(execFile);
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const hash = (body) => createHash('sha256').update(body).digest('hex');
+const record = (value) => value && typeof value === 'object' ? value : {};
+export async function executeProductionStage(state, input, processRecord, track) {
+    await verifyProductionLease(input);
+    const store = productionOutputStore(input);
+    const stage = input.stage;
+    const workspaceId = input.task.workspaceId;
+    const resultId = String(input.payload.resultVersionId ?? input.task.payload.resultVersionId ?? input.task.attemptId);
+    const previous = (name) => input.stages?.find(value => value.stage === name && value.status === 'completed')?.result;
+    const run = async (cwd, command, env, trusted = false) => {
+        const outcome = await runProductionCommand(state, { processId: `production-${input.task.attemptId}-${stage}`, cwd, command, env, trusted,
+            timeoutMs: 10 * 60_000, record: processRecord });
+        if (!outcome.stopped || outcome.code === undefined)
+            throw new Error('production_process_unknown');
+        if (outcome.code !== 0)
+            throw new Error(`production_${stage}_failed`);
+        return outcome.output;
+    };
+    const git = async (root, ...args) => (await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root, ...args], {
+        timeout: 20_000, maxBuffer: 1024 * 1024, env: { PATH: process.env.PATH, HOME: state.config.stateDir, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' },
+    })).stdout.trim();
+    if (stage === 'prepare' && input.directoryName !== 'basic') {
+        const baseline = record(input.payload.baseline ?? input.task.payload.baseline);
+        const authority = record(input.payload.workspace);
+        const sourceCommit = baseline.commitHash;
+        if (typeof sourceCommit !== 'string')
+            throw new Error('production_approved_commit_required');
+        const directory = { workspaceId, directoryName: input.directoryName,
+            remixId: String(authority.remixId), branchName: String(authority.branchName), sourceCommit };
+        await registerWorkspaceDirectory(state, directory, state.acceptedLeaseFence);
+    }
+    const root = await workspaceRoot(state, workspaceId, input.directoryName);
+    if (stage === 'capture-source') {
+        if (input.directoryName !== 'basic')
+            throw new Error('production_source_directory_mismatch');
+        if (workspaceSessions(state, workspaceId, 'basic').some(session => session.turnBlock === 'uncertain' || ['starting', 'running', 'waiting_for_user'].includes(session.turnStatus ?? '')))
+            throw new Error('production_source_busy');
+        await settleDependencyInstalls(state);
+        await resolveProductionDependencies(root);
+        await excludeFromGit(root);
+        await excludeFromGit(root, '/.env*');
+        await git(root, 'config', 'user.name', 'PlayCraft');
+        await git(root, 'config', 'user.email', 'playcraft@localhost');
+        await run(root, 'git -c core.hooksPath=/dev/null add -A . && (git diff --cached --quiet || git -c core.hooksPath=/dev/null commit -m "Preserve basic before common repair")', undefined, true);
+        const commitHash = await git(root, 'rev-parse', 'HEAD');
+        const snapshot = await freezeBatchCommit({ source: { workspaceId, root }, commitHash, snapshotId: `${input.task.attemptId}-capture-source` });
+        return { sourceSnapshot: snapshot, commitHash };
+    }
+    if (stage === 'prepare') {
+        await settleDependencyInstalls(state);
+        const policy = await resolveProductionDependencies(root);
+        await run(root, process.env.PLAYCRAFT_PRODUCTION_INSTALL_COMMAND ?? 'pnpm install --frozen-lockfile --store-dir /var/cache/playcraft/pnpm-store --ignore-scripts');
+        await verifyProductionDependencyLocks(root, policy);
+        return { prepared: true, directoryName: input.directoryName };
+    }
+    if (stage === 'generate') {
+        await runProductionNative(state, input, root, processRecord, track);
+        await resolveProductionDependencies(root);
+        return { generated: true };
+    }
+    if (stage === 'save') {
+        if (!input.git)
+            throw new Error('production_git_scope_required');
+        const binding = state.journal.getWorkspace(workspaceId);
+        const branch = input.directoryName === 'basic' ? binding.branchName : binding.directories?.find(value => value.directoryName === input.directoryName)?.branchName;
+        if (input.git.branchName !== branch || await git(root, 'symbolic-ref', '--short', 'HEAD') !== branch)
+            throw new Error('production_git_binding_mismatch');
+        await excludeFromGit(root);
+        await excludeFromGit(root, '/.env*');
+        await excludeFromGit(root, '/.playcraft-temp/');
+        await excludeFromGit(root, '/.playcraft-preview-out/');
+        await git(root, 'config', 'user.name', 'PlayCraft');
+        await git(root, 'config', 'user.email', 'playcraft@localhost');
+        const env = { PRODUCTION_REPOSITORY: input.git.repositoryUrl, PRODUCTION_BRANCH: input.git.branchName,
+            GIT_TERMINAL_PROMPT: '0', GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1' };
+        if (input.git.username && input.git.password)
+            Object.assign(env, { GIT_CONFIG_COUNT: '1',
+                GIT_CONFIG_KEY_0: `http.${input.git.repositoryUrl}.extraHeader`,
+                GIT_CONFIG_VALUE_0: `Authorization: Basic ${Buffer.from(`${input.git.username}:${input.git.password}`).toString('base64')}` });
+        if (typeof input.payload.expectedParent === 'string')
+            env.PRODUCTION_EXPECTED_PARENT = input.payload.expectedParent;
+        await run(root, productionSaveCommand(), env, true);
+        const commitHash = await git(root, 'rev-parse', 'HEAD');
+        const snapshot = await freezeBatchCommit({ source: { workspaceId, root }, commitHash, snapshotId: `${input.task.attemptId}-save` });
+        return { snapshot, saved: { attemptId: input.task.attemptId, resultVersionId: resultId, workspaceId, sourceDigest: snapshot.checksum, commitHash, pushedCommitHash: commitHash } };
+    }
+    if (stage === 'freeze') {
+        const saved = record(previous('save')?.saved);
+        if (typeof saved.commitHash !== 'string')
+            throw new Error('production_saved_commit_required');
+        const snapshot = await freezeBatchCommit({ source: { workspaceId, root }, commitHash: saved.commitHash, snapshotId: `${input.task.attemptId}-freeze` });
+        const baseline = batchBaselineSnapshotSchema.parse({ batchId: input.task.batchId, projectId: String(input.payload.projectId ?? input.task.payload.projectId),
+            snapshotId: snapshot.snapshotId, sourceWorkspaceId: snapshot.sourceWorkspaceId, commitHash: snapshot.commitHash, checksum: snapshot.checksum,
+            sourceVersion: snapshot.sourceVersion, engine: String(input.payload.engine ?? input.task.payload.engine), skillLockDigest: snapshot.skillLockDigest, frozenAt: snapshot.frozenAt });
+        return { snapshot, baseline };
+    }
+    if (stage === 'build') {
+        const saved = record(input.payload.saved ?? previous('save')?.saved);
+        const snapshot = (previous('freeze')?.snapshot ?? previous('save')?.snapshot);
+        if (!snapshot || snapshot.commitHash !== saved.commitHash || snapshot.checksum !== saved.sourceDigest)
+            throw new Error('production_saved_snapshot_mismatch');
+        const destination = join(root, '.playcraft-temp', `production-${input.task.attemptId}`);
+        await excludeFromGit(root, '/.playcraft-temp/');
+        await rm(destination, { recursive: true, force: true });
+        try {
+            await checkoutBatchCommit({ source: { workspaceId, root }, frozen: snapshot, destination });
+            await openDirectoryToDevelopment(destination, (await lstat(state.config.workspaceRoot)).gid);
+            const policy = await resolveProductionDependencies(destination);
+            await run(destination, process.env.PLAYCRAFT_PRODUCTION_INSTALL_COMMAND ?? 'pnpm install --frozen-lockfile --store-dir /var/cache/playcraft/pnpm-store --ignore-scripts');
+            await verifyProductionDependencyLocks(destination, policy);
+            const output = join(destination, '.production-html');
+            const command = process.env.PLAYCRAFT_PRODUCTION_BUILD_COMMAND ?? 'playcraft build --mode full --platform playcraft --format html';
+            await run(destination, `${command} --output ${quote(output)} .`);
+            await verifyProductionDependencyLocks(destination, policy);
+            const entries = await readdir(output, { withFileTypes: true });
+            const single = classifyPreviewOutput(entries.map(entry => ({ name: entry.name, kind: entry.isFile() ? 'file' : entry.isDirectory() ? 'dir' : 'symlink' })));
+            if (!single.ok)
+                throw new Error('production_preview_not_single_file');
+            const path = join(output, single.entry);
+            if (!(await lstat(path)).isFile())
+                throw new Error('production_preview_invalid');
+            const body = await readFile(path);
+            if (findExternalLocalReferences(body.toString()).length)
+                throw new Error('production_preview_external_reference');
+            const outputDigest = hash(body), outputKey = `workspaces/${workspaceId}/production/${input.task.attemptId}/${outputDigest}.html`;
+            await store.put(outputKey, body);
+            return { outputKey, outputDigest, build: { attemptId: input.task.attemptId, resultVersionId: resultId, workspaceId,
+                    sourceDigest: snapshot.checksum, commitHash: snapshot.commitHash, buildId: `${input.task.attemptId}-build`, succeeded: true } };
+        }
+        finally {
+            await rm(destination, { recursive: true, force: true });
+        }
+    }
+    if (stage === 'preview') {
+        const built = previous('build');
+        if (typeof built?.outputKey !== 'string' || typeof built.outputDigest !== 'string')
+            throw new Error('production_build_required');
+        const body = await store.get(built.outputKey);
+        if (hash(body) !== built.outputDigest)
+            throw new Error('production_preview_digest_mismatch');
+        const previewPath = join(root, '.playcraft-temp', `${input.task.attemptId}.html`);
+        await mkdir(dirname(previewPath), { recursive: true });
+        await writeFile(previewPath, body);
+        try {
+            const browser = process.env.PLAYCRAFT_PRODUCTION_PREVIEW_COMMAND ?? 'chromium --headless --no-sandbox --disable-gpu --virtual-time-budget=1000 --dump-dom';
+            const opened = await run(root, `${browser} ${quote(`file://${previewPath}`)}`);
+            if (!/<html[\s>]/i.test(opened))
+                throw new Error('production_preview_not_opened');
+            return { opened: true, outputDigest: built.outputDigest };
+        }
+        finally {
+            await rm(previewPath, { force: true });
+        }
+    }
+    throw new Error('invalid_production_stage');
+}

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

@@ -0,0 +1,32 @@
+const taskUrl = (input) => `${input.callbackUrl.replace(/\/+$/, '')}/internal/cloud-production/tasks/${input.task.taskId}`;
+/** Build output travels through the Runtime that leased the task; engineering files travel through Git. */
+export function productionOutputStore(input) {
+    const object = (key) => `${taskUrl(input)}/objects/${encodeURIComponent(key)}`;
+    const headers = { authorization: `Bearer ${input.runnerToken}`, 'x-playcraft-object-client': 'cli' };
+    return {
+        async get(key) {
+            const response = await fetch(object(key), { headers, redirect: 'error', signal: AbortSignal.timeout(60_000) });
+            if (response.status === 404)
+                throw new Error('object_missing');
+            if (!response.ok)
+                throw new Error('object_get_failed');
+            return Buffer.from(await response.arrayBuffer());
+        },
+        async put(key, body) {
+            const response = await fetch(object(key), { method: 'PUT', body: new Uint8Array(body), redirect: 'error', signal: AbortSignal.timeout(60_000),
+                headers: { ...headers, 'content-type': 'application/octet-stream' } });
+            if (!response.ok)
+                throw new Error(response.status === 409 ? 'object_conflict' : 'object_put_failed');
+        },
+    };
+}
+export async function verifyProductionLease(input) {
+    const response = await fetch(`${taskUrl(input)}/runner`, {
+        headers: { authorization: `Bearer ${input.runnerToken}` }, redirect: 'error', signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok)
+        throw new Error('production_lease_unavailable');
+    const { task } = await response.json();
+    if (!task || task.taskId !== input.task.taskId || task.attemptId !== input.task.attemptId || task.leaseOwner !== input.lease.owner || task.leaseFence !== input.lease.fence || task.status !== 'running' || task.cancelRequested)
+        throw new Error('production_lease_unavailable');
+}

package/dist/workspace-runtime/serve.js

@@ -18,8 +18,7 @@ import { WorkspaceModelBroker } from './codex/model-broker.js';
 import { recoverInterruptedPreviews } from './previews/publish.js';
 import { recoverInterruptedInstalls } from './workspaces/dependencies.js';
 import { loadWorkspaceSkillArtifact } from './workspaces/skill-artifact-loader.js';
-import { workspaceRoot } from './workspaces/registry.js';
-import { basename } from 'node:path';
+import { workspaceContextFromRoot } from './workspaces/registry.js';
 export async function startWorkspaceRuntime(config, options = {}) {
     process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
     const negotiated = negotiateProtocol(config);
@@ -190,10 +189,8 @@ function defaultNativeAdapter(state) {
             config,
             ...(multi ? { modelBroker: new WorkspaceModelBroker(state) } : {}),
             loadSkillArtifact: async (cwd, entry) => {
-                const id = basename(cwd);
-                if (await workspaceRoot(state, id) !== cwd)
-                    throw new Error('workspace_skills_unavailable');
-                return loadWorkspaceSkillArtifact(state, id, entry);
+                const { workspaceId, directoryName } = await workspaceContextFromRoot(state, cwd);
+                return loadWorkspaceSkillArtifact(state, workspaceId, entry, directoryName === 'root' ? 'basic' : directoryName);
             },
             onSkillProcessRestart: process => state.journal.noteExecutionGroup(process),
         });

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

@@ -94,7 +94,7 @@ export class DesktopHost {
                 this.preview ??= new DesktopPreviewHost(this.state, {
                     canNavigate: () => !this.disposed && !this.state.journal.destroyed() && this.holder !== 'human',
                 });
-                await this.preview.open(url.searchParams.get('workspaceId') ?? undefined);
+                await this.preview.open(url.searchParams.get('workspaceId') ?? undefined, url.searchParams.get('directoryName') ?? 'basic');
                 if (this.disposed || this.state.journal.destroyed()) {
                     writeError(response, 'runtime_destroyed');
                     return;

package/dist/workspace-runtime/server/desktop-preview.js

@@ -31,15 +31,15 @@ export class DesktopPreviewHost {
         this.state = state;
         this.options = options;
     }
-    open(workspaceId) {
+    open(workspaceId, directoryName = 'basic') {
         if (!this.canNavigate())
             return Promise.resolve();
-        const key = workspaceId ?? 'single';
+        const key = workspaceId ? `${workspaceId}:${directoryName}` : 'single';
         this.requestedKey = key;
         const existing = this.pending.get(key);
         if (existing)
             return existing;
-        const task = this.openWorkspace(key, workspaceId).catch((error) => {
+        const task = this.openWorkspace(key, workspaceId, directoryName).catch((error) => {
             if (error instanceof DesktopPreviewError || error instanceof WorkspaceContextError)
                 throw error;
             throw new DesktopPreviewError('desktop_preview_start_failed');
@@ -67,8 +67,8 @@ export class DesktopPreviewHost {
     canNavigate() {
         return !this.disposed && !this.state.journal.destroyed() && (this.options.canNavigate?.() ?? true);
     }
-    async openWorkspace(key, workspaceId) {
-        const root = await workspaceRoot(this.state, workspaceId);
+    async openWorkspace(key, workspaceId, directoryName = 'basic') {
+        const root = await workspaceRoot(this.state, workspaceId, directoryName);
         const deadline = Date.now() + (this.options.timeoutMs ?? 90_000);
         if (!this.canNavigate())
             return;

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

@@ -1,5 +1,5 @@
 import { withObservedFile } from '../workspaces/revisions.js';
-import { revisionScope, workspaceRoot, workspaceSessions } from '../workspaces/registry.js';
+import { revisionScope, sessionWorkspaceRoot, workspaceRoot, workspaceSessions } from '../workspaces/registry.js';
 import { join } from 'node:path';
 import { z } from 'zod';
 import { PLATFORM_ROUTES, platformEndpoint, fileWritePayloadSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, parameterPatchPayloadSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, } from '@playcraft/common/cloud-workspace/runtime';
@@ -55,7 +55,7 @@ export async function executeOperation(state, scopeKey, operation, payload, reco
     if (['runtime.destroy', 'session.interrupt', 'session.approval.respond', 'preview.publish'].includes(operation.kind)) {
         return run();
     }
-    return state.journal.exclusive(`workspace:${revisionScope(state, operation.workspaceId) ?? 'single'}`, run);
+    return state.journal.exclusive(`workspace:${revisionScope(state, operation.workspaceId, operation.directoryName) ?? 'single'}`, run);
 }
 async function executeScopedOperation(state, scopeKey, operation, payload, recovery) {
     let current = await persist(state, scopeKey, transitionOperation(operation, 'dispatched'));
@@ -122,10 +122,10 @@ async function executeSkillsUpdate(state, scopeKey, operation, payload) {
     const parsed = workspaceSkillsUpdatePayloadSchema.safeParse(payload);
     if (!parsed.success)
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'invalid_skills_update' }));
-    if (workspaceSessions(state, operation.workspaceId).some(sessionTurnBusy))
+    if (workspaceSessions(state, operation.workspaceId, operation.directoryName).some(sessionTurnBusy))
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'turn_already_active' }));
     try {
-        const root = await workspaceRoot(state, operation.workspaceId);
+        const root = await workspaceRoot(state, operation.workspaceId, operation.directoryName);
         const snapshot = await readWorkspaceSkillSnapshot(root);
         if (parsed.data.expectedDeclarationHash && parsed.data.expectedDeclarationHash !== snapshot.lock.declarationHash)
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'skills_revision_conflict' }));
@@ -158,7 +158,7 @@ async function executeCreate(state, scopeKey, operation, payload) {
     try {
         started = await native(state).startThread({
             sessionId,
-            cwd: await workspaceRoot(state, operation.workspaceId),
+            cwd: await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName),
             modelConfigId: selected.data,
         });
     }
@@ -174,8 +174,9 @@ async function executeCreate(state, scopeKey, operation, payload) {
     await state.journal.putSession({
         sessionId,
         workspaceId: operation.workspaceId,
+        directoryName: operation.directoryName,
         threadId: started.threadId,
-        cwd: await workspaceRoot(state, operation.workspaceId),
+        cwd: await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName),
         recoverability: 'native',
         modelConfigId: started.modelConfigId,
     });
@@ -217,7 +218,7 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
     }
     let attachments;
     try {
-        attachments = await resolveWorkspaceAttachments(await workspaceRoot(state, operation.workspaceId), body.attachmentIds);
+        attachments = await resolveWorkspaceAttachments(await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName), body.attachmentIds);
     }
     catch {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'attachment_unavailable' }));
@@ -311,7 +312,7 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
 async function rebindSession(state, operation, binding, modelConfigId) {
     const sessionId = required(operation.sessionId, 'sessionId');
     const adapter = native(state);
-    const cwd = await workspaceRoot(state, operation.workspaceId);
+    const cwd = await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName);
     const group = state.journal.executionGroup();
     try {
         if (binding && adapter.resumeThread && (!group.replaced || group.stopConfirmed)) {
@@ -340,6 +341,7 @@ async function rebindSession(state, operation, binding, modelConfigId) {
         const next = {
             sessionId,
             workspaceId: operation.workspaceId,
+            directoryName: operation.directoryName,
             threadId: started.threadId,
             cwd,
             recoverability: 'native',
@@ -457,13 +459,13 @@ async function executeFileWrite(state, scopeKey, operation, payload) {
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'revision_conflict' }));
         }
         try {
-            const root = await workspaceRoot(state, operation.workspaceId);
+            const root = await workspaceRoot(state, operation.workspaceId, operation.directoryName);
             const written = await writeWorkspaceFile(root, parsed.data.path, parsed.data.content);
             const revision = currentRevision + 1;
             await state.journal.putFileRevision(parsed.data.path, {
                 revision,
                 contentHash: written.contentHash,
-            }, revisionScope(state, operation.workspaceId));
+            }, revisionScope(state, operation.workspaceId, operation.directoryName));
             if (parsed.data.hold && parsed.data.writeId) {
                 let pid;
                 if (writer === 'background') {
@@ -498,7 +500,7 @@ async function executeFileWrite(state, scopeKey, operation, payload) {
             const code = error instanceof InvalidWorkspacePathError ? 'invalid_workspace_path' : 'file_write_failed';
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: code }));
         }
-    }).catch((error) => {
+    }, operation.directoryName).catch((error) => {
         const code = error instanceof InvalidWorkspacePathError ? 'invalid_workspace_path' : 'file_write_failed';
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: code }));
     });
@@ -509,7 +511,7 @@ async function executeGitCommit(state, scopeKey, operation, payload) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'invalid_git_commit' }));
     }
     try {
-        const sha = await commitWorkspaceGit(await workspaceRoot(state, operation.workspaceId), parsed.data, boundBranch(state, operation));
+        const sha = await commitWorkspaceGit(await workspaceRoot(state, operation.workspaceId, operation.directoryName), parsed.data, boundBranch(state, operation));
         const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));
         await recordNativeEvents(state, accepted, [
             {
@@ -525,9 +527,10 @@ async function executeGitCommit(state, scopeKey, operation, payload) {
     }
 }
 /**
- * Saves the workspace to Git: commit everything that changed, then push a Remix branch. A
- * standalone workspace has no remote, and the Git gateway never lets a workspace write its
- * project's main branch, so those two only commit.
+ * Saves the workspace directory to Git: commit everything that changed, then push a Remix branch
+ * (a `remix-*` directory is always on its own Remix branch). A standalone workspace has no remote,
+ * and the Git gateway never lets a workspace write its project's main branch, so those two only
+ * commit.
  */
 async function executeWorkspaceSave(state, scopeKey, operation, payload) {
     const parsed = workspaceSavePayloadSchema.safeParse(payload ?? {});
@@ -536,9 +539,9 @@ async function executeWorkspaceSave(state, scopeKey, operation, payload) {
     }
     const binding = operation.workspaceId ? state.journal.getWorkspace(operation.workspaceId) : undefined;
     try {
-        const saved = await saveWorkspaceGit(await workspaceRoot(state, operation.workspaceId), {
+        const saved = await saveWorkspaceGit(await workspaceRoot(state, operation.workspaceId, operation.directoryName), {
             message: parsed.data.trigger === 'auto' ? 'Autosave workspace' : 'Save workspace',
-            push: binding?.targetKind === 'remix',
+            push: binding?.targetKind === 'remix' || Boolean(operation.directoryName && operation.directoryName !== 'basic'),
             boundBranch: boundBranch(state, operation),
         });
         const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));
@@ -561,7 +564,7 @@ async function executeGitPush(state, scopeKey, operation, payload) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'remote_not_configurable' }));
     }
     try {
-        await pushWorkspaceGit(await workspaceRoot(state, operation.workspaceId), boundBranch(state, operation));
+        await pushWorkspaceGit(await workspaceRoot(state, operation.workspaceId, operation.directoryName), boundBranch(state, operation));
         const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));
         await recordNativeEvents(state, accepted, [
             {
@@ -589,7 +592,7 @@ async function executeGitIndex(state, scopeKey, operation, payload) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'invalid_git_paths' }));
     }
     try {
-        await change.run(await workspaceRoot(state, operation.workspaceId), parsed.data);
+        await change.run(await workspaceRoot(state, operation.workspaceId, operation.directoryName), parsed.data);
         const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));
         await recordNativeEvents(state, accepted, [
             { type: change.event, payload: { paths: parsed.data.paths }, occurredAt: new Date().toISOString() },
@@ -605,8 +608,8 @@ async function executeParameterPatch(state, scopeKey, operation, payload) {
     if (!parsed.success) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'invalid_parameter_patch' }));
     }
-    const root = await workspaceRoot(state, operation.workspaceId);
-    const scope = revisionScope(state, operation.workspaceId);
+    const root = await workspaceRoot(state, operation.workspaceId, operation.directoryName);
+    const scope = revisionScope(state, operation.workspaceId, operation.directoryName);
     const document = await readWorkspaceParameters(root, state.journal.fileRevisions(scope));
     if (document.status === 'missing' || document.status === 'schema_only' || !document.dataPath) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'parameter_data_missing' }));
@@ -642,7 +645,7 @@ async function executeParameterPatch(state, scopeKey, operation, payload) {
         catch (error) {
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: parameterPatchError(error) }));
         }
-    }).catch((error) => persist(state, scopeKey, transitionOperation(operation, 'failed', { error: parameterPatchError(error) })));
+    }, operation.directoryName).catch((error) => persist(state, scopeKey, transitionOperation(operation, 'failed', { error: parameterPatchError(error) })));
 }
 /**
  * A preview build takes minutes, so the request returns once the operation is accepted; Runtime
@@ -678,7 +681,7 @@ async function executeTerminalCreate(state, scopeKey, operation, payload) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'invalid_terminal_create' }));
     }
     const existing = state.journal.getTerminal(terminalId);
-    if (existing && existing.workspaceId !== workspaceId) {
+    if (existing && (existing.workspaceId !== workspaceId || (existing.directoryName ?? 'basic') !== (operation.directoryName ?? 'basic'))) {
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'terminal_already_bound' }));
     }
     if (existing?.status === 'destroyed') {
@@ -689,6 +692,7 @@ async function executeTerminalCreate(state, scopeKey, operation, payload) {
     const record = await state.journal.putTerminal({
         terminalId,
         workspaceId,
+        directoryName: operation.directoryName,
         environment: state.config.environment,
         userId: state.config.userId,
         runtimeId: state.config.runtimeId,
@@ -711,7 +715,12 @@ async function executeTerminalCreate(state, scopeKey, operation, payload) {
 }
 /** The branch a registered workspace is bound to; the single-workspace mode has none. */
 function boundBranch(state, operation) {
-    return operation.workspaceId ? state.journal.getWorkspace(operation.workspaceId)?.branchName ?? undefined : undefined;
+    const binding = operation.workspaceId ? state.journal.getWorkspace(operation.workspaceId) : undefined;
+    if (!binding)
+        return undefined;
+    return operation.directoryName && operation.directoryName !== 'basic'
+        ? binding.directories?.find(directory => directory.directoryName === operation.directoryName)?.branchName
+        : binding.branchName ?? undefined;
 }
 function gitErrorCode(error) {
     return error instanceof GitWorkspaceError ? error.code : 'git_command_failed';
@@ -764,6 +773,7 @@ export async function recordNativeEvents(state, operation, events) {
             ...(asRecord(event.payload)),
             ...(operation.sessionId ? { sessionId: operation.sessionId } : {}),
             ...(operation.workspaceId ? { workspaceId: operation.workspaceId } : {}),
+            ...(operation.directoryName ? { directoryName: operation.directoryName } : {}),
         };
         recorded.push(await state.journal.allocateSourceEvent({
             runtimeId: state.config.runtimeId,