@xiaohhhh1/canvas-agent 0.4.74 → 0.4.76

package/dist/agent/codex-client.d.ts

@@ -5,10 +5,40 @@ export type CodexModelSettings = {
     model?: string;
     reasoningEffort?: string;
 };
+export type CodexAppPhase = "spawn" | "initialize" | "idle" | "thread/start" | "turn/start" | "turn/running" | "terminating" | "exited";
+export type CodexAppProcessFailureDetails = {
+    phase: CodexAppPhase | string;
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stderr: string;
+    cause?: unknown;
+    source?: "spawn" | "exit" | "stdin" | "timeout";
+    diagnosticId?: string;
+    cleanupConfirmed?: boolean;
+    cleanupBarrier?: Promise<void>;
+};
+/** 可安全向网页和本机状态暴露的 app-server 进程故障。 */
+export declare class CodexAppProcessError extends Error {
+    readonly phase: string;
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly stderr: string;
+    readonly source: "spawn" | "exit" | "stdin" | "timeout";
+    readonly diagnosticId: string;
+    cleanupConfirmed: boolean;
+    cleanupBarrier?: Promise<void>;
+    constructor(details: CodexAppProcessFailureDetails);
+}
+export declare function isCodexAppProcessError(error: unknown): error is CodexAppProcessError;
+/** 去掉凭证、图片、用户目录及控制符，只保留有界的 stderr 尾部。 */
+export declare function sanitizeCodexDiagnosticText(value: unknown, maxChars?: number): string;
+/** Append stderr only after redaction so the in-memory tail never holds raw payloads. */
+export declare function appendCodexDiagnosticTail(current: string, chunk: unknown, maxChars?: number): string;
 /** 封装 Codex app-server 的 JSON-RPC 通信与事件转换。 */
 export declare class CodexAppClient {
     private child;
     private emit;
+    private onExit;
     private nextId;
     private buffer;
     private currentThreadId;
@@ -22,10 +52,20 @@ export declare class CodexAppClient {
     private pendingDeltas;
     private plansByTurn;
     private approvalRequests;
+    private phase;
+    private stderrTail;
+    private logicalClosed;
+    private osExitSeen;
+    private failDelivered;
+    private terminationExpected;
+    private exitDelivered;
+    private terminalError;
+    private exitPromise;
+    private resolveExit;
     /** 保存 app-server 子进程和事件出口。 */
     private constructor();
     /** 启动并初始化 Codex app-server。 */
-    static start(emit: AgentEmit, onExit: () => void): Promise<CodexAppClient>;
+    static start(emit: AgentEmit, onExit: () => void, initializeTimeoutMs?: number): Promise<CodexAppClient>;
     /** 创建新的 Codex 线程。 */
     startThread(cwd?: string, permissionMode?: AgentPermissionMode, modelSettings?: CodexModelSettings): Promise<import("./codex-protocol.js").CodexThread>;
     /** 恢复已有 Codex 线程。 */
@@ -51,7 +91,12 @@ export declare class CodexAppClient {
     /** 中断当前正在运行的 Codex turn。 */
     interruptCurrentTurn(): Promise<boolean>;
     /** 终止失去响应的 app-server，让后续队列可以在新进程继续。 */
-    terminate(message?: string): Promise<void>;
+    terminate(message?: string, diagnostics?: {
+        persistDiagnostic?: boolean;
+        phase?: CodexAppPhase | string;
+    }): Promise<boolean>;
+    /** 仅供 worker 隔离等待真实 OS exit；不包含 stderr 或其它诊断内容。 */
+    waitForExit(): Promise<void>;
     /** 回复网页端已经确认的 Codex 权限请求。 */
     resolveApproval(requestId: string, decision: string): boolean;
     /** 发送 JSON-RPC 请求并保存待处理 Promise。 */
@@ -83,6 +128,12 @@ export declare class CodexAppClient {
     private resolve;
     /** 拒绝指定 JSON-RPC 请求。 */
     private reject;
+    /** 只在内存保存 stderr 尾部；原文绝不直接发往网页或写入日志。 */
+    private recordStderr;
+    /** error/exit/stdin 统一且只执行一次的进程收尾。 */
+    private handleProcessFailure;
+    private noteOsExit;
+    private deliverExit;
     /** 拒绝进程退出时仍未完成的请求与 turn。 */
     private failAll;
 }

package/dist/agent/codex-client.js

@@ -1,8 +1,10 @@
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { VERSION } from "../config.js";
+import { CONFIG_DIR, VERSION } from "../config.js";
 import { logger } from "../utils/logger.js";
 import { field } from "../utils/value.js";
 const canvasAgentMcp = canvasAgentMcpCommand();
@@ -10,10 +12,89 @@ const require = createRequire(import.meta.url);
 const STREAM_UPDATE_INTERVAL_MS = 40;
 const TURN_RECONCILE_INTERVAL_MS = 5_000;
 const APP_SERVER_INITIALIZE_TIMEOUT_MS = 30_000;
+const CODEX_STDERR_TAIL_CHARS = 32 * 1024;
+const CODEX_VISIBLE_DIAGNOSTIC_CHARS = 2_048;
+const CODEX_DIAGNOSTIC_FILE_BYTES = 512 * 1024;
+const CODEX_DIAGNOSTIC_ENTRY_BYTES = 12 * 1024;
+let diagnosticWriteQueue = Promise.resolve();
+/** 可安全向网页和本机状态暴露的 app-server 进程故障。 */
+export class CodexAppProcessError extends Error {
+    phase;
+    code;
+    signal;
+    stderr;
+    source;
+    diagnosticId;
+    cleanupConfirmed;
+    cleanupBarrier;
+    constructor(details) {
+        const stderr = sanitizeCodexDiagnosticText(details.stderr, 8_192);
+        const source = details.source || "exit";
+        const diagnosticId = details.diagnosticId || randomUUID();
+        const summary = [
+            `Codex app-server process failure (phase=${details.phase}`,
+            `code=${details.code ?? "none"}`,
+            `signal=${details.signal ?? "none"}`,
+            `diagnosticId=${diagnosticId})`,
+        ].join(", ");
+        super(summary);
+        this.name = "CodexAppProcessError";
+        this.phase = details.phase;
+        this.code = details.code;
+        this.signal = details.signal;
+        this.stderr = stderr;
+        this.source = source;
+        this.diagnosticId = diagnosticId;
+        this.cleanupConfirmed = details.cleanupConfirmed !== false;
+        this.cleanupBarrier = details.cleanupBarrier;
+        if (details.cause !== undefined)
+            this.cause = details.cause;
+    }
+}
+export function isCodexAppProcessError(error) {
+    return error instanceof CodexAppProcessError || Boolean(error && typeof error === "object" && error.name === "CodexAppProcessError");
+}
+/** 去掉凭证、图片、用户目录及控制符，只保留有界的 stderr 尾部。 */
+export function sanitizeCodexDiagnosticText(value, maxChars = CODEX_VISIBLE_DIAGNOSTIC_CHARS) {
+    const budget = Math.max(0, Math.floor(maxChars));
+    if (!budget)
+        return "";
+    let text = String(value || "")
+        .replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "")
+        .replace(/data:image\/[a-z0-9.+-]+;base64,[a-z0-9+/=_-]+/gi, "data:image/[REDACTED]")
+        // `trim()` below can remove the only space when "Bearer " and its
+        // value arrive in separate stderr chunks, so also redact the joined
+        // continuation form before it can enter the retained tail.
+        .replace(/\bBearer\s*[^\s"',;]+/gi, "Bearer [REDACTED]")
+        .replace(/\bsk-[a-z0-9_-]+/gi, "sk-[REDACTED]")
+        // stderr can arrive in arbitrary chunks. If the previous chunk ended
+        // inside a redacted value, discard every token-like continuation first
+        // so later assignment rules stay idempotent.
+        .replace(/["']?\[REDACTED(?:_LONG_TOKEN)?\]["']?[a-z0-9._~+/_=-]+/gi, "[REDACTED]")
+        .replace(/(["']?)([a-z][a-z0-9_]*(?:_token|_secret|_password|_api_key))\1(\s*[:=]\s*)(?:\[REDACTED(?:_LONG_TOKEN)?\]|"[^"]*"|'[^']*'|[^\s,;\]}]+)/gi, '$1$2$1$3"[REDACTED]"')
+        .replace(/([?&](?:access_token|refresh_token|connect_token|token|api_?key|secret|password)=)[^&\s]+/gi, "$1[REDACTED]")
+        .replace(/(["']?(?:authorization|api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|connect[-_ ]?token|cookie|session|password|secret)["']?\s*[=:]\s*)["'][^"']*["']/gi, "$1\"[REDACTED]\"")
+        .replace(/((?:authorization|api[-_ ]?key|access[-_ ]?token|refresh[-_ ]?token|connect[-_ ]?token|cookie|session|password|secret)\s*[=:]\s*)(?:\[REDACTED(?:_LONG_TOKEN)?\]|[^\s"',;\]}]+)/gi, "$1[REDACTED]")
+        // A tail slice can begin in the middle of an image payload or unknown
+        // credential and therefore no longer contain a recognisable prefix.
+        .replace(/(?<![a-z0-9])[a-z0-9._~+/_=-]{32,}(?![a-z0-9])/gi, "[REDACTED_LONG_TOKEN]")
+        .replace(/[a-z]:[\\/]Users[\\/][^\\/]+(?=[\\/])/gi, "%USERPROFILE%")
+        .replace(/\/(?:Users|home)\/[^/\s]+/g, "$HOME")
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "")
+        .trim();
+    if (text.length > budget)
+        text = text.slice(-budget);
+    return text;
+}
+/** Append stderr only after redaction so the in-memory tail never holds raw payloads. */
+export function appendCodexDiagnosticTail(current, chunk, maxChars = CODEX_STDERR_TAIL_CHARS) {
+    return sanitizeCodexDiagnosticText(`${current}${String(chunk || "")}`, maxChars);
+}
 /** 封装 Codex app-server 的 JSON-RPC 通信与事件转换。 */
 export class CodexAppClient {
     child;
     emit;
+    onExit;
     nextId = 1;
     buffer = "";
     currentThreadId = "";
@@ -27,55 +108,89 @@ export class CodexAppClient {
     pendingDeltas = new Map();
     plansByTurn = new Map();
     approvalRequests = new Map();
+    phase = "spawn";
+    stderrTail = "";
+    logicalClosed = false;
+    osExitSeen = false;
+    failDelivered = false;
+    terminationExpected = false;
+    exitDelivered = false;
+    terminalError = null;
+    exitPromise;
+    resolveExit;
     /** 保存 app-server 子进程和事件出口。 */
-    constructor(child, emit) {
+    constructor(child, emit, onExit) {
         this.child = child;
         this.emit = emit;
+        this.onExit = onExit;
+        this.exitPromise = new Promise((resolve) => { this.resolveExit = resolve; });
     }
     /** 启动并初始化 Codex app-server。 */
-    static async start(emit, onExit) {
+    static async start(emit, onExit, initializeTimeoutMs = APP_SERVER_INITIALIZE_TIMEOUT_MS) {
         logger.info("Starting Codex app-server", { executable: process.execPath, codex: codexBin() });
         const child = spawn(process.execPath, [codexBin(), "app-server", "--stdio"], { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
-        const client = new CodexAppClient(child, emit);
+        const client = new CodexAppClient(child, emit, onExit);
         child.stdout?.on("data", (chunk) => client.read(chunk.toString()));
         child.stderr?.on("data", (chunk) => {
-            const text = chunk.toString();
-            logger.warn("Codex app-server stderr", { text });
-            emit("agent_log", { text });
+            client.recordStderr(chunk.toString());
+        });
+        child.once("error", (error) => {
+            client.handleProcessFailure(new CodexAppProcessError({ phase: client.phase, code: null, signal: null, stderr: `${client.stderrTail}\n${error.message}`, cause: error, source: "spawn" }));
         });
-        child.on("error", (error) => {
-            logger.error("Codex app-server process error", error);
-            emit("agent_error", { message: error.message });
+        child.once("exit", (code, signal) => {
+            client.handleProcessFailure(new CodexAppProcessError({ phase: client.phase, code, signal, stderr: client.stderrTail, source: "exit" }), true);
         });
-        child.on("exit", (code) => {
-            logger.warn("Codex app-server exited", { code });
-            client.failAll(`Codex app-server exited: ${code ?? 0}`);
-            onExit();
-            emit("agent_log", { text: `Codex app-server exited: ${code ?? 0}` });
+        // spawn 失败时 Node 可能只有 error + close 而没有 exit；close 表示 stdio
+        // 已关闭，可安全解除 worker 的 OS-exit 隔离。正常 exit + close 由幂等保护处理。
+        child.once("close", () => {
+            client.noteOsExit();
         });
         try {
-            await withTimeout(client.request("initialize", { clientInfo: { name: "canvas-agent", title: "Infinite Canvas Agent", version: VERSION }, capabilities: { experimentalApi: true, requestAttestation: false } }), APP_SERVER_INITIALIZE_TIMEOUT_MS, "Codex app-server initialize timed out");
+            client.phase = "initialize";
+            await withTimeout(client.request("initialize", { clientInfo: { name: "canvas-agent", title: "Infinite Canvas Agent", version: VERSION }, capabilities: { experimentalApi: true, requestAttestation: false } }), Math.max(1, Math.min(APP_SERVER_INITIALIZE_TIMEOUT_MS, initializeTimeoutMs)), "Codex app-server initialize timed out");
             client.notify("initialized");
+            client.phase = "idle";
             return client;
         }
         catch (error) {
-            await client.terminate("Codex app-server 初始化超时，已回收失去响应的进程");
-            throw error;
+            const processError = isCodexAppProcessError(error) ? error : new CodexAppProcessError({ phase: "initialize", code: child.exitCode, signal: child.signalCode, stderr: `${client.stderrTail}\n${error instanceof Error ? error.message : String(error)}`, cause: error, source: "timeout" });
+            if (!isCodexAppProcessError(error))
+                void persistCodexProcessDiagnostic(processError);
+            processError.cleanupConfirmed = await client.terminate("Codex app-server 初始化失败，已回收当前进程");
+            if (!processError.cleanupConfirmed)
+                processError.cleanupBarrier = client.waitForExit();
+            throw processError;
         }
     }
     /** 创建新的 Codex 线程。 */
     async startThread(cwd, permissionMode = "request", modelSettings = {}) {
-        const { thread } = await this.request("thread/start", { ...threadSettings(permissionMode, modelSettings), ...(cwd ? { cwd } : {}), ...(modelSettings.model ? { model: modelSettings.model } : {}), threadSource: "user" });
-        if (!thread.id)
-            throw new Error("Codex app-server 没有返回 thread id");
-        return thread;
+        this.stderrTail = "";
+        this.phase = "thread/start";
+        try {
+            const { thread } = await this.request("thread/start", { ...threadSettings(permissionMode, modelSettings), ...(cwd ? { cwd } : {}), ...(modelSettings.model ? { model: modelSettings.model } : {}), threadSource: "user" });
+            if (!thread.id)
+                throw new Error("Codex app-server 没有返回 thread id");
+            return thread;
+        }
+        finally {
+            if (!this.logicalClosed)
+                this.phase = "idle";
+        }
     }
     /** 恢复已有 Codex 线程。 */
     async resumeThread(threadId, cwd, permissionMode = "request", modelSettings = {}) {
-        const { thread } = await this.request("thread/resume", { threadId, ...threadSettings(permissionMode, modelSettings), ...(cwd ? { cwd } : {}), ...(modelSettings.model ? { model: modelSettings.model } : {}) });
-        if (!thread.id)
-            throw new Error("Codex app-server 没有返回 thread id");
-        return thread;
+        this.stderrTail = "";
+        this.phase = "thread/start";
+        try {
+            const { thread } = await this.request("thread/resume", { threadId, ...threadSettings(permissionMode, modelSettings), ...(cwd ? { cwd } : {}), ...(modelSettings.model ? { model: modelSettings.model } : {}) });
+            if (!thread.id)
+                throw new Error("Codex app-server 没有返回 thread id");
+            return thread;
+        }
+        finally {
+            if (!this.logicalClosed)
+                this.phase = "idle";
+        }
     }
     /** 查询 Codex 线程列表。 */
     listThreads(params) {
@@ -103,25 +218,33 @@ export class CodexAppClient {
     /** 启动一个 Codex turn 并等待完成通知。 */
     async startTurn(threadId, prompt, images, permissionMode, onTurn, outputSchema, modelSettings = {}) {
         this.currentThreadId = threadId;
-        const { turn } = await this.request("turn/start", { threadId, input: codexInput(prompt, images), ...turnSettings(permissionMode), ...(modelSettings.model ? { model: modelSettings.model } : {}), ...(modelSettings.reasoningEffort ? { effort: modelSettings.reasoningEffort } : {}), ...(outputSchema ? { outputSchema } : {}) });
-        const turnId = turn.id;
-        if (!turnId)
-            throw new Error("Codex app-server 没有返回 turn id");
-        this.currentTurnId = turnId;
-        onTurn?.(turnId);
-        const completed = this.completedTurns.get(turnId);
-        if (this.completedTurns.has(turnId)) {
-            this.completedTurns.delete(turnId);
-            this.currentThreadId = "";
-            this.currentTurnId = "";
-            if (completed?.error)
-                throw completed.error;
-            return completed?.text || "";
+        this.phase = "turn/start";
+        try {
+            const { turn } = await this.request("turn/start", { threadId, input: codexInput(prompt, images), ...turnSettings(permissionMode), ...(modelSettings.model ? { model: modelSettings.model } : {}), ...(modelSettings.reasoningEffort ? { effort: modelSettings.reasoningEffort } : {}), ...(outputSchema ? { outputSchema } : {}) });
+            const turnId = turn.id;
+            if (!turnId)
+                throw new Error("Codex app-server 没有返回 turn id");
+            this.currentTurnId = turnId;
+            this.phase = "turn/running";
+            onTurn?.(turnId);
+            const completed = this.completedTurns.get(turnId);
+            if (this.completedTurns.has(turnId)) {
+                this.completedTurns.delete(turnId);
+                this.currentThreadId = "";
+                this.currentTurnId = "";
+                if (completed?.error)
+                    throw completed.error;
+                return completed?.text || "";
+            }
+            return await new Promise((resolve, reject) => {
+                this.activeTurns.set(turnId, { resolve, reject });
+                this.scheduleTurnReconciliation(threadId, turnId);
+            });
+        }
+        finally {
+            if (!this.logicalClosed)
+                this.phase = "idle";
         }
-        return await new Promise((resolve, reject) => {
-            this.activeTurns.set(turnId, { resolve, reject });
-            this.scheduleTurnReconciliation(threadId, turnId);
-        });
     }
     /** 中断当前正在运行的 Codex turn。 */
     async interruptCurrentTurn() {
@@ -140,15 +263,40 @@ export class CodexAppClient {
         }
     }
     /** 终止失去响应的 app-server，让后续队列可以在新进程继续。 */
-    terminate(message = "Codex app-server was restarted") {
-        this.failAll(message);
-        if (this.child.exitCode !== null)
-            return Promise.resolve();
-        return new Promise((resolve) => {
-            const timer = setTimeout(resolve, 2000);
-            this.child.once("exit", () => { clearTimeout(timer); resolve(); });
+    async terminate(message = "Codex app-server was restarted", diagnostics = {}) {
+        const failurePhase = diagnostics.phase || this.phase;
+        if (!this.logicalClosed) {
+            this.terminationExpected = true;
+            this.logicalClosed = true;
+            this.terminalError = new Error(message);
+            this.phase = "terminating";
+            this.failAll(this.terminalError);
+            this.deliverExit();
+        }
+        if (diagnostics.persistDiagnostic) {
+            void persistCodexProcessDiagnostic(new CodexAppProcessError({ phase: failurePhase, code: this.child.exitCode, signal: this.child.signalCode, stderr: `${this.stderrTail}\n${message}`, source: "timeout" }));
+        }
+        if (this.osExitSeen || this.child.exitCode !== null) {
+            this.noteOsExit();
+            return true;
+        }
+        if (!this.child.killed)
             this.child.kill();
-        });
+        let timer;
+        try {
+            return await Promise.race([
+                this.exitPromise.then(() => true),
+                new Promise((resolve) => { timer = setTimeout(() => resolve(false), 2_000); }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** 仅供 worker 隔离等待真实 OS exit；不包含 stderr 或其它诊断内容。 */
+    waitForExit() {
+        return this.exitPromise;
     }
     /** 回复网页端已经确认的 Codex 权限请求。 */
     resolveApproval(requestId, decision) {
@@ -166,8 +314,18 @@ export class CodexAppClient {
     /** 发送 JSON-RPC 请求并保存待处理 Promise。 */
     request(method, params) {
         const id = this.nextId++;
-        this.write({ id, method, params });
-        return new Promise((resolve, reject) => this.pending.set(id, { resolve: (result) => resolve(result), reject }));
+        return new Promise((resolve, reject) => {
+            if (this.logicalClosed || this.terminalError)
+                return reject(this.terminalError || new Error("Codex app-server is closed"));
+            this.pending.set(id, { resolve: (result) => resolve(result), reject });
+            try {
+                this.write({ id, method, params });
+            }
+            catch (error) {
+                this.pending.delete(id);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
     }
     /** 发送无需响应的 JSON-RPC 通知。 */
     notify(method, params) {
@@ -179,7 +337,24 @@ export class CodexAppClient {
         const params = field(value, "params");
         if (method)
             logger.debug(`Codex ${method}`, { id: field(value, "id"), threadId: field(params, "threadId") });
-        this.child.stdin?.write(`${JSON.stringify(value)}\n`);
+        const stdin = this.child.stdin;
+        if (!stdin || stdin.destroyed || !stdin.writable) {
+            const error = new CodexAppProcessError({ phase: this.phase, code: this.child.exitCode, signal: this.child.signalCode, stderr: this.stderrTail, source: "stdin" });
+            this.handleProcessFailure(error);
+            throw error;
+        }
+        try {
+            stdin.write(`${JSON.stringify(value)}\n`, (cause) => {
+                if (!cause)
+                    return;
+                this.handleProcessFailure(new CodexAppProcessError({ phase: this.phase, code: this.child.exitCode, signal: this.child.signalCode, stderr: `${this.stderrTail}\n${cause.message}`, cause, source: "stdin" }));
+            });
+        }
+        catch (cause) {
+            const error = new CodexAppProcessError({ phase: this.phase, code: this.child.exitCode, signal: this.child.signalCode, stderr: `${this.stderrTail}\n${cause instanceof Error ? cause.message : String(cause)}`, cause, source: "stdin" });
+            this.handleProcessFailure(error);
+            throw error;
+        }
     }
     /** 按行解析 app-server 标准输出。 */
     read(chunk) {
@@ -191,8 +366,8 @@ export class CodexAppClient {
                 this.handle(JSON.parse(line));
             }
             catch (error) {
-                logger.warn("Invalid Codex app-server output", { error, line });
-                this.emit("agent_log", { text: line });
+                logger.warn("Invalid Codex app-server output", { error: error instanceof Error ? error.message : String(error), bytes: line.length });
+                this.emit("agent_log", { text: "Codex app-server 返回了无法解析的本地响应；为保护提示词和凭证，原始内容仅丢弃不展示" });
             }
         });
     }
@@ -395,14 +570,55 @@ export class CodexAppClient {
         if (pending)
             (this.pending.delete(id), pending.reject(new Error(message)));
     }
+    /** 只在内存保存 stderr 尾部；原文绝不直接发往网页或写入日志。 */
+    recordStderr(chunk) {
+        this.stderrTail = appendCodexDiagnosticTail(this.stderrTail, chunk);
+    }
+    /** error/exit/stdin 统一且只执行一次的进程收尾。 */
+    handleProcessFailure(error, exitSeen = false) {
+        if (exitSeen)
+            this.noteOsExit();
+        if (this.logicalClosed)
+            return;
+        this.logicalClosed = true;
+        this.terminalError = error;
+        const expected = this.terminationExpected;
+        if (exitSeen)
+            this.phase = "exited";
+        if (!expected) {
+            this.failAll(error);
+            void persistCodexProcessDiagnostic(error);
+            logger.warn("Codex app-server process failure", { message: error.message });
+            this.emit("agent_log", { text: error.message });
+            if (this.child.exitCode === null && !this.child.killed)
+                this.child.kill();
+        }
+        this.deliverExit();
+    }
+    noteOsExit() {
+        if (this.osExitSeen)
+            return;
+        this.osExitSeen = true;
+        this.phase = "exited";
+        this.resolveExit();
+    }
+    deliverExit() {
+        if (this.exitDelivered)
+            return;
+        this.exitDelivered = true;
+        this.onExit();
+    }
     /** 拒绝进程退出时仍未完成的请求与 turn。 */
-    failAll(message) {
-        [...this.pending.values()].forEach((item) => item.reject(new Error(message)));
+    failAll(error) {
+        if (this.failDelivered)
+            return;
+        this.failDelivered = true;
+        [...this.pending.values()].forEach((item) => item.reject(error));
         [...this.activeTurns.entries()].forEach(([turnId, item]) => {
             if (item.reconcileTimer)
                 clearTimeout(item.reconcileTimer);
             this.activeTurns.delete(turnId);
-            item.reject(new Error(message));
+            item.reject(error);
         });
         this.pendingDeltas.forEach((item) => clearTimeout(item.timer));
         this.pending.clear();
@@ -415,6 +631,29 @@ export class CodexAppClient {
         this.currentTurnId = "";
     }
 }
+/** 将脱敏诊断写入用户目录；单日有界，写入失败不影响脚本恢复。 */
+function persistCodexProcessDiagnostic(error) {
+    diagnosticWriteQueue = diagnosticWriteQueue.catch(() => undefined).then(async () => {
+        const directory = path.join(CONFIG_DIR, "logs");
+        const file = path.join(directory, `codex-app-server-diagnostics-${new Date().toISOString().slice(0, 10)}.jsonl`);
+        await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+        const currentBytes = await fs.stat(file).then((value) => value.size).catch(() => 0);
+        const entry = `${JSON.stringify({
+            at: new Date().toISOString(),
+            diagnosticId: error.diagnosticId,
+            phase: error.phase,
+            source: error.source,
+            code: error.code,
+            signal: error.signal,
+            stderr: sanitizeCodexDiagnosticText(error.stderr, 8_192),
+        })}\n`;
+        const bytes = Buffer.byteLength(entry);
+        if (bytes > CODEX_DIAGNOSTIC_ENTRY_BYTES || currentBytes + bytes > CODEX_DIAGNOSTIC_FILE_BYTES)
+            return;
+        await fs.appendFile(file, entry, { encoding: "utf8", mode: 0o600 });
+    }).catch((error) => logger.debug("Failed to persist Codex process diagnostic", { error }));
+    return diagnosticWriteQueue;
+}
 async function withTimeout(promise, timeoutMs, message) {
     let timer;
     try {

package/dist/agent/codex.d.ts

@@ -1,3 +1,4 @@
+import { type CodexAppProcessError } from "./codex-client.js";
 import type { AgentAttachment, AgentEmit, AgentPermissionMode } from "./types.js";
 type CodexRunOptions = {
     threadId?: string;
@@ -29,19 +30,34 @@ export type CodexWorkflowRunResult = {
     ok: false;
     error: string;
     retryable: boolean;
+    failureKind: "contract" | "transport" | "timeout" | "turn";
     timings: {
         queueWaitMs: number;
         threadStartMs: number;
         modelMs: number;
     };
 };
+type CodexWorkflowFailureKind = Extract<CodexWorkflowRunResult, {
+    ok: false;
+}>["failureKind"];
 export declare const FLOW_C_CODEX_MODEL = "gpt-5.6-terra";
 export declare const FLOW_C_CODEX_REASONING_EFFORT = "medium";
 export declare const FLOW_C_CODEX_WORKER_CONCURRENCY: number;
+export declare const FLOW_C_CODEX_PROCESS_MAX_ATTEMPTS = 3;
 export declare function flowCCodexWorkerStatus(): {
     active: number;
     limit: number;
 };
+/**
+ * 记录尚未确认 OS exit 的 worker 进程。worker 可以释放给队列，但在对应
+ * barrier 完成前只能等待/失败，绝不能启动替代 app-server。
+ */
+export declare class WorkflowCodexLaneQuarantine {
+    private barriers;
+    quarantine(workerIndex: number, barrier: Promise<void>): Promise<undefined>;
+    wait(workerIndex: number, timeoutMs: number): Promise<boolean>;
+    isQuarantined(workerIndex: number): boolean;
+}
 export { summarizeCodexThread } from "./codex-history.js";
 /** 将 Codex turn 加入串行队列并等待执行完成。 */
 export declare function runCodexTurn(prompt: string, emit: AgentEmit, attachments?: AgentAttachment[], options?: CodexRunOptions): Promise<CodexRunResult>;
@@ -57,6 +73,15 @@ export declare function runCodexWorkflowTurn(prompt: string, emit: AgentEmit, op
     onWorkerStart?: () => void;
     onWorkerFinish?: () => void;
 }): Promise<CodexWorkflowRunResult>;
+/** A deadline exhausted after process recovery is terminal for this handoff wave. */
+export declare function isWorkflowFailureRetryable(failureKind: CodexWorkflowFailureKind, cleanupConfirmed: boolean, processRecoveryObserved: boolean): boolean;
+type CodexProcessRetryOptions = {
+    maxAttempts?: number;
+    backoffMs?: number | ((failedAttempt: number) => number);
+    onRetry?: (error: CodexAppProcessError, failedAttempt: number) => Promise<void> | void;
+};
+/** 只重试明确的 app-server 进程/stdio 故障；结构契约和普通模型失败均立即上抛。 */
+export declare function runCodexProcessRetries<T>(operation: (attempt: number) => Promise<T>, options?: CodexProcessRetryOptions): Promise<T>;
 /**
  * 给 Flow C 的完整 app-server 链路设置硬截止时间。超时后不再等待原 Promise
  * 自行结束；否则初始化或 thread/start 永不返回时会永久占住 worker lane。