@playcraft/cli 0.1.57-beta → 0.1.59-beta

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

@@ -100,6 +100,11 @@ export async function startPlatformExport(state, input) {
         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);

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

@@ -1,6 +1,6 @@
 import { execFile } from 'node:child_process';
 import { lstat, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
-import { join, relative } from 'node:path';
+import { dirname, 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';
@@ -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 };
@@ -160,7 +163,7 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
             await prepareWorkspaceCheckout(state, binding, preparation, leaseFence);
             root = await checkedDirectory(state, binding.workspaceId);
         }
-        const git = async (...args) => (await exec('git', ['-C', root, ...args], {
+        const gitIn = (cwd) => async (...args) => (await exec('git', ['-C', cwd, ...args], {
             timeout: 5000,
             maxBuffer: 64 * 1024,
             env: {
@@ -170,11 +173,19 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
                 GIT_CONFIG_GLOBAL: '/dev/null',
             },
         })).stdout.trim();
+        const git = gitIn(root);
+        // The checkout, not the journal, decides whether the remote is still missing: the state volume is
+        // per generation and forgets a standalone→main promotion, while the checkout outlives it.
+        const needsRemote = binding.targetKind === 'main' && !preservedLocalBasic
+            && (await git('remote').catch(() => undefined)) === '';
         // 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 (binding.targetKind === 'main' && !preservedLocalBasic
+            && (needsRemote || 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 });
@@ -213,6 +224,10 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
                 throw error;
             throw new WorkspaceContextError('workspace_not_prepared');
         }
+        // Variants share basic's volume but have no registration step of their own, so a swap can leave
+        // them checked out, on the right branch, and without the remote their saves need.
+        if (!readOnlyBasic && !preservedLocalBasic)
+            await restoreDirectoryRemotes(binding, root, gitIn);
         if (state.journal.destroyed())
             throw new WorkspaceContextError('runtime_destroyed');
         if (leaseFence < state.acceptedLeaseFence)
@@ -240,6 +255,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));
         }
@@ -249,3 +270,34 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
         return binding;
     });
 }
+/**
+ * Variant checkouts outlive the journal that registered them: a sandbox swap keeps the files and the
+ * branch but drops the remote. Only an already-correct branch is repaired; rebuilding another one
+ * would discard the variant's own commits, so that case stays a checkout mismatch.
+ */
+async function restoreDirectoryRemotes(binding, root, gitIn) {
+    const repositoryUrl = binding.repositoryUrl;
+    if (!repositoryUrl)
+        return;
+    for (const directory of binding.directories ?? []) {
+        if (directory.directoryName === 'basic')
+            continue;
+        const checkout = join(dirname(root), directory.directoryName);
+        const stat = await lstat(checkout).catch(() => undefined);
+        if (!stat?.isDirectory() || stat.isSymbolicLink())
+            continue;
+        const git = gitIn(checkout);
+        if ((await git('symbolic-ref', '--short', 'HEAD').catch(() => undefined)) !== directory.branchName)
+            continue;
+        const origin = await git('config', '--get', 'remote.origin.url').catch(() => undefined);
+        if (origin === repositoryUrl)
+            continue;
+        try {
+            if (origin === undefined)
+                await git('remote', 'add', 'origin', repositoryUrl);
+            else
+                await git('remote', 'set-url', 'origin', repositoryUrl);
+        }
+        catch { /* The variant still opens; its next save reports the missing remote. */ }
+    }
+}

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 });
+    }
+}

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

@@ -1,5 +1,5 @@
-import { createHash, randomUUID } from 'node:crypto';
-import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { cp, lstat, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
 import { load } from 'js-yaml';
 import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
@@ -9,6 +9,7 @@ import { selectPlatformSkillSnapshot } from '../../project-skills/builtin-import
 import { EMPTY_WORKSPACE_REPOSITORY_SKILLS, EMPTY_WORKSPACE_PLATFORM_SKILLS } from './empty-template.js';
 import { excludeFromGit } from './dependencies.js';
 import { selectOptionalPlatformSkills } from './optional-platform-skills.js';
+import { ensureSharedDirectory, writeSharedFile } from './shared-write.js';
 /** Runtime availability is determined by the locked metadata, independent of unsynced source edits. */
 export async function readWorkspaceSkillSnapshot(root) {
     const management = await lstat(join(root, '.playcraft'));
@@ -42,7 +43,7 @@ export async function ensureWorkspaceSkills(root, cache, access, options = {}) {
                     continue;
                 await safeDirectory(root, '.agents/skills');
                 const source = `.agents/skills/${name}`;
-                await mkdir(join(root, source), { mode: 0o755 });
+                await ensureSharedDirectory(root, join(root, source));
                 added.add(source);
                 const template = join(resolveCliPackageRoot(), 'project-template/.claude/skills', name);
                 for (const child of await readdir(template))
@@ -61,12 +62,16 @@ async function safeDirectory(root, path) {
     let current = root;
     for (const segment of path.split('/')) {
         current = join(current, segment);
-        await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
-            throw error; });
-        const stat = await lstat(current);
-        if (!stat.isDirectory() || stat.isSymbolicLink())
+        // Validate every existing segment before creating anything, so a link never redirects the tree.
+        const stat = await lstat(current).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
             throw new Error('workspace_skills_invalid');
     }
+    await ensureSharedDirectory(root, current);
     return current;
 }
 /** Cache misses may reconstruct only the exact locked repository bytes, never a newer source. */
@@ -111,14 +116,7 @@ async function lockedFiles(root, cache, entry, view, loadArtifact) {
         throw new Error('workspace_skills_invalid_bundle');
     if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
         throw new Error('workspace_skills_digest_mismatch');
-    const temporary = `${saved}.${randomUUID()}.tmp`;
-    try {
-        await writeFile(temporary, archive, { flag: 'wx', mode: 0o644 });
-        await rename(temporary, saved);
-    }
-    finally {
-        await rm(temporary, { force: true });
-    }
+    await writeSharedFile(root, saved, archive);
     return extracted.files;
 }
 function metadata(entryKey, content) {
@@ -155,6 +153,7 @@ export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
             const relative = join(entry.entryKey, file.path);
             expectedFiles.add(relative);
             await safeDirectory(generation, dirname(relative));
+            // shared
             await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(async (error) => {
                 if (error.code !== 'EEXIST')
                     throw error;