@playcraft/cli 0.1.56-beta → 0.1.58-beta

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

@@ -2,9 +2,9 @@ import { readdir, readFile, realpath } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { posix, relative, resolve, sep } from 'node:path';
 import JSON5 from 'json5';
-import { parameterDocumentSchema, parameterPatchPayloadSchema, parameterCatalog, validateParameterChange, workspaceRelativePathSchema, WORKSPACE_FILE_CONTENT_MAX, } from '@playcraft/common/cloud-workspace/runtime';
+import { parameterDocumentSchema, parameterPatchPayloadSchema, parameterCatalog, parameterI18nCatalog, parameterRuntimeTranslations, PARAMETER_RUNTIME_LOCALES, validateParameterChange, validateParameterI18nChange, workspaceRelativePathSchema, WORKSPACE_FILE_CONTENT_MAX, } from '@playcraft/common/cloud-workspace/runtime';
 import { InvalidWorkspacePathError, writeWorkspaceFile } from './files.js';
-import { editJson5Paths, ParameterEditError } from './json5-edit.js';
+import { editJson5Paths, editJson5StringRecords, ParameterEditError } from './json5-edit.js';
 import { prepareParameterAssetRegistration, writeParameterAssetRegistration, } from './parameter-assets.js';
 import { themeAssetIndexFingerprint } from './theme-asset-index.js';
 const MANIFEST_PATH = '.playcraft/workspace.json';
@@ -32,6 +32,7 @@ async function sourceFingerprint(root, located, ownIndexWrite) {
         readOptionalText(root, MANIFEST_PATH),
         readOptionalText(root, THEME_INDEX_PATH),
         selectedIndex ? readOptionalText(root, selectedIndex) : undefined,
+        located.schemaPath ? readOptionalText(root, runtimeI18nGlobalPath(located.schemaPath)) : undefined,
     ]);
     const hashes = sources.map((text) => text === undefined ? null : createHash('sha256').update(text).digest('hex'));
     const rawIndexHash = hashes[4];
@@ -106,6 +107,10 @@ async function readParameterDocuments(root, revisions, located) {
             ? { platformI18n: platformFile.value, platformI18nPath: i18nPath }
             : {}),
     };
+    const runtimeI18n = await readRuntimeI18n(root, revisions, located);
+    if (runtimeI18n.errors.length)
+        return parameterDocumentSchema.parse({ ...schemaDocument, status: 'invalid', errors: runtimeI18n.errors });
+    Object.assign(schemaDocument, runtimeI18n.document ? { runtimeI18n: runtimeI18n.document } : {});
     if (platformFile.status === 'invalid') {
         return parameterDocumentSchema.parse({
             ...schemaDocument,
@@ -148,6 +153,8 @@ async function readParameterDocuments(root, revisions, located) {
 export async function patchWorkspaceParameters(root, revisions, payload, observed, options = {}) {
     const parsed = parameterPatchPayloadSchema.parse(payload);
     const document = await readWorkspaceParameters(root, revisions);
+    if ('documentId' in parsed)
+        return patchWorkspaceParameterI18n(root, document, parsed, observed);
     if (document.status === 'invalid')
         throw new ParameterEditError('parameter_document_invalid');
     if (document.status === 'missing' || document.status === 'schema_only' || !document.dataPath) {
@@ -169,7 +176,7 @@ export async function patchWorkspaceParameters(root, revisions, payload, observe
     if (observed && createHash('sha256').update(source).digest('hex') !== observed.contentHash) {
         throw new ParameterEditError('revision_conflict');
     }
-    const next = editJson5Paths(source, changes);
+    const next = formatParameterData(document.dataPath, source, editJson5Paths(source, changes));
     JSON5.parse(next);
     if (Buffer.byteLength(next, 'utf8') > WORKSPACE_FILE_CONTENT_MAX) {
         throw new ParameterEditError('parameter_document_invalid');
@@ -209,6 +216,91 @@ export async function patchWorkspaceParameters(root, revisions, payload, observe
     const written = await writeWorkspaceFile(root, document.dataPath, next);
     return { ...written, ...(additionalWrites.length ? { additionalWrites } : {}) };
 }
+/** Strict data files must remain consumable by the project's original production importer. */
+function formatParameterData(path, source, edited) {
+    if (!/\.json$/i.test(path))
+        return edited;
+    const indentation = source.match(/^[\t ]+(?=")/m)?.[0] ?? (/[\r\n]/.test(source.trim()) ? '  ' : undefined);
+    const next = JSON.stringify(JSON5.parse(edited), (_key, value) => {
+        // Unknown authored values must not silently change from non-finite numbers into null.
+        if (typeof value === 'number' && !Number.isFinite(value))
+            throw new ParameterEditError('parameter_document_invalid');
+        return value;
+    }, indentation);
+    const eol = source.includes('\r\n') ? '\r\n' : '\n';
+    return next.replaceAll('\n', eol) + (source.endsWith('\n') ? eol : '');
+}
+async function readRuntimeI18n(root, revisions, located) {
+    if (!located.schemaPath || !located.dataPath)
+        return { errors: [] };
+    const globalPath = runtimeI18nGlobalPath(located.schemaPath);
+    const themePath = runtimeI18nThemePath(located.dataPath);
+    const [globalFile, themeFile] = await Promise.all([readOptionalJson5(root, globalPath), readOptionalJson5(root, themePath)]);
+    const errors = [];
+    if (globalFile.status === 'invalid')
+        errors.push({ path: globalPath, reason: globalFile.reason });
+    if (themeFile.status === 'invalid')
+        errors.push({ path: themePath, reason: themeFile.reason });
+    if (errors.length || globalFile.status === 'missing' && themeFile.status === 'missing')
+        return { errors };
+    return { errors, document: {
+            globalPath, themePath,
+            global: globalFile.status === 'ok' ? globalFile.value : {},
+            theme: themeFile.status === 'ok' ? themeFile.value : {},
+            ...(globalFile.status === 'ok' ? { globalHash: globalFile.contentHash } : {}),
+            ...(themeFile.status === 'ok' ? { themeHash: themeFile.contentHash } : {}),
+            globalRevision: revisions[globalPath]?.revision ?? 0,
+            themeRevision: revisions[themePath]?.revision ?? 0,
+            locales: [...PARAMETER_RUNTIME_LOCALES],
+        } };
+}
+async function patchWorkspaceParameterI18n(root, document, payload, observed) {
+    if (document.status !== 'ready' || !document.runtimeI18n)
+        throw new ParameterEditError('parameter_i18n_global_invalid');
+    const runtime = document.runtimeI18n;
+    if (payload.sourceFingerprint !== document.sourceFingerprint || observed && observed.dataPath !== runtime.themePath)
+        throw new ParameterEditError('parameter_source_conflict');
+    for (const change of payload.changes) {
+        const error = validateParameterI18nChange(document, change);
+        if (error)
+            throw new ParameterEditError(error);
+    }
+    const source = await readOptionalText(root, runtime.themePath);
+    if (observed && (source === undefined ? '' : createHash('sha256').update(source).digest('hex')) !== observed.contentHash)
+        throw new ParameterEditError('revision_conflict');
+    const globals = runtime.global;
+    const themes = runtime.theme;
+    const nextEntries = new Map();
+    const changedLocales = new Set();
+    for (const change of payload.changes) {
+        const field = parameterI18nCatalog(document, change.locale).find(entry => entry.key === change.fieldPath.join('.'));
+        const key = field.runtimeI18nKey;
+        const identity = JSON.stringify([key, change.locale]);
+        if (changedLocales.has(identity))
+            throw new ParameterEditError('parameter_changes_overlap');
+        changedLocales.add(identity);
+        const defaults = parameterRuntimeTranslations(globals[key]);
+        const previous = parameterRuntimeTranslations(themes[key]) ?? defaults;
+        const entry = nextEntries.get(key) ?? { ...previous };
+        entry[change.locale] = change.op === 'remove' ? defaults[change.locale] : change.value;
+        nextEntries.set(key, entry);
+    }
+    const edits = [...nextEntries].map(([key, value]) => PARAMETER_RUNTIME_LOCALES.every(locale => value[locale] === globals[key][locale]) ? { key, op: 'remove' } : { key, value });
+    const next = editJson5StringRecords(source ?? '{}\n', edits);
+    if (Buffer.byteLength(next, 'utf8') > WORKSPACE_FILE_CONTENT_MAX)
+        throw new ParameterEditError('parameter_document_invalid');
+    if (await sourceFingerprint(root, await locateParameterFiles(root)) !== document.sourceFingerprint)
+        throw new ParameterEditError('parameter_source_conflict');
+    if (await readOptionalText(root, runtime.themePath) !== source)
+        throw new ParameterEditError('revision_conflict');
+    return writeWorkspaceFile(root, runtime.themePath, next);
+}
+function runtimeI18nGlobalPath(schemaPath) {
+    return posix.join(posix.dirname(schemaPath), 'i18n.runtime.json5');
+}
+function runtimeI18nThemePath(dataPath) {
+    return posix.join(posix.dirname(dataPath), 'theme.i18n.runtime.json5');
+}
 async function locateParameterFiles(root) {
     const manifest = await readOptionalJson5(root, MANIFEST_PATH);
     if (manifest.status === 'invalid') {

package/dist/workspace-runtime/workspaces/platform-export.js

@@ -0,0 +1,190 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { z } from 'zod';
+import { buildStageAt } from '@playcraft/common/build-progress';
+import { PLATFORM_ROUTES, platformEndpoint } from '@playcraft/common/cloud-workspace/runtime';
+import { submitTrustedOperation } from '../server/submit-operation.js';
+import { businessEndpoint } from '../../utils/environment-endpoints.js';
+import { ensureCliCredentials } from './cli-credentials.js';
+import { readWorkspaceGitStatus } from './git.js';
+import { sessionWorkspaceRoot } from './registry.js';
+const run = promisify(execFile);
+const REQUEST_TIMEOUT_MS = 60_000;
+/** Validation findings beyond this are summarized by count; the Agent fixes the first ones first. */
+const MAX_FINDINGS = 30;
+/** A tool error the Agent sees as its reason; `code` is stable, the detail explains it. */
+export class PlatformExportError extends Error {
+    code;
+    constructor(code, detail) {
+        super(detail ? `${code}: ${detail}` : code);
+        this.code = code;
+    }
+}
+/** The project and branch a workspace directory exports, or undefined when it has no project. */
+export async function platformExportTarget(state, scope) {
+    const binding = state.journal.getWorkspace(scope.workspaceId);
+    if (!binding?.projectId)
+        return undefined;
+    const root = await sessionWorkspaceRoot(state, scope.workspaceId, scope.directoryName);
+    return { projectId: binding.projectId, root };
+}
+/**
+ * A standalone workspace has no remote to export from. The platform gives it a project (as its
+ * first save does) and registers it again; the registration reaches this runtime before the reply.
+ */
+async function promoteStandalone(state, scope) {
+    if (state.journal.getWorkspace(scope.workspaceId)?.targetKind !== 'standalone' || scope.directoryName !== 'basic')
+        return;
+    const config = state.config;
+    const response = await fetch(platformEndpoint(config.publicBaseUrl, PLATFORM_ROUTES.workspacePromotions), {
+        method: 'POST',
+        redirect: 'error',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: { authorization: `Bearer ${config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': config.environment },
+        body: JSON.stringify({ runtimeId: config.runtimeId, generation: config.generation, runtimeEpoch: state.runtimeEpoch,
+            workspaceId: scope.workspaceId }),
+    });
+    if (!response.ok) {
+        const body = await response.json().catch(() => undefined);
+        throw new PlatformExportError('workspace_promotion_failed', typeof body?.reason === 'string' ? body.reason : String(response.status));
+    }
+    await response.body?.cancel().catch(() => undefined);
+}
+const credentialSchema = z.object({ apiUrl: z.string().url(), token: z.string().min(1) });
+async function request(state, path, init) {
+    await ensureCliCredentials(state).catch(() => { throw new PlatformExportError('cli_credentials_unavailable'); });
+    const credential = credentialSchema.parse(JSON.parse(await readFile(join(state.config.workspaceRoot, '.playcraft.json'), 'utf8')));
+    const response = await fetch(businessEndpoint(credential.apiUrl, path), {
+        method: init.method,
+        redirect: 'error',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'X-Sandbox-Token': credential.token,
+            'playcraft-env': state.config.environment,
+            ...(init.body !== undefined ? { 'content-type': 'application/json' } : {}),
+        },
+        ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+    });
+    const text = await response.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = undefined;
+    }
+    const error = body && typeof body === 'object' && 'error' in body ? body.error : undefined;
+    if (!response.ok || (typeof error === 'string' && !('id' in body))) {
+        const message = body && typeof body === 'object' && 'message' in body ? body.message : error;
+        throw new PlatformExportError('platform_export_rejected', `${response.status} ${typeof message === 'string' ? message : Array.isArray(message) ? message.join('; ') : text.slice(0, 300)}`);
+    }
+    return body;
+}
+/**
+ * Saves the directory (commit + push), then exports that commit for the channels through the
+ * platform, as the delivery panel's Export does. Each channel repeats its latest export of the
+ * branch, or uses the defaults without one. A standalone workspace first becomes a project.
+ */
+export async function startPlatformExport(state, input) {
+    await promoteStandalone(state, input);
+    const target = await platformExportTarget(state, input);
+    if (!target)
+        throw new PlatformExportError('platform_export_requires_project');
+    const saved = await submitTrustedOperation(state, {
+        kind: 'workspace.save',
+        workspaceId: input.workspaceId,
+        directoryName: input.directoryName,
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        clientRequestId: `${input.clientRequestId.slice(0, 80)}:export-save`,
+        payload: {},
+    });
+    if (['queued', 'dispatched', 'accepted'].includes(saved.status))
+        return {
+            status: 'pending', operationId: saved.operationId, stage: 'workspace.save', builds: [],
+            nextAction: 'Finish the current turn so the queued save can run. Do not poll or wait for it within this turn. In a later turn, call the delivery tool again to continue the export.',
+        };
+    if (saved.status !== 'completed')
+        throw new PlatformExportError('workspace_save_failed', saved.error);
+    const status = await readWorkspaceGitStatus(target.root);
+    // A save skips the push during a merge; with an upstream, `ahead` says the push did not land.
+    if (status.merging || (status.hasUpstream && status.ahead > 0))
+        throw new PlatformExportError('workspace_not_pushed');
+    if (status.branch === 'HEAD')
+        throw new PlatformExportError('workspace_detached_head');
+    const commit = (await run('git', ['-C', target.root, 'rev-parse', 'HEAD'])).stdout.trim();
+    const result = await request(state, '/api/builds/agent-exports', {
+        method: 'POST',
+        body: {
+            projectId: target.projectId,
+            branchName: status.branch,
+            commitHash: commit,
+            platforms: input.channels,
+            ...(input.format ? { format: input.format } : {}),
+            clientRequestId: input.clientRequestId,
+        },
+    });
+    return {
+        commit: commit.slice(0, 7),
+        branch: status.branch,
+        builds: result.builds.map((build) => ({
+            buildId: build.id,
+            channel: build.platform,
+            status: build.status,
+            ...(build.format ? { format: build.format } : {}),
+            ...(build.error ? { error: build.error } : {}),
+            ...(result.options?.[build.platform] ? { options: result.options[build.platform] } : {}),
+        })),
+    };
+}
+/** One platform export as the Agent reads it: status, the recorded failure and the checks. */
+export async function readPlatformExport(state, input) {
+    const target = await platformExportTarget(state, input);
+    if (!target)
+        throw new PlatformExportError('platform_export_requires_project');
+    let buildId = input.buildId;
+    if (!buildId) {
+        const { branch } = await readWorkspaceGitStatus(target.root);
+        const query = new URLSearchParams({ projectId: target.projectId, branchName: branch, limit: '1',
+            ...(input.channel ? { platform: input.channel } : {}) });
+        const list = await request(state, `/api/agent/tools/list-builds?${query}`, { method: 'GET' });
+        buildId = list.items[0]?.id;
+        if (!buildId)
+            throw new PlatformExportError('delivery_build_not_found');
+    }
+    const build = await request(state, `/api/agent/tools/get-build?${new URLSearchParams({ id: buildId })}`, { method: 'GET' });
+    const running = build.status === 'queued' || build.status === 'running';
+    const findings = (build.validationWarnings ?? []).map((warning) => ({
+        code: warning.code,
+        severity: warning.severity,
+        message: warning.message,
+        ...(typeof warning.details?.status === 'string' ? { status: warning.details.status } : {}),
+        ...(typeof warning.details?.recommendation === 'string' ? { recommendation: warning.details.recommendation } : {}),
+        ...(typeof warning.details?.file === 'string' ? { file: warning.details.file } : {}),
+        ...(typeof warning.details?.line === 'number' ? { line: warning.details.line } : {}),
+    }));
+    return {
+        build: {
+            buildId: build.id,
+            channel: build.platform,
+            format: build.format,
+            status: build.status,
+            ...(running ? { stage: buildStageAt(build.progress).stage } : {}),
+            ...(build.commitHash ? { commit: build.commitHash } : {}),
+            ...(build.error ? { error: build.error } : {}),
+            ...(build.previewUrl ? { previewUrl: build.previewUrl } : {}),
+            ...(build.downloadUrl ? { downloadUrl: build.downloadUrl } : {}),
+            ...(typeof build.outputSize === 'number' ? { sizeBytes: build.outputSize } : {}),
+            ...(typeof build.sizeLimit === 'number' ? { sizeLimitBytes: build.sizeLimit } : {}),
+        },
+        ...(build.artifacts?.failure ? { failure: build.artifacts.failure } : {}),
+        ...(!running && build.validationPassed !== null && build.validationPassed !== undefined ? {
+            validation: {
+                passed: build.validationPassed,
+                findings: findings.slice(0, MAX_FINDINGS),
+                ...(findings.length > MAX_FINDINGS ? { omitted: findings.length - MAX_FINDINGS } : {}),
+            },
+        } : {}),
+    };
+}

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

@@ -38,6 +38,7 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
     workspaceDirectoryNameSchema.parse(directoryName);
     const target = join(workspace, directoryName);
     const receiptDir = join(state.config.stateDir, 'workspace-preparations');
+    // private
     await mkdir(receiptDir, { recursive: true, mode: 0o700 });
     const receiptPath = join(receiptDir, `${binding.workspaceId}${directoryName === 'basic' ? '' : `--${directoryName}`}.json`);
     let previous = await readReceipt(receiptPath, binding);
@@ -73,6 +74,7 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
         // 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 });
+        // private
         await mkdir(staging, { mode: 0o700 });
         const access = clone?.gitAccess;
         const credential = clone?.directAccess ?? access;
@@ -163,6 +165,7 @@ export async function prepareWorkspaceCheckout(state, binding, input, leaseFence
         if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(workspace) !== workspace)
             throw new WorkspaceContextError('invalid_workspace_directory');
     }
+    // shared
     await mkdir(workspace, { recursive: true, mode: 0o700 });
     await rename(staging, target);
     // The terminal and Codex run as the development user, so a checkout only the control user can
@@ -234,6 +237,7 @@ async function readReceipt(path, binding) {
 }
 async function writeReceipt(path, value) {
     const temp = `${path}.tmp`;
+    // private
     await writeFile(temp, `${JSON.stringify(value)}\n`, { mode: 0o600 });
     await rename(temp, path);
 }

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

@@ -11,6 +11,7 @@ import { loadWorkspaceSkillArtifact, workspacePlatformSkillAccess } from './skil
 import { writeWorkspaceCliContext } from './cli-context.js';
 import { attachWorkspaceRemote } from './git.js';
 import { ensureWorkspaceArtifactInstructions } from './instructions.js';
+import { repairWorkspaceShares } from './workspace-shares.js';
 export { WorkspaceContextError } from './context-error.js';
 const exec = promisify(execFile);
 export function revisionScope(state, workspaceId, directoryName = 'basic') {
@@ -128,6 +129,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
                 throw new WorkspaceContextError('invalid_workspace_registration');
             // Production restores its assigned result from durable bytes, without touching basic.
             const parent = await realpath(state.config.workspaceRoot);
+            // shared
             await mkdir(join(parent, binding.workspaceId), { mode: 0o2770 }).catch(error => {
                 if (error.code !== 'EEXIST')
                     throw error;
@@ -141,6 +143,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
             // 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);
+            // shared
             await mkdir(container, { mode: 0o2770 }).catch(error => { if (error.code !== 'EEXIST')
                 throw error; });
             const registered = { ...binding, directories };
@@ -174,7 +177,9 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
         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');
+            // private
             await mkdir(join(state.config.stateDir, 'workspace-remote-attach'), { recursive: true, mode: 0o700 });
+            // private
             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 });
@@ -240,6 +245,12 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
         await writeWorkspaceCliContext(root, binding.workspaceId);
         await ensureWorkspaceArtifactInstructions(root);
         await state.journal.putWorkspace({ ...binding, directories });
+        // Registration is the one point every reused container reaches: the root repair is skipped
+        // when the binding did not change, so the shared subtrees repair themselves here (idempotent).
+        // Keep registration latency independent of workspace size; build and scan paths also repair.
+        void repairWorkspaceShares(state, root).catch(error => {
+            console.warn('[workspace-runtime] share repair failed:', error instanceof Error ? error.message : error);
+        });
         try {
             await readWorkspaceSkills(root, join(state.config.stateDir, 'skill-artifacts'), entry => loadWorkspaceSkillArtifact(state, binding.workspaceId, entry));
         }

package/dist/workspace-runtime/workspaces/remix-references.js

@@ -24,6 +24,7 @@ async function safeDirectory(root, relative = '', create = false) {
     let current = root;
     for (const segment of relative.split('/').filter(Boolean)) {
         current = join(current, segment);
+        // shared
         if (create)
             await mkdir(current, { mode: 0o755 }).catch((error) => {
                 if (error.code !== 'EEXIST')
@@ -255,9 +256,12 @@ async function importReference(root, directoryName, input, assertCurrent) {
             for (const file of files) {
                 assertCurrent();
                 await safeDirectory(stage, dirname(file.targetPath) === '.' ? '' : dirname(file.targetPath), true);
+                // shared
                 await writeFile(join(stage, file.targetPath), file.bytes, { flag: 'wx', mode: 0o644 });
             }
+            // shared
             await writeFile(join(stage, RECEIPT), JSON.stringify(record), { flag: 'wx', mode: 0o644 });
+            // shared
             await writeFile(join(stage, ATTRIBUTES), SNAPSHOT_ATTRIBUTES, { flag: 'wx', mode: 0o644 });
             await chmod(stage, 0o755);
             assertCurrent();
@@ -276,6 +280,7 @@ async function importReference(root, directoryName, input, assertCurrent) {
     await safeDirectory(rootReal, '.playcraft', true);
     const temporary = join(rootReal, '.playcraft', `.remix-references-${randomUUID()}.tmp`);
     try {
+        // shared
         await writeFile(temporary, serialized, { flag: 'wx', mode: 0o644 });
         assertCurrent();
         await safeDirectory(rootReal, '.playcraft');

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

@@ -0,0 +1,187 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { chmod, chown, lstat, mkdir, open, rename, rm, } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+/**
+ * Cloud workspaces are shared by two Linux identities: the controller (`playcraft-control`) and the
+ * development user that runs agents and builds (`playcraft-dev`). Every inode either of them must
+ * read or write has to carry the development group plus group read/write (and setgid on
+ * directories, so new entries inherit that group).
+ *
+ * Only the owner of an inode can chmod/chown it, so a call that finds a foreign owner leaves the
+ * entry alone instead of failing the operation; `repairWorkspaceShares` re-runs the same shaping as
+ * the owning identity.
+ */
+export const SHARED_DIRECTORY_MODE = 0o2770;
+export const SHARED_FILE_MODE = 0o660;
+const PERMISSION_BITS = 0o7777;
+const OWNER_ONLY_ERRORS = new Set(['EPERM', 'EACCES']);
+/** The development group, read from the workspace container that owns the tree. */
+export async function workspaceGroup(workspaceRoot) {
+    const stat = await lstat(workspaceRoot);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error('invalid_workspace_directory');
+    }
+    return stat.gid;
+}
+function currentUid() {
+    return typeof process.getuid === 'function' ? process.getuid() : undefined;
+}
+/** Another identity owns this inode; only its owner can re-shape it. */
+function canShape(owner) {
+    const current = currentUid();
+    return current === undefined || current === 0 || owner === current;
+}
+function isOwnerOnly(error) {
+    const code = error?.code;
+    return typeof code === 'string' && OWNER_ONLY_ERRORS.has(code);
+}
+async function shapePath(path, groupId, mode, union = false) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink())
+        throw new Error('invalid_shared_path');
+    const desired = union ? (stat.mode & 0o777) | mode : mode;
+    if (stat.gid === groupId && (stat.mode & PERMISSION_BITS) === desired)
+        return false;
+    if (!canShape(stat.uid))
+        return false;
+    try {
+        if (stat.gid !== groupId)
+            await chown(path, stat.uid, groupId);
+        await chmod(path, desired);
+        return true;
+    }
+    catch (error) {
+        if (isOwnerOnly(error))
+            return false;
+        throw error;
+    }
+}
+async function shapeHandle(handle, groupId, mode) {
+    const stat = await handle.stat();
+    if (stat.gid === groupId && (stat.mode & PERMISSION_BITS) === mode)
+        return false;
+    if (!canShape(stat.uid))
+        return false;
+    try {
+        if (stat.gid !== groupId)
+            await handle.chown(stat.uid, groupId);
+        await handle.chmod(mode);
+        return true;
+    }
+    catch (error) {
+        if (isOwnerOnly(error))
+            return false;
+        throw error;
+    }
+}
+/** True when `target` is the root itself or lives below it. */
+export function isInsideRoot(root, target) {
+    const base = resolve(root), path = resolve(target);
+    return path === base || path.startsWith(`${base}${sep}`);
+}
+/**
+ * Chain of directories below `root` down to `target`; empty when `target` is the root itself or
+ * outside it. The root is shared by checkout preparation, never as a side effect of a write.
+ */
+function directoryChain(root, target) {
+    if (!isInsideRoot(root, target))
+        return [];
+    const parts = relative(resolve(root), resolve(target)).split(sep).filter(Boolean);
+    return parts.map((_, index) => resolve(root, ...parts.slice(0, index + 1)));
+}
+/**
+ * Shares one existing path with the development group. Returns whether the mode changed; an entry
+ * owned by the other identity is reported as unchanged because this process cannot re-shape it.
+ */
+export async function shareIfNeeded(workspaceRoot, path) {
+    const groupId = await workspaceGroup(workspaceRoot);
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink())
+        throw new Error('invalid_shared_path');
+    return shapePath(path, groupId, stat.isDirectory() ? SHARED_DIRECTORY_MODE : SHARED_FILE_MODE);
+}
+/**
+ * Shapes an existing path with an explicit group and mode. Used by the legacy helpers that receive
+ * the group from their caller (scratch trees and checkout preparation) so there is one implementation.
+ */
+export async function sharePathWithGroup(path, groupId, mode, union = false) {
+    return shapePath(path, groupId, mode, union);
+}
+/** Shapes an already open file. Cross-owner failures are tolerated like `shareIfNeeded`. */
+export async function shareHandleWithGroup(handle, groupId, mode) {
+    return shapeHandle(handle, groupId, mode);
+}
+/**
+ * Creates a directory tree both identities can use. Missing ancestors are created with the shared
+ * mode and every segment below `workspaceRoot` is re-checked, so a pre-existing private parent is
+ * repaired when this process owns it.
+ */
+export async function ensureSharedDirectory(workspaceRoot, path) {
+    const root = resolve(workspaceRoot), target = resolve(path);
+    const groupId = await workspaceGroup(root);
+    const chain = directoryChain(root, target);
+    const shapes = isInsideRoot(root, target) ? chain : [target];
+    // Reject redirected ancestors before mkdir follows them.
+    for (const directory of chain) {
+        const stat = await lstat(directory).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink())) {
+            throw new Error('invalid_shared_directory');
+        }
+    }
+    await mkdir(target, { recursive: true, mode: SHARED_DIRECTORY_MODE });
+    for (const directory of shapes) {
+        const stat = await lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error('invalid_shared_directory');
+        }
+        await shapePath(directory, groupId, SHARED_DIRECTORY_MODE);
+    }
+    return target;
+}
+/**
+ * Opens (optionally creating) a file the development group can read and write. The handle keeps
+ * the descriptor, so a concurrent `chmod` cannot redirect what is written.
+ */
+export async function openSharedFile(workspaceRoot, path, flags) {
+    const groupId = await workspaceGroup(workspaceRoot);
+    const handle = await open(path, flags, SHARED_FILE_MODE);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error('invalid_shared_file');
+        await shapeHandle(handle, groupId, SHARED_FILE_MODE);
+        return handle;
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        throw error;
+    }
+}
+/** Writes through a temporary file in the same directory, then renames, so readers never see a partial file. */
+export async function writeSharedFile(workspaceRoot, path, data) {
+    const root = resolve(workspaceRoot), target = resolve(path);
+    if (isInsideRoot(root, target))
+        await ensureSharedDirectory(root, dirname(target));
+    const groupId = await workspaceGroup(root);
+    const temporary = join(dirname(target), `.${basename(target)}.${randomUUID()}.tmp`);
+    try {
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, SHARED_FILE_MODE);
+        try {
+            await shapeHandle(handle, groupId, SHARED_FILE_MODE);
+            await handle.writeFile(data);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, target);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}