@playcraft/cli 0.1.0 → 0.1.1

package/README.md

@@ -192,13 +192,25 @@ echo '{"token":"<sandbox-jwt>","apiUrl":"https://..."}' > .playcraft.json
 
 业务工具写请求要求服务支持持久操作协议。命令行先保存请求编号、路径和输入摘要到 `~/.playcraft/tool-requests/`，再发送请求；记录不包含凭证或请求正文。可用绝对路径环境变量 `PLAYCRAFT_TOOL_REQUEST_DIR` 指定可持久保留的目录。
 
-如果请求超时或连接中断，错误会显示请求编号。使用相同参数重跑命令，并设置该编号，只查询原操作的确定结果：
+原样重跑同一条命令（路径与参数都相同）时，命令行按上一次的结果决定是否沿用原请求编号：
+
+| 上一次的结果                                                         | 原样重跑时                                               |
+| -------------------------------------------------------------------- | -------------------------------------------------------- |
+| 成功（2xx）                                                          | 新操作                                                   |
+| 请求被拒绝（4xx，下列 409 除外）：请求没有被执行                     | 新操作                                                   |
+| 服务端错误（5xx）、超时或连接中断：结果未知                          | 沿用原编号，不会另起一次操作；服务端按下文的恢复方式处理 |
+| 409 `business_operation_in_progress`：原操作仍在执行                 | 沿用原编号，稍后重跑取得结果                             |
+| 409 `business_operation_requires_reconciliation`：结果未知，需要核对 | 沿用原编号，不会再执行                                   |
+
+沿用原编号时，服务端按原操作的状态处理：已完成则返回原结果；仍在执行则返回 409 `business_operation_in_progress`；没有拿到结果就结束时，按该工具声明的恢复方式决定，可以安全重做的工具（生图、构建、发布到 COS 等）用原编号再执行一次，其余返回 409 `business_operation_requires_reconciliation`。原调用的执行租约有效期间（执行中每 20 秒续期，60 秒未续即过期），同一编号不会被再次执行；续期因服务或数据库故障中断超过 60 秒时，重做可能与仍在运行的原调用重叠。
+
+需要核对的操作，只有确认它没有生效后，才可设置 `PLAYCRAFT_TOOL_NEW_REQUEST=1` 强制发起新操作；不要删除记录来绕过。也可以显式指定编号，只查询原操作的确定结果（不会重新执行；声明了恢复方式的工具若上次报错，返回那次的错误）。只查询时即使是可以安全重做的工具，没有结果也返回需要核对；去掉 `PLAYCRAFT_TOOL_REQUEST_ID` 原样重跑即可续做：
 
 ```bash
 PLAYCRAFT_TOOL_REQUEST_ID=<错误中显示的请求编号> playcraft tools build-project --project-id <原项目编号>
 ```
 
-恢复不会重新构建。操作尚未完成、结果未知或没有回执时会明确失败；不要换编号或删除记录来强行重试。只有错误明确说明能力检查失败且尚未发送操作时，才可在服务恢复后发起新的正常命令。服务不兼容时命令会在发送业务请求前停止；沙箱命令行与 Business 须排空旧调用后同步升级。
+能力检查失败时命令会明确说明尚未发送操作。服务不兼容时命令会在发送业务请求前停止；沙箱命令行与 Business 须排空旧调用后同步升级。
 
 ### 构建相关
 

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

@@ -72,7 +72,13 @@ export class AgentApiClient {
         const serializedBody = JSON.stringify(body);
         if (serializedBody === undefined)
             throw new Error('Tool request body is required');
-        const operation = beginToolOperation(url.pathname, serializedBody, options?.requestId ?? process.env.PLAYCRAFT_TOOL_REQUEST_ID);
+        const recoverId = options?.requestId ?? process.env.PLAYCRAFT_TOOL_REQUEST_ID;
+        const operation = beginToolOperation(url.pathname, serializedBody, recoverId, {
+            newRequest: options?.newRequest ?? process.env.PLAYCRAFT_TOOL_NEW_REQUEST === '1',
+        });
+        const unknownOutcome = `Tool request ${operation.requestId}: the outcome is unknown. Rerun the same command to ` +
+            `continue this request: it returns the result if the request finished, or finishes it if ` +
+            `the tool can be safely redone; it never starts a second operation. Record: ${operation.file}.`;
         try {
             const capabilityResponse = await fetch(this.toolsRequestUrl(AGENT_TOOL_OPERATION_CAPABILITIES_PATH), {
                 headers: this.authHeaders(),
@@ -81,12 +87,12 @@ export class AgentApiClient {
             });
             if (!capabilityResponse.ok) {
                 await capabilityResponse.body?.cancel();
-                throw new Error(`Business tool protocol unavailable (${capabilityResponse.status}); no operation was sent`);
+                throw new ToolRequestError(`Business tool protocol unavailable (${capabilityResponse.status}); no operation was sent`);
             }
             const capabilities = (await capabilityResponse.json());
             if (capabilities.protocol !== AGENT_TOOL_OPERATION_PROTOCOL ||
                 capabilities.settledOnly !== true)
-                throw new Error('Business tool protocol is incompatible; no operation was sent');
+                throw new ToolRequestError('Business tool protocol is incompatible; no operation was sent');
             const res = await fetch(url, {
                 method: 'POST',
                 redirect: 'error',
@@ -103,10 +109,31 @@ 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) {
                 await res.body?.cancel();
+                // Possibly an instance that ignores identities: a rerun may only read the receipt.
+                operation.requireReceipt();
                 throw new Error('Business did not acknowledge a durable receipt; outcome remains unconfirmed');
             }
             if (!res.ok) {
                 const text = await res.text().catch(() => res.statusText);
+                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 ` +
+                        'same command later to get its result.');
+                if (res.status === 409 && code === 'business_operation_requires_reconciliation')
+                    throw new ToolRequestError(recoverId !== undefined
+                        ? // A receipt query never runs the request, even for a tool that can be safely redone.
+                            `API 409: ${text}\nTool request ${operation.requestId} has no settled result yet. ` +
+                                'Rerun the same command without PLAYCRAFT_TOOL_REQUEST_ID: a tool that can be ' +
+                                'safely redone continues this request; any other tool then needs reconciliation.'
+                        : `API 409: ${text}\nTool request ${operation.requestId} needs reconciliation: its ` +
+                            'outcome is unknown, and rerunning the same command will not run it again. Only ' +
+                            'after confirming it had no effect, rerun with PLAYCRAFT_TOOL_NEW_REQUEST=1 to ' +
+                            'start a new operation.');
+                if (res.status >= 400 && res.status < 500) {
+                    // The request itself was refused and not carried out: a rerun is a new operation.
+                    operation.reject();
+                    throw new ToolRequestError(`API ${res.status}: ${text}`);
+                }
                 throw new Error(`API ${res.status}: ${text}`);
             }
             const result = (await res.json());
@@ -114,10 +141,14 @@ export class AgentApiClient {
             return result;
         }
         catch (error) {
-            throw new Error(`${error instanceof Error ? error.message : String(error)}\n` +
-                `Tool request ${operation.requestId}; record: ${operation.file}. ` +
-                `To query its settled result, rerun the same command with PLAYCRAFT_TOOL_REQUEST_ID=${operation.requestId}. ` +
-                'This recovery does not start another operation.');
+            if (error instanceof ToolRequestError)
+                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.`
+                : unknownOutcome}`);
+        }
+        finally {
+            operation.release();
         }
     }
     async get(path, params) {
@@ -160,3 +191,15 @@ export class AgentApiClient {
         return { apiUrl: '', token: '' };
     }
 }
+/** A failure whose meaning is settled; no recovery hint applies. */
+class ToolRequestError extends Error {
+}
+function errorCode(text) {
+    try {
+        const message = JSON.parse(text).message;
+        return typeof message === 'string' ? message : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -1,31 +1,61 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join } from 'node:path';
 import { isAgentToolRequestId } from '@playcraft/common/agent-tools';
+/** Operations this process is sending now; never continued by another call of this process. */
+const inFlight = new Set();
+/** Linux start time of a process, so a reused pid is not taken for the process that held it. */
+function startOf(pid) {
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
+        return stat.slice(stat.lastIndexOf(')') + 2).split(' ')[19] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function holderAlive(holder) {
+    if (!holder || holder.pid === process.pid)
+        return false;
+    try {
+        process.kill(holder.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== 'EPERM')
+            return false;
+    }
+    return holder.start === null || startOf(holder.pid) === holder.start;
+}
 /** Persist an identity before sending. Store neither credentials nor request/response bodies. */
-export function beginToolOperation(path, serializedBody, recoverId) {
-    const identifier = recoverId ?? randomUUID();
-    if (!isAgentToolRequestId(identifier))
-        throw new Error('Invalid PLAYCRAFT_TOOL_REQUEST_ID');
-    const requestId = identifier.toLowerCase();
+export function beginToolOperation(path, serializedBody, recoverId, options = {}) {
     const directory = process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests');
     if (!isAbsolute(directory))
         throw new Error('PLAYCRAFT_TOOL_REQUEST_DIR must be an absolute path');
     mkdirSync(directory, { recursive: true, mode: 0o700 });
-    const file = join(directory, `${requestId}.json`);
     const inputHash = createHash('sha256').update(serializedBody).digest('hex');
+    // Rerunning the same command while its outcome is unknown continues that operation: the server
+    // answers the same identity with its receipt instead of running it again.
+    const unconfirmed = recoverId === undefined && !options.newRequest
+        ? findUnconfirmed(directory, path, inputHash)
+        : undefined;
+    const identifier = recoverId ?? unconfirmed?.requestId ?? randomUUID();
+    if (!isAgentToolRequestId(identifier))
+        throw new Error('Invalid PLAYCRAFT_TOOL_REQUEST_ID');
+    const requestId = identifier.toLowerCase();
+    const file = join(directory, `${requestId}.json`);
     const now = new Date().toISOString();
+    const holder = { pid: process.pid, start: startOf(process.pid) };
     const entry = {
         version: 1,
         requestId,
         path,
         inputHash,
         state: 'unconfirmed',
+        holder,
         createdAt: now,
         updatedAt: now,
     };
-    let settledOnly = recoverId !== undefined;
     try {
         writeFileSync(file, JSON.stringify(entry), { flag: 'wx', mode: 0o600 });
     }
@@ -38,17 +68,53 @@ export function beginToolOperation(path, serializedBody, recoverId) {
             previous.path !== path ||
             previous.inputHash !== inputHash)
             throw new Error(`Tool request ${requestId} conflicts with its durable local record`);
-        settledOnly = true;
     }
+    const update = (change) => {
+        const current = JSON.parse(readFileSync(file, 'utf8'));
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, JSON.stringify({ ...current, ...change, updatedAt: new Date().toISOString() }), { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, file);
+    };
+    // Only the sender holds an operation; a concurrent run of the same command gets its own.
+    inFlight.add(requestId);
+    if (unconfirmed || recoverId !== undefined)
+        update({ holder });
     return {
         requestId,
-        settledOnly,
+        /** An explicit recovery, or a server that did not acknowledge the identity, reads only. */
+        settledOnly: recoverId !== undefined || unconfirmed?.receiptOnly === true,
         file,
-        complete() {
-            const current = JSON.parse(readFileSync(file, 'utf8'));
-            const temporary = `${file}.${randomUUID()}.tmp`;
-            writeFileSync(temporary, JSON.stringify({ ...current, state: 'completed', updatedAt: new Date().toISOString() }), { flag: 'wx', mode: 0o600 });
-            renameSync(temporary, file);
-        },
+        complete: () => update({ state: 'completed' }),
+        /** A definite refusal: the request was not carried out, so a rerun is a new operation. */
+        reject: () => update({ state: 'rejected' }),
+        /** The outcome stays unknown and a rerun may only read the receipt. */
+        requireReceipt: () => update({ receiptOnly: true }),
+        /** This call is done with the operation; a later run of the command may continue it. */
+        release: () => inFlight.delete(requestId),
     };
 }
+function findUnconfirmed(directory, path, inputHash) {
+    let latest;
+    for (const name of readdirSync(directory)) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const entry = JSON.parse(readFileSync(join(directory, name), 'utf8'));
+            if (entry.version === 1 &&
+                entry.state === 'unconfirmed' &&
+                entry.path === path &&
+                entry.inputHash === inputHash &&
+                isAgentToolRequestId(entry.requestId) &&
+                (!latest || entry.updatedAt > latest.updatedAt) &&
+                // Still being sent, here or by another live process: that run is not interrupted.
+                // Checked last, so only this command's candidates cost a process probe.
+                !inFlight.has(entry.requestId) &&
+                !holderAlive(entry.holder))
+                latest = entry;
+        }
+        catch {
+            // A torn or foreign file is not an operation of this command.
+        }
+    }
+    return latest;
+}

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

@@ -1,8 +1,11 @@
 import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { startLauncherProcess } from './launcher-client.js';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { writePlaycraftCodexConfig } from './config-toml.js';
 import { createJsonRpcStdioClient } from './jsonrpc-stdio.js';
+import { projectNativeThread } from '@playcraft/common/cloud-workspace/runtime';
 import { collectedEvent } from './native-adapter.js';
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
@@ -45,7 +48,10 @@ async function readToken(options) {
     throw new Error('model_proxy_token_missing');
 }
 export function createCodexAppServerAdapter(options) {
-    const homeDir = options.homeDir || process.env.PLAYCRAFT_CODEX_HOME || join(options.config.stateDir, 'codex-home');
+    const launcherSocket = options.launcherSocket || process.env.PLAYCRAFT_LAUNCHER_SOCKET;
+    const homeDir = options.homeDir || process.env.PLAYCRAFT_CODEX_HOME ||
+        (launcherSocket ? '/var/lib/playcraft/codex' : join(options.config.stateDir, 'codex-home'));
+    let executionEpoch = options.config.runtimeEpoch;
     const model = options.model || process.env.PLAYCRAFT_CODEX_MODEL || 'gpt-4o';
     const turnTimeoutMs = options.turnTimeoutMs ?? Number(process.env.PLAYCRAFT_CODEX_TURN_TIMEOUT_MS || 120_000);
     const threads = new Map();
@@ -70,25 +76,50 @@ export function createCodexAppServerAdapter(options) {
     }
     async function start() {
         const token = await readToken(options);
-        await writePlaycraftCodexConfig({
-            homeDir,
-            modelProxyUrl: options.config.modelProxyUrl,
-            model,
-        });
-        const bin = options.command || process.env.PLAYCRAFT_CODEX_BIN || 'codex';
+        const bin = options.command || process.env.PLAYCRAFT_CODEX_BIN || (launcherSocket ? '/usr/local/bin/codex' : 'codex');
         const { command, prefix } = spawnCommand(bin);
         const args = [...prefix, ...(options.args ?? ['app-server'])];
-        child = spawn(command, args, {
-            cwd: options.config.workspaceRoot,
-            env: {
-                ...process.env,
-                ...options.env,
-                CODEX_HOME: homeDir,
-                OPENAI_API_KEY: token,
-                PLAYCRAFT_SKIP_UPDATE_CHECK: '1',
-            },
-            stdio: ['pipe', 'pipe', 'pipe'],
-        });
+        if (launcherSocket) {
+            // Configuration travels as non-secret overrides: control cannot write dev's home.
+            for (const [key, value] of Object.entries({
+                model,
+                model_provider: 'playcraft',
+                approval_policy: 'never',
+                sandbox_mode: 'danger-full-access',
+                'model_providers.playcraft.name': 'PlayCraft Model Proxy',
+                'model_providers.playcraft.base_url': options.config.modelProxyUrl.replace(/\/+$/, ''),
+                'model_providers.playcraft.env_key': 'OPENAI_API_KEY',
+                'model_providers.playcraft.wire_api': 'responses',
+                'model_providers.playcraft.requires_openai_auth': false,
+            }))
+                args.push('-c', `${key}=${JSON.stringify(value)}`);
+            child = await startLauncherProcess({
+                socketPath: launcherSocket,
+                processId: `codex-${randomUUID()}`,
+                runtimeEpoch: executionEpoch,
+                argv: [command, ...args],
+                cwd: options.config.workspaceRoot,
+                env: { CODEX_HOME: homeDir, OPENAI_API_KEY: token },
+            });
+        }
+        else {
+            await writePlaycraftCodexConfig({ homeDir, modelProxyUrl: options.config.modelProxyUrl, model });
+            const local = spawn(command, args, {
+                cwd: options.config.workspaceRoot,
+                env: { ...process.env, ...options.env, CODEX_HOME: homeDir, OPENAI_API_KEY: token, PLAYCRAFT_SKIP_UPDATE_CHECK: '1' },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            await new Promise((resolve, reject) => { local.once('spawn', resolve); local.once('error', reject); });
+            child = {
+                pid: local.pid, stdin: local.stdin, stdout: local.stdout, stderr: local.stderr,
+                onExit(listener) { local.once('exit', listener); },
+                async stop() {
+                    if (local.exitCode === null && local.signalCode === null)
+                        local.kill('SIGTERM');
+                    await waitForChildExit(local);
+                },
+            };
+        }
         child.stderr?.on('data', (chunk) => {
             process.stderr.write(chunk);
         });
@@ -118,12 +149,12 @@ export function createCodexAppServerAdapter(options) {
             superseded: false,
         };
         live = current;
-        child.once('exit', () => {
+        child.onExit(() => {
+            void current.rpc.close();
             if (live === current) {
                 readyFlag = false;
-                live = undefined;
+                // Retain the old handle until its entire execution group is confirmed stopped.
                 rpc = undefined;
-                child = undefined;
                 emitCollected(collectedEvent('process_exit', 'process.exited', { pid: current.pid }));
             }
             if (!current.superseded && !closed) {
@@ -131,15 +162,23 @@ export function createCodexAppServerAdapter(options) {
                     listener({ pid: current.pid });
             }
         });
-        await rpc.request('initialize', {
-            clientInfo: {
-                name: 'playcraft_workspace_runtime',
-                title: 'PlayCraft Workspace Runtime',
-                version: options.config.cliVersion,
-            },
-        });
-        rpc.notify('initialized', {});
-        readyFlag = true;
+        try {
+            await rpc.request('initialize', {
+                clientInfo: {
+                    name: 'playcraft_workspace_runtime',
+                    title: 'PlayCraft Workspace Runtime',
+                    version: options.config.cliVersion,
+                },
+            });
+            rpc.notify('initialized', {});
+            readyFlag = true;
+        }
+        catch (error) {
+            current.superseded = true;
+            await current.rpc.close();
+            await current.child.stop();
+            throw error;
+        }
     }
     return {
         name: 'codex-app-server',
@@ -167,12 +206,10 @@ export function createCodexAppServerAdapter(options) {
             startPromise = undefined;
             threads.clear();
             approvals.clear();
-            if (previous && previous.child.exitCode === null && previous.child.signalCode === null) {
-                previous.child.kill('SIGTERM');
-            }
             await previous?.rpc.close().catch(() => undefined);
             if (previous)
-                await waitForChildExit(previous.child);
+                await previous.child.stop();
+            executionEpoch += 1;
             if (closed)
                 throw new Error('codex_not_started');
             try {
@@ -204,6 +241,22 @@ export function createCodexAppServerAdapter(options) {
                 return false;
             }
         },
+        async readThread(input) {
+            try {
+                await ensureStarted();
+                if (!rpc)
+                    return undefined;
+                const result = await rpc.request('thread/read', {
+                    threadId: input.threadId,
+                    includeTurns: true,
+                }, 30_000);
+                const projected = projectNativeThread(input.threadId, result.thread ?? result);
+                return projected;
+            }
+            catch {
+                return undefined;
+            }
+        },
         async captureNativeCheckpoint(input) {
             const thread = threads.get(input.threadId);
             if (!thread || thread.sessionId !== input.sessionId)
@@ -299,20 +352,8 @@ export function createCodexAppServerAdapter(options) {
             const current = child;
             await rpc?.close().catch(() => undefined);
             rpc = undefined;
-            if (current && current.exitCode === null && !current.killed) {
-                current.kill('SIGTERM');
-                await new Promise((resolve) => {
-                    const timer = setTimeout(() => {
-                        if (current.exitCode === null)
-                            current.kill('SIGKILL');
-                        resolve();
-                    }, 3000);
-                    current.once('exit', () => {
-                        clearTimeout(timer);
-                        resolve();
-                    });
-                });
-            }
+            if (current)
+                await current.stop();
             child = undefined;
             live = undefined;
         },

package/dist/workspace-runtime/codex/launcher-client.js

@@ -0,0 +1,155 @@
+import { EventEmitter } from 'node:events';
+import { createConnection } from 'node:net';
+import { PassThrough, Writable } from 'node:stream';
+import { setTimeout as delay } from 'node:timers/promises';
+function request(socketPath, message) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(socketPath);
+        let buffer = '';
+        socket.setEncoding('utf8');
+        const timer = setTimeout(() => socket.destroy(new Error('launcher_request_timeout')), 5000);
+        socket.on('connect', () => socket.write(`${JSON.stringify(message)}\n`));
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            if (buffer.length > 64 * 1024)
+                return socket.destroy(new Error('launcher_reply_too_large'));
+            if (!buffer.includes('\n'))
+                return;
+            try {
+                const reply = JSON.parse(buffer.split('\n')[0]);
+                if (!reply.ok)
+                    throw new Error(reply.error || 'launcher_request_failed');
+                resolve(reply);
+            }
+            catch (error) {
+                reject(error);
+            }
+            socket.destroy();
+        });
+        socket.on('error', reject);
+        socket.on('close', () => {
+            clearTimeout(timer);
+            reject(new Error('launcher_connection_closed'));
+        });
+    });
+}
+export async function startLauncherProcess(input) {
+    const socket = createConnection(input.socketPath);
+    const stdout = new PassThrough();
+    const stderr = new PassThrough();
+    const events = new EventEmitter();
+    let exited = false;
+    let buffer = '';
+    let identity;
+    let stopPromise;
+    const stdin = new Writable({
+        write(chunk, _encoding, callback) {
+            socket.write(`${JSON.stringify({ action: 'stdin', data: chunk.toString('base64') })}\n`, callback);
+        },
+        final(callback) {
+            socket.write(`${JSON.stringify({ action: 'stdin-end' })}\n`, callback);
+        },
+    });
+    // Transport loss is reported through onExit, never an unhandled stream error.
+    stdin.on('error', () => socket.destroy());
+    function exit() {
+        if (exited)
+            return;
+        exited = true;
+        events.emit('exit');
+    }
+    socket.setEncoding('utf8');
+    const pid = await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => socket.destroy(new Error('launcher_start_timeout')), 5000);
+        let started = false;
+        socket.on('connect', () => {
+            const { socketPath: _socketPath, ...payload } = input;
+            socket.write(`${JSON.stringify({ ...payload, action: 'start-stdio' })}\n`);
+        });
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            if (buffer.length > 8 * 1024 * 1024)
+                return socket.destroy(new Error('launcher_reply_too_large'));
+            let newline;
+            while ((newline = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, newline);
+                buffer = buffer.slice(newline + 1);
+                try {
+                    const frame = JSON.parse(line);
+                    if (!started) {
+                        if (!frame.ok || !frame.pid || !frame.instanceId)
+                            throw new Error(frame.error || 'launcher_start_failed');
+                        identity = {
+                            processId: input.processId,
+                            runtimeEpoch: input.runtimeEpoch,
+                            instanceId: frame.instanceId,
+                        };
+                        started = true;
+                        clearTimeout(timer);
+                        resolve(frame.pid);
+                    }
+                    else if (frame.channel === 'stdout' || frame.channel === 'stderr') {
+                        if (typeof frame.data !== 'string')
+                            throw new Error('launcher_invalid_frame');
+                        const stream = frame.channel === 'stdout' ? stdout : stderr;
+                        if (!stream.write(Buffer.from(frame.data, 'base64'))) {
+                            socket.pause();
+                            stream.once('drain', () => socket.resume());
+                        }
+                    }
+                    else if (frame.event === 'exit')
+                        exit();
+                    else
+                        throw new Error('launcher_invalid_frame');
+                }
+                catch (error) {
+                    socket.destroy(error instanceof Error ? error : new Error('launcher_invalid_frame'));
+                    return;
+                }
+            }
+        });
+        socket.on('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        socket.on('close', () => {
+            clearTimeout(timer);
+            reject(new Error('launcher_connection_closed'));
+            stdout.end();
+            stderr.end();
+            stdin.destroy();
+            exit();
+        });
+    });
+    return {
+        pid,
+        stdin,
+        stdout,
+        stderr,
+        onExit(listener) {
+            if (exited)
+                queueMicrotask(listener);
+            else
+                events.once('exit', listener);
+        },
+        stop() {
+            stopPromise ??= (async () => {
+                // A new launcher's empty registry cannot confirm an old group's exit.
+                for (const signal of ['SIGTERM', 'SIGKILL']) {
+                    await request(input.socketPath, { ...identity, action: 'stop', signal });
+                    const deadline = Date.now() + 3000;
+                    while (Date.now() < deadline) {
+                        const status = await request(input.socketPath, { ...identity, action: 'status' });
+                        if (status.running === false) {
+                            socket.destroy();
+                            return;
+                        }
+                        await delay(50);
+                    }
+                }
+                throw new Error('codex_group_stop_unconfirmed');
+            })();
+            return stopPromise;
+        },
+    };
+}