@playcraft/cli 0.1.53-beta → 0.1.54

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

@@ -1,278 +0,0 @@
-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, workspaceDirectoryNameSchema, } from '@playcraft/common/cloud-workspace/runtime';
-import { WorkspaceContextError } from './context-error.js';
-import { workspacePlatformSkillAccess } from './skill-artifact-loader.js';
-import { scaffoldEmptyWorkspace } from './empty-template.js';
-const SKILL_PREPARATION_ERRORS = new Set([
-    'workspace_skills_unavailable',
-    'workspace_skills_platform_required',
-    'workspace_skills_platform_unavailable',
-    'workspace_skills_artifact_unavailable',
-    'workspace_skills_artifact_too_large',
-    'workspace_skills_digest_mismatch',
-    'workspace_skills_invalid',
-    'workspace_skills_invalid_bundle',
-    'workspace_skills_builtin_unknown',
-    'workspace_skills_builtin_conflict',
-]);
-/** The caller holds the Workspace lock. Only an absent, never-published directory may be prepared. */
-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');
-    const standalone = binding.targetKind === 'standalone';
-    if (standalone !== (preparation.data.mode === 'empty'))
-        throw new WorkspaceContextError('invalid_workspace_preparation');
-    const clone = preparation.data.mode === 'clone' ? preparation.data : undefined;
-    const source = binding.repositoryUrl ? parseCloneSource(binding.repositoryUrl) : undefined;
-    const direct = isLocalWorkspaceGitAuthMode(clone?.authMode);
-    if (direct && (!isLocalWorkspaceGitEnvironment(state.config.environment) || !clone?.directAccess
-        || clone.directAccess.repositoryUrl !== binding.repositoryUrl))
-        throw new WorkspaceContextError('workspace_git_gateway_unavailable');
-    const parent = await realpath(state.config.workspaceRoot);
-    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}${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)
-        await rm(join(parent, previous.stagingName), { recursive: true, force: true });
-    const receipt = previous && forkMatches ? previous : {
-        binding,
-        stagingName: `.prepare-${binding.workspaceId}-${randomUUID()}`,
-        status: 'cloning',
-    };
-    const staging = join(parent, receipt.stagingName);
-    const assertCurrent = () => {
-        if (state.journal.destroyed())
-            throw new WorkspaceContextError('runtime_destroyed');
-        if (leaseFence < state.acceptedLeaseFence)
-            throw new WorkspaceContextError('stale_lease');
-    };
-    assertCurrent();
-    if (receipt.status === 'cloning') {
-        // Persist ownership before creating/removing a staging directory, so a crash can be retried.
-        await writeReceipt(receiptPath, receipt);
-        await rm(staging, { recursive: true, force: true });
-        await mkdir(staging, { mode: 0o700 });
-        const access = clone?.gitAccess;
-        const credential = clone?.directAccess ?? access;
-        const now = Date.now();
-        if (access &&
-            (Date.parse(access.issuedAt) > now || Date.parse(access.expiresAt) <= now + 10_000)) {
-            await rm(staging, { recursive: true, force: true });
-            throw new WorkspaceContextError('workspace_git_access_expired');
-        }
-        const transport = clone?.transport;
-        if (transport && !matchWorkspaceGitGatewayCloneUrl(transport.cloneUrl, state.config.gitGatewayOrigins, binding.repositoryUrl).ok) {
-            await rm(staging, { recursive: true, force: true });
-            throw new WorkspaceContextError('workspace_git_gateway_unavailable');
-        }
-        const deadline = Math.min(now + 90_000, access ? Date.parse(access.expiresAt) : Infinity);
-        const env = {
-            PATH: process.env.PATH,
-            HOME: state.config.stateDir,
-            GIT_CONFIG_NOSYSTEM: '1',
-            GIT_CONFIG_GLOBAL: '/dev/null',
-            GIT_TERMINAL_PROMPT: '0',
-            GIT_ALLOW_PROTOCOL: 'http:https',
-        };
-        // The authenticated registration already carries this operation's scoped credential.
-        // No publisher ledger is mounted in the sandbox; secrets exist only in this child environment.
-        if (credential) {
-            env.GIT_CONFIG_COUNT = transport ? '2' : '1';
-            env.GIT_CONFIG_KEY_0 = `http.${transport?.cloneUrl ?? source.href}.extraHeader`;
-            env.GIT_CONFIG_VALUE_0 = `Authorization: Basic ${Buffer.from(`${credential.username}:${credential.password}`).toString('base64')}`;
-            if (transport) {
-                env.GIT_CONFIG_KEY_1 = `url.${transport.cloneUrl}.insteadOf`;
-                env.GIT_CONFIG_VALUE_1 = binding.repositoryUrl;
-            }
-        }
-        try {
-            if (standalone) {
-                await runGit(['init', '--initial-branch=main', staging], env, deadline);
-                await scaffoldEmptyWorkspace(staging, join(state.config.stateDir, 'skill-artifacts'), workspacePlatformSkillAccess(state, binding.workspaceId));
-            }
-            else {
-                const fork = binding.pendingFork;
-                const cloneBranch = fork?.sourceBranchName ?? binding.branchName;
-                await runGit(['check-ref-format', '--branch', binding.branchName], env, deadline);
-                await runGit(['check-ref-format', '--branch', cloneBranch], env, deadline);
-                await runGit([
-                    'clone',
-                    '--no-checkout',
-                    '--single-branch',
-                    '--branch',
-                    cloneBranch,
-                    '--',
-                    binding.repositoryUrl,
-                    staging,
-                ], env, deadline);
-                // Checkout never receives the temporary credential and never invokes repository hooks or global filters.
-                clearCloneSecrets(env);
-                if (fork) {
-                    await runGit(['-C', staging, 'checkout', '-b', binding.branchName, fork.sourceCommit], env, deadline);
-                }
-                else {
-                    await runGit(['-C', staging, 'checkout', '--force', binding.branchName], env, deadline);
-                }
-            }
-            assertCurrent();
-            receipt.status = 'ready';
-            await writeReceipt(receiptPath, receipt);
-        }
-        catch (error) {
-            await rm(staging, { recursive: true, force: true });
-            if (error instanceof WorkspaceContextError)
-                throw error;
-            if (standalone && error instanceof Error && SKILL_PREPARATION_ERRORS.has(error.message))
-                throw new WorkspaceContextError(error.message);
-            throw new WorkspaceContextError('workspace_clone_failed');
-        }
-        finally {
-            clearCloneSecrets(env);
-        }
-    }
-    const stat = await lstat(staging).catch(() => undefined);
-    if (!stat?.isDirectory() || stat.isSymbolicLink())
-        throw new WorkspaceContextError('workspace_recovery_required');
-    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);
-}
-function clearCloneSecrets(env) {
-    for (const key of [
-        'GIT_CONFIG_COUNT',
-        'GIT_CONFIG_KEY_0',
-        'GIT_CONFIG_VALUE_0',
-        'GIT_CONFIG_KEY_1',
-        'GIT_CONFIG_VALUE_1',
-    ]) {
-        delete env[key];
-    }
-}
-function parseCloneSource(value) {
-    try {
-        const source = new URL(value);
-        if ((source.protocol !== 'https:' &&
-            !(source.protocol === 'http:' &&
-                ['127.0.0.1', '[::1]', 'localhost'].includes(source.hostname))) ||
-            source.username ||
-            source.password ||
-            source.search ||
-            source.hash)
-            throw new Error();
-        return source;
-    }
-    catch {
-        throw new WorkspaceContextError('workspace_clone_transport_unavailable');
-    }
-}
-async function exists(path) {
-    try {
-        await lstat(path);
-        return true;
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return false;
-        throw error;
-    }
-}
-function samePendingFork(left, right) {
-    const fork = (value) => value.targetKind === 'standalone' ? undefined : value.pendingFork;
-    return JSON.stringify(fork(left) ?? null) === JSON.stringify(fork(right) ?? null);
-}
-async function readReceipt(path, binding) {
-    try {
-        const value = JSON.parse(await readFile(path, 'utf8'));
-        const parsed = workspaceRegistrationSchema.parse(value.binding);
-        if (!sameWorkspaceRegistration(parsed, binding) ||
-            !['cloning', 'ready', 'published'].includes(value.status) ||
-            !new RegExp(`^\\.prepare-${binding.workspaceId}-[0-9a-f-]{36}$`).test(value.stagingName))
-            throw new Error();
-        return { binding: parsed, stagingName: value.stagingName, status: value.status };
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return undefined;
-        throw new WorkspaceContextError('workspace_preparation_receipt_invalid');
-    }
-}
-async function writeReceipt(path, value) {
-    const temp = `${path}.tmp`;
-    await writeFile(temp, `${JSON.stringify(value)}\n`, { mode: 0o600 });
-    await rename(temp, path);
-}
-function runGit(args, env, deadline) {
-    return new Promise((resolve, reject) => {
-        let timedOut = false;
-        const child = spawn('git', [
-            '-c',
-            'core.hooksPath=/dev/null',
-            '-c',
-            'credential.helper=',
-            '-c',
-            'http.followRedirects=false',
-            '-c',
-            'init.templateDir=',
-            ...args,
-        ], {
-            env,
-            detached: process.platform !== 'win32',
-            stdio: 'ignore',
-        });
-        const timer = setTimeout(() => {
-            timedOut = true;
-            try {
-                if (process.platform !== 'win32' && child.pid)
-                    process.kill(-child.pid, 'SIGKILL');
-                else
-                    child.kill('SIGKILL');
-            }
-            catch {
-                /* The process may have already exited. */
-            }
-        }, Math.max(1, deadline - Date.now()));
-        child.once('error', () => {
-            clearTimeout(timer);
-            reject(new WorkspaceContextError('workspace_clone_failed'));
-        });
-        child.once('exit', (code) => {
-            clearTimeout(timer);
-            if (timedOut)
-                reject(new WorkspaceContextError('workspace_clone_timeout'));
-            else if (code === 0)
-                resolve();
-            else
-                reject(new WorkspaceContextError('workspace_clone_failed'));
-        });
-    });
-}

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

@@ -1,251 +0,0 @@
-import { execFile } from 'node:child_process';
-import { lstat, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-import { promisify } from 'node:util';
-import { isLocalWorkspaceGitAuthMode, sameWorkspaceRegistration, workspaceRegistrationSchema, batchSourceSnapshotSchema, } from '@playcraft/common/cloud-workspace/runtime';
-import { prepareWorkspaceCheckout } from './prepare.js';
-import { WorkspaceContextError } from './context-error.js';
-import { scheduleDependencyInstall } from './dependencies.js';
-import { ensureWorkspaceSkills, readWorkspaceSkills } from './skills.js';
-import { loadWorkspaceSkillArtifact, workspacePlatformSkillAccess } from './skill-artifact-loader.js';
-import { writeWorkspaceCliContext } from './cli-context.js';
-import { attachWorkspaceRemote } from './git.js';
-import { ensureWorkspaceArtifactInstructions } from './instructions.js';
-export { WorkspaceContextError } from './context-error.js';
-const exec = promisify(execFile);
-export function revisionScope(state, workspaceId, directoryName = 'basic') {
-    return state.config.workspaceMode === 'multi' ? `${workspaceId}:${directoryName}` : undefined;
-}
-export function workspaceSessions(state, workspaceId, directoryName = 'basic') {
-    return state.journal
-        .listSessions()
-        .filter((item) => state.config.workspaceMode !== 'multi' || (item.workspaceId === workspaceId && (item.directoryName ?? 'basic') === directoryName));
-}
-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');
-    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, directoryName = 'basic') {
-    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 containerStat = await lstat(container).catch(error => { throw new WorkspaceContextError('workspace_not_prepared', { cause: error }); });
-    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(container, await realpath(target)) !== directoryName) {
-            throw new WorkspaceContextError('invalid_workspace_directory');
-        }
-        const stateDir = await realpath(state.config.stateDir);
-        if (stateDir === target || stateDir.startsWith(`${target}/`))
-            throw new WorkspaceContextError('invalid_workspace_directory');
-        return target;
-    }
-    catch (error) {
-        if (error instanceof WorkspaceContextError)
-            throw error;
-        throw new WorkspaceContextError('workspace_not_prepared', { cause: error });
-    }
-}
-/** 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(error => { throw new WorkspaceContextError('workspace_not_prepared', { cause: error }); });
-    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, readOnlyBasic = false, sourceSnapshot) {
-    if (state.config.workspaceMode !== 'multi')
-        throw new WorkspaceContextError('multi_workspace_unavailable');
-    const parsed = workspaceRegistrationSchema.safeParse(input);
-    if (!parsed.success)
-        throw new WorkspaceContextError('invalid_workspace_registration');
-    const binding = parsed.data;
-    return state.journal.exclusive(`workspace:${binding.workspaceId}`, async () => {
-        if (state.journal.destroyed())
-            throw new WorkspaceContextError('runtime_destroyed');
-        if (leaseFence < state.acceptedLeaseFence)
-            throw new WorkspaceContextError('stale_lease');
-        state.acceptedLeaseFence = leaseFence;
-        await state.journal.setAcceptedLeaseFence(leaseFence);
-        const existing = state.journal.getWorkspace(binding.workspaceId);
-        const preservedLocalBasic = binding.targetKind !== 'standalone' && binding.preserveLocalBasic === true;
-        const localUpgrade = preservedLocalBasic && binding.targetKind === 'main' && existing?.targetKind === 'standalone';
-        // A standalone workspace promoted to a project's main keeps its checkout and gains that remote.
-        const remoteUpgrade = !preservedLocalBasic && binding.targetKind === 'main' && existing?.targetKind === 'standalone';
-        if (existing && !sameWorkspaceRegistration(existing, binding) && !localUpgrade && !remoteUpgrade)
-            throw new WorkspaceContextError('workspace_binding_conflict');
-        const attachMarker = join(state.config.stateDir, 'workspace-remote-attach', `${binding.workspaceId}.json`);
-        const existingByDir = new Map((existing?.directories ?? []).map(item => [item.directoryName, item]));
-        const directories = binding.directories
-            ? binding.directories.map(item => {
-                const local = existingByDir.get(item.directoryName);
-                return local && local.remixId === item.remixId && local.status === 'ready' && item.status === 'pending'
-                    ? { ...item, status: 'ready', sourceCommit: item.sourceCommit ?? local.sourceCommit }
-                    : item;
-            })
-            : existing?.directories;
-        if (sourceSnapshot) {
-            const snapshot = batchSourceSnapshotSchema.parse(sourceSnapshot);
-            if (!readOnlyBasic || snapshot.sourceWorkspaceId !== binding.workspaceId)
-                throw new WorkspaceContextError('invalid_workspace_registration');
-            // Production restores its assigned result from durable bytes, without touching basic.
-            const parent = await realpath(state.config.workspaceRoot);
-            await mkdir(join(parent, binding.workspaceId), { 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;
-        }
-        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);
-        }
-        catch (error) {
-            if (existing && error instanceof WorkspaceContextError && error.message === 'workspace_not_prepared')
-                throw new WorkspaceContextError('workspace_recovery_required');
-            if (!preparation || !(error instanceof WorkspaceContextError) || error.message !== 'workspace_not_prepared')
-                throw error;
-            await prepareWorkspaceCheckout(state, binding, preparation, leaseFence);
-            root = await checkedDirectory(state, binding.workspaceId);
-        }
-        const git = async (...args) => (await exec('git', ['-C', root, ...args], {
-            timeout: 5000,
-            maxBuffer: 64 * 1024,
-            env: {
-                PATH: process.env.PATH,
-                HOME: process.env.HOME,
-                GIT_CONFIG_NOSYSTEM: '1',
-                GIT_CONFIG_GLOBAL: '/dev/null',
-            },
-        })).stdout.trim();
-        // Unfinished if it failed part way: the marker outlives the journal entry written below.
-        if (binding.targetKind === 'main' && !preservedLocalBasic && (remoteUpgrade || await lstat(attachMarker).then(() => true, () => false))) {
-            if (preparation?.mode !== 'clone' || !state.gitCredentials)
-                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
-            await mkdir(join(state.config.stateDir, 'workspace-remote-attach'), { recursive: true, mode: 0o700 });
-            await writeFile(attachMarker, JSON.stringify({ repositoryUrl: binding.repositoryUrl, branchName: binding.branchName }), { mode: 0o600 });
-            // The credential helper only serves a workspace the journal knows to be bound.
-            await state.journal.putWorkspace({ ...binding, directories });
-            try {
-                await state.gitCredentials.configure(binding, preparation);
-            }
-            catch {
-                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
-            }
-            try {
-                await attachWorkspaceRemote(root, binding.repositoryUrl, binding.branchName);
-            }
-            catch {
-                throw new WorkspaceContextError('workspace_remote_attach_failed');
-            }
-            await rm(attachMarker, { force: true });
-        }
-        try {
-            let checkoutMatches;
-            if (binding.targetKind === 'standalone' || preservedLocalBasic) {
-                const gitDirectory = await lstat(join(root, '.git'));
-                checkoutMatches = gitDirectory.isDirectory() && !gitDirectory.isSymbolicLink()
-                    && (await git('rev-parse', '--absolute-git-dir')) === join(root, '.git')
-                    && (await git('remote')) === '';
-            }
-            else {
-                checkoutMatches = (await git('config', '--get', 'remote.origin.url')) === binding.repositoryUrl
-                    && (await git('symbolic-ref', '--short', 'HEAD')) === binding.branchName;
-            }
-            if ((await realpath(await git('rev-parse', '--show-toplevel'))) !== root || !checkoutMatches) {
-                throw new WorkspaceContextError('workspace_checkout_mismatch');
-            }
-        }
-        catch (error) {
-            if (error instanceof WorkspaceContextError)
-                throw error;
-            throw new WorkspaceContextError('workspace_not_prepared');
-        }
-        if (state.journal.destroyed())
-            throw new WorkspaceContextError('runtime_destroyed');
-        if (leaseFence < state.acceptedLeaseFence)
-            throw new WorkspaceContextError('stale_lease');
-        if (readOnlyBasic || preservedLocalBasic) {
-            await state.journal.putWorkspace({ ...binding, directories });
-            return binding;
-        }
-        if (preparation?.mode === 'clone' && (preparation.transport?.kind === 'git-gateway-v2' || isLocalWorkspaceGitAuthMode(preparation.authMode))) {
-            if (!state.gitCredentials)
-                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
-            try {
-                await state.gitCredentials.configure(binding, preparation);
-            }
-            catch {
-                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
-            }
-        }
-        try {
-            await ensureWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'), workspacePlatformSkillAccess(state, binding.workspaceId), { optionalPlatformDefaults: true });
-        }
-        catch {
-            throw new WorkspaceContextError('workspace_skills_unavailable');
-        }
-        await writeWorkspaceCliContext(root, binding.workspaceId);
-        await ensureWorkspaceArtifactInstructions(root);
-        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, revisionScope(state, binding.workspaceId), root);
-        return binding;
-    });
-}