@playcraft/cli 0.1.9 → 0.1.11

package/README.md

@@ -141,6 +141,17 @@ playcraft login --url https://your-playcraft.example.com
 
 登录成功后，`tools`、`recommend`、`fix-ids` 等所有需要后端 API 的命令均无需额外配置，直接使用。
 
+账号提示待激活时，使用同一目标环境及已保存的个人访问令牌主动激活：
+
+```bash
+playcraft login --activate
+playcraft login --activate --url https://your-playcraft.example.com
+```
+
+也可通过 `PLAYCRAFT_TOKEN` 提供个人访问令牌。激活只发送一次请求，成功后重新执行原业务命令；该动作不会打开浏览器或续签令牌。目标服务须已接入身份服务的激活入口；封禁、停用账号及沙箱执行令牌不能用于激活。
+
+若本地、全局或环境变量配置冲突，激活会要求明确指定 `--url`、所需的 `PLAYCRAFT_ENV` 和对应的个人访问令牌。
+
 ### 沙箱环境（CI / Agent）
 
 在沙箱或 CI 中可通过 `.playcraft.json` 或环境变量配置：

package/dist/auth/account-activation.js

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadGlobalConfig } from '../config.js';
+import { accountActivationMessage } from './messages.js';
+export const ACCOUNT_PENDING_ACTIVATION = 'account_pending_activation';
+export class AccountActivationError extends Error {
+    code;
+    status;
+    retryable = false;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'AccountActivationError';
+    }
+}
+export function responseErrorCode(payload) {
+    if (!payload || typeof payload !== 'object')
+        return undefined;
+    const { error, code } = payload;
+    return typeof error?.code === 'string' ? error.code : typeof code === 'string' ? code : undefined;
+}
+export function pendingAccountActivationError(status, payload) {
+    return status === 403 && responseErrorCode(payload) === ACCOUNT_PENDING_ACTIVATION
+        ? new AccountActivationError(ACCOUNT_PENDING_ACTIVATION, `${ACCOUNT_PENDING_ACTIVATION}: ${accountActivationMessage('pending')}`, status)
+        : undefined;
+}
+export function parseErrorPayload(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function localActivationConfig() {
+    for (const path of [
+        join(process.cwd(), '.playcraft.json'),
+        '/project/.playcraft.json',
+        join(homedir(), '.playcraft.json'),
+    ]) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const config = JSON.parse(readFileSync(path, 'utf8'));
+            if (config && typeof config === 'object' && !Array.isArray(config))
+                return config;
+        }
+        catch {
+            // Follow the existing local credential lookup when a file is unreadable.
+        }
+    }
+    return {};
+}
+function stringValue(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+function activationBaseUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (!['http:', 'https:'].includes(url.protocol) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash)
+            throw new Error();
+        url.pathname = url.pathname.replace(/\/+$/, '').replace(/\/api$/, '');
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        throw new AccountActivationError('INVALID_ACTIVATION_TARGET', accountActivationMessage('invalidTarget'));
+    }
+}
+function savedTokenForTarget(config, rawUrl, target, environment) {
+    if (!rawUrl || (stringValue(config.env)?.trim() || '') !== environment)
+        return undefined;
+    try {
+        return activationBaseUrl(rawUrl) === target ? stringValue(config.token) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizedSavedUrl(raw) {
+    try {
+        return raw ? activationBaseUrl(raw) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function activateAccount(options, defaultBaseUrl) {
+    const local = localActivationConfig();
+    const global = loadGlobalConfig();
+    const localUrl = stringValue(local.apiUrl);
+    const globalUrl = stringValue(global.backendUrl) || stringValue(global.url);
+    const explicitUrl = options.url || process.env.PLAYCRAFT_API_URL || process.env.PLAYCRAFT_URL;
+    const target = activationBaseUrl(explicitUrl || localUrl || globalUrl || defaultBaseUrl);
+    const explicitToken = options.token || process.env.PLAYCRAFT_TOKEN || process.env.PLAYCRAFT_SANDBOX_TOKEN;
+    const savedUrls = [normalizedSavedUrl(localUrl), normalizedSavedUrl(globalUrl)].filter(Boolean);
+    const savedTokens = [stringValue(local.token), stringValue(global.token)].filter(Boolean);
+    const environmentsConflict = savedUrls.length === 2 &&
+        savedUrls[0] === savedUrls[1] &&
+        (stringValue(local.env)?.trim() || '') !== (stringValue(global.env)?.trim() || '');
+    const environmentTokensConflict = process.env.PLAYCRAFT_TOKEN &&
+        process.env.PLAYCRAFT_SANDBOX_TOKEN &&
+        process.env.PLAYCRAFT_TOKEN !== process.env.PLAYCRAFT_SANDBOX_TOKEN;
+    const environmentUrlsConflict = process.env.PLAYCRAFT_API_URL &&
+        process.env.PLAYCRAFT_URL &&
+        normalizedSavedUrl(process.env.PLAYCRAFT_API_URL) !==
+            normalizedSavedUrl(process.env.PLAYCRAFT_URL);
+    if ((!explicitUrl && new Set(savedUrls).size > 1) ||
+        (!explicitToken && new Set(savedTokens).size > 1) ||
+        (environmentsConflict && !process.env.PLAYCRAFT_ENV) ||
+        (environmentTokensConflict && !options.token) ||
+        (environmentUrlsConflict && !options.url)) {
+        throw new AccountActivationError('AMBIGUOUS_ACTIVATION_TARGET', accountActivationMessage('ambiguous'));
+    }
+    const environment = (process.env.PLAYCRAFT_ENV ||
+        (!explicitUrl ? (localUrl ? stringValue(local.env) : stringValue(global.env)) : '') ||
+        '').trim();
+    const token = explicitToken ||
+        savedTokenForTarget(local, localUrl, target, environment) ||
+        savedTokenForTarget(global, globalUrl, target, environment);
+    if (!token)
+        throw new AccountActivationError('AUTH_REQUIRED', accountActivationMessage('missingToken'));
+    if (!/^playcraft_pat_[A-Za-z0-9_-]{32}$/.test(token)) {
+        throw new AccountActivationError('INVALID_ACTIVATION_TOKEN', accountActivationMessage('invalidToken'));
+    }
+    let response;
+    try {
+        response = await fetch(`${target}/api/settings/personal-access-tokens/activate`, {
+            method: 'POST',
+            redirect: 'error',
+            signal: AbortSignal.timeout(30_000),
+            headers: {
+                Authorization: `Bearer ${token}`,
+                ...(environment ? { 'playcraft-env': environment } : {}),
+            },
+        });
+    }
+    catch {
+        throw new AccountActivationError('ACTIVATION_UNCONFIRMED', accountActivationMessage('unavailable'));
+    }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        throw new AccountActivationError('ACTIVATION_FAILED', accountActivationMessage('failed'), response.status);
+    }
+    const result = await response.json().catch(() => undefined);
+    if (!result ||
+        typeof result !== 'object' ||
+        result.accountStatus !== 'active') {
+        throw new AccountActivationError('ACTIVATION_UNCONFIRMED', accountActivationMessage('unavailable'), response.status);
+    }
+    console.log(accountActivationMessage('success'));
+}

package/dist/auth/messages.js

@@ -0,0 +1,30 @@
+const messages = {
+    en: {
+        activateOption: 'Explicitly activate the account using the current personal access token',
+        tokenOption: 'Personal access token for --activate (or use PLAYCRAFT_TOKEN)',
+        pending: 'Account activation is required. Run `playcraft login --activate` with the same token and target environment, then rerun your command.',
+        success: 'Account activated. Rerun your original command to continue.',
+        missingToken: 'No personal access token matches this target environment. Provide PLAYCRAFT_TOKEN or log in to this environment first.',
+        invalidToken: 'Account activation requires a personal access token. A sandbox token cannot activate an account.',
+        ambiguous: 'Activation credentials or target environments conflict. Specify --url, PLAYCRAFT_ENV when needed, and an explicit personal access token using --token or PLAYCRAFT_TOKEN.',
+        invalidTarget: 'Use a web service base address (http:// or https://) without credentials, a query, or a fragment.',
+        failed: 'Account activation failed. Check the target environment and token before trying again.',
+        unavailable: 'Account activation could not be confirmed. Check your account status before explicitly trying again.',
+    },
+    zh: {
+        activateOption: '明确使用当前个人访问令牌激活账号',
+        tokenOption: '用于 --activate 的个人访问令牌（也可使用 PLAYCRAFT_TOKEN）',
+        pending: '账号需要激活。请使用同一令牌和目标环境主动运行 `playcraft login --activate`，然后重新执行原命令。',
+        success: '账号已激活，请重新执行原命令继续。',
+        missingToken: '没有与目标环境匹配的个人访问令牌。请提供 PLAYCRAFT_TOKEN，或先登录此环境。',
+        invalidToken: '激活账号需要个人访问令牌，沙箱令牌不能用于激活账号。',
+        ambiguous: '激活凭据或目标环境存在冲突。请明确指定 --url、所需的 PLAYCRAFT_ENV，并通过 --token 或 PLAYCRAFT_TOKEN 提供个人访问令牌。',
+        invalidTarget: '激活目标必须是网页服务基址（http:// 或 https://），不能包含凭据、查询参数或片段。',
+        failed: '账号激活失败，请检查目标环境和令牌后再尝试。',
+        unavailable: '无法确认账号是否已激活。请先检查账号状态，再主动决定是否重试。',
+    },
+};
+export function accountActivationMessage(key) {
+    const locale = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[locale.startsWith('zh') ? 'zh' : 'en'][key];
+}

package/dist/commands/login.js

@@ -2,6 +2,7 @@ import http from 'http';
 import { exec } from 'child_process';
 import crypto from 'crypto';
 import { saveGlobalConfig, loadGlobalConfig } from '../config.js';
+import { activateAccount } from '../auth/account-activation.js';
 /** 默认云端 Portal（Next.js `/cli-auth` 与 API 同源时的基址；可通过 --url 或 PLAYCRAFT_URL 覆盖） */
 export const DEFAULT_PLAYCRAFT_CLOUD_BASE = 'https://playcraft.aix.intlgame.com';
 const CALLBACK_PORT = 3456;
@@ -100,6 +101,10 @@ export async function renewExistingToken(options) {
     }
 }
 export async function loginCommand(options) {
+    if (options.activate) {
+        await activateAccount(options, DEFAULT_PLAYCRAFT_CLOUD_BASE);
+        return;
+    }
     const backendUrl = resolveLoginBaseUrl(options);
     const callbackPort = options.callbackPort ?? CALLBACK_PORT;
     const globalConfig = loadGlobalConfig();

package/dist/commands/workspace-runtime.js

@@ -14,7 +14,7 @@ export async function runWorkspaceRuntimeServe(configPath) {
         return;
     }
     try {
-        const runtime = await startWorkspaceRuntime(config);
+        const runtime = await startWorkspaceRuntime(config, { configPath });
         console.log(JSON.stringify({
             status: 'listening',
             url: runtime.url,

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { accountActivationMessage } from './auth/messages.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -66,6 +67,8 @@ program
     .command('login')
     .description('登录 PlayCraft 账号并获取 CLI token')
     .option('--url <url>', 'Portal / API 基址（默认 https://playcraft.aix.intlgame.com，可用环境变量 PLAYCRAFT_URL 覆盖）')
+    .option('--activate', accountActivationMessage('activateOption'))
+    .option('--token <token>', accountActivationMessage('tokenOption'))
     .action(async (options) => {
     const { loginCommand } = await import('./commands/login.js');
     await loginCommand(options);

package/dist/utils/agent-api-client.js

@@ -5,6 +5,7 @@ import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
 import { AGENT_TOOL_OPERATION_PROTOCOL, AGENT_TOOL_OPERATION_HEADERS, AGENT_TOOL_OPERATION_CAPABILITIES_PATH, } from '@playcraft/common/agent-tools';
 import { beginToolOperation } from './tool-operation-journal.js';
+import { AccountActivationError, parseErrorPayload, pendingAccountActivationError, } from '../auth/account-activation.js';
 /**
  * 判断 token 是否为用户 PAT（Personal Access Token）。
  * PAT 以 "playcraft_pat_" 开头；沙箱 JWT 为三段式 base64。
@@ -86,6 +87,14 @@ export class AgentApiClient {
                 signal: AbortSignal.timeout(30_000),
             });
             if (!capabilityResponse.ok) {
+                if (capabilityResponse.status === 403) {
+                    const pending = pendingAccountActivationError(403, parseErrorPayload(await capabilityResponse.clone().text().catch(() => '')));
+                    if (pending) {
+                        if (operation.createdNew && !operation.settledOnly)
+                            operation.reject();
+                        throw pending;
+                    }
+                }
                 await capabilityResponse.body?.cancel();
                 throw new ToolRequestError(`Business tool protocol unavailable (${capabilityResponse.status}); no operation was sent`);
             }
@@ -108,6 +117,14 @@ export class AgentApiClient {
             });
             if (res.headers.get(AGENT_TOOL_OPERATION_HEADERS.protocol) !== AGENT_TOOL_OPERATION_PROTOCOL ||
                 res.headers.get(AGENT_TOOL_OPERATION_HEADERS.requestId) !== operation.requestId) {
+                if (res.status === 403) {
+                    const pending = pendingAccountActivationError(403, parseErrorPayload(await res.clone().text().catch(() => '')));
+                    if (pending) {
+                        if (operation.createdNew && !operation.settledOnly)
+                            operation.reject();
+                        throw pending;
+                    }
+                }
                 await res.body?.cancel();
                 // Possibly an instance that ignores identities: a rerun may only read the receipt.
                 operation.requireReceipt();
@@ -115,6 +132,9 @@ export class AgentApiClient {
             }
             if (!res.ok) {
                 const text = await res.text().catch(() => res.statusText);
+                const pending = pendingAccountActivationError(res.status, parseErrorPayload(text));
+                if (pending)
+                    throw pending;
                 const code = errorCode(text);
                 if (res.status === 409 && code === 'business_operation_in_progress')
                     throw new ToolRequestError(`API 409: ${text}\nTool request ${operation.requestId} is still running. Rerun the ` +
@@ -141,7 +161,7 @@ export class AgentApiClient {
             return result;
         }
         catch (error) {
-            if (error instanceof ToolRequestError)
+            if (error instanceof ToolRequestError || error instanceof AccountActivationError)
                 throw error;
             throw new Error(`${error instanceof Error ? error.message : String(error)}\n${operation.settledOnly
                 ? `Tool request ${operation.requestId}; record: ${operation.file}. Its settled result is not available yet.`
@@ -164,6 +184,9 @@ export class AgentApiClient {
         });
         if (!res.ok) {
             const text = await res.text().catch(() => res.statusText);
+            const pending = pendingAccountActivationError(res.status, parseErrorPayload(text));
+            if (pending)
+                throw pending;
             throw new Error(`API ${res.status}: ${text}`);
         }
         return res.json();

package/dist/utils/playcraft-http-client.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
+import { pendingAccountActivationError } from '../auth/account-activation.js';
 export class PlayCraftApiError extends Error {
     code;
     status;
@@ -95,19 +96,20 @@ export class PlayCraftHttpClient {
                 }
                 if (!response.ok) {
                     const error = payload?.error;
-                    const code = typeof error?.code === 'string' ? error.code : statusCode(response.status);
-                    const message = typeof error?.message === 'string'
+                    const pending = pendingAccountActivationError(response.status, payload);
+                    const code = pending?.code ?? (typeof error?.code === 'string' ? error.code : statusCode(response.status));
+                    const message = pending?.message ?? (typeof error?.message === 'string'
                         ? error.message
                         : typeof payload?.message === 'string'
                             ? payload.message
                             : typeof payload === 'string'
                                 ? payload
-                                : response.statusText || 'PlayCraft request failed';
+                                : response.statusText || 'PlayCraft request failed');
                     throw new PlayCraftApiError({
                         code,
                         message,
                         status: response.status,
-                        details: error?.details ?? payload,
+                        details: pending ? { loginCommand: 'playcraft login --activate' } : error?.details ?? payload,
                         retryable: response.status >= 500,
                     });
                 }

package/dist/utils/tool-operation-journal.js

@@ -56,8 +56,10 @@ export function beginToolOperation(path, serializedBody, recoverId, options = {}
         createdAt: now,
         updatedAt: now,
     };
+    let createdNew = false;
     try {
         writeFileSync(file, JSON.stringify(entry), { flag: 'wx', mode: 0o600 });
+        createdNew = true;
     }
     catch (error) {
         if (error.code !== 'EEXIST')
@@ -81,6 +83,8 @@ export function beginToolOperation(path, serializedBody, recoverId, options = {}
         update({ holder });
     return {
         requestId,
+        /** This call created the identity; a refusal cannot settle an older unknown operation. */
+        createdNew,
         /** An explicit recovery, or a server that did not acknowledge the identity, reads only. */
         settledOnly: recoverId !== undefined || unconfirmed?.receiptOnly === true,
         file,

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

@@ -7,6 +7,7 @@ import { writePlaycraftCodexConfig } from './config-toml.js';
 import { createJsonRpcStdioClient } from './jsonrpc-stdio.js';
 import { projectNativeThread } from '@playcraft/common/cloud-workspace/runtime';
 import { collectedEvent, NativePreparationError } from './native-adapter.js';
+import { exportTranscript } from './transcripts.js';
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -68,6 +69,18 @@ export function createCodexAppServerAdapter(options) {
         for (const listener of collected)
             listener(event);
     }
+    function transcriptHome() {
+        if (!launcherSocket)
+            return { homeDir };
+        return {
+            homeDir,
+            launcher: {
+                socketPath: launcherSocket,
+                runtimeEpoch: executionEpoch,
+                cwd: options.config.workspaceMode === 'multi' ? '/home/playcraft-dev' : options.config.workspaceRoot,
+            },
+        };
+    }
     async function ensureStarted() {
         if (readyFlag && rpc)
             return;
@@ -272,6 +285,9 @@ export function createCodexAppServerAdapter(options) {
                 return undefined;
             }
         },
+        exportThread(input) {
+            return exportTranscript(transcriptHome(), input.threadId);
+        },
         async captureNativeCheckpoint(input) {
             const thread = threads.get(input.threadId);
             if (!thread || thread.sessionId !== input.sessionId)

package/dist/workspace-runtime/codex/transcripts.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { startLauncherProcess } from './launcher-client.js';
+export const TRANSCRIPT_MAX_BYTES = 64 * 1024 * 1024;
+const THREAD_ID = /^[A-Za-z0-9_-]{1,128}$/;
+const TRANSCRIPT_PATH = /^sessions\/\d{4}\/\d{2}\/\d{2}\/rollout-[A-Za-z0-9_.-]{1,200}\.jsonl$/;
+const COMMAND_TIMEOUT_MS = 60_000;
+/**
+ * Reads the transcript Codex keeps for one thread. Codex appends to it while a turn runs, so a
+ * trailing partial line is dropped; what is returned always parses line by line.
+ */
+export async function exportTranscript(home, threadId) {
+    if (!THREAD_ID.test(threadId))
+        return undefined;
+    const found = home.launcher
+        ? await exportAsDeveloper(home.homeDir, home.launcher, threadId)
+        : await exportDirect(home.homeDir, threadId);
+    if (!found || !transcriptPathFor(found.path, threadId))
+        return undefined;
+    const end = found.body.lastIndexOf(0x0a);
+    if (end < 0)
+        return undefined;
+    return { path: found.path, body: found.body.subarray(0, end + 1) };
+}
+function transcriptPathFor(path, threadId) {
+    return TRANSCRIPT_PATH.test(path) && path.endsWith(`-${threadId}.jsonl`);
+}
+async function exportDirect(homeDir, threadId) {
+    const suffix = `-${threadId}.jsonl`;
+    for (const year of await names(join(homeDir, 'sessions'))) {
+        for (const month of await names(join(homeDir, 'sessions', year))) {
+            for (const day of await names(join(homeDir, 'sessions', year, month))) {
+                const directory = join('sessions', year, month, day);
+                const match = (await names(join(homeDir, directory))).find((name) => name.endsWith(suffix));
+                if (!match)
+                    continue;
+                const path = `${directory}/${match}`;
+                const absolute = join(homeDir, path);
+                if ((await stat(absolute)).size > TRANSCRIPT_MAX_BYTES)
+                    return undefined;
+                return { path, body: await readFile(absolute) };
+            }
+        }
+    }
+    return undefined;
+}
+async function exportAsDeveloper(homeDir, launcher, threadId) {
+    const limitKib = TRANSCRIPT_MAX_BYTES / 1024;
+    const outcome = await runAsDeveloper(launcher, [
+        `home=${quote(homeDir)}`,
+        `f=$(find "$home/sessions" -mindepth 4 -maxdepth 4 -type f -name ${quote(`rollout-*-${threadId}.jsonl`)} -size -${limitKib}k 2>/dev/null | head -n 1)`,
+        '[ -n "$f" ] || exit 3',
+        'printf \'%s\\n\' "${f#"$home"/}"',
+        'base64 -w 0 "$f"',
+    ].join('; '));
+    if (outcome.code !== 0)
+        return undefined;
+    const text = outcome.stdout.toString('utf8');
+    const newline = text.indexOf('\n');
+    if (newline < 0)
+        return undefined;
+    return { path: text.slice(0, newline), body: Buffer.from(text.slice(newline + 1).trim(), 'base64') };
+}
+async function runAsDeveloper(launcher, command) {
+    const child = await startLauncherProcess({
+        socketPath: launcher.socketPath,
+        processId: `transcript-${randomUUID()}`,
+        runtimeEpoch: launcher.runtimeEpoch,
+        argv: ['/usr/bin/bash', '-c', `{ ${command}; } </dev/null 2>/dev/null`],
+        cwd: launcher.cwd,
+        env: {},
+    });
+    child.stdin?.end();
+    const chunks = [];
+    child.stdout?.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+    const code = await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            void child.stop().catch(() => undefined);
+            resolve(null);
+        }, COMMAND_TIMEOUT_MS);
+        child.onExit((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        });
+    });
+    return { code, stdout: Buffer.concat(chunks) };
+}
+async function names(directory) {
+    return readdir(directory).then((entries) => entries.sort(), () => []);
+}
+function quote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}

package/dist/workspace-runtime/previews/publish.js

@@ -33,6 +33,12 @@ export async function previewWorkspaceRoot(state, operation) {
     if (!operation.workspaceId || !/^[A-Za-z0-9_-]+$/.test(operation.operationId)) {
         throw new PreviewFailure('invalid_preview_publish');
     }
+    if (operation.sessionId !== undefined) {
+        const session = state.journal.getSession(operation.sessionId);
+        if (!session || (state.config.workspaceMode === 'multi' && session.workspaceId !== operation.workspaceId)) {
+            throw new PreviewFailure('session_workspace_mismatch');
+        }
+    }
     return workspaceRoot(state, operation.workspaceId);
 }
 /** Tracks a background publish so tests and shutdown can wait for it. */
@@ -55,10 +61,13 @@ export async function recoverInterruptedPreviews(journal) {
 }
 export async function runPreviewPublish(state, operation, root) {
     const workspaceId = operation.workspaceId;
+    const scope = operation.sessionId === undefined
+        ? {}
+        : { sessionId: operation.sessionId, clientRequestId: operation.clientRequestId };
     const outputDir = join(root, OUTPUT_FOLDER, operation.operationId);
     const output = { log: '' };
     try {
-        await ensureDependencies(state, workspaceId, root);
+        await ensureDependencies(state, workspaceId, root, output);
         await excludeFromGit(root, `/${OUTPUT_FOLDER}/`);
         await excludeFromGit(root, `/${BUILDER_TEMP_FOLDER}/`);
         await buildPreview(state, root, outputDir, operation.operationId, output);
@@ -73,6 +82,7 @@ export async function runPreviewPublish(state, operation, root) {
         const source = await sourceRevision(root);
         const reserved = previewReservationSchema.parse(await postControl(state, '/runtime/internal/preview-reservations', {
             workspaceId,
+            ...scope,
             operationId: operation.operationId,
             contentDigest,
             contentMd5,
@@ -81,6 +91,8 @@ export async function runPreviewPublish(state, operation, root) {
             dirty: source.dirty,
             cliVersion: state.config.cliVersion,
         }));
+        if (reserved.sessionId !== operation.sessionId)
+            throw new PreviewFailure('preview_scope_mismatch');
         if (!reserved.alreadyUploaded) {
             const uploaded = await fetch(reserved.uploadUrl, {
                 method: 'PUT',
@@ -99,11 +111,16 @@ export async function runPreviewPublish(state, operation, root) {
         }
         const published = previewPublishResultSchema.parse(await postControl(state, '/runtime/internal/preview-completions', {
             workspaceId,
+            ...scope,
             operationId: operation.operationId,
             artifactId: reserved.artifactId,
             expectedPublishRevision: reserved.expectedPublishRevision,
             logTail: tail(output.log),
         }));
+        if (published.sessionId !== operation.sessionId || published.previewId !== reserved.previewId ||
+            published.artifactId !== reserved.artifactId) {
+            throw new PreviewFailure('preview_scope_mismatch');
+        }
         if (published.status === 'conflict')
             throw new PreviewFailure('publish_conflict');
         return published;
@@ -113,6 +130,7 @@ export async function runPreviewPublish(state, operation, root) {
         if (code !== 'publish_conflict') {
             await postControl(state, '/runtime/internal/preview-failures', {
                 workspaceId,
+                ...scope,
                 operationId: operation.operationId,
                 error: code,
                 logTail: tail(output.log || (error instanceof Error ? error.message : '')),
@@ -137,11 +155,13 @@ export function previewFailureCode(error) {
  * Codex added since the workspace opened is installed first. A running install is joined rather
  * than started twice; a failed one is retried once here.
  */
-async function ensureDependencies(state, workspaceId, root) {
+async function ensureDependencies(state, workspaceId, root, output) {
     await scheduleDependencyInstall(state, workspaceId, root);
-    const status = readDependencies(state, workspaceId).status;
-    if (status !== 'ready' && status !== 'none')
+    const dependencies = readDependencies(state, workspaceId);
+    if (dependencies.status !== 'ready' && dependencies.status !== 'none') {
+        output.log = [dependencies.error, dependencies.logTail].filter(Boolean).join('\n');
         throw new PreviewFailure('dependencies_not_ready');
+    }
 }
 async function buildPreview(state, root, outputDir, operationId, output) {
     // Tests replace the build; the real one needs a project and the published CLI.

package/dist/workspace-runtime/serve.js

@@ -33,11 +33,15 @@ export async function startWorkspaceRuntime(config, options = {}) {
     try {
         journal = new RuntimeJournal(config.stateDir);
         await journal.load();
+        const previousEpoch = journal.storedRuntimeEpoch();
+        const previousGroup = journal.executionGroup();
+        const previousIdentityMatches = journal.epochsSnapshot().some((epoch) => epoch.runtime_id === config.runtimeId && epoch.generation === config.generation && epoch.runtime_epoch === previousEpoch);
         await recoverInterruptedInstalls(journal);
         await recoverInterruptedPreviews(journal);
         await mkdir(config.workspaceRoot, { recursive: true, mode: 0o700 });
         const state = {
             config: { ...config, protocolMinor: negotiated.protocolMinor },
+            configPath: options.configPath,
             journal,
             acceptedLeaseFence: journal.acceptedLeaseFence(),
             gitAvailable: await probeGitBinary(),
@@ -63,8 +67,28 @@ export async function startWorkspaceRuntime(config, options = {}) {
         try {
             await native?.start?.();
             const group = native?.executionProcess?.();
-            if (group)
-                await journal.noteExecutionGroup(group);
+            if (group) {
+                let previousStopped = false;
+                if (previousGroup.pid && previousGroup.pid !== group.pid) {
+                    try {
+                        process.kill(previousGroup.pid, 0);
+                    }
+                    catch (error) {
+                        previousStopped = error.code === 'ESRCH';
+                    }
+                }
+                // The supervisor advances the trusted config epoch only after stopping the old
+                // native group. Reconfirm its recorded PID before publishing that replacement.
+                if (previousIdentityMatches && previousEpoch !== undefined && config.runtimeEpoch > previousEpoch && previousStopped) {
+                    await journal.writeExecutionEpoch({
+                        runtimeEpoch: state.runtimeEpoch, ...group, previousPid: previousGroup.pid, stopConfirmed: true,
+                    });
+                    await journal.replaceSessions(journal.listSessions().map((session) => ({ ...session, recoverability: 'history_only' })));
+                }
+                else {
+                    await journal.noteExecutionGroup(group);
+                }
+            }
         }
         catch (error) {
             const code = error instanceof Error ? error.message : '';