@playcraft/cli 0.1.25 → 0.1.27

package/dist/workspace-runtime/codex/app-server.js

@@ -10,6 +10,9 @@ import { projectNativeThread } from '@playcraft/common/cloud-workspace/runtime';
 import { collectedEvent, NativePreparationError } from './native-adapter.js';
 import { readProjectSkillsLockFile } from '@playcraft/common/project-skills';
 import { freezeWorkspaceSkills } from '../workspaces/skills.js';
+function codexReasoningEffort(effort) {
+    return effort === 'max' ? 'xhigh' : effort;
+}
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -85,24 +88,25 @@ export function createCodexAppServerAdapter(options) {
         startPromise ??= start();
         await startPromise;
     }
-    async function threadConfig(cwd, modelConfigId, sessionId) {
+    async function threadConfig(cwd, modelConfigId, sessionId, reasoningEffort) {
         try {
-            return await options.modelBroker?.prepareThreadConfig(cwd, modelConfigId, sessionId)
+            return await options.modelBroker?.prepareThreadConfig(cwd, modelConfigId, sessionId, reasoningEffort)
                 ?? { ...options.fixedThreadConfig, modelConfigId: undefined, activate: () => { } };
         }
         catch (error) {
             const reason = error instanceof Error ? error.message : '';
             throw new NativePreparationError(['model_config_required',
-                'model_credential_scope_mismatch', 'model_config_denied', 'workspace_not_registered'].includes(reason)
+                'model_credential_scope_mismatch', 'model_config_denied', 'reasoning_effort_denied', 'reasoning_effort_unsupported', 'workspace_not_registered'].includes(reason)
                 ? reason : 'model_credential_unavailable');
         }
     }
-    async function lockedThreadConfig(cwd, selectedConfigId, sessionId) {
-        const { modelConfigId, activate, ...providedModelConfig } = await threadConfig(cwd, selectedConfigId, sessionId);
+    async function lockedThreadConfig(cwd, selectedConfigId, sessionId, reasoningEffort) {
+        const { modelConfigId, activate, ...providedModelConfig } = await threadConfig(cwd, selectedConfigId, sessionId, reasoningEffort);
         // Both local and managed threads must use the verified portable catalog.
         const modelConfig = { ...providedModelConfig, config: {
                 ...('config' in providedModelConfig ? asRecord(providedModelConfig.config) : {}),
                 ...portableCodexConfig(catalogDirectory ? join(catalogDirectory, 'portable-models.json') : undefined),
+                ...(reasoningEffort ? { model_reasoning_effort: codexReasoningEffort(reasoningEffort) } : {}),
             } };
         const scope = relative(options.config.workspaceRoot, cwd);
         const orchestration = options.config.workspaceMode === 'multi' && /^[0-9a-f-]{36}$/i.test(scope);
@@ -175,7 +179,7 @@ export function createCodexAppServerAdapter(options) {
             throw new NativePreparationError('workspace_skills_unavailable');
         }
     }
-    async function restartForSkills(threadId, selectedConfigId) {
+    async function restartForSkills(threadId, selectedConfigId, reasoningEffort) {
         if ([...threads.values()].some(thread => thread.turnActive) || approvals.size)
             throw new NativePreparationError('skills_reload_pending');
         const previous = live;
@@ -206,7 +210,7 @@ export function createCodexAppServerAdapter(options) {
             // Other workspaces resume lazily, so a damaged unrelated lock cannot block this workspace.
             const thread = threads.get(threadId);
             if (thread?.hasNativeHistory && thread.cwd)
-                await resumePreparedThread(threadId, thread, await lockedThreadConfig(thread.cwd, selectedConfigId ?? thread.modelConfigId, thread.sessionId));
+                await resumePreparedThread(threadId, thread, await lockedThreadConfig(thread.cwd, selectedConfigId ?? thread.modelConfigId, thread.sessionId, reasoningEffort));
         }
         catch {
             readyFlag = false;
@@ -452,7 +456,7 @@ export function createCodexAppServerAdapter(options) {
                 await ensureStarted();
                 if (!rpc)
                     throw new Error('codex_not_started');
-                const prepared = await lockedThreadConfig(input.cwd, input.modelConfigId, input.sessionId);
+                const prepared = await lockedThreadConfig(input.cwd, input.modelConfigId, input.sessionId, input.reasoningEffort);
                 const result = await rpc.request('thread/start', {
                     cwd: input.cwd,
                     model,
@@ -463,8 +467,8 @@ export function createCodexAppServerAdapter(options) {
                     throw new Error('native_receipt_lost');
                 prepared.activate();
                 threads.set(threadId, { sessionId: input.sessionId, cwd: input.cwd, skillsHash: prepared.skillsHash,
-                    discoveryHash: prepared.discoveryHash, modelConfigId: prepared.modelConfigId, hasNativeHistory: false, loaded: true });
-                return { threadId, modelConfigId: prepared.modelConfigId };
+                    discoveryHash: prepared.discoveryHash, modelConfigId: prepared.modelConfigId, reasoningEffort: input.reasoningEffort, hasNativeHistory: false, loaded: true });
+                return { threadId, modelConfigId: prepared.modelConfigId, reasoningEffort: input.reasoningEffort };
             });
         },
         async resumeThread(input) {
@@ -472,7 +476,7 @@ export function createCodexAppServerAdapter(options) {
                 await ensureStarted();
                 if (!rpc)
                     throw new Error('codex_not_started');
-                const prepared = await lockedThreadConfig(input.cwd, input.modelConfigId, input.sessionId);
+                const prepared = await lockedThreadConfig(input.cwd, input.modelConfigId, input.sessionId, input.reasoningEffort);
                 let resumedId;
                 try {
                     const resumed = await rpc.request('thread/resume', {
@@ -487,8 +491,8 @@ export function createCodexAppServerAdapter(options) {
                     return undefined;
                 prepared.activate();
                 threads.set(input.threadId, { sessionId: input.sessionId, cwd: input.cwd, skillsHash: prepared.skillsHash,
-                    discoveryHash: prepared.discoveryHash, modelConfigId: prepared.modelConfigId, hasNativeHistory: true, loaded: true });
-                return { modelConfigId: prepared.modelConfigId };
+                    discoveryHash: prepared.discoveryHash, modelConfigId: prepared.modelConfigId, reasoningEffort: input.reasoningEffort, hasNativeHistory: true, loaded: true });
+                return { modelConfigId: prepared.modelConfigId, reasoningEffort: input.reasoningEffort };
             });
         },
         async startTurn(input) {
@@ -506,11 +510,13 @@ export function createCodexAppServerAdapter(options) {
                     return { outcome: 'failed', error: 'workspace_skills_changed' };
                 let selectedModel;
                 let modelConfigId = thread.modelConfigId;
+                const modelChanged = input.modelConfigId !== undefined && input.modelConfigId !== thread.modelConfigId;
+                const reasoningEffort = input.reasoningEffort ?? (modelChanged ? undefined : thread.reasoningEffort);
                 let activateModel = () => { };
                 let execution;
                 if (thread.cwd) {
                     try {
-                        const prepared = await lockedThreadConfig(thread.cwd, input.modelConfigId ?? thread.modelConfigId, input.sessionId);
+                        const prepared = await lockedThreadConfig(thread.cwd, input.modelConfigId ?? thread.modelConfigId, input.sessionId, reasoningEffort);
                         selectedModel = 'model' in prepared.params ? prepared.params.model : undefined;
                         modelConfigId = prepared.modelConfigId;
                         activateModel = prepared.activate;
@@ -521,7 +527,7 @@ export function createCodexAppServerAdapter(options) {
                                 return { outcome: 'failed', error: 'workspace_skills_changed' };
                         }
                         else if (thread.skillsHash && (prepared.skillsHash !== thread.skillsHash || prepared.discoveryHash !== thread.discoveryHash)) {
-                            await restartForSkills(input.threadId, prepared.modelConfigId);
+                            await restartForSkills(input.threadId, prepared.modelConfigId, reasoningEffort);
                         }
                         if (!thread.loaded)
                             await resumePreparedThread(input.threadId, thread, prepared);
@@ -533,9 +539,10 @@ export function createCodexAppServerAdapter(options) {
                     }
                 }
                 const requestId = rpc.reserveRequest();
-                await input.persistReservation({ nativeRequestId: String(requestId), modelConfigId });
+                await input.persistReservation({ nativeRequestId: String(requestId), modelConfigId, reasoningEffort });
                 activateModel();
                 thread.modelConfigId = modelConfigId;
+                thread.reasoningEffort = reasoningEffort;
                 if (input.simulateLostReceipt)
                     return { outcome: 'uncertain', threadId: input.threadId };
                 try {
@@ -543,7 +550,9 @@ export function createCodexAppServerAdapter(options) {
                     const started = await rpc.sendReserved(requestId, 'turn/start', { threadId: input.threadId, input: [
                             { type: 'text', text: input.text },
                             ...(input.images ?? []).map((path) => ({ type: 'localImage', path })),
-                        ], ...(selectedModel ? { model: selectedModel } : {}), ...execution }, turnTimeoutMs);
+                        ], ...(selectedModel ? { model: selectedModel } : {}),
+                        ...(reasoningEffort ? { effort: codexReasoningEffort(reasoningEffort) } : modelChanged ? { effort: null } : {}),
+                        ...execution }, turnTimeoutMs);
                     const turnId = started.turn?.id;
                     if (!turnId)
                         return { outcome: 'uncertain', threadId: input.threadId };
@@ -554,7 +563,7 @@ export function createCodexAppServerAdapter(options) {
                         acceptedThread.modelConfigId = modelConfigId;
                         acceptedThread.turnActive = acceptedThread.lastCompletedTurnId !== turnId;
                     }
-                    return { outcome: 'accepted', threadId: input.threadId, turnId, modelConfigId };
+                    return { outcome: 'accepted', threadId: input.threadId, turnId, modelConfigId, reasoningEffort };
                 }
                 catch {
                     return { outcome: 'uncertain', threadId: input.threadId };

package/dist/workspace-runtime/codex/config-toml.js

@@ -47,8 +47,6 @@ export function portableCodexCatalog(raw) {
             multi_agent_version: 'v1',
             supports_search_tool: false,
             experimental_supported_tools: [],
-            default_reasoning_level: null,
-            supported_reasoning_levels: [],
         };
     });
     return { ...catalog, models };

package/dist/workspace-runtime/codex/model-broker.js

@@ -9,6 +9,7 @@ import { PLATFORM_ROUTES, modelResponsesPath, platformEndpoint } from '@playcraf
 const credentialSchema = z.object({
     token: z.string().min(1), expiresAt: z.string().datetime(),
     configId: z.string().uuid(), model: z.string().min(1).max(128),
+    supportsReasoning: z.boolean().optional(),
     claims: z.object({
         environment: z.string(), userId: z.string(), workspaceId: z.string(), runtimeId: z.string(),
         generation: z.number().int(), runtimeEpoch: z.number().int(),
@@ -43,12 +44,12 @@ export class WorkspaceModelBroker {
             throw new Error('model_broker_unavailable');
         this.baseUrl = `http://127.0.0.1:${address.port}`;
     }
-    async threadConfig(cwd, modelConfigId, sessionId) {
-        const { activate, ...settings } = await this.prepareThreadConfig(cwd, modelConfigId, sessionId);
+    async threadConfig(cwd, modelConfigId, sessionId, reasoningEffort) {
+        const { activate, ...settings } = await this.prepareThreadConfig(cwd, modelConfigId, sessionId, reasoningEffort);
         activate();
         return settings;
     }
-    async prepareThreadConfig(cwd, modelConfigId, sessionId) {
+    async prepareThreadConfig(cwd, modelConfigId, sessionId, reasoningEffort) {
         if (!this.server)
             throw new Error('workspace_not_registered');
         const { workspaceId } = await workspaceContextFromRoot(this.state, cwd);
@@ -57,10 +58,11 @@ export class WorkspaceModelBroker {
         const routeKey = sessionId ? `${workspaceId}/${createHash('sha256').update(sessionId).digest('hex').slice(0, 32)}` : workspaceId;
         let route = this.routes.get(routeKey);
         const selected = modelConfigId ?? (route?.epoch === this.state.runtimeEpoch ? route.selected?.entry.modelConfigId : undefined);
-        const cacheKey = `${workspaceId}:${selected ?? 'default'}`;
-        let entry = this.entries.get(cacheKey) ?? [...this.entries.values()].find(item => item.workspaceId === workspaceId && item.epoch === this.state.runtimeEpoch && item.modelConfigId === selected);
+        const cacheKey = `${workspaceId}:${selected ?? 'default'}:${reasoningEffort ?? 'default'}`;
+        let entry = this.entries.get(cacheKey) ?? [...this.entries.values()].find(item => item.workspaceId === workspaceId && item.epoch === this.state.runtimeEpoch && item.modelConfigId === selected
+            && item.reasoningEffort === reasoningEffort);
         if (!entry || entry.epoch !== this.state.runtimeEpoch) {
-            entry = { workspaceId, epoch: this.state.runtimeEpoch, cacheKey, modelConfigId: selected };
+            entry = { workspaceId, epoch: this.state.runtimeEpoch, cacheKey, modelConfigId: selected, reasoningEffort };
             this.entries.set(cacheKey, entry);
         }
         // Resolve current model metadata and permission at every native turn boundary.
@@ -113,11 +115,12 @@ export class WorkspaceModelBroker {
             headers: { authorization: `Bearer ${config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': config.environment },
             body: JSON.stringify({ runtimeId: config.runtimeId, generation: config.generation,
                 runtimeEpoch: entry.epoch, workspaceId: entry.workspaceId,
-                ...(entry.modelConfigId ? { modelConfigId: entry.modelConfigId } : {}) }),
+                ...(entry.modelConfigId ? { modelConfigId: entry.modelConfigId } : {}),
+                ...(entry.reasoningEffort ? { reasoningEffort: entry.reasoningEffort } : {}) }),
         });
         if (!response.ok) {
             const error = await response.json().catch(() => ({}));
-            throw new Error(['model_config_required', 'model_config_denied'].includes(error.reason ?? '') ? error.reason : 'model_credential_unavailable');
+            throw new Error(['model_config_required', 'model_config_denied', 'reasoning_effort_denied', 'reasoning_effort_unsupported'].includes(error.reason ?? '') ? error.reason : 'model_credential_unavailable');
         }
         const credential = credentialSchema.parse(await response.json());
         const claims = credential.claims;
@@ -176,6 +179,22 @@ export class WorkspaceModelBroker {
             }
             // The browser selects a configuration, never an arbitrary billable upstream model.
             body.model = selected.model;
+            if (credential.supportsReasoning === false) {
+                const reasoning = body.reasoning;
+                if (reasoning && typeof reasoning === 'object' && !Array.isArray(reasoning)) {
+                    delete reasoning.effort;
+                }
+            }
+            else if (entry.reasoningEffort) {
+                const reasoning = body.reasoning;
+                const modelName = selected.model.split('/').pop() ?? selected.model;
+                const effort = entry.reasoningEffort === 'max' && /^o\d|gpt-[5-9]/i.test(modelName)
+                    ? 'xhigh' : entry.reasoningEffort;
+                body.reasoning = {
+                    ...(reasoning && typeof reasoning === 'object' && !Array.isArray(reasoning) ? reasoning : {}),
+                    effort,
+                };
+            }
             const expires = setTimeout(cancel, Math.max(0, Date.parse(credential.expiresAt) - Date.now()));
             try {
                 const upstream = await fetch(platformEndpoint(this.state.config.publicBaseUrl, modelResponsesPath(credential.configId)), {

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

@@ -2,7 +2,7 @@ import { withObservedFile } from '../workspaces/revisions.js';
 import { revisionScope, sessionWorkspaceRoot, workspaceRoot, workspaceSessions } from '../workspaces/registry.js';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { PLATFORM_ROUTES, platformEndpoint, fileWritePayloadSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, parameterPatchPayloadSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { PLATFORM_ROUTES, platformEndpoint, fileWritePayloadSchema, gitCommitPayloadSchema, gitPathsPayloadSchema, gitPushPayloadSchema, parameterPatchPayloadSchema, reasoningEffortSchema, terminalCreatePayloadSchema, terminalProcessIdentity, transitionOperation, workspaceSavePayloadSchema, workspaceSkillsUpdatePayloadSchema, } from '@playcraft/common/cloud-workspace/runtime';
 import { closeCliCredentials } from '../workspaces/cli-credentials.js';
 import { artifactFormat } from '../workspaces/artifact-files.js';
 import { refreshWorkspaceArtifacts } from '../workspaces/artifact-events.js';
@@ -163,12 +163,16 @@ async function executeCreate(state, scopeKey, operation, payload) {
     const selected = z.string().uuid().optional().safeParse(asRecord(payload).modelConfigId);
     if (!selected.success)
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'model_config_denied' }));
+    const effort = reasoningEffortSchema.optional().safeParse(asRecord(payload).reasoningEffort);
+    if (!effort.success)
+        return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'reasoning_effort_denied' }));
     let started;
     try {
         started = await native(state).startThread({
             sessionId,
             cwd: await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName),
             modelConfigId: selected.data,
+            reasoningEffort: effort.data,
         });
     }
     catch (error) {
@@ -188,11 +192,13 @@ async function executeCreate(state, scopeKey, operation, payload) {
         cwd: await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName),
         recoverability: 'native',
         modelConfigId: started.modelConfigId,
+        reasoningEffort: started.reasoningEffort ?? effort.data,
     });
     const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted', {
         nativeRequestId: `thread/start:${sessionId}`,
         nativeThreadId: started.threadId,
         modelConfigId: started.modelConfigId,
+        reasoningEffort: started.reasoningEffort ?? effort.data,
     }));
     await recordNativeEvents(state, accepted, [
         { type: 'session.created', payload: { sessionId, threadId: started.threadId }, occurredAt: new Date().toISOString() },
@@ -205,9 +211,14 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
     const selected = z.string().uuid().optional().safeParse(body.modelConfigId);
     if (!selected.success)
         return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'model_config_denied' }));
+    const effort = reasoningEffortSchema.optional().safeParse(body.reasoningEffort);
+    if (!effort.success)
+        return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: 'reasoning_effort_denied' }));
     let found = state.journal.getSession(sessionId);
+    const modelChanged = selected.data !== undefined && selected.data !== (found?.modelConfigId ?? recovery?.modelConfigId);
+    const requestedEffort = effort.data ?? (modelChanged ? undefined : recovery?.reasoningEffort ?? found?.reasoningEffort);
     if (recovery && found?.recoverability !== 'native') {
-        const rebound = await rebindSession(state, operation, found, selected.data ?? recovery.modelConfigId);
+        const rebound = await rebindSession(state, operation, found, selected.data ?? recovery.modelConfigId, requestedEffort);
         if (typeof rebound === 'string') {
             return persist(state, scopeKey, transitionOperation(operation, 'failed', { error: rebound }));
         }
@@ -246,16 +257,19 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
         images: attachments.filter((file) => file.mimeType.startsWith('image/')).map((file) => file.path),
         clientRequestId: operation.clientRequestId,
         modelConfigId: selected.data ?? binding.modelConfigId,
+        reasoningEffort: requestedEffort,
         simulateLostReceipt: body.simulateLostReceipt === true,
-        persistReservation: async ({ nativeRequestId, modelConfigId }) => {
+        persistReservation: async ({ nativeRequestId, modelConfigId, reasoningEffort }) => {
+            const selectedEffort = reasoningEffort ?? requestedEffort;
             await persist(state, scopeKey, {
                 ...operation,
                 nativeRequestId,
                 nativeThreadId: binding.threadId,
                 modelConfigId,
+                reasoningEffort: selectedEffort,
                 updatedAt: new Date().toISOString(),
             });
-            await state.journal.putSession({ ...binding, modelConfigId, turnStatus: 'starting' });
+            await state.journal.putSession({ ...binding, modelConfigId, reasoningEffort: selectedEffort, turnStatus: 'starting' });
         },
     });
     const reserved = state.journal.getOperation(scopeKey) ?? operation;
@@ -323,7 +337,7 @@ async function executeTurn(state, scopeKey, operation, payload, recovery) {
  * carry the earlier conversation until a turn starts on it.
  * Returns an error code when the thread cannot be prepared.
  */
-async function rebindSession(state, operation, binding, modelConfigId) {
+async function rebindSession(state, operation, binding, modelConfigId, reasoningEffort) {
     const sessionId = required(operation.sessionId, 'sessionId');
     const adapter = native(state);
     const cwd = await sessionWorkspaceRoot(state, operation.workspaceId, operation.directoryName);
@@ -335,6 +349,7 @@ async function rebindSession(state, operation, binding, modelConfigId) {
                 threadId: binding.threadId,
                 cwd,
                 modelConfigId: modelConfigId ?? binding.modelConfigId,
+                reasoningEffort,
             });
             if (resumed) {
                 const next = {
@@ -342,6 +357,7 @@ async function rebindSession(state, operation, binding, modelConfigId) {
                     cwd,
                     recoverability: 'native',
                     modelConfigId: resumed.modelConfigId ?? binding.modelConfigId,
+                    reasoningEffort: resumed.reasoningEffort ?? reasoningEffort,
                     turnStatus: undefined,
                     turnBlock: undefined,
                     activeTurnId: undefined,
@@ -351,7 +367,8 @@ async function rebindSession(state, operation, binding, modelConfigId) {
                 return next;
             }
         }
-        const started = await adapter.startThread({ sessionId, cwd, modelConfigId: modelConfigId ?? binding?.modelConfigId });
+        const started = await adapter.startThread({ sessionId, cwd, modelConfigId: modelConfigId ?? binding?.modelConfigId,
+            reasoningEffort });
         const next = {
             sessionId,
             workspaceId: operation.workspaceId,
@@ -360,6 +377,7 @@ async function rebindSession(state, operation, binding, modelConfigId) {
             cwd,
             recoverability: 'native',
             modelConfigId: started.modelConfigId,
+            reasoningEffort: started.reasoningEffort ?? reasoningEffort,
             recoveryContextPending: true,
         };
         await state.journal.putSession(next);
@@ -563,6 +581,15 @@ async function executeGitCommit(state, scopeKey, operation, payload) {
  * and the Git gateway never lets a workspace write its project's main branch, so those two only
  * commit.
  */
+/**
+ * Whether a save pushes after it commits. A workspace bound to a project (its main branch or a
+ * Remix branch) pushes the way the Git panel does; the credential decides whether the remote
+ * accepts it. A standalone workspace has no remote, so its saves stay local; its project
+ * directories have their own branch.
+ */
+export function savePushesBranch(targetKind, directoryName) {
+    return targetKind === 'main' || targetKind === 'remix' || Boolean(directoryName && directoryName !== 'basic');
+}
 async function executeWorkspaceSave(state, scopeKey, operation, payload) {
     const parsed = workspaceSavePayloadSchema.safeParse(payload ?? {});
     if (!parsed.success) {
@@ -572,7 +599,7 @@ async function executeWorkspaceSave(state, scopeKey, operation, payload) {
     try {
         const saved = await saveWorkspaceGit(await workspaceRoot(state, operation.workspaceId, operation.directoryName), {
             message: parsed.data.trigger === 'auto' ? 'Autosave workspace' : 'Save workspace',
-            push: binding?.targetKind === 'remix' || Boolean(operation.directoryName && operation.directoryName !== 'basic'),
+            push: savePushesBranch(binding?.targetKind, operation.directoryName),
             boundBranch: boundBranch(state, operation),
         });
         const accepted = await persist(state, scopeKey, transitionOperation(operation, 'accepted'));

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

@@ -12,6 +12,7 @@ import { readDependencies } from '../workspaces/dependencies.js';
 import { desktopHost, desktopRoute } from './desktop-host.js';
 import { ensureCliCredentials } from '../workspaces/cli-credentials.js';
 import { readAttachmentUpload, uploadWorkspaceAttachment, uploadWorkspaceVideoAttachment } from '../workspaces/attachments.js';
+import { serveWorkspaceAttachment } from '../workspaces/attachment-content.js';
 import { readWorkspaceSkills } from '../workspaces/skills.js';
 import { loadWorkspaceSkillArtifact } from '../workspaces/skill-artifact-loader.js';
 import { join } from 'node:path';
@@ -190,6 +191,13 @@ export async function handleRuntimeRequest(state, request, response) {
             }
             return;
         }
+        if (['GET', 'HEAD'].includes(request.method ?? '') && url.pathname === '/runtime/attachment-content') {
+            if (writeDestroyed(state, response))
+                return;
+            const root = await workspaceRoot(state, url.searchParams.get('workspaceId') ?? '', directoryName);
+            await serveWorkspaceAttachment(root, url.searchParams.get('attachmentId') ?? '', request, response);
+            return;
+        }
         if (request.method === 'GET' && url.pathname === '/runtime/artifacts') {
             if (writeDestroyed(state, response))
                 return;

package/dist/workspace-runtime/workspaces/attachment-content.js

@@ -0,0 +1,111 @@
+import { constants } from 'node:fs';
+import { open } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { attachmentIdsSchema, attachmentUploadSchema, WORKSPACE_ATTACHMENT_MAX_BYTES, WORKSPACE_USER_UPLOADS_DIRECTORY, WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES, } from '@playcraft/common/cloud-workspace/runtime';
+import { artifactMime, artifactPath } from './artifact-files.js';
+const additionalMediaTypes = {
+    '.aac': 'audio/aac', '.opus': 'audio/ogg', '.oga': 'audio/ogg', '.aif': 'audio/aiff', '.aiff': 'audio/aiff',
+    '.bmp': 'image/bmp', '.ico': 'image/vnd.microsoft.icon', '.heic': 'image/heic', '.heif': 'image/heif',
+    '.tif': 'image/tiff', '.tiff': 'image/tiff',
+};
+const detectedImageTypes = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+function attachmentRange(header, size) {
+    if (!header)
+        return undefined;
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match || (!match[1] && !match[2]) || !size)
+        return null;
+    const first = match[1] ? Number(match[1]) : undefined;
+    const last = match[2] ? Number(match[2]) : undefined;
+    if ((first !== undefined && !Number.isSafeInteger(first)) || (last !== undefined && !Number.isSafeInteger(last)))
+        return null;
+    const start = first ?? Math.max(0, size - (last ?? 0));
+    const end = first === undefined ? size - 1 : Math.min(last ?? size - 1, size - 1);
+    return start >= size || start > end ? null : { start, end };
+}
+async function openAttachment(root, id) {
+    const metadataPath = await artifactPath(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata/${id}.json`);
+    const metadataFile = await open(metadataPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let metadata;
+    try {
+        const stat = await metadataFile.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 8192)
+            throw new Error('attachment_unavailable');
+        metadata = JSON.parse(await metadataFile.readFile('utf8'));
+        if (metadata.id !== id || !attachmentUploadSchema.shape.name.safeParse(metadata.name).success)
+            throw new Error('attachment_unavailable');
+    }
+    finally {
+        await metadataFile.close();
+    }
+    const path = await artifactPath(root, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${id}/${metadata.name}`);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        const mimeType = detectedImageTypes.has(metadata.mimeType) ? metadata.mimeType
+            : additionalMediaTypes[extname(metadata.name).toLowerCase()] ?? artifactMime(metadata.name);
+        const limit = mimeType.startsWith('video/') ? WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES : WORKSPACE_ATTACHMENT_MAX_BYTES;
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size !== metadata.size || stat.size > limit)
+            throw new Error('attachment_unavailable');
+        return { handle, name: metadata.name, mimeType, size: stat.size };
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+/** Serve only registered references; no caller-supplied file paths reach the filesystem. */
+export async function serveWorkspaceAttachment(root, attachmentId, request, response) {
+    if (!attachmentIdsSchema.safeParse([attachmentId]).success) {
+        response.writeHead(400, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+        response.end(JSON.stringify({ error: 'invalid_attachment' }));
+        return;
+    }
+    let content;
+    try {
+        content = await openAttachment(root, attachmentId);
+    }
+    catch {
+        response.writeHead(404, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+        response.end(JSON.stringify({ error: 'attachment_not_found' }));
+        return;
+    }
+    try {
+        const range = attachmentRange(request.headers.range, content.size);
+        const headers = {
+            'content-type': content.mimeType,
+            'cache-control': 'private, no-store',
+            'x-content-type-options': 'nosniff',
+            'content-security-policy': "sandbox; default-src 'none'; style-src 'unsafe-inline'",
+            'referrer-policy': 'no-referrer',
+            'accept-ranges': 'bytes',
+        };
+        if (!/^(?:image|video|audio|model)\//.test(content.mimeType) || content.mimeType === 'image/svg+xml')
+            headers['content-disposition'] = `attachment; filename*=UTF-8''${encodeURIComponent(content.name).replace(/'/g, '%27')}`;
+        if (range === null) {
+            response.writeHead(416, { ...headers, 'content-range': `bytes */${content.size}`, 'content-length': '0' });
+            response.end();
+            return;
+        }
+        if (range)
+            headers['content-range'] = `bytes ${range.start}-${range.end}/${content.size}`;
+        headers['content-length'] = String(range ? range.end - range.start + 1 : content.size);
+        response.writeHead(range ? 206 : 200, headers);
+        if (request.method === 'HEAD' || !content.size) {
+            response.end();
+            return;
+        }
+        await pipeline(content.handle.createReadStream({
+            start: range?.start ?? 0,
+            end: range?.end ?? content.size - 1,
+            autoClose: false,
+        }), response);
+    }
+    catch (error) {
+        response.destroy(error instanceof Error ? error : undefined);
+    }
+    finally {
+        await content.handle.close();
+    }
+}

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

@@ -189,6 +189,16 @@ async function assertBoundBranch(rootReal, boundBranch) {
  * A push the remote refused for this ref is a definite outcome, unlike a lost response. Porcelain
  * output marks the ref with "!" and says whether the remote has commits this checkout lacks.
  */
+/**
+ * The gateway or the host refused the push over HTTP before any ref changed: no write access, the
+ * gateway's writes switched off, or no such repository. Like a protected-branch refusal, nothing
+ * was pushed and the commit is kept.
+ */
+function httpRefusal(stderr) {
+    return /returned error: (?:401|403|404)\b|Authentication failed|Access denied|could not read Username|repository '[^']*' not found/i.test(stderr)
+        ? 'git_push_rejected'
+        : undefined;
+}
 function pushRejection(stdout) {
     const line = stdout.split('\n').find((item) => item.startsWith('!\t'));
     if (!line)
@@ -235,7 +245,7 @@ export async function pushWorkspaceGit(root, boundBranch) {
     catch { /* A lost response does not prove the remote rejected the update. */ }
     if (pushed?.code === 0)
         return;
-    const rejected = pushed ? pushRejection(pushed.stdout) : undefined;
+    const rejected = pushed ? pushRejection(pushed.stdout) ?? httpRefusal(pushed.stderr) : undefined;
     if (rejected)
         throw new GitWorkspaceError(rejected, rejected);
     try {
@@ -282,6 +292,42 @@ export async function saveWorkspaceGit(root, input) {
     await recordPushedHead(rootReal);
     return { ...(commit ? { commit } : {}), pushed: true, withheld };
 }
+/**
+ * Connects a standalone checkout to the repository it was just given, keeping all its history and
+ * uncommitted work. The new repository holds one empty commit on `branch`; it becomes the base of an
+ * unborn checkout, or is merged into existing history, so the next push is a plain fast-forward.
+ * Credentials come from the workspace's configured helper and never enter the remote URL.
+ * Safe to run again after a failure part way.
+ */
+export async function attachWorkspaceRemote(root, repositoryUrl, branch) {
+    const rootReal = await ensureWorkspaceGit(root);
+    const origin = await gitAllowFail(rootReal, ['remote', 'get-url', 'origin']);
+    if (origin.code !== 0)
+        await git(rootReal, ['remote', 'add', 'origin', repositoryUrl]);
+    else if (origin.stdout.trim() !== repositoryUrl)
+        throw new GitWorkspaceError('remote_not_configured', 'origin_mismatch');
+    const remoteRef = `refs/remotes/origin/${branch}`;
+    const fetched = await gitAllowFail(rootReal, ['fetch', '--no-tags', 'origin', `+refs/heads/${branch}:${remoteRef}`], 90000);
+    if (fetched.code !== 0)
+        throw new GitWorkspaceError(httpRefusal(fetched.stderr) ?? 'git_command_failed', 'git_fetch_failed');
+    const current = (await gitAllowFail(rootReal, ['symbolic-ref', '--quiet', '--short', 'HEAD'])).stdout.trim();
+    const born = (await gitAllowFail(rootReal, ['rev-parse', '-q', '--verify', 'HEAD^{commit}'])).code === 0;
+    if (current !== branch) {
+        await git(rootReal, born ? ['branch', '-M', branch] : ['symbolic-ref', 'HEAD', `refs/heads/${branch}`]);
+    }
+    if (!born) {
+        // Nothing committed yet: start the branch at the remote commit; the files stay as changes.
+        await git(rootReal, ['update-ref', `refs/heads/${branch}`, remoteRef]);
+    }
+    else if ((await gitAllowFail(rootReal, ['merge-base', '--is-ancestor', remoteRef, 'HEAD'])).code !== 0) {
+        const merged = await gitAllowFail(rootReal, [...(await commitIdentity(rootReal)), 'merge', '--allow-unrelated-histories', '--no-edit', remoteRef], 60000);
+        if (merged.code !== 0) {
+            await gitAllowFail(rootReal, ['merge', '--abort']);
+            throw new GitWorkspaceError('git_command_failed', merged.stderr.trim() || 'git_merge_failed');
+        }
+    }
+    await git(rootReal, ['branch', `--set-upstream-to=origin/${branch}`, branch]);
+}
 async function unstage(rootReal, paths) {
     if (paths.length === 0)
         return;

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

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { lstat, mkdir, realpath } from 'node:fs/promises';
+import { lstat, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import { promisify } from 'node:util';
 import { isLocalWorkspaceGitAuthMode, sameWorkspaceRegistration, workspaceRegistrationSchema, } from '@playcraft/common/cloud-workspace/runtime';
@@ -9,6 +9,7 @@ import { scheduleDependencyInstall } from './dependencies.js';
 import { ensureWorkspaceSkills, readWorkspaceSkills } from './skills.js';
 import { loadWorkspaceSkillArtifact, workspacePlatformSkillAccess } from './skill-artifact-loader.js';
 import { writeWorkspaceCliContext } from './cli-context.js';
+import { attachWorkspaceRemote } from './git.js';
 export { WorkspaceContextError } from './context-error.js';
 const exec = promisify(execFile);
 export function revisionScope(state, workspaceId, directoryName = 'basic') {
@@ -106,8 +107,11 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
         const existing = state.journal.getWorkspace(binding.workspaceId);
         const preservedLocalBasic = binding.targetKind !== 'standalone' && binding.preserveLocalBasic === true;
         const localUpgrade = preservedLocalBasic && binding.targetKind === 'main' && existing?.targetKind === 'standalone';
-        if (existing && !sameWorkspaceRegistration(existing, binding) && !localUpgrade)
+        // A standalone workspace promoted to a project's main keeps its checkout and gains that remote.
+        const remoteUpgrade = !preservedLocalBasic && binding.targetKind === 'main' && existing?.targetKind === 'standalone';
+        if (existing && !sameWorkspaceRegistration(existing, binding) && !localUpgrade && !remoteUpgrade)
             throw new WorkspaceContextError('workspace_binding_conflict');
+        const attachMarker = join(state.config.stateDir, 'workspace-remote-attach', `${binding.workspaceId}.json`);
         const directories = binding.directories ?? existing?.directories;
         if (directories?.some(directory => directory.directoryName === 'basic' && directory.status === 'reclaimed')) {
             // Registration publishes trusted identity. Only an explicit basic ensure restores the checkout.
@@ -142,6 +146,28 @@ export async function registerWorkspace(state, input, leaseFence, preparation, r
                 GIT_CONFIG_GLOBAL: '/dev/null',
             },
         })).stdout.trim();
+        // Unfinished if it failed part way: the marker outlives the journal entry written below.
+        if (binding.targetKind === 'main' && !preservedLocalBasic && (remoteUpgrade || await lstat(attachMarker).then(() => true, () => false))) {
+            if (preparation?.mode !== 'clone' || !state.gitCredentials)
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            await mkdir(join(state.config.stateDir, 'workspace-remote-attach'), { recursive: true, mode: 0o700 });
+            await writeFile(attachMarker, JSON.stringify({ repositoryUrl: binding.repositoryUrl, branchName: binding.branchName }), { mode: 0o600 });
+            // The credential helper only serves a workspace the journal knows to be bound.
+            await state.journal.putWorkspace({ ...binding, directories });
+            try {
+                await state.gitCredentials.configure(binding, preparation);
+            }
+            catch {
+                throw new WorkspaceContextError('workspace_git_gateway_unavailable');
+            }
+            try {
+                await attachWorkspaceRemote(root, binding.repositoryUrl, binding.branchName);
+            }
+            catch {
+                throw new WorkspaceContextError('workspace_remote_attach_failed');
+            }
+            await rm(attachMarker, { force: true });
+        }
         try {
             let checkoutMatches;
             if (binding.targetKind === 'standalone' || preservedLocalBasic) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "private": false,
   "type": "module",
   "engines": {
@@ -50,8 +50,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.1.25",
-    "@playcraft/common": "^0.1.25",
+    "@playcraft/build": "^0.1.27",
+    "@playcraft/common": "^0.1.27",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",