@playcraft/cli 0.1.58-beta → 0.1.60-beta

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

@@ -41,6 +41,7 @@ import { workspaceArtifactContentQuerySchema } from '@playcraft/common/cloud-wor
 import { searchWorkspaceFiles } from '../workspaces/files-search.js';
 import { serveWorkspaceArchive } from '../workspaces/archive.js';
 import { handleWorkspaceTransfer } from './workspace-transfer.js';
+import { handleWorkspaceStorage } from './workspace-storage.js';
 import { serveSessionImage } from '../workspaces/session-image.js';
 import { restoreNativeSession, SessionRestoreError } from './session-restore.js';
 import { handleAssetTransferRequest } from './asset-transfers.js';
@@ -51,7 +52,8 @@ export async function handleRuntimeRequest(state, request, response) {
     const workspaceId = url.searchParams.get('workspaceId');
     // Body-scoped operations, members and terminal control take their own lifetime-aware leases.
     const ownLease = url.pathname.startsWith('/runtime/operations') || url.pathname.startsWith('/runtime/terminals/') ||
-        url.pathname.startsWith('/runtime/batch-') || /^\/runtime\/sessions\/[^/]+\/ui-results$/.test(url.pathname);
+        url.pathname.startsWith('/runtime/batch-') || /^\/runtime\/sessions\/[^/]+\/ui-results$/.test(url.pathname) ||
+        /^\/runtime\/sessions\/[^/]+\/prediction$/.test(url.pathname);
     if (authorizeRuntime(state, request) === 'control' && workspaceId &&
         (!['GET', 'HEAD', 'OPTIONS'].includes(request.method ?? 'GET') || url.pathname === '/runtime/git-bundle') && !ownLease) {
         try {
@@ -82,6 +84,8 @@ async function dispatchRuntimeRequest(state, request, response) {
         return;
     }
     try {
+        if (await handleWorkspaceStorage(state, request, response, url))
+            return;
         const transfer = await handleAssetTransferRequest(state, request, url);
         if (transfer) {
             writeJson(response, transfer.status, transfer.body);
@@ -128,6 +132,9 @@ async function dispatchRuntimeRequest(state, request, response) {
                 instanceToken: state.instanceToken,
                 permissionsVersion: 1,
                 composerContextVersion: 1,
+                scheduledTaskIdentityVersion: 1,
+                scheduledTaskCancellationVersion: 1,
+                ...(state.native?.scheduledTaskProposalSource ? { scheduledTaskProposalVersion: 1 } : {}),
                 parameterAgentVersion: 1,
                 directoryConcurrencyVersion: 1,
                 parameterInitializationVersion: 1,
@@ -136,6 +143,7 @@ async function dispatchRuntimeRequest(state, request, response) {
                 ...(state.native?.workspaceUi ? { workspaceUiVersion: 1 } : {}),
                 ...(state.native?.startReview && state.native?.steer ? { turnControlVersion: 1 } : {}),
                 ...(state.native?.startCompact ? { compactionVersion: 1 } : {}),
+                ...(state.native?.startPrediction ? { predictionVersion: 1 } : {}),
                 sourceReadToken: state.journal.sourceReadToken(),
                 workspaceMode: state.config.workspaceMode,
                 executionGroup: {
@@ -208,6 +216,27 @@ async function dispatchRuntimeRequest(state, request, response) {
             writeJson(response, result.outcome === 'accepted' ? 200 : 409, result);
             return;
         }
+        const predictionRoute = /^\/runtime\/sessions\/([^/]+)\/prediction$/.exec(url.pathname);
+        if (request.method === 'POST' && predictionRoute) {
+            if (writeDestroyed(state, response))
+                return;
+            const sessionId = decodeURIComponent(predictionRoute[1]);
+            const session = state.journal.getSession(sessionId);
+            if (!session || productionSessionAttemptId(sessionId) || session.workspaceId !== url.searchParams.get('workspaceId')
+                || (session.directoryName ?? 'basic') !== directoryName) {
+                writeJson(response, 404, { error: 'session_not_found' });
+                return;
+            }
+            if (!state.native?.startPrediction) {
+                writeJson(response, 409, { error: 'prediction_unavailable' });
+                return;
+            }
+            // Best-effort and read-only: no instruction/journal reservation, and the ephemeral
+            // fork never becomes a user-visible thread.
+            const result = await state.native.startPrediction({ sessionId, threadId: session.threadId });
+            writeJson(response, result.outcome === 'ok' ? 200 : 409, result);
+            return;
+        }
         if (request.method === 'POST' && url.pathname === '/runtime/workspaces/register') {
             if (writeDestroyed(state, response))
                 return;
@@ -784,6 +813,16 @@ async function dispatchRuntimeRequest(state, request, response) {
             writeJson(response, 200, operation);
             return;
         }
+        if (request.method === 'POST' && url.pathname === '/runtime/scheduled-task-proposals/source') {
+            const body = await readJson(request);
+            if (!body || Object.keys(body).some(key => !['bridge', 'threadId', 'turnId', 'toolCallId'].includes(key))
+                || !['bridge', 'threadId', 'turnId', 'toolCallId'].every(key => typeof body[key] === 'string' && Boolean(body[key]))) {
+                writeJson(response, 400, { valid: false });
+                return;
+            }
+            writeJson(response, 200, { valid: state.native?.scheduledTaskProposalSource?.(body) === true });
+            return;
+        }
         if (request.method === 'POST' && url.pathname === '/runtime/operations') {
             // Track creation before accepting it, so a new unconnected terminal is known not to have spawned.
             terminalHost(state);
@@ -949,7 +988,9 @@ async function acceptOperation(state, request, response) {
         ? { snapshot: parsed.data.remixReferenceSnapshot }
         : parsed.data.kind === 'asset.library.import'
             ? { selection: parsed.data.payload, snapshot: parsed.data.libraryAssetImports }
-            : parsed.data.payload;
+            : parsed.data.kind === 'session.turn' && parsed.data.scheduledTaskProposalBridge
+                ? { ...asRecord(parsed.data.payload), scheduledTaskProposalBridge: parsed.data.scheduledTaskProposalBridge }
+                : parsed.data.payload;
     const accept = async () => {
         const result = await acceptOperationCore(state, parsed.data, {
             leaseFence: incomingFence,

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

@@ -1,6 +1,7 @@
 import { batchDirectoryHeld } from '../batch/occupancy.js';
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
+import { readdirSync, readFileSync } from 'node:fs';
 import { lstat } from 'node:fs/promises';
 import { StringDecoder } from 'node:string_decoder';
 import { WebSocketServer } from 'ws';
@@ -12,11 +13,19 @@ import { stopBackgroundWriter } from '../processes/managed-writes.js';
 import { controlTokenMatches, extractControlToken } from './auth.js';
 import { cancelPendingDirectoryAccess, holdDirectoryAccess } from './directory-access.js';
 const require = createRequire(import.meta.url);
+/** A shell nobody views, silent this long and running nothing besides itself, is closed. */
+const IDLE_RECLAIM_MS = 30 * 60_000;
+const IDLE_SWEEP_MS = 120_000;
 const commands = new WeakMap();
+const sessionProbes = new WeakMap();
 const hosts = new WeakMap();
 export function setTerminalCommand(state, command) {
     commands.set(state, command);
 }
+/** Replaces the /proc session scan, for platforms without /proc. */
+export function setTerminalSessionProbe(state, probe) {
+    sessionProbes.set(state, probe);
+}
 export function terminalHost(state) {
     let host = hosts.get(state);
     if (!host) {
@@ -25,6 +34,20 @@ export function terminalHost(state) {
     }
     return host;
 }
+/**
+ * The supervisor advances the runtime epoch only after the launcher confirms that every process it
+ * started, terminals included, has exited. A terminal from an earlier epoch is gone whatever its record says.
+ */
+export async function retireStoppedTerminals(journal, runtimeEpoch, previousEpoch) {
+    if (previousEpoch === undefined || runtimeEpoch <= previousEpoch)
+        return;
+    const destroyedAt = new Date().toISOString();
+    for (const terminal of journal.listTerminals()) {
+        if (terminal.status === 'destroyed' || (terminal.runtimeEpoch ?? 0) >= runtimeEpoch)
+            continue;
+        await journal.putTerminal({ ...terminal, status: 'destroyed', destroyedAt });
+    }
+}
 export function disposeTerminalHost(state) {
     hosts.get(state)?.dispose();
     hosts.delete(state);
@@ -41,10 +64,14 @@ export class TerminalHost {
     confirmed = new Set();
     directoryReleases = new Map();
     sockets = new WebSocketServer({ noServer: true });
+    idleSweep;
     constructor(state) {
         this.state = state;
+        this.idleSweep = setInterval(() => void this.reclaimIdle(), IDLE_SWEEP_MS);
+        this.idleSweep.unref?.();
         // An absent in-memory session cannot prove a restored terminal's old process group stopped.
-        this.restored = new Set((state.journal?.listTerminals?.() ?? []).map(terminal => terminal.terminalId));
+        this.restored = new Set((state.journal?.listTerminals?.() ?? [])
+            .filter(terminal => terminal.status !== 'destroyed').map(terminal => terminal.terminalId));
     }
     async handleUpgrade(request, socket, head) {
         const url = new URL(request.url ?? '/', 'http://127.0.0.1');
@@ -152,7 +179,28 @@ export class TerminalHost {
         session.listeners.clear();
         void session.stop().then(() => this.exited(terminalId, session, null)).catch(() => undefined);
     }
+    /** Closes shells with no browser, no input or output for the idle window, and nothing else running. */
+    async reclaimIdle(now = Date.now()) {
+        const reclaimed = [];
+        for (const [terminalId, session] of [...this.sessions]) {
+            if (session.exited || session.listeners.size > 0 || this.closing.has(terminalId)
+                || now - session.lastActivity < IDLE_RECLAIM_MS)
+                continue;
+            // A background job keeps the shell; a session that cannot be inspected is kept too.
+            if (!session.pid || (sessionProbes.get(this.state) ?? runsOtherProcesses)(session.pid) !== false)
+                continue;
+            try {
+                await this.destroy(terminalId);
+                reclaimed.push(terminalId);
+            }
+            catch {
+                // The next sweep tries again.
+            }
+        }
+        return reclaimed;
+    }
     dispose() {
+        clearInterval(this.idleSweep);
         this.disposed = true;
         for (const terminalId of [...this.sessions.keys()])
             this.revoke(terminalId, 'runtime_destroyed');
@@ -199,6 +247,7 @@ export class TerminalHost {
                 throw new Error('pty_unavailable');
             }
             const session = { terminalId: terminal.terminalId, streamId: randomUUID(), log: createTerminalOutputLog(), listeners: new Set(),
+                pid: child.pid ?? 0, lastActivity: Date.now(),
                 stop: () => child.stop(),
                 pty: { write: (data) => { child.stdin?.write(data); }, resize: child.resize,
                     kill: () => { void child.stop().catch(() => undefined); } } };
@@ -233,6 +282,8 @@ export class TerminalHost {
                 cwd,
                 env: shellEnv(command.file, cwd),
             }),
+            pid: 0,
+            lastActivity: Date.now(),
             stop: async () => {
                 if (!didExit)
                     session.pty.kill();
@@ -250,6 +301,7 @@ export class TerminalHost {
             },
         };
         const local = session.pty;
+        session.pid = local.pid;
         local.onData((data) => publish(session, data));
         local.onExit(({ exitCode, signal }) => {
             finishExit();
@@ -297,6 +349,7 @@ export class TerminalHost {
             send(frame);
         };
         session.listeners.add(listener);
+        session.lastActivity = Date.now();
         ws.on('message', (raw) => {
             let body;
             try {
@@ -332,6 +385,7 @@ export class TerminalHost {
             }
             if (!resumed)
                 return;
+            session.lastActivity = Date.now();
             if (frame.type === 'resize') {
                 session.pty.resize(frame.cols, frame.rows);
                 return;
@@ -341,12 +395,14 @@ export class TerminalHost {
         const detach = () => {
             open = false;
             session.listeners.delete(listener);
+            session.lastActivity = Date.now();
         };
         ws.on('close', detach);
         ws.on('error', detach);
     }
 }
 function publish(session, text) {
+    session.lastActivity = Date.now();
     const before = session.log.end;
     session.log = appendTerminalOutput(session.log, text);
     const since = terminalOutputSince(session.log, before);
@@ -361,6 +417,31 @@ function publish(session, text) {
             listener(frame);
     }
 }
+/** `true` while a process other than the shell runs in its session; `undefined` when /proc cannot tell. */
+function runsOtherProcesses(shellPid) {
+    let names;
+    try {
+        names = readdirSync('/proc');
+    }
+    catch {
+        return undefined;
+    }
+    for (const name of names) {
+        if (!/^\d+$/.test(name) || Number(name) === shellPid)
+            continue;
+        try {
+            const stat = readFileSync(`/proc/${name}/stat`, 'utf8');
+            const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+            if (Number(fields[3]) === shellPid && !['Z', 'X'].includes(fields[0] ?? ''))
+                return true;
+        }
+        catch (error) {
+            if (!['ENOENT', 'ESRCH'].includes(error.code ?? ''))
+                return undefined;
+        }
+    }
+    return false;
+}
 function exitFrame(session) {
     return {
         type: 'exit',

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

@@ -0,0 +1,193 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { workspaceDirectoryOccupied } from '../workspaces/directory-maintenance.js';
+import { openDirectoryToDevelopment } from '../workspaces/directory-access.js';
+import { createStorageSnapshot, extractStorageSnapshot, STORAGE_SNAPSHOT_MAX_BYTES } from '../workspaces/storage-snapshot.js';
+import { withDirectoryWrite } from './directory-access.js';
+const SHA256 = /^[a-f0-9]{64}$/;
+/** Private control routes. Workspace identity survives disk eviction in the runtime journal. */
+export async function handleWorkspaceStorage(state, request, response, url) {
+    const route = /^\/runtime\/workspaces\/([^/]+)\/storage-(status|snapshot|evict|restore)$/.exec(url.pathname);
+    if (!route)
+        return false;
+    const [, workspaceId, action] = route;
+    const json = (status, body) => { response.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'private, no-store' }); response.end(JSON.stringify(body)); };
+    const controller = new AbortController(), abort = () => controller.abort();
+    let download;
+    let result;
+    const closed = () => { if (!response.writableEnded)
+        abort(); };
+    request.once('aborted', abort);
+    response.once('close', closed);
+    try {
+        if (state.config.workspaceMode !== 'multi' || !/^[0-9a-f-]{36}$/i.test(workspaceId))
+            throw new Error('storage_snapshot_invalid');
+        if (state.journal.destroyed())
+            throw new Error('runtime_destroyed');
+        if ((action === 'status' || action === 'snapshot') ? request.method !== 'GET' : request.method !== 'POST') {
+            json(405, { error: 'method_not_allowed' });
+            return true;
+        }
+        for (const [name, expected] of [['x-playcraft-generation', state.config.generation], ['x-playcraft-runtime-epoch', state.runtimeEpoch]]) {
+            const value = request.headers[name];
+            if (value !== undefined && value !== String(expected))
+                throw new Error('generation_mismatch');
+        }
+        const parent = await realpath(state.config.workspaceRoot), root = join(parent, workspaceId);
+        const stateRoot = await realpath(state.config.stateDir);
+        if (stateRoot === root || stateRoot.startsWith(`${root}${sep}`))
+            throw new Error('storage_snapshot_invalid');
+        const present = async () => {
+            const info = await lstat(root).catch(error => { if (error.code === 'ENOENT')
+                return undefined; throw error; });
+            if (!info)
+                return false;
+            if (!info.isDirectory() || info.isSymbolicLink() || relative(parent, await realpath(root)) !== workspaceId)
+                throw new Error('storage_snapshot_invalid');
+            return (await readdir(root)).length > 0;
+        };
+        if (action === 'status') {
+            json(200, { present: await present() });
+            return true;
+        }
+        if ((action === 'snapshot' || action === 'evict') && !state.journal.getWorkspace(workspaceId))
+            throw new Error('workspace_not_registered');
+        const directories = [...new Set(['root', 'basic', ...(state.journal.getWorkspace(workspaceId)?.directories ?? []).map(item => item.directoryName)])];
+        const assertIdle = async () => {
+            controller.signal.throwIfAborted();
+            if (state.journal.destroyed())
+                throw new Error('runtime_destroyed');
+            for (const directory of directories)
+                if (await workspaceDirectoryOccupied(state, workspaceId, directory))
+                    throw new Error('workspace_directory_occupied');
+        };
+        await withDirectoryWrite(state, { workspaceId, directoryName: 'root', mode: 'exclusive', wait: false }, async () => {
+            await assertIdle();
+            const markerDir = join(state.config.stateDir, 'workspace-storage'), marker = join(markerDir, `${workspaceId}.json`);
+            if (action === 'snapshot') {
+                if (!(await present()))
+                    throw new Error('workspace_not_prepared');
+                const snapshot = await createStorageSnapshot(root, { signal: controller.signal, excludedRoots: [state.config.stateDir] });
+                try {
+                    await assertIdle();
+                    download = snapshot;
+                }
+                catch (error) {
+                    await snapshot.cleanup();
+                    throw error;
+                }
+                return;
+            }
+            if (action === 'evict') {
+                let body = '';
+                for await (const part of request) {
+                    body += part.toString();
+                    if (body.length > 1024)
+                        throw new Error('storage_snapshot_invalid');
+                }
+                const sha256 = JSON.parse(body).sha256;
+                if (typeof sha256 !== 'string' || !SHA256.test(sha256))
+                    throw new Error('storage_snapshot_invalid');
+                const removed = join(parent, `.storage-evicted-${workspaceId}-${sha256}`);
+                if (!(await present())) {
+                    const saved = await readFile(marker, 'utf8').then(value => JSON.parse(value), () => undefined);
+                    if (saved?.sha256 !== sha256)
+                        throw new Error('storage_snapshot_conflict');
+                    await rm(removed, { recursive: true, force: true });
+                    result = { evicted: true };
+                    return;
+                }
+                const snapshot = await createStorageSnapshot(root, { signal: controller.signal, excludedRoots: [state.config.stateDir] });
+                try {
+                    if (snapshot.sha256 !== sha256)
+                        throw new Error('storage_snapshot_conflict');
+                    await assertIdle();
+                    // private
+                    await mkdir(markerDir, { recursive: true, mode: 0o700 });
+                    const temporary = `${marker}.${randomUUID()}.tmp`;
+                    // private
+                    await writeFile(temporary, JSON.stringify({ sha256 }), { flag: 'wx', mode: 0o600 });
+                    await rename(temporary, marker);
+                    // Moving first makes a partially-deleted directory invisible to readers and safe to retry.
+                    await rename(root, removed);
+                    await rm(removed, { recursive: true, force: true });
+                    result = { evicted: true };
+                }
+                finally {
+                    await snapshot.cleanup();
+                }
+                return;
+            }
+            if (await present())
+                throw new Error('storage_snapshot_destination_exists');
+            const sha256 = request.headers['x-playcraft-snapshot-sha256'];
+            if (typeof sha256 !== 'string' || !SHA256.test(sha256))
+                throw new Error('storage_snapshot_invalid');
+            const rawLength = request.headers['content-length'];
+            if (rawLength !== undefined && (typeof rawLength !== 'string' || !/^\d+$/.test(rawLength) || !Number.isSafeInteger(Number(rawLength)) || Number(rawLength) > STORAGE_SNAPSHOT_MAX_BYTES))
+                throw new Error('storage_snapshot_too_large');
+            const temporary = await mkdtemp(join(parent, '.storage-restore-'));
+            try {
+                const incoming = join(temporary, 'incoming.gz'), staged = join(temporary, 'workspace');
+                const hash = createHash('sha256');
+                let size = 0;
+                await pipeline(Readable.from(request.iterator({ destroyOnReturn: false })), new Transform({ transform(chunk, _encoding, done) {
+                        size += chunk.length;
+                        hash.update(chunk);
+                        done(size > STORAGE_SNAPSHOT_MAX_BYTES ? new Error('storage_snapshot_too_large') : null, chunk);
+                    } }), createWriteStream(incoming, { flags: 'wx', mode: 0o600 }), { signal: controller.signal }); // private
+                if (hash.digest('hex') !== sha256 || rawLength !== undefined && size !== Number(rawLength))
+                    throw new Error('storage_snapshot_checksum_mismatch');
+                // private
+                await mkdir(staged, { mode: 0o700 });
+                await extractStorageSnapshot(incoming, staged, { signal: controller.signal });
+                await openDirectoryToDevelopment(staged, (await lstat(parent)).gid);
+                await assertIdle();
+                if (await present())
+                    throw new Error('storage_snapshot_destination_exists');
+                const evicted = await readFile(marker, 'utf8').then(value => JSON.parse(value), () => undefined);
+                if (typeof evicted?.sha256 === 'string' && SHA256.test(evicted.sha256))
+                    await rm(join(parent, `.storage-evicted-${workspaceId}-${evicted.sha256}`), { recursive: true, force: true });
+                await rmdir(root).catch(error => { if (error.code !== 'ENOENT')
+                    throw error; });
+                await rename(staged, root);
+                await rm(marker, { force: true });
+                result = { restored: true };
+            }
+            finally {
+                await rm(temporary, { recursive: true, force: true });
+            }
+        });
+        if (result)
+            json(200, result);
+        if (download) {
+            const snapshot = download;
+            try {
+                response.writeHead(200, { 'content-type': 'application/octet-stream', 'content-length': snapshot.bytes,
+                    'cache-control': 'private, no-store', 'x-content-type-options': 'nosniff', 'x-playcraft-snapshot-sha256': snapshot.sha256 });
+                await pipeline(createReadStream(snapshot.path), response, { signal: controller.signal });
+            }
+            finally {
+                await snapshot.cleanup();
+            }
+        }
+    }
+    catch (error) {
+        if (response.headersSent)
+            response.destroy(error instanceof Error ? error : undefined);
+        else if (!controller.signal.aborted) {
+            const reason = error instanceof Error ? error.message : '';
+            const code = /^(?:storage_snapshot_[a-z_]+|workspace_(?:not_registered|not_prepared|directory_occupied)|directory_busy|runtime_destroyed|generation_mismatch)$/.test(reason) ? reason : 'storage_snapshot_failed';
+            json(code === 'storage_snapshot_too_large' ? 413 : code === 'storage_snapshot_invalid' ? 400 : 409, { error: code });
+        }
+    }
+    finally {
+        request.off('aborted', abort);
+        response.off('close', closed);
+    }
+    return true;
+}

package/dist/workspace-runtime/workspaces/empty-template.js

@@ -6,12 +6,14 @@ import { createHash } from 'node:crypto';
 import { canonicalProjectSkillsJson } from '@playcraft/common/project-skills';
 import { syncLocalProjectSkills } from '../../project-skills/local-store.js';
 import { selectOptionalPlatformSkills } from './optional-platform-skills.js';
+import { WORKSPACE_REMIX_REFERENCES_SKILL } from './remix-reference-skill.js';
 export const EMPTY_WORKSPACE_REPOSITORY_SKILLS = [
     'playcraft-skill-recommender',
     'playcraft-image-generation',
     'playcraft-audio-generation',
     'playcraft-image-processing',
     'playcraft-workspace-assets',
+    WORKSPACE_REMIX_REFERENCES_SKILL,
     'playcraft-build-optimizer',
 ];
 export const EMPTY_WORKSPACE_PLATFORM_SKILLS = ['playcraft-video-understanding', 'playcraft-replica-validation'];

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';
@@ -163,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: {
@@ -173,8 +173,14 @@ 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
@@ -218,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)
@@ -260,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. */ }
+    }
+}