@playcraft/cli 0.1.56-beta → 0.1.58-beta

package/dist/workspace-runtime/workspaces/asset-transfer-storage.js

@@ -1,8 +1,9 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
 import { link, lstat, mkdir, open, readdir, realpath, rename, rm, unlink } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, relative } from 'node:path';
 import { ASSET_TRANSFER_BODY_MAX_BYTES, ASSET_TRANSFER_CHUNK_BYTES, ASSET_TRANSFER_FILE_MAX_BYTES, assetBundleReceiptSchema, assetTransferChunkSchema, assetTransferManifestSchema, assetTransferStatusSchema, hashAssetTransferManifest, isAssetBundleReceiptForManifest, } from '@playcraft/common/cloud-workspace/runtime';
+import { ensureSharedDirectory } from './shared-write.js';
 export class AssetTransferError extends Error {
     code;
     status;
@@ -27,9 +28,19 @@ export async function safeAssetTransferDirectory(root, path = '', create = false
         if (part === '.' || part === '..' || /[\\:\x00-\x1f\x7f]/.test(part))
             failPath();
         current = join(current, part);
-        if (create)
+        // The scratch root is shared by both identities; each transaction below it stays private.
+        if (create && relative(root, current) === '.playcraft-temp') {
+            await ensureSharedDirectory(root, current).catch(error => {
+                if (error.message === 'invalid_shared_directory')
+                    failPath();
+                throw error;
+            });
+        }
+        else if (create) {
+            // private
             await mkdir(current, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
                 throw error; });
+        }
         const stat = await lstat(current);
         if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(current) !== current)
             failPath();
@@ -93,6 +104,7 @@ export async function hashAssetTransferFile(path, limit = ASSET_TRANSFER_FILE_MA
 export async function saveAssetTransfer(transfer) {
     await safeAssetTransferDirectory(transfer.directory);
     const temporary = join(transfer.directory, `record-${randomUUID()}.tmp`);
+    // private
     const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
     try {
         await handle.writeFile(JSON.stringify(transfer.record));
@@ -194,6 +206,7 @@ export async function withAssetTransfer(root, scope, id, action) {
 }
 async function saveProgress(transfer, files) {
     const temporary = join(transfer.directory, `progress-${randomUUID()}.tmp`);
+    // private
     const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
     try {
         await handle.writeFile(JSON.stringify(files));
@@ -292,6 +305,7 @@ async function createAssetTransferUnlocked(root, scope, input) {
     const directory = await safeAssetTransferDirectory(rootReal, `.playcraft-temp/asset-transfers/${manifest.transferId}`, true);
     const record = { version: 1, createdAt: Date.now(), scope, manifest, manifestHash: hashAssetTransferManifest(manifest), status: 'uploading' };
     const temporary = join(directory, `create-${randomUUID()}.tmp`);
+    // private
     const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
     try {
         await handle.writeFile(JSON.stringify(record));
@@ -366,6 +380,7 @@ export async function putAssetTransferChunk(root, scope, id, input) {
                 throw error;
         }
         const temporary = join(directory, `chunk-${randomUUID()}.tmp`);
+        // private
         const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
         try {
             await handle.writeFile(bytes);

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

@@ -13,6 +13,7 @@ async function attachmentRoot(root) {
     let directory = root;
     for (const part of WORKSPACE_USER_UPLOADS_DIRECTORY.split('/')) {
         directory = join(directory, part);
+        // shared
         await mkdir(directory, { mode: 0o755 }).catch((error) => {
             if (error.code !== 'EEXIST')
                 throw error;
@@ -62,6 +63,7 @@ export async function uploadWorkspaceAttachment(root, body) {
     const uploads = await attachmentRoot(root);
     const directory = join(uploads, attachment.id);
     const metadataDirectory = join(uploads, '.metadata');
+    // shared
     await mkdir(metadataDirectory, { mode: 0o755 }).catch((error) => {
         if (error.code !== 'EEXIST')
             throw error;
@@ -69,8 +71,11 @@ export async function uploadWorkspaceAttachment(root, body) {
     if (!(await lstat(metadataDirectory)).isDirectory())
         throw new Error('invalid_attachment');
     // Codex can run as a different user from the sandbox control process.
+    // shared
     await mkdir(directory, { mode: 0o755 });
+    // shared
     await writeFile(join(directory, attachment.name), bytes, { flag: 'wx', mode: 0o644 });
+    // shared
     await writeFile(join(metadataDirectory, `${attachment.id}.json`), JSON.stringify(attachment), {
         flag: 'wx',
         mode: 0o644,
@@ -88,11 +93,14 @@ export async function uploadWorkspaceVideoAttachment(root, request, query) {
     await excludeFromGit(root, `/${WORKSPACE_USER_UPLOADS_DIRECTORY}/`);
     const uploads = await attachmentRoot(root);
     const id = randomUUID(), directory = join(uploads, id), metadataDirectory = join(uploads, '.metadata');
+    // shared
     await mkdir(metadataDirectory, { mode: 0o755 }).catch((error) => { if (error.code !== 'EEXIST')
         throw error; });
     if (!(await lstat(metadataDirectory)).isDirectory())
         throw new Error('invalid_attachment');
+    // shared
     await mkdir(directory, { mode: 0o755 });
+    // shared
     const handle = await open(join(directory, name), constants.O_CREAT | constants.O_EXCL | constants.O_RDWR | constants.O_NOFOLLOW, 0o644);
     try {
         let size = 0;
@@ -112,6 +120,7 @@ export async function uploadWorkspaceVideoAttachment(root, request, query) {
         if (contentType !== media.mimeType && !(contentType === 'video/quicktime' && media.mimeType === 'video/mp4'))
             throw new Error('invalid_attachment');
         const attachment = { id, name, size, ...media, sha256: await hashAttachment(handle) };
+        // shared
         await writeFile(join(metadataDirectory, `${id}.json`), JSON.stringify(attachment), { flag: 'wx', mode: 0o644 });
         return attachment;
     }

package/dist/workspace-runtime/workspaces/batch-commit.js

@@ -1,11 +1,12 @@
 import { execFile } from 'node:child_process';
 import { constants } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { lstat, mkdir, open, realpath, rm, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, open, realpath, rm } from 'node:fs/promises';
 import { dirname, isAbsolute, join, relative, sep } from 'node:path';
 import { promisify } from 'node:util';
 import { batchCommitSourceVersion } from '@playcraft/common/cloud-workspace/runtime';
 import { validateProjectSkillsSnapshot } from '@playcraft/common/project-skills';
+import { ensureSharedDirectory, writeSharedFile } from './shared-write.js';
 const execute = promisify(execFile);
 const ID = /^[A-Za-z0-9_-]{1,128}$/;
 const COMMIT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
@@ -131,8 +132,9 @@ export async function checkoutBatchCommit(input) {
             if (await lstat(target).catch(() => undefined))
                 continue;
             const body = await readArtifact(root, path);
-            await mkdir(dirname(target), { recursive: true });
-            await writeFile(target, body, { flag: 'wx', mode: 0o600 });
+            // The checkout is handed to the development identity, so its archives must be group readable.
+            await ensureSharedDirectory(input.destination, dirname(target));
+            await writeSharedFile(input.destination, target, body);
         }
     }
     catch (cause) {

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

@@ -1,12 +1,13 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
-import { link, lstat, mkdir, open, realpath, rename, unlink } from 'node:fs/promises';
+import { link, lstat, open, realpath, rename, unlink } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { fileBinaryWritePayloadSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { artifactPath } from './artifact-files.js';
 import { sampleDiskFile } from './disk-snapshot.js';
 import { InvalidWorkspacePathError } from './files.js';
-import { shareWorkspaceAssetDirectory, shareWorkspaceAssetFile } from './asset-publication-access.js';
+import { shareWorkspaceAssetFile } from './asset-publication-access.js';
+import { ensureSharedDirectory } from './shared-write.js';
 export class BinaryWorkspaceWriteError extends Error {
     code;
     constructor(code) {
@@ -45,14 +46,17 @@ export async function writeWorkspaceBinaryFile(root, input) {
         throw new InvalidWorkspacePathError(payload.path);
     for (const part of parts.slice(0, -1)) {
         parent = join(parent, part);
-        let created = false;
-        await mkdir(parent, { mode: 0o700 }).then(() => { created = true; }).catch(error => { if (error.code !== 'EEXIST')
-            throw error; });
+        const existing = await lstat(parent).catch((error) => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        // Only new parents are shared; an existing directory keeps whatever access its owner chose.
+        if (!existing)
+            await ensureSharedDirectory(rootReal, parent);
         const stat = await lstat(parent);
         if (!stat.isDirectory() || stat.isSymbolicLink())
             throw new InvalidWorkspacePathError(payload.path);
-        if (created)
-            await shareWorkspaceAssetDirectory(rootReal, parent);
     }
     const parentStat = await lstat(parent);
     const target = join(parent, basename(payload.path));
@@ -61,6 +65,7 @@ export async function writeWorkspaceBinaryFile(root, input) {
     let staged = false;
     try {
         await verifyPreconditions(rootReal, payload);
+        // shared
         const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
         staged = true;
         try {

package/dist/workspace-runtime/workspaces/cli-context.js

@@ -5,6 +5,7 @@ import { excludeFromGit } from './dependencies.js';
 /** Non-secret routing hint; the business service still authorizes the selected workspace. */
 export async function writeWorkspaceCliContext(root, workspaceId) {
     const management = join(root, '.playcraft');
+    // shared
     await mkdir(management, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
         throw error; });
     const stat = await lstat(management);
@@ -12,6 +13,7 @@ export async function writeWorkspaceCliContext(root, workspaceId) {
         throw new Error('workspace_skills_invalid');
     const temporary = join(management, `workspace-context.${randomUUID()}.tmp`);
     try {
+        // shared
         await writeFile(temporary, `${JSON.stringify({ schemaVersion: 'playcraft.workspace-context.v1', workspaceId })}\n`, { flag: 'wx', mode: 0o644 });
         await rename(temporary, join(management, 'workspace-context.json'));
         await excludeFromGit(root, '/.playcraft/workspace-context.json');

package/dist/workspace-runtime/workspaces/cli-credentials.js

@@ -76,6 +76,7 @@ async function renew(state, entry) {
         await mkdir(config.workspaceRoot, { recursive: true });
         const temporary = join(config.workspaceRoot, `.playcraft-credential-${randomUUID()}.tmp`);
         try {
+            // private
             await writeFile(temporary, JSON.stringify({
                 apiUrl: credential.apiUrl,
                 token: credential.token,

package/dist/workspace-runtime/workspaces/delivery-build.js

@@ -1,15 +1,17 @@
 import { randomUUID } from 'node:crypto';
 import { constants } from 'node:fs';
-import { copyFile, cp, chmod, lstat, mkdir, mkdtemp, readdir, readlink, rename, rm, stat, symlink } from 'node:fs/promises';
+import { copyFile, cp, lstat, mkdir, mkdtemp, readdir, readlink, rename, rm, stat, symlink } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { basename, dirname, join, relative, sep } from 'node:path';
 import { createPlatformAdapter, getChannelRuleProfile, } from '@playcraft/build';
 import { DELIVERY_QUEUE_LIMIT, isWorkspaceArtifactOutputPath, } from '@playcraft/common/cloud-workspace/runtime';
-import { workspaceRoot } from './registry.js';
+import { revisionScope, workspaceRoot } from './registry.js';
 import { excludeFromGit, ensureWorkspaceDependencies } from './dependencies.js';
 import { listWorkspaceBuildInputs } from './git.js';
 import { runDeveloperCommand } from './developer-command.js';
 import { openScratchToDevelopment } from './directory-access.js';
+import { ensureSharedDirectory } from './shared-write.js';
+import { driftScope, permissionDriftFromOutput, repairWorkspaceShares } from './workspace-shares.js';
 import { DeliveryStore } from './delivery-store.js';
 import { DeliveryValidationError, validateDeliveryArtifact } from './delivery.js';
 export const DELIVERY_BUILD_TIMEOUT_MS = 10 * 60_000;
@@ -196,7 +198,7 @@ async function copyToDist(root, staging, channel, format) {
             throw new DeliveryBuildError('delivery_output_missing');
         const target = join(root, relative);
         const directory = dirname(target);
-        await mkdir(directory, { recursive: true });
+        await ensureSharedDirectory(root, directory);
         const temporary = join(directory, `.${basename(file)}.${randomUUID()}.tmp`);
         try {
             await copyFile(join(staging, file), temporary);
@@ -249,9 +251,8 @@ async function copyInput(root, destination, path) {
  * caches, logs and local outputs stay behind. Without a repository the whole tree is copied.
  */
 export async function isolateWorkspaceForBuild(root, destination) {
-    await mkdir(destination, { recursive: true });
     // The build runs as the development identity and writes its scratch folder inside this copy.
-    await chmod(destination, 0o2770);
+    await ensureSharedDirectory(root, destination);
     const modules = join(root, 'node_modules');
     const modulesEntry = await lstat(modules).catch(() => undefined);
     if (modulesEntry?.isDirectory() || modulesEntry?.isSymbolicLink()) {
@@ -319,11 +320,10 @@ async function executeBuild(state, input, controller) {
         await openScratchToDevelopment(scratch, (await lstat(root)).gid);
         staging = join(scratch, 'output');
         const project = join(scratch, 'project');
-        await mkdir(staging, { recursive: true });
-        await chmod(staging, 0o2770);
+        await ensureSharedDirectory(root, staging);
         await excludeFromGit(root, `/${STAGING_DIRECTORY}/`);
         await excludeFromGit(root, '/dist/');
-        const dependencies = await ensureWorkspaceDependencies(state, input.workspaceId, root);
+        const dependencies = await ensureWorkspaceDependencies(state, revisionScope(state, input.workspaceId, input.directoryName) ?? input.workspaceId, root);
         if (!dependencies.ok) {
             if (dependencies.logTail) {
                 await store.appendLog(input.buildId, `\n${dependencies.logTail}\n`);
@@ -338,7 +338,8 @@ async function executeBuild(state, input, controller) {
         }
         const planned = process.env.PLAYCRAFT_DELIVERY_BUILD_COMMAND || 'playcraft build';
         const command = `umask 002 && NO_COLOR=1 CI=1 ${planned} . --platform ${input.payload.channel} --format ${input.payload.format} --output ${shellQuote(staging)} --mode full`;
-        const outcome = await runDeveloperCommand(state, {
+        let outputTail = '';
+        const runBuild = () => runDeveloperCommand(state, {
             processId: `delivery-${input.buildId}`,
             cwd: project,
             command,
@@ -348,10 +349,28 @@ async function executeBuild(state, input, controller) {
                 const text = String(chunk);
                 if (!text)
                     return;
+                outputTail = (outputTail + text).slice(-64 * 1024);
                 logChain = logChain.then(() => store.appendLog(input.buildId, text)).catch(() => undefined);
             },
         });
-        if (outcome.canceled) {
+        let outcome = await runBuild();
+        let permissionDrift = false;
+        if (outcome.code !== 0 && !outcome.canceled && !outcome.timedOut) {
+            // The build runs as the development identity; an entry only that identity owns repairs its
+            // own shared subtree, then the build is retried exactly once.
+            const drift = permissionDriftFromOutput(outputTail);
+            if (drift) {
+                permissionDrift = true;
+                await repairWorkspaceShares(state, root, await driftScope(root, drift.path)).catch(() => undefined);
+                outcome = await runBuild();
+                permissionDrift = outcome.code !== 0;
+            }
+        }
+        if (outcome.code === undefined) {
+            status = 'failed';
+            error = 'delivery_process_unknown';
+        }
+        else if (outcome.canceled) {
             status = 'canceled';
             error = 'delivery_canceled';
         }
@@ -361,7 +380,7 @@ async function executeBuild(state, input, controller) {
         }
         else if (outcome.code !== 0) {
             status = 'failed';
-            error = 'delivery_build_failed';
+            error = permissionDrift ? 'workspace_permission_drift' : 'delivery_build_failed';
         }
         else {
             const output = await copyToDist(root, staging, input.payload.channel, input.payload.format);

package/dist/workspace-runtime/workspaces/delivery-store.js

@@ -24,6 +24,7 @@ export class DeliveryStore {
         this.directory = workspaceDirectory(stateDir, workspaceId);
     }
     async ready() {
+        // private
         await mkdir(this.directory, { recursive: true, mode: 0o700 });
         return this.directory;
     }
@@ -42,6 +43,7 @@ export class DeliveryStore {
     async writeJson(path, value) {
         const temporary = `${path}.${randomUUID()}.tmp`;
         try {
+            // private
             await writeFile(temporary, JSON.stringify(value), { mode: 0o600 });
             await rename(temporary, path);
         }

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

@@ -4,6 +4,7 @@ import { constants } from 'node:fs';
 import { setTimeout as delay } from 'node:timers/promises';
 import { join } from 'node:path';
 import { launcherSocket, runDeveloperCommand } from './developer-command.js';
+import { adoptDirectoryAccess, holdDirectoryAccess, managedDirectoryScope } from '../server/directory-access.js';
 /** Long enough for a cold store on a game template; a stuck registry must not hold the write lease. */
 const INSTALL_TIMEOUT_MS = 10 * 60_000;
 const LOG_TAIL_LINES = 50;
@@ -15,16 +16,21 @@ const SHARE_WAIT_MS = 60_000;
  * prompts, and writes plain lines to the log. Package scripts run: the workspace is the user's own
  * sandbox and the install runs as the development user.
  */
-const INSTALL_COMMAND = 'pnpm install --no-frozen-lockfile --store-dir /var/cache/playcraft/pnpm-store --reporter=append-only --config.confirm-modules-purge=false';
-/** Installs whenever there is a package.json; the hash says whether a finished install is current. */
+export function dependencyInstallCommand(state, options = {}) {
+    const store = process.env.PLAYCRAFT_PNPM_STORE ?? (process.platform === 'linux' ? '/var/cache/playcraft/pnpm-store' : join(state.config.stateDir, 'pnpm-store'));
+    const quotedStore = `'${store.replaceAll("'", "'\\''")}'`;
+    return `pnpm install --${options.frozenLockfile ? 'frozen' : 'no-frozen'}-lockfile --store-dir ${quotedStore} --reporter=append-only --config.confirm-modules-purge=false`;
+}
+/** pnpm owns installation; other package managers' lockfiles remain untouched. */
 export async function planInstall(root) {
     const manifest = await readOptional(join(root, 'package.json'));
     if (manifest === undefined)
         return { kind: 'skip' };
-    const lock = (await readOptional(join(root, 'pnpm-lock.yaml'))) ?? '';
+    const lock = await readOptional(join(root, 'pnpm-lock.yaml'));
     return {
         kind: 'install',
-        lockHash: createHash('sha256').update(manifest).update('\0').update(lock).digest('hex'),
+        lockHash: createHash('sha256').update(manifest).update('\0').update(lock ?? '').digest('hex'),
+        hasLockfile: lock !== undefined,
     };
 }
 const running = new WeakMap();
@@ -39,17 +45,18 @@ export function scheduleDependencyInstall(state, workspaceId, root, shouldStart)
     running.set(state, inFlight);
     const existing = inFlight.get(workspaceId);
     if (existing?.root === root) {
+        void adoptDirectoryAccess(state, `managed:${existing.writeId}`).catch(() => undefined);
         if (!shouldStart)
             existing.guards = undefined;
         else
             existing.guards?.push(shouldStart);
         return existing.task;
     }
-    const scheduled = { root, task: Promise.resolve(), guards: shouldStart ? [shouldStart] : undefined };
+    const scheduled = { root, writeId: `${WRITE_PREFIX}${workspaceId}-${randomUUID()}`, task: Promise.resolve(), guards: shouldStart ? [shouldStart] : undefined };
     const begin = () => {
         if (state.journal.destroyed() || (scheduled.guards && !scheduled.guards.some((guard) => guard())))
             return;
-        return installOnce(state, workspaceId, root);
+        return installOnce(state, workspaceId, root, scheduled.writeId);
     };
     const task = (existing ? existing.task.then(begin) : begin() ?? Promise.resolve())
         .catch((error) => {
@@ -86,8 +93,8 @@ export async function ensureWorkspaceDependencies(state, workspaceId, root) {
     };
 }
 /**
- * An install cut off by a restart left no process behind (the launcher stops the group when its
- * connection closes), so its status and write lease are closed rather than left in progress.
+ * A lost controller makes the install result unknown. Keep its writer claim until a supervisor
+ * confirms that the process group stopped; a closed connection alone cannot prove that.
  */
 export async function recoverInterruptedInstalls(journal) {
     const now = new Date().toISOString();
@@ -101,72 +108,96 @@ export async function recoverInterruptedInstalls(journal) {
             finishedAt: now,
         });
     }
-    for (const write of journal.listManagedWrites()) {
-        if (write.writeId.startsWith(WRITE_PREFIX) && !write.stoppedAt) {
-            await journal.putManagedWrite({ ...write, stoppedAt: now });
-        }
-    }
 }
-async function installOnce(state, workspaceId, root) {
-    const plan = await planInstall(root);
-    const current = state.journal.getWorkspaceDependencies(workspaceId);
-    if (plan.kind === 'skip') {
-        if (current?.status !== 'none') {
+async function installOnce(state, workspaceId, root, writeId) {
+    const startedAt = new Date().toISOString();
+    const release = await holdDirectoryAccess(state, managedDirectoryScope(state, workspaceId), `managed:${writeId}`, 'shared');
+    let processMayRun = false;
+    let processStopped = false;
+    try {
+        if (state.journal.listManagedWrites().some(writer => writer.workspaceId === workspaceId &&
+            writer.writeId !== writeId && writer.writeId.startsWith(WRITE_PREFIX) && !writer.stoppedAt)) {
             await state.journal.putWorkspaceDependencies({
-                workspaceId,
-                status: 'none',
-                finishedAt: new Date().toISOString(),
+                workspaceId, status: 'failed', error: 'dependency_run_unconfirmed', finishedAt: new Date().toISOString(),
             });
+            return;
         }
-        return;
-    }
-    if (current?.status === 'ready' &&
-        current.lockHash === plan.lockHash &&
-        (await isDirectory(join(root, 'node_modules')))) {
-        return;
-    }
-    await excludeFromGit(root);
-    const startedAt = new Date().toISOString();
-    const writeId = `${WRITE_PREFIX}${workspaceId}-${randomUUID()}`;
-    // A checkpoint waits for this write: node_modules is half written until the install ends.
-    await state.journal.putManagedWrite({ writeId, workspaceId, source: 'background', startedAt });
-    await state.journal.putWorkspaceDependencies({
-        workspaceId,
-        status: 'installing',
-        startedAt,
-    });
-    let outcome;
-    try {
-        // Through the launcher the install runs as the development group, which cannot enter the
-        // checkout until Runtime has opened it; a local install runs as the owner and need not wait.
-        const shared = !launcherSocket(state) || (await waitUntilShared(root));
-        outcome = shared
-            ? await runInstall(state, workspaceId, root)
-            : { code: undefined, timedOut: false, log: '', error: 'workspace_not_shared' };
-    }
-    finally {
-        await state.journal.putManagedWrite({
-            writeId,
+        let plan;
+        try {
+            plan = await planInstall(root);
+        }
+        catch {
+            await state.journal.putWorkspaceDependencies({
+                workspaceId, status: 'failed', error: 'dependency_inputs_unreadable', finishedAt: new Date().toISOString(),
+            });
+            return;
+        }
+        const current = state.journal.getWorkspaceDependencies(workspaceId);
+        if (plan.kind === 'skip') {
+            if (current?.status !== 'none') {
+                await state.journal.putWorkspaceDependencies({
+                    workspaceId,
+                    status: 'none',
+                    finishedAt: new Date().toISOString(),
+                });
+            }
+            return;
+        }
+        if (current?.status === 'ready' &&
+            current.lockHash === plan.lockHash &&
+            (await isDirectory(join(root, 'node_modules')))) {
+            return;
+        }
+        await excludeFromGit(root);
+        // A checkpoint waits for this write: node_modules is half written until the install ends.
+        await state.journal.putManagedWrite({ writeId, workspaceId, source: 'background', startedAt });
+        await state.journal.putWorkspaceDependencies({
             workspaceId,
-            source: 'background',
+            status: 'installing',
             startedAt,
-            stoppedAt: new Date().toISOString(),
+        });
+        let outcome;
+        try {
+            // Through the launcher the install runs as the development group, which cannot enter the
+            // checkout until Runtime has opened it; a local install runs as the owner and need not wait.
+            const shared = !launcherSocket(state) || (await waitUntilShared(root));
+            if (shared) {
+                processMayRun = true;
+                outcome = await runInstall(state, workspaceId, root);
+                processStopped = outcome.code !== undefined;
+            }
+            else
+                outcome = { code: undefined, timedOut: false, log: '', error: 'workspace_not_shared' };
+        }
+        finally {
+            if (!processMayRun || processStopped)
+                await state.journal.putManagedWrite({
+                    writeId,
+                    workspaceId,
+                    source: 'background',
+                    startedAt,
+                    stoppedAt: new Date().toISOString(),
+                });
+        }
+        const ok = outcome.code === 0 && !outcome.timedOut;
+        await state.journal.putWorkspaceDependencies({
+            workspaceId,
+            status: ok ? 'ready' : 'failed',
+            ...(ok
+                ? { lockHash: plan.lockHash }
+                : {
+                    error: outcome.error ??
+                        (outcome.timedOut ? 'install_timeout' : `install_exit_${outcome.code ?? 'lost'}`),
+                }),
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            logTail: tail(outcome.log),
         });
     }
-    const ok = outcome.code === 0 && !outcome.timedOut;
-    await state.journal.putWorkspaceDependencies({
-        workspaceId,
-        status: ok ? 'ready' : 'failed',
-        ...(ok
-            ? { lockHash: plan.lockHash }
-            : {
-                error: outcome.error ??
-                    (outcome.timedOut ? 'install_timeout' : `install_exit_${outcome.code ?? 'lost'}`),
-            }),
-        startedAt,
-        finishedAt: new Date().toISOString(),
-        logTail: tail(outcome.log),
-    });
+    finally {
+        if (!processMayRun || processStopped)
+            release();
+    }
 }
 /**
  * Runs as the development user through the launcher, so the packages belong to the same user as
@@ -174,12 +205,12 @@ async function installOnce(state, workspaceId, root) {
  */
 async function runInstall(state, workspaceId, root) {
     // Tests replace the install; a real registry is never reached from them.
-    const store = process.env.PLAYCRAFT_PNPM_STORE ?? (process.platform === 'linux' ? '/var/cache/playcraft/pnpm-store' : join(state.config.stateDir, 'pnpm-store'));
-    const quotedStore = `'${store.replaceAll("'", "'\\''")}'`;
-    const planned = process.env.PLAYCRAFT_DEPENDENCY_INSTALL_COMMAND || INSTALL_COMMAND.replace('/var/cache/playcraft/pnpm-store', quotedStore);
+    const planned = process.env.PLAYCRAFT_DEPENDENCY_INSTALL_COMMAND || dependencyInstallCommand(state);
     const logDir = join(state.config.stateDir, 'dependency-logs');
+    // private
     await mkdir(logDir, { recursive: true, mode: 0o700 });
     const logPath = join(logDir, `${workspaceId}.log`);
+    // private
     await writeFile(logPath, `$ ${planned}\n`, { mode: 0o600 });
     let log = '';
     let pending = Promise.resolve();
@@ -242,6 +273,7 @@ export async function excludeFromGit(root, entry = '/node_modules/') {
         });
         const info = await open(join(gitPath, 'info'), flags);
         handles.push(info);
+        // shared
         file = await open(join(pinned(info, join(root, '.git/info')), 'exclude'), constants.O_RDWR | constants.O_CREAT | constants.O_APPEND | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o666);
         const metadata = await file.stat();
         if (!metadata.isFile() || metadata.nlink !== 1 || metadata.size > 1024 * 1024) {
@@ -265,8 +297,10 @@ async function readOptional(path) {
     try {
         return await readFile(path, 'utf8');
     }
-    catch {
-        return undefined;
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
     }
 }
 async function isDirectory(path) {

package/dist/workspace-runtime/workspaces/developer-command.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import { startLauncherProcess } from '../codex/launcher-client.js';
+import { stopBackgroundWriter } from '../processes/managed-writes.js';
 export function launcherSocket(state) {
     const socketPath = process.env.PLAYCRAFT_LAUNCHER_SOCKET;
     return socketPath && state.config.workspaceMode === 'multi' ? socketPath : undefined;
@@ -94,5 +95,15 @@ export async function runDeveloperCommand(state, input) {
             local.once('close', (value) => finish(value));
         }
     });
-    return { code, timedOut, ...(canceled ? { canceled: true } : {}) };
+    let stopped = !launched && !local?.pid;
+    try {
+        if (launched) {
+            await launched.stop();
+            stopped = true;
+        }
+        else if (local?.pid)
+            stopped = await stopBackgroundWriter(local.pid);
+    }
+    catch { /* Transport loss cannot prove the process group has stopped. */ }
+    return { code: stopped ? code : undefined, timedOut, ...(canceled ? { canceled: true } : {}) };
 }