@wix/pathgrade 0.29.0

package/dist/agents/codex-app-server/protocol/McpElicitationRequestParams.js

@@ -0,0 +1,8 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/McpServerElicitationRequestParams.ts
+// GENERATED CODE in upstream; do not modify locally either.
+//
+// Filename localized to `McpElicitationRequestParams.ts` (spec §What to build).
+// `JsonValue` and `McpElicitationSchema` are opaque aliases — v1 declines elicitations
+// rather than interpreting them (decisions §7).
+export {};

package/dist/agents/codex-app-server/protocol/Op.d.ts

@@ -0,0 +1,11 @@
+import type { ToolRequestUserInputResponse } from './ToolRequestUserInputResponse.js';
+/**
+ * The wire envelope for an UserInputAnswer op. `itemId` correlates with the
+ * originating `item/tool/requestUserInput` server request.
+ */
+export interface OpUserInputAnswer {
+    type: 'Op::UserInputAnswer';
+    itemId: string;
+    answers: ToolRequestUserInputResponse['answers'];
+}
+export type Op = OpUserInputAnswer;

package/dist/agents/codex-app-server/protocol/Op.js

@@ -0,0 +1,5 @@
+// Pathgrade-local composition; not a single upstream file.
+// Upstream models the ops/event bus as discriminated payloads. The driver only
+// writes the UserInputAnswer op (in response to an item/tool/requestUserInput
+// server request); that shape is captured here.
+export {};

package/dist/agents/codex-app-server/protocol/PermissionsRequestApprovalParams.d.ts

@@ -0,0 +1,10 @@
+export type AbsolutePathBuf = string;
+export type RequestPermissionProfile = unknown;
+export type PermissionsRequestApprovalParams = {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    cwd: AbsolutePathBuf;
+    reason: string | null;
+    permissions: RequestPermissionProfile;
+};

package/dist/agents/codex-app-server/protocol/PermissionsRequestApprovalParams.js

@@ -0,0 +1,6 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/PermissionsRequestApprovalParams.ts
+// GENERATED CODE in upstream; do not modify locally either.
+//
+// `AbsolutePathBuf` and `RequestPermissionProfile` are opaque to the driver today.
+export {};

package/dist/agents/codex-app-server/protocol/PermissionsRequestApprovalResponse.d.ts

@@ -0,0 +1,15 @@
+import type { GrantedPermissionProfile } from './GrantedPermissionProfile.js';
+/**
+ * Scope for a granted permission — `'turn'` auto-grants within the current
+ * turn only; `'thread'` persists until the thread ends. Upstream union is
+ * represented as a string literal set here.
+ */
+export type PermissionGrantScope = 'turn' | 'thread';
+export type PermissionsRequestApprovalResponse = {
+    permissions: GrantedPermissionProfile;
+    scope: PermissionGrantScope;
+    /**
+     * Review every subsequent command in this turn before normal sandboxed execution.
+     */
+    strictAutoReview?: boolean;
+};

package/dist/agents/codex-app-server/protocol/PermissionsRequestApprovalResponse.js

@@ -0,0 +1,4 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/PermissionsRequestApprovalResponse.ts
+// GENERATED CODE in upstream; do not modify locally either.
+export {};

package/dist/agents/codex-app-server/protocol/SandboxMode.d.ts

@@ -0,0 +1 @@
+export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';

package/dist/agents/codex-app-server/protocol/SandboxMode.js

@@ -0,0 +1,4 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/SandboxMode.ts
+// GENERATED CODE in upstream; do not modify locally either.
+export {};

package/dist/agents/codex-app-server/protocol/ServerRequest.d.ts

@@ -0,0 +1,42 @@
+import type { ToolRequestUserInputParams } from './ToolRequestUserInputParams.js';
+import type { PermissionsRequestApprovalParams } from './PermissionsRequestApprovalParams.js';
+import type { DynamicToolCallParams } from './DynamicToolCallParams.js';
+import type { McpElicitationRequestParams } from './McpElicitationRequestParams.js';
+export type ServerRequestMethod = 'item/tool/requestUserInput' | 'item/permissions/requestApproval' | 'item/tool/call' | 'mcpServer/elicitation/request' | 'item/commandExecution/requestApproval' | 'item/fileChange/requestApproval' | 'applyPatchApproval' | 'execCommandApproval' | 'account/chatgptAuthTokens/refresh';
+export type ServerRequest = {
+    method: 'item/tool/requestUserInput';
+    id: number | string;
+    params: ToolRequestUserInputParams;
+} | {
+    method: 'item/permissions/requestApproval';
+    id: number | string;
+    params: PermissionsRequestApprovalParams;
+} | {
+    method: 'item/tool/call';
+    id: number | string;
+    params: DynamicToolCallParams;
+} | {
+    method: 'mcpServer/elicitation/request';
+    id: number | string;
+    params: McpElicitationRequestParams;
+} | {
+    method: 'item/commandExecution/requestApproval';
+    id: number | string;
+    params: unknown;
+} | {
+    method: 'item/fileChange/requestApproval';
+    id: number | string;
+    params: unknown;
+} | {
+    method: 'applyPatchApproval';
+    id: number | string;
+    params: unknown;
+} | {
+    method: 'execCommandApproval';
+    id: number | string;
+    params: unknown;
+} | {
+    method: 'account/chatgptAuthTokens/refresh';
+    id: number | string;
+    params: unknown;
+};

package/dist/agents/codex-app-server/protocol/ServerRequest.js

@@ -0,0 +1,7 @@
+// Pathgrade-local composition; not a single upstream file.
+// Enumerates the 9 server-request variants the driver observes over the wire
+// under rust-v0.124.0. Upstream ships the discriminated union at
+// `codex-rs/app-server-protocol/schema/typescript/ServerRequest.ts`
+// (top-level, NOT `typescript/v2/`); the per-variant params files this module
+// imports live under the `v2/` subdirectory.
+export {};

package/dist/agents/codex-app-server/protocol/ThreadStartParams.d.ts

@@ -0,0 +1,45 @@
+import type { SandboxMode } from './SandboxMode.js';
+export type Personality = unknown;
+export type ServiceTier = unknown;
+export type JsonValue = unknown;
+export type ApprovalsReviewer = unknown;
+export type AskForApproval = unknown;
+export type PermissionProfile = unknown;
+export type ThreadStartSource = unknown;
+export type ThreadStartParams = {
+    model?: string | null;
+    modelProvider?: string | null;
+    serviceTier?: ServiceTier | null | null;
+    cwd?: string | null;
+    approvalPolicy?: AskForApproval | null;
+    /**
+     * Override where approval requests are routed for review on this thread
+     * and subsequent turns.
+     */
+    approvalsReviewer?: ApprovalsReviewer | null;
+    sandbox?: SandboxMode | null;
+    /**
+     * Full permissions override for this thread. Cannot be combined with
+     * `sandbox`.
+     */
+    permissionProfile?: PermissionProfile | null;
+    config?: {
+        [key: string]: JsonValue | undefined;
+    } | null;
+    serviceName?: string | null;
+    baseInstructions?: string | null;
+    developerInstructions?: string | null;
+    personality?: Personality | null;
+    ephemeral?: boolean | null;
+    sessionStartSource?: ThreadStartSource | null;
+    /**
+     * If true, opt into emitting raw Responses API items on the event stream.
+     * This is for internal use only (e.g. Codex Cloud).
+     */
+    experimentalRawEvents: boolean;
+    /**
+     * If true, persist additional rollout EventMsg variants required to
+     * reconstruct a richer thread history on resume/fork/read.
+     */
+    persistExtendedHistory: boolean;
+};

package/dist/agents/codex-app-server/protocol/ThreadStartParams.js

@@ -0,0 +1,10 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/ThreadStartParams.ts
+// GENERATED CODE in upstream; do not modify locally either.
+//
+// NOTE: upstream imports additional shared types (Personality, ServiceTier, JsonValue,
+// ApprovalsReviewer, AskForApproval, PermissionProfile, ThreadStartSource) that are not
+// required by the pathgrade Codex driver. They are modelled here as opaque aliases so the
+// vendored surface compiles standalone. Refresh policy: when a new upstream version lands,
+// replace each alias with the vendored definition if the driver starts consuming it.
+export {};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputAnswer.d.ts

@@ -0,0 +1,6 @@
+/**
+ * EXPERIMENTAL. Captures a user's answer to a request_user_input question.
+ */
+export type ToolRequestUserInputAnswer = {
+    answers: Array<string>;
+};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputAnswer.js

@@ -0,0 +1,4 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/ToolRequestUserInputAnswer.ts
+// GENERATED CODE in upstream; do not modify locally either.
+export {};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputOption.d.ts

@@ -0,0 +1,7 @@
+/**
+ * EXPERIMENTAL. Defines a single selectable option for request_user_input.
+ */
+export type ToolRequestUserInputOption = {
+    label: string;
+    description: string;
+};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputOption.js

@@ -0,0 +1,4 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/ToolRequestUserInputOption.ts
+// GENERATED CODE in upstream; do not modify locally either.
+export {};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputParams.d.ts

@@ -0,0 +1,10 @@
+import type { ToolRequestUserInputQuestion } from './ToolRequestUserInputQuestion.js';
+/**
+ * EXPERIMENTAL. Params sent with a request_user_input event.
+ */
+export type ToolRequestUserInputParams = {
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    questions: Array<ToolRequestUserInputQuestion>;
+};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputParams.js

@@ -0,0 +1,4 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/ToolRequestUserInputParams.ts
+// GENERATED CODE in upstream; do not modify locally either.
+export {};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputQuestion.d.ts

@@ -0,0 +1,12 @@
+import type { ToolRequestUserInputOption } from './ToolRequestUserInputOption.js';
+/**
+ * EXPERIMENTAL. Represents one request_user_input question and its required options.
+ */
+export type ToolRequestUserInputQuestion = {
+    id: string;
+    header: string;
+    question: string;
+    isOther: boolean;
+    isSecret: boolean;
+    options: Array<ToolRequestUserInputOption> | null;
+};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputQuestion.js

@@ -0,0 +1,4 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/ToolRequestUserInputQuestion.ts
+// GENERATED CODE in upstream; do not modify locally either.
+export {};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputResponse.d.ts

@@ -0,0 +1,9 @@
+import type { ToolRequestUserInputAnswer } from './ToolRequestUserInputAnswer.js';
+/**
+ * EXPERIMENTAL. Response payload mapping question ids to answers.
+ */
+export type ToolRequestUserInputResponse = {
+    answers: {
+        [key: string]: ToolRequestUserInputAnswer | undefined;
+    };
+};

package/dist/agents/codex-app-server/protocol/ToolRequestUserInputResponse.js

@@ -0,0 +1,4 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/ToolRequestUserInputResponse.ts
+// GENERATED CODE in upstream; do not modify locally either.
+export {};

package/dist/agents/codex-app-server/protocol/TurnCompletedNotification.d.ts

@@ -0,0 +1,5 @@
+export type Turn = unknown;
+export type TurnCompletedNotification = {
+    threadId: string;
+    turn: Turn;
+};

package/dist/agents/codex-app-server/protocol/TurnCompletedNotification.js

@@ -0,0 +1,4 @@
+// Vendored from openai/codex@rust-v0.124.0
+// Source: codex-rs/app-server-protocol/schema/typescript/v2/TurnCompletedNotification.ts
+// GENERATED CODE in upstream; do not modify locally either.
+export {};

package/dist/agents/codex-app-server/protocol/index.d.ts

@@ -0,0 +1,16 @@
+export type { ClientRequest, ClientRequestMethod } from './ClientRequest.js';
+export type { ServerRequest, ServerRequestMethod } from './ServerRequest.js';
+export type { Op, OpUserInputAnswer } from './Op.js';
+export type { ToolRequestUserInputParams } from './ToolRequestUserInputParams.js';
+export type { ToolRequestUserInputQuestion } from './ToolRequestUserInputQuestion.js';
+export type { ToolRequestUserInputOption } from './ToolRequestUserInputOption.js';
+export type { ToolRequestUserInputResponse } from './ToolRequestUserInputResponse.js';
+export type { ToolRequestUserInputAnswer } from './ToolRequestUserInputAnswer.js';
+export type { PermissionsRequestApprovalParams } from './PermissionsRequestApprovalParams.js';
+export type { PermissionsRequestApprovalResponse, PermissionGrantScope, } from './PermissionsRequestApprovalResponse.js';
+export type { GrantedPermissionProfile } from './GrantedPermissionProfile.js';
+export type { DynamicToolCallParams } from './DynamicToolCallParams.js';
+export type { McpElicitationRequestParams } from './McpElicitationRequestParams.js';
+export type { ThreadStartParams } from './ThreadStartParams.js';
+export type { SandboxMode } from './SandboxMode.js';
+export type { TurnCompletedNotification } from './TurnCompletedNotification.js';

package/dist/agents/codex-app-server/protocol/index.js

@@ -0,0 +1,11 @@
+// Curated re-exports for the pathgrade Codex app-server driver and fixture
+// tests. Every re-exported symbol is either vendored verbatim from
+// openai/codex@rust-v0.124.0 (with an upstream-citation header in its file) or
+// a pathgrade-local composition (ClientRequest, ServerRequest, Op) whose
+// header spells out the composition rationale.
+//
+// Refresh policy: to bump the vendored version, update each file's header
+// citation to the new tag, replace the `unknown` aliases with their vendored
+// shapes as the driver starts consuming them, and re-run the protocol fixture
+// suite (slice #10) to catch wire-format drift.
+export {};

package/dist/agents/codex-app-server/transport.d.ts

@@ -0,0 +1,84 @@
+import type { Readable, Writable } from 'stream';
+export type Unsubscribe = () => void;
+export interface ServerRequestMessage {
+    readonly id: number | string;
+    readonly method: string;
+    readonly params: unknown;
+}
+export interface ServerNotificationMessage {
+    readonly method: string;
+    readonly params: unknown;
+}
+export interface TransportCloseInfo {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly pid?: number;
+}
+export interface AppServerTransport {
+    sendRequest<T = unknown>(method: string, params: unknown): Promise<T>;
+    sendNotification(method: string, params: unknown): void;
+    sendResponse(id: number | string, result: unknown): void;
+    sendErrorResponse(id: number | string, code: number, message: string): void;
+    onServerRequest(handler: (req: ServerRequestMessage) => void): Unsubscribe;
+    onNotification(handler: (n: ServerNotificationMessage) => void): Unsubscribe;
+    onClose(handler: (info: TransportCloseInfo) => void): Unsubscribe;
+    close(): Promise<void>;
+    readonly pid?: number;
+}
+export interface CreateNdjsonTransportInput {
+    /** Stream the driver writes JSON-RPC lines to (e.g. child.stdin). */
+    output: Writable;
+    /** Stream the driver reads JSON-RPC lines from (e.g. child.stdout). */
+    input: Readable;
+    /** Optional pid for diagnostics. */
+    pid?: number;
+}
+export declare function createNdjsonTransport(cfg: CreateNdjsonTransportInput): AppServerTransport;
+export interface SpawnAppServerTransportInput {
+    binary?: string;
+    args?: readonly string[];
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    /**
+     * Grace period between SIGTERM and SIGKILL during handle close.
+     * Exposed for tests; defaults to 2s for production spawns.
+     */
+    killGracePeriodMs?: number;
+}
+export declare function buildAppServerSpawnArgs(args?: readonly string[], env?: NodeJS.ProcessEnv): string[];
+/**
+ * Minimal child-process surface the session handle needs. Real spawns satisfy
+ * this via `ChildProcessWithoutNullStreams`; tests can substitute a fake that
+ * controls `kill` and `exit` timing without booting a subprocess.
+ */
+export interface SessionChildHandle {
+    readonly pid?: number;
+    kill(signal?: NodeJS.Signals): boolean;
+    once(event: 'exit', listener: () => void): void;
+    readonly exitCode: number | null;
+    readonly signalCode: NodeJS.Signals | null;
+}
+/**
+ * Lifecycle-aware wrapper around the `codex app-server` subprocess and its
+ * NDJSON transport. Centralizes the close-then-kill sequence — SIGTERM, wait,
+ * escalate to SIGKILL if the child has not exited — so the rest of the driver
+ * does not have to coordinate the two resources.
+ */
+export interface AppServerSessionHandle {
+    readonly transport: AppServerTransport;
+    readonly pid: number | undefined;
+    close(): Promise<void>;
+}
+interface CreateAppServerSessionHandleInput {
+    transport: AppServerTransport;
+    child: SessionChildHandle | null;
+    killGracePeriodMs?: number;
+}
+export declare function createAppServerSessionHandle(input: CreateAppServerSessionHandleInput): AppServerSessionHandle;
+/**
+ * Spawn `codex ... app-server` and wrap its stdio in an NDJSON transport.
+ * --config overrides (if any) must appear in `args` before `app-server`,
+ * matching spike §1 which pins them to the parent `codex` binary.
+ */
+export declare function spawnAppServerTransport(cfg?: SpawnAppServerTransportInput): AppServerSessionHandle;
+export {};

package/dist/agents/codex-app-server/transport.js

@@ -0,0 +1,246 @@
+import { spawn } from 'child_process';
+import { createInterface } from 'readline';
+export function createNdjsonTransport(cfg) {
+    return createNdjsonTransportInternal(cfg);
+}
+function createNdjsonTransportInternal(cfg) {
+    const { output, input, pid } = cfg;
+    let nextId = 1;
+    const pendingRequests = new Map();
+    const serverRequestHandlers = new Set();
+    const notificationHandlers = new Set();
+    const closeHandlers = new Set();
+    let closed = false;
+    const rl = createInterface({ input });
+    rl.on('line', (raw) => {
+        const line = raw.trim();
+        if (!line)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        // Response to a request we sent.
+        if (parsed.id !== undefined
+            && parsed.id !== null
+            && parsed.method === undefined
+            && (parsed.result !== undefined || parsed.error !== undefined)) {
+            const resolver = pendingRequests.get(parsed.id);
+            if (resolver) {
+                pendingRequests.delete(parsed.id);
+                resolver(parsed);
+            }
+            return;
+        }
+        // Server-initiated request.
+        if (parsed.method !== undefined && parsed.id !== undefined && parsed.id !== null) {
+            const msg = {
+                id: parsed.id,
+                method: parsed.method,
+                params: parsed.params,
+            };
+            for (const h of serverRequestHandlers) {
+                try {
+                    h(msg);
+                }
+                catch (err) {
+                    console.error('AppServerTransport serverRequest handler threw', err);
+                }
+            }
+            return;
+        }
+        // Notification.
+        if (parsed.method !== undefined) {
+            const msg = {
+                method: parsed.method,
+                params: parsed.params,
+            };
+            for (const h of notificationHandlers) {
+                try {
+                    h(msg);
+                }
+                catch (err) {
+                    console.error('AppServerTransport notification handler threw', err);
+                }
+            }
+        }
+    });
+    const writeLine = (obj) => {
+        if (closed)
+            return;
+        output.write(JSON.stringify(obj) + '\n');
+    };
+    return {
+        sendRequest(method, params) {
+            if (closed)
+                return Promise.reject(new Error('AppServerTransport closed'));
+            const id = nextId++;
+            return new Promise((resolve, reject) => {
+                pendingRequests.set(id, (env) => {
+                    if (env.error) {
+                        reject(new Error(`codex app-server '${method}' failed (${env.error.code}): ${env.error.message}`));
+                        return;
+                    }
+                    resolve(env.result);
+                });
+                writeLine({ jsonrpc: '2.0', id, method, params });
+            });
+        },
+        sendNotification(method, params) {
+            writeLine({ jsonrpc: '2.0', method, params });
+        },
+        sendResponse(id, result) {
+            writeLine({ jsonrpc: '2.0', id, result });
+        },
+        sendErrorResponse(id, code, message) {
+            writeLine({ jsonrpc: '2.0', id, error: { code, message } });
+        },
+        onServerRequest(handler) {
+            serverRequestHandlers.add(handler);
+            return () => {
+                serverRequestHandlers.delete(handler);
+            };
+        },
+        onNotification(handler) {
+            notificationHandlers.add(handler);
+            return () => {
+                notificationHandlers.delete(handler);
+            };
+        },
+        onClose(handler) {
+            closeHandlers.add(handler);
+            return () => {
+                closeHandlers.delete(handler);
+            };
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            rl.close();
+            pendingRequests.clear();
+        },
+        notifyClose(info) {
+            for (const h of closeHandlers) {
+                try {
+                    h(info);
+                }
+                catch (err) {
+                    console.error('AppServerTransport close handler threw', err);
+                }
+            }
+        },
+        pid,
+    };
+}
+const CODEX_PROXY_PROVIDER_ID = 'pathgrade_openai_proxy';
+function quoteCodexConfigString(value) {
+    return JSON.stringify(value);
+}
+export function buildAppServerSpawnArgs(args = [], env = process.env) {
+    const baseUrl = env.OPENAI_BASE_URL?.trim();
+    if (!baseUrl)
+        return [...args, 'app-server'];
+    return [
+        '-c', `model_provider=${quoteCodexConfigString(CODEX_PROXY_PROVIDER_ID)}`,
+        '-c', `model_providers.${CODEX_PROXY_PROVIDER_ID}.name=${quoteCodexConfigString('PathGrade OpenAI Proxy')}`,
+        '-c', `model_providers.${CODEX_PROXY_PROVIDER_ID}.base_url=${quoteCodexConfigString(baseUrl)}`,
+        '-c', `model_providers.${CODEX_PROXY_PROVIDER_ID}.env_key=${quoteCodexConfigString('OPENAI_API_KEY')}`,
+        '-c', `model_providers.${CODEX_PROXY_PROVIDER_ID}.wire_api=${quoteCodexConfigString('responses')}`,
+        '-c', `model_providers.${CODEX_PROXY_PROVIDER_ID}.supports_websockets=false`,
+        ...args,
+        'app-server',
+    ];
+}
+export function createAppServerSessionHandle(input) {
+    const { transport, child } = input;
+    const killGrace = input.killGracePeriodMs ?? 2_000;
+    let closed = false;
+    return {
+        transport,
+        pid: child?.pid,
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            // Release the transport first so pending pipe writes are not lost.
+            await transport.close();
+            if (!child)
+                return;
+            if (child.exitCode !== null || child.signalCode !== null)
+                return;
+            const exited = new Promise((resolve) => {
+                child.once('exit', () => resolve());
+            });
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // Already exited or missing permissions; ignore and let the
+                // exit listener settle if the kill actually landed.
+            }
+            const killTimer = setTimeout(() => {
+                if (child.exitCode !== null || child.signalCode !== null)
+                    return;
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // Best-effort escalation.
+                }
+            }, killGrace);
+            // Don't keep the Node event loop alive just for the kill timer.
+            if (typeof killTimer.unref === 'function')
+                killTimer.unref();
+            await exited;
+            clearTimeout(killTimer);
+        },
+    };
+}
+/**
+ * Spawn `codex ... app-server` and wrap its stdio in an NDJSON transport.
+ * --config overrides (if any) must appear in `args` before `app-server`,
+ * matching spike §1 which pins them to the parent `codex` binary.
+ */
+export function spawnAppServerTransport(cfg = {}) {
+    const binary = cfg.binary ?? 'codex';
+    const args = cfg.args ?? [];
+    const env = cfg.env ?? process.env;
+    const child = spawn(binary, buildAppServerSpawnArgs(args, env), {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env,
+        cwd: cfg.cwd,
+    });
+    // Capture codex stderr so we can surface it on unexpected exits. Without
+    // this, a codex auth or connectivity failure just shows up as an empty
+    // turn with no explanation — especially painful in CI logs.
+    let stderrBuf = '';
+    const STDERR_CAP_BYTES = 8_192;
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk) => {
+        if (stderrBuf.length >= STDERR_CAP_BYTES)
+            return;
+        stderrBuf += chunk;
+        if (stderrBuf.length > STDERR_CAP_BYTES)
+            stderrBuf = stderrBuf.slice(0, STDERR_CAP_BYTES);
+    });
+    const transport = createNdjsonTransportInternal({
+        output: child.stdin,
+        input: child.stdout,
+        pid: child.pid,
+    });
+    child.on('exit', (exitCode, signal) => {
+        if (stderrBuf.trim().length > 0) {
+            console.error(`[codex app-server pid=${child.pid}] exited with code=${exitCode} signal=${signal}. stderr:\n${stderrBuf}`);
+        }
+        transport.notifyClose({ exitCode, signal, pid: child.pid });
+    });
+    return createAppServerSessionHandle({
+        transport,
+        child,
+        ...(cfg.killGracePeriodMs !== undefined ? { killGracePeriodMs: cfg.killGracePeriodMs } : {}),
+    });
+}