cli-jaw 2.2.15 → 2.2.17

package/dist/src/agent/codex-app-client.js

@@ -6,68 +6,221 @@ import { EventEmitter } from 'events';
 import { createInterface } from 'readline';
 // A bogus thread/resume on codex-cli 0.146.0 returns "no rollout found for thread id ...".
 const RECOVERABLE_RESUME_RE = /not found|no rollout found|unknown thread|no such thread|invalid thread|thread.*missing/i;
+const TERMINAL_INTERRUPT_RACE_RE = /turn not active|already completed|no active turn|unknown turn/i;
+const PENDING_NOTIFICATION_LIMIT = 128;
+const PENDING_NOTIFICATION_TTL_MS = 5_000;
+const TURN_OWNED_METHODS = new Set([
+    'thread/tokenUsage/updated',
+    'turn/diff/updated',
+    'turn/plan/updated',
+    'item/started',
+    'item/autoApprovalReview/started',
+    'item/autoApprovalReview/completed',
+    'item/completed',
+    'rawResponseItem/completed',
+    'rawResponse/completed',
+    'item/agentMessage/delta',
+    'item/plan/delta',
+    'item/commandExecution/outputDelta',
+    'item/commandExecution/terminalInteraction',
+    'item/fileChange/outputDelta',
+    'item/fileChange/patchUpdated',
+    'item/mcpToolCall/progress',
+    'item/reasoning/summaryTextDelta',
+    'item/reasoning/summaryPartAdded',
+    'item/reasoning/textDelta',
+    'thread/compacted',
+    'model/rerouted',
+    'model/verification',
+    'turn/moderationMetadata',
+    'model/safetyBuffering/updated',
+]);
+const NULLABLE_TURN_METHODS = new Set([
+    'thread/goal/updated',
+    'hook/started',
+    'hook/completed',
+]);
+const THREAD_OWNED_METHODS = new Set([
+    'thread/status/changed',
+    'thread/archived',
+    'thread/deleted',
+    'thread/unarchived',
+    'thread/closed',
+    'thread/name/updated',
+    'thread/goal/cleared',
+    'thread/environment/connected',
+    'thread/environment/disconnected',
+    'thread/settings/updated',
+    'serverRequest/resolved',
+    'guardianWarning',
+]);
+const REALTIME_THREAD_METHODS = new Set([
+    'thread/realtime/started',
+    'thread/realtime/itemAdded',
+    'thread/realtime/transcript/delta',
+    'thread/realtime/transcript/done',
+    'thread/realtime/outputAudio/delta',
+    'thread/realtime/sdp',
+    'thread/realtime/error',
+    'thread/realtime/closed',
+]);
+const NULLABLE_THREAD_METHODS = new Set([
+    'mcpServer/oauthLogin/completed',
+    'mcpServer/startupStatus/updated',
+    'warning',
+]);
+const REQUEST_HOST_METHODS = new Set([
+    'command/exec/outputDelta',
+    'process/outputDelta',
+    'process/exited',
+    'externalAgentConfig/import/progress',
+    'externalAgentConfig/import/completed',
+    'fs/changed',
+    'fuzzyFileSearch/sessionUpdated',
+    'fuzzyFileSearch/sessionCompleted',
+]);
+const PROCESS_HOST_METHODS = new Set([
+    'skills/changed',
+    'account/updated',
+    'account/rateLimits/updated',
+    'app/list/updated',
+    'remoteControl/status/changed',
+    'deprecationNotice',
+    'configWarning',
+    'windows/worldWritableWarning',
+    'windowsSandbox/setupCompleted',
+    'account/login/completed',
+]);
+const TERMINAL_NOTIFICATION_METHODS = new Set([
+    'error',
+    'turn/completed',
+    'thread/closed',
+    'thread/deleted',
+]);
 export function isRecoverableResumeError(message) {
     return RECOVERABLE_RESUME_RE.test(message);
 }
-const TERMINAL_INTERRUPT_RACE_RE = /turn not active|already completed|no active turn|unknown turn/i;
 function isTerminalInterruptRaceError(err) {
     return TERMINAL_INTERRUPT_RACE_RE.test(err.message);
 }
 export class CodexAppClient extends EventEmitter {
     proc = null;
-    threadId = null;
-    activeTurnId = null;
     binary;
     workDir;
     spawnEnv;
-    model;
-    effort;
-    fastMode;
+    unknownNotificationPolicy;
+    scopes = new Map();
+    threadToScope = new Map();
+    turnToScope = new Map();
+    scopeDisposers = new Map();
+    pendingNotifications = [];
+    pendingNotificationSequence = 0;
+    pendingNotificationTimer = null;
+    scopedNotificationHandoffs = new Map();
+    hostNotificationHandoff = {
+        consumers: 0,
+        replaying: false,
+        buffer: [],
+    };
+    pendingNotificationLimit = PENDING_NOTIFICATION_LIMIT;
+    pendingNotificationTtlMs = PENDING_NOTIFICATION_TTL_MS;
     nextId = 1;
     pending = new Map();
     rl = null;
     cleaned = false;
-    pendingInterrupt = false;
+    terminal = false;
     constructor(options = {}) {
         super();
         this.binary = options.binary || 'codex';
         this.workDir = options.workDir || process.cwd();
         this.spawnEnv = options.env || process.env;
-        this.model = options.model || 'gpt-5.5';
-        this.effort = options.effort || 'medium';
-        this.fastMode = options.fastMode ?? false;
+        this.unknownNotificationPolicy = options.unknownNotificationPolicy ?? 'legacy-raw';
     }
     get alive() {
         return this.proc !== null && this.proc.exitCode === null && !this.proc.killed;
     }
-    listenTurn(handlers) {
-        const onNotification = (method, params) => {
-            handlers.onNotification(method, params);
+    getThreadId(scope) {
+        return this.scopes.get(scope)?.threadId ?? null;
+    }
+    getActiveTurnId(scope) {
+        return this.scopes.get(scope)?.activeTurnId ?? null;
+    }
+    listenTurn(scope, handlers) {
+        const handoff = this.ensureScopedNotificationHandoff(scope);
+        const role = handlers.role;
+        const onNotification = (method, params, owner) => {
+            if (role === 'consumer' && handoff?.replaying)
+                return;
+            handlers.onNotification(method, params, owner);
         };
         const onStderr = (text) => { handlers.onStderr(text); };
         const onExit = (code, signal) => { handlers.onExit?.(code, signal); };
         const onError = (err) => { handlers.onError?.(err); };
         const onInterruptFailed = (err) => { handlers.onInterruptFailed?.(err); };
-        this.on('notification', onNotification);
+        this.on(`notification:${scope}`, onNotification);
         this.on('stderr', onStderr);
         this.on('exit', onExit);
         this.on('error', onError);
-        this.on('interrupt-failed', onInterruptFailed);
+        this.on(`interrupt-failed:${scope}`, onInterruptFailed);
+        const scopedConsumerWasIdle = role === 'consumer' && handoff?.consumers === 0;
+        if (role === 'consumer' && handoff)
+            handoff.consumers += 1;
         let disposed = false;
-        return {
-            dispose: () => {
-                if (disposed)
-                    return;
-                disposed = true;
-                this.off('notification', onNotification);
-                this.off('stderr', onStderr);
-                this.off('exit', onExit);
-                this.off('error', onError);
-                this.off('interrupt-failed', onInterruptFailed);
-            },
+        const dispose = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            this.off(`notification:${scope}`, onNotification);
+            this.off('stderr', onStderr);
+            this.off('exit', onExit);
+            this.off('error', onError);
+            this.off(`interrupt-failed:${scope}`, onInterruptFailed);
+            if (role === 'consumer' && handoff) {
+                handoff.consumers = Math.max(0, handoff.consumers - 1);
+            }
+            const disposers = this.scopeDisposers.get(scope);
+            disposers?.delete(dispose);
+            if (disposers?.size === 0)
+                this.scopeDisposers.delete(scope);
         };
+        const disposers = this.scopeDisposers.get(scope) ?? new Set();
+        disposers.add(dispose);
+        this.scopeDisposers.set(scope, disposers);
+        // The handover runs a caller-supplied callback, so it happens only after
+        // registration is complete and a disposer exists. A throwing handler
+        // would otherwise leave the listener attached with no way to detach it,
+        // and with queueing switched off for good.
+        if (scopedConsumerWasIdle && handoff && handoff.buffer.length > 0) {
+            this.replayNotificationHandoff(handoff, handlers.onNotification, dispose);
+        }
+        return { dispose };
+    }
+    listenHostNotifications(handlers) {
+        const listener = (method, params) => {
+            if (this.hostNotificationHandoff.replaying)
+                return;
+            handlers.onNotification(method, params);
+        };
+        this.on('host-notification', listener);
+        this.on('notification', listener);
+        const wasIdle = this.hostNotificationHandoff.consumers === 0;
+        this.hostNotificationHandoff.consumers += 1;
+        let disposed = false;
+        const dispose = () => {
+            if (disposed)
+                return;
+            disposed = true;
+            this.off('host-notification', listener);
+            this.off('notification', listener);
+            this.hostNotificationHandoff.consumers = Math.max(0, this.hostNotificationHandoff.consumers - 1);
+        };
+        if (wasIdle && this.hostNotificationHandoff.buffer.length > 0) {
+            this.replayNotificationHandoff(this.hostNotificationHandoff, handlers.onNotification, dispose);
+        }
+        return { dispose };
     }
     spawn() {
+        this.assertReusable();
         const isCmdShim = process.platform === 'win32' && !this.binary.toLowerCase().endsWith('.exe');
         this.proc = spawn(this.binary, ['app-server', '--listen', 'stdio://'], {
             cwd: this.workDir,
@@ -81,13 +234,11 @@ export class CodexAppClient extends EventEmitter {
         this.proc.stderr?.on('data', (chunk) => {
             this.emit('stderr', chunk.toString());
         });
-        this.proc.on('error', (err) => this.emit('error', err));
-        this.proc.on('exit', (code, signal) => {
-            this.rejectAllPending('Process exited');
-            this.emit('exit', code, signal);
-        });
+        this.proc.on('error', (err) => { this.handleProcessError(err); });
+        this.proc.on('exit', (code, signal) => { this.handleProcessExit(code, signal); });
     }
     async initialize() {
+        this.assertReusable();
         const result = await this.request('initialize', {
             clientInfo: {
                 name: 'cli_jaw_codex_app_server',
@@ -105,60 +256,42 @@ export class CodexAppClient extends EventEmitter {
         this.notify('initialized', {});
         return result;
     }
-    async startThread(options = {}) {
-        const result = await this.request('thread/start', {
-            model: this.model,
-            approvalPolicy: 'never',
-            sandbox: 'danger-full-access',
-            cwd: options.cwd || this.workDir,
-            config: this.reasoningConfig(),
-            ...(options.instructions ? { developerInstructions: options.instructions } : {}),
-        });
-        this.threadId = result.thread.id;
-        return this.threadId;
+    async startThread(scope, options) {
+        return this.startThreadScoped(scope, options);
     }
-    async resumeThread(threadId, options = {}) {
-        const result = await this.request('thread/resume', {
-            threadId,
-            model: this.model,
-            approvalPolicy: 'never',
-            sandbox: 'danger-full-access',
-            cwd: this.workDir,
-            config: this.reasoningConfig(),
-            excludeTurns: true,
-            ...(options.instructions ? { developerInstructions: options.instructions } : {}),
-        });
-        this.threadId = result.thread.id;
-        return this.threadId;
-    }
-    async startTurn(prompt) {
-        if (!this.threadId)
-            throw new Error('No active thread');
-        const result = await this.request('turn/start', {
-            threadId: this.threadId,
-            input: [{
-                    type: 'text',
-                    text: prompt,
-                    text_elements: [],
-                }],
-            effort: this.effort || undefined,
-            summary: 'detailed',
-        });
-        this.setActiveTurnId(result.turn?.id ?? null);
+    async resumeThread(scope, threadId, options) {
+        return this.resumeThreadScoped(scope, threadId, options);
+    }
+    async startTurn(scope, prompt) {
+        return this.startTurnScoped(scope, prompt);
     }
-    async interruptTurn() {
-        if (!this.threadId)
+    async interruptTurn(scope) {
+        const state = this.requireScope(scope);
+        if (!state.threadId)
             return;
-        if (!this.activeTurnId) {
-            this.pendingInterrupt = true;
+        if (!state.activeTurnId) {
+            state.pendingInterrupt = true;
             return;
         }
-        await this.request('turn/interrupt', {
-            threadId: this.threadId,
-            turnId: this.activeTurnId,
-        });
+        await this.sendInterrupt(state, state.activeTurnId);
+    }
+    async closeScope(scope) {
+        const state = this.requireScope(scope);
+        if (state.operation !== 'idle' || state.activeTurnId) {
+            throw new Error(`Cannot close active scope ${scope}`);
+        }
+        state.operation = 'closing';
+        try {
+            if (!this.terminal && state.threadId) {
+                await this.request('thread/unsubscribe', { threadId: state.threadId }).catch(() => { });
+            }
+        }
+        finally {
+            this.removeScope(scope);
+        }
     }
     async listModels(options = {}) {
+        this.assertReusable();
         const all = [];
         let cursor = null;
         do {
@@ -173,20 +306,21 @@ export class CodexAppClient extends EventEmitter {
     }
     async closeGracefully() {
         try {
-            if (this.threadId) {
-                await this.request('thread/unsubscribe', { threadId: this.threadId }).catch(() => { });
+            if (!this.terminal) {
+                const ids = new Set([...this.scopes.values()].flatMap((state) => state.threadId ? [state.threadId] : []));
+                await Promise.all([...ids].map((threadId) => this.request('thread/unsubscribe', { threadId }).catch(() => { })));
             }
         }
         catch { /* best effort */ }
         this.proc?.stdin?.end();
-        await new Promise((r) => {
-            const t = setTimeout(() => { this.kill(); r(); }, 3000);
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => { this.kill(); resolve(); }, 3_000);
             if (this.proc) {
-                this.proc.once('exit', () => { clearTimeout(t); r(); });
+                this.proc.once('exit', () => { clearTimeout(timer); resolve(); });
             }
             else {
-                clearTimeout(t);
-                r();
+                clearTimeout(timer);
+                resolve();
             }
         });
     }
@@ -196,19 +330,718 @@ export class CodexAppClient extends EventEmitter {
             setTimeout(() => {
                 if (this.proc && !this.proc.killed)
                     this.proc.kill('SIGKILL');
-            }, 2000);
+            }, 2_000);
         }
     }
     cleanup() {
         if (this.cleaned)
             return;
         this.cleaned = true;
-        this.rejectAllPending('Client cleanup');
+        if (this.beginProcessDeath('Client cleanup'))
+            this.finalizeProcessDeath();
         this.rl?.close();
         this.rl = null;
         this.removeAllListeners();
     }
-    // ─── Internal ─────────────────────────────────
+    // ─── Scoped operations ───────────────────────────
+    async startThreadScoped(scope, options) {
+        const state = this.beginScopeRebind(scope, options);
+        const operation = this.beginPendingOperation(state, 'binding');
+        try {
+            const result = await Promise.race([
+                this.request('thread/start', {
+                    model: state.model,
+                    approvalPolicy: 'never',
+                    sandbox: 'danger-full-access',
+                    cwd: state.cwd,
+                    config: this.reasoningConfig(state),
+                    ...(state.instructions ? { developerInstructions: state.instructions } : {}),
+                }),
+                operation.failure,
+            ]);
+            this.bindThread(scope, result.thread.id);
+            this.throwIfOperationFailed(operation);
+            state.operation = 'idle';
+            return result.thread.id;
+        }
+        catch (err) {
+            if (state.operation !== 'terminal')
+                state.operation = 'idle';
+            throw err;
+        }
+        finally {
+            if (state.pendingOperation === operation)
+                state.pendingOperation = null;
+        }
+    }
+    async resumeThreadScoped(scope, threadId, options) {
+        const state = this.beginScopeRebind(scope, options);
+        const operation = this.beginPendingOperation(state, 'binding');
+        try {
+            const result = await Promise.race([
+                this.request('thread/resume', {
+                    threadId,
+                    model: state.model,
+                    approvalPolicy: 'never',
+                    sandbox: 'danger-full-access',
+                    cwd: state.cwd,
+                    config: this.reasoningConfig(state),
+                    excludeTurns: true,
+                    ...(state.instructions ? { developerInstructions: state.instructions } : {}),
+                }),
+                operation.failure,
+            ]);
+            this.bindThread(scope, result.thread.id);
+            this.throwIfOperationFailed(operation);
+            state.operation = 'idle';
+            return result.thread.id;
+        }
+        catch (err) {
+            if (state.operation !== 'terminal')
+                state.operation = 'idle';
+            throw err;
+        }
+        finally {
+            if (state.pendingOperation === operation)
+                state.pendingOperation = null;
+        }
+    }
+    async startTurnScoped(scope, prompt) {
+        this.assertReusable();
+        const state = this.requireScope(scope);
+        if (state.operation !== 'idle') {
+            throw new Error(`Scope ${scope} already has ${state.operation} operation`);
+        }
+        if (!state.threadId)
+            throw new Error(`No active thread for scope ${scope}`);
+        state.operation = 'turn';
+        const operation = this.beginPendingOperation(state, 'turn');
+        try {
+            const result = await Promise.race([
+                this.request('turn/start', {
+                    threadId: state.threadId,
+                    input: [{
+                            type: 'text',
+                            text: prompt,
+                            text_elements: [],
+                        }],
+                    ...(state.effort ? { effort: state.effort } : {}),
+                    summary: 'detailed',
+                }),
+                operation.failure,
+            ]);
+            const turnId = result.turn?.id;
+            if (!turnId)
+                throw new Error(`turn/start returned no turn id for scope ${scope}`);
+            // The notification stream may have started and finished this turn
+            // while the response was still travelling. Rebinding it here would
+            // make a completed turn active again and block every turn after it.
+            if (operation.settledTurnIds.has(turnId)) {
+                this.throwIfOperationFailed(operation);
+                return;
+            }
+            if (state.activeTurnId && state.activeTurnId !== turnId) {
+                throw new Error(`turn/start response ${turnId} conflicts with active turn ${state.activeTurnId} for scope ${scope}`);
+            }
+            if (!state.activeTurnId)
+                this.bindTurn(scope, turnId);
+            this.throwIfOperationFailed(operation);
+        }
+        catch (err) {
+            // A terminal notification can end this turn and let the next one
+            // start before this request settles. Cleaning up unconditionally
+            // would then tear down a turn that is already running, so only the
+            // operation still owned by the lane may touch its state.
+            if (!this.terminal && state.pendingOperation === operation) {
+                this.clearActiveTurn(state);
+                state.operation = 'idle';
+            }
+            throw err;
+        }
+        finally {
+            if (state.pendingOperation === operation)
+                state.pendingOperation = null;
+        }
+    }
+    // ─── Lane lifecycle ──────────────────────────────
+    beginScopeRebind(scope, options) {
+        this.assertReusable();
+        const current = this.scopes.get(scope);
+        if (current && (current.operation !== 'idle' || current.activeTurnId)) {
+            throw new Error(`Scope ${scope} already has ${current.operation} operation`);
+        }
+        if (current)
+            this.clearScopeBinding(current);
+        const state = current ?? this.createScope(scope, options);
+        state.model = options.model;
+        state.effort = options.effort;
+        state.cwd = options.cwd;
+        state.fastMode = options.fastMode;
+        if (options.instructions !== undefined)
+            state.instructions = options.instructions;
+        else
+            delete state.instructions;
+        state.threadId = null;
+        state.activeTurnId = null;
+        state.pendingInterrupt = false;
+        state.operation = 'binding';
+        state.pendingOperation = null;
+        this.scopes.set(scope, state);
+        this.removeBufferedForScope(scope);
+        return state;
+    }
+    bindThread(scope, threadId) {
+        const state = this.requireScope(scope);
+        const owner = this.threadToScope.get(threadId);
+        if (owner && owner !== scope) {
+            throw new Error(`Thread ${threadId} is already bound to scope ${owner}`);
+        }
+        if (state.threadId && state.threadId !== threadId)
+            this.clearScopeBinding(state);
+        state.threadId = threadId;
+        this.threadToScope.set(threadId, scope);
+        this.replayPendingForScope(scope);
+    }
+    bindTurn(scope, turnId, replayPending = true) {
+        const state = this.requireScope(scope);
+        if (!state.threadId)
+            throw new Error(`No active thread for scope ${scope}`);
+        const owner = this.turnToScope.get(turnId);
+        if (owner && owner !== scope) {
+            throw new Error(`Turn ${turnId} is already bound to scope ${owner}`);
+        }
+        if (state.activeTurnId && state.activeTurnId !== turnId) {
+            this.turnToScope.delete(state.activeTurnId);
+        }
+        state.activeTurnId = turnId;
+        this.turnToScope.set(turnId, scope);
+        if (state.pendingInterrupt) {
+            state.pendingInterrupt = false;
+            void this.sendInterrupt(state, turnId).catch(() => { });
+        }
+        if (replayPending)
+            this.replayPendingForScope(scope);
+    }
+    clearActiveTurn(state) {
+        // Record the id before dropping it. The turn/start response may still be
+        // in flight, and it must not resurrect a turn that has already ended.
+        if (state.activeTurnId && state.pendingOperation?.kind === 'turn') {
+            state.pendingOperation.settledTurnIds.add(state.activeTurnId);
+        }
+        if (state.activeTurnId && this.turnToScope.get(state.activeTurnId) === state.scope) {
+            this.turnToScope.delete(state.activeTurnId);
+        }
+        state.activeTurnId = null;
+        state.pendingInterrupt = false;
+        if (state.operation === 'turn')
+            state.operation = 'idle';
+    }
+    clearScopeBinding(state) {
+        if (state.threadId && this.threadToScope.get(state.threadId) === state.scope) {
+            this.threadToScope.delete(state.threadId);
+        }
+        if (state.activeTurnId && this.turnToScope.get(state.activeTurnId) === state.scope) {
+            this.turnToScope.delete(state.activeTurnId);
+        }
+        state.threadId = null;
+        state.activeTurnId = null;
+        state.pendingInterrupt = false;
+    }
+    removeScope(scope) {
+        const state = this.scopes.get(scope);
+        if (state)
+            this.clearScopeBinding(state);
+        for (const dispose of [...(this.scopeDisposers.get(scope) ?? [])])
+            dispose();
+        this.scopeDisposers.delete(scope);
+        this.removeAllListeners(`notification:${scope}`);
+        this.removeAllListeners(`interrupt-failed:${scope}`);
+        this.removeBufferedForScope(scope);
+        this.scopedNotificationHandoffs.delete(scope);
+        this.scopes.delete(scope);
+    }
+    createScope(scope, options) {
+        return {
+            ...options,
+            scope,
+            threadId: null,
+            activeTurnId: null,
+            pendingInterrupt: false,
+            operation: 'idle',
+            pendingOperation: null,
+        };
+    }
+    requireScope(scope) {
+        this.assertReusable();
+        const state = this.scopes.get(scope);
+        if (!state)
+            throw new Error(`Unknown scope ${scope}`);
+        if (state.operation === 'terminal')
+            throw new Error(`Scope ${scope} is terminal`);
+        return state;
+    }
+    beginPendingOperation(state, kind) {
+        let reject;
+        const failure = new Promise((_resolve, rejectPromise) => {
+            reject = rejectPromise;
+        });
+        const operation = {
+            kind, failure, reject, failed: null, settledTurnIds: new Set(),
+        };
+        state.pendingOperation = operation;
+        return operation;
+    }
+    failPendingOperation(scope, err) {
+        const state = this.scopes.get(scope);
+        const operation = state?.pendingOperation;
+        if (!state || !operation || operation.failed)
+            return false;
+        operation.failed = err;
+        operation.reject(err);
+        return true;
+    }
+    throwIfOperationFailed(operation) {
+        if (operation.failed)
+            throw operation.failed;
+    }
+    assertReusable() {
+        if (this.terminal)
+            throw new Error('Codex App client is terminal');
+    }
+    // ─── Notification routing ────────────────────────
+    routeNotification(method, params, allowBuffer = true) {
+        this.expirePendingNotifications();
+        if (method === 'error') {
+            this.routeError(params, allowBuffer);
+            return;
+        }
+        if (method === 'turn/started' || method === 'turn/completed') {
+            this.routeTurnLifecycle(method, params, allowBuffer);
+            return;
+        }
+        if (TURN_OWNED_METHODS.has(method)) {
+            this.routeTurnOwned(method, params, allowBuffer);
+            return;
+        }
+        if (NULLABLE_TURN_METHODS.has(method)) {
+            this.routeNullableTurn(method, params, allowBuffer);
+            return;
+        }
+        if (method === 'thread/started') {
+            this.routeThreadStarted(params, allowBuffer);
+            return;
+        }
+        if (THREAD_OWNED_METHODS.has(method) || REALTIME_THREAD_METHODS.has(method)) {
+            this.routeThreadOwned(method, params, allowBuffer);
+            return;
+        }
+        if (NULLABLE_THREAD_METHODS.has(method)) {
+            this.routeNullableThread(method, params, allowBuffer);
+            return;
+        }
+        if (REQUEST_HOST_METHODS.has(method) || PROCESS_HOST_METHODS.has(method)) {
+            this.emitHostNotification(method, params);
+            return;
+        }
+        this.emitUnrouted(method, params, 'unknown-method');
+        if (this.unknownNotificationPolicy === 'legacy-raw') {
+            this.recordHostNotification(method, params);
+            this.emit('notification', method, params);
+        }
+    }
+    routeError(params, allowBuffer) {
+        const threadId = this.stringField(params, 'threadId');
+        const turnId = this.stringField(params, 'turnId');
+        if (!threadId || !turnId) {
+            this.emitHostNotification('error', params);
+            this.emit('server-error', params);
+            return;
+        }
+        const scope = this.resolveTurnOwner(threadId, turnId);
+        if (!scope) {
+            if (allowBuffer && this.shouldBufferTurn(threadId)) {
+                this.bufferNotification('error', params, threadId, turnId);
+            }
+            else {
+                this.emitUnrouted('error', params, 'turn-owner-mismatch');
+            }
+            return;
+        }
+        this.emitLaneNotification(scope, 'error', params, { threadId, turnId });
+        if (params['willRetry'] !== true) {
+            const state = this.scopes.get(scope);
+            if (state)
+                this.clearActiveTurn(state);
+        }
+    }
+    routeTurnLifecycle(method, params, allowBuffer) {
+        const threadId = this.stringField(params, 'threadId');
+        const turn = this.recordField(params, 'turn');
+        const turnId = turn ? this.stringField(turn, 'id') : null;
+        if (!threadId || !turnId) {
+            this.emitUnrouted(method, params, 'malformed-turn-lifecycle');
+            return;
+        }
+        if (method === 'turn/started') {
+            const threadScope = this.threadToScope.get(threadId);
+            const state = threadScope ? this.scopes.get(threadScope) : undefined;
+            if (threadScope
+                && state?.threadId === threadId
+                && (state.operation === 'turn' || state.pendingInterrupt)
+                && (!state.activeTurnId || state.activeTurnId === turnId)) {
+                if (state.operation === 'idle')
+                    state.operation = 'turn';
+                if (!state.activeTurnId)
+                    this.bindTurn(threadScope, turnId, allowBuffer);
+                if (this.resolveTurnOwner(threadId, turnId) === threadScope) {
+                    this.emitLaneNotification(threadScope, method, params, { threadId, turnId });
+                }
+                return;
+            }
+            if (allowBuffer && this.shouldBufferTurn(threadId)) {
+                this.bufferNotification(method, params, threadId, turnId);
+            }
+            else {
+                this.emitUnrouted(method, params, 'turn-start-owner-mismatch');
+            }
+            return;
+        }
+        const scope = this.resolveTurnOwner(threadId, turnId);
+        if (!scope) {
+            if (allowBuffer && this.shouldBufferTurn(threadId)) {
+                this.bufferNotification(method, params, threadId, turnId);
+            }
+            else {
+                this.emitUnrouted(method, params, 'turn-complete-owner-mismatch');
+            }
+            return;
+        }
+        this.emitLaneNotification(scope, method, params, { threadId, turnId });
+        const state = this.scopes.get(scope);
+        if (state)
+            this.clearActiveTurn(state);
+    }
+    routeTurnOwned(method, params, allowBuffer) {
+        const threadId = this.stringField(params, 'threadId');
+        const turnId = this.stringField(params, 'turnId');
+        if (!threadId || !turnId) {
+            this.emitUnrouted(method, params, 'malformed-turn-owner');
+            return;
+        }
+        const scope = this.resolveTurnOwner(threadId, turnId);
+        if (scope) {
+            this.emitLaneNotification(scope, method, params, { threadId, turnId });
+            return;
+        }
+        if (allowBuffer && this.shouldBufferTurn(threadId)) {
+            this.bufferNotification(method, params, threadId, turnId);
+        }
+        else {
+            this.emitUnrouted(method, params, 'turn-owner-mismatch');
+        }
+    }
+    routeNullableTurn(method, params, allowBuffer) {
+        const threadId = this.stringField(params, 'threadId');
+        if (!threadId || !Object.hasOwn(params, 'turnId')) {
+            this.emitUnrouted(method, params, 'malformed-nullable-turn-owner');
+            return;
+        }
+        if (params['turnId'] === null) {
+            this.routeThreadIdentity(method, params, threadId, allowBuffer);
+            return;
+        }
+        const turnId = this.stringField(params, 'turnId');
+        if (!turnId) {
+            this.emitUnrouted(method, params, 'malformed-nullable-turn-owner');
+            return;
+        }
+        const scope = this.resolveTurnOwner(threadId, turnId);
+        if (scope) {
+            this.emitLaneNotification(scope, method, params, { threadId, turnId });
+        }
+        else if (allowBuffer && this.shouldBufferTurn(threadId)) {
+            this.bufferNotification(method, params, threadId, turnId);
+        }
+        else {
+            this.emitUnrouted(method, params, 'turn-owner-mismatch');
+        }
+    }
+    routeThreadStarted(params, allowBuffer) {
+        const thread = this.recordField(params, 'thread');
+        const threadId = thread ? this.stringField(thread, 'id') : null;
+        if (!threadId) {
+            this.emitUnrouted('thread/started', params, 'malformed-thread-lifecycle');
+            return;
+        }
+        this.routeThreadIdentity('thread/started', params, threadId, allowBuffer);
+    }
+    routeThreadOwned(method, params, allowBuffer) {
+        const threadId = this.stringField(params, 'threadId');
+        if (!threadId) {
+            this.emitUnrouted(method, params, 'malformed-thread-owner');
+            return;
+        }
+        this.routeThreadIdentity(method, params, threadId, allowBuffer);
+    }
+    routeThreadIdentity(method, params, threadId, allowBuffer) {
+        const scope = this.threadToScope.get(threadId);
+        const state = scope ? this.scopes.get(scope) : undefined;
+        if (scope && state?.threadId === threadId) {
+            this.emitLaneNotification(scope, method, params, { threadId, turnId: null });
+            if (method === 'thread/closed' || method === 'thread/deleted') {
+                const pendingKind = state.pendingOperation?.kind;
+                this.clearScopeBinding(state);
+                if (state.operation !== 'terminal')
+                    state.operation = 'idle';
+                if (pendingKind) {
+                    this.failPendingOperation(scope, new Error(`Thread ${threadId} ${method === 'thread/closed' ? 'closed' : 'was deleted'} during ${pendingKind}`));
+                }
+            }
+            return;
+        }
+        if (allowBuffer && this.hasPendingBinding()) {
+            this.bufferNotification(method, params, threadId, null);
+        }
+        else {
+            this.emitUnrouted(method, params, 'thread-owner-mismatch');
+        }
+    }
+    routeNullableThread(method, params, allowBuffer) {
+        if (!Object.hasOwn(params, 'threadId')) {
+            this.emitUnrouted(method, params, 'malformed-nullable-thread-owner');
+            return;
+        }
+        if (params['threadId'] === null) {
+            this.emitHostNotification(method, params);
+            return;
+        }
+        const threadId = this.stringField(params, 'threadId');
+        if (!threadId) {
+            this.emitUnrouted(method, params, 'malformed-nullable-thread-owner');
+            return;
+        }
+        this.routeThreadIdentity(method, params, threadId, allowBuffer);
+    }
+    resolveTurnOwner(threadId, turnId) {
+        const threadScope = this.threadToScope.get(threadId);
+        const turnScope = this.turnToScope.get(turnId);
+        if (!threadScope || threadScope !== turnScope)
+            return null;
+        const state = this.scopes.get(threadScope);
+        if (state?.threadId !== threadId || state.activeTurnId !== turnId)
+            return null;
+        return threadScope;
+    }
+    shouldBufferTurn(threadId) {
+        const scope = this.threadToScope.get(threadId);
+        if (!scope)
+            return false;
+        const state = this.scopes.get(scope);
+        return state?.threadId === threadId
+            && state.operation === 'turn'
+            && state.pendingOperation?.kind === 'turn';
+    }
+    emitLaneNotification(scope, method, params, owner) {
+        this.recordScopedNotification(scope, method, params, owner);
+        this.emit(`notification:${scope}`, method, params, owner);
+    }
+    emitHostNotification(method, params) {
+        this.recordHostNotification(method, params);
+        this.emit('host-notification', method, params);
+    }
+    emitUnrouted(method, params, reason) {
+        this.emit('unrouted-notification', { method, params, reason });
+    }
+    ensureScopedNotificationHandoff(scope) {
+        const current = this.scopedNotificationHandoffs.get(scope);
+        if (current)
+            return current;
+        const handoff = { consumers: 0, replaying: false, buffer: [] };
+        this.scopedNotificationHandoffs.set(scope, handoff);
+        return handoff;
+    }
+    recordScopedNotification(scope, method, params, owner) {
+        const handoff = this.ensureScopedNotificationHandoff(scope);
+        if (handoff.consumers > 0 && !handoff.replaying)
+            return;
+        this.bufferHandoffNotification(handoff, { method, params, owner });
+    }
+    recordHostNotification(method, params) {
+        const handoff = this.hostNotificationHandoff;
+        if (handoff.consumers > 0 && !handoff.replaying)
+            return;
+        this.bufferHandoffNotification(handoff, { method, params, owner: undefined });
+    }
+    bufferHandoffNotification(handoff, entry, diagnoseOverflow = true) {
+        if (handoff.buffer.length >= this.pendingNotificationLimit) {
+            const evicted = handoff.buffer.shift();
+            if (evicted && diagnoseOverflow) {
+                this.emitUnrouted(evicted.method, evicted.params, 'pre-listener-overflow');
+            }
+        }
+        handoff.buffer.push(entry);
+    }
+    replayNotificationHandoff(handoff, deliver, dispose) {
+        handoff.replaying = true;
+        try {
+            while (handoff.buffer.length > 0) {
+                const entry = handoff.buffer.shift();
+                try {
+                    deliver(entry.method, entry.params, entry.owner);
+                }
+                catch (err) {
+                    if (handoff.buffer.length >= this.pendingNotificationLimit) {
+                        const evicted = handoff.buffer.shift();
+                        if (evicted) {
+                            this.emitUnrouted(evicted.method, evicted.params, 'pre-listener-overflow');
+                        }
+                    }
+                    handoff.buffer.unshift(entry);
+                    dispose();
+                    throw err;
+                }
+            }
+        }
+        finally {
+            handoff.replaying = false;
+        }
+    }
+    // ─── Bounded pending notification replay ─────────
+    bufferNotification(method, params, threadId, turnId) {
+        this.expirePendingNotifications();
+        const terminal = TERMINAL_NOTIFICATION_METHODS.has(method);
+        if (this.pendingNotifications.length >= this.pendingNotificationLimit) {
+            const oldestNonTerminal = this.pendingNotifications.findIndex((entry) => !entry.terminal);
+            if (oldestNonTerminal >= 0) {
+                const [evicted] = this.pendingNotifications.splice(oldestNonTerminal, 1);
+                if (evicted)
+                    this.diagnoseBuffered(evicted, 'capacity-evicted');
+            }
+            else if (terminal) {
+                this.failBufferedOperation(this.makeBufferedNotification(method, params, threadId, turnId, terminal), 'capacity-terminal-full');
+                return;
+            }
+            else {
+                this.emitUnrouted(method, params, 'capacity-terminal-reserved');
+                return;
+            }
+        }
+        this.pendingNotifications.push(this.makeBufferedNotification(method, params, threadId, turnId, terminal));
+        this.schedulePendingExpiry();
+    }
+    makeBufferedNotification(method, params, threadId, turnId, terminal) {
+        const candidateScopes = new Set();
+        if (threadId) {
+            const scope = this.threadToScope.get(threadId);
+            if (scope)
+                candidateScopes.add(scope);
+        }
+        if (candidateScopes.size === 0) {
+            for (const state of this.scopes.values()) {
+                if (state.pendingOperation)
+                    candidateScopes.add(state.scope);
+            }
+        }
+        return {
+            sequence: this.pendingNotificationSequence++,
+            receivedAt: Date.now(),
+            method,
+            params,
+            threadId,
+            turnId,
+            terminal,
+            candidateScopes,
+        };
+    }
+    replayPendingForScope(scope) {
+        this.expirePendingNotifications();
+        const state = this.scopes.get(scope);
+        if (!state?.threadId)
+            return;
+        const replay = this.pendingNotifications
+            .filter((entry) => {
+            if (entry.threadId !== state.threadId)
+                return false;
+            if (!entry.turnId)
+                return true;
+            return entry.method === 'turn/started' || entry.turnId === state.activeTurnId;
+        })
+            .sort((a, b) => a.sequence - b.sequence);
+        if (replay.length === 0)
+            return;
+        const replayed = new Set(replay);
+        this.pendingNotifications = this.pendingNotifications.filter((entry) => !replayed.has(entry));
+        for (const entry of replay)
+            this.routeNotification(entry.method, entry.params, false);
+        this.schedulePendingExpiry();
+    }
+    expirePendingNotifications() {
+        if (this.pendingNotifications.length === 0) {
+            this.clearPendingTimer();
+            return;
+        }
+        const cutoff = Date.now() - this.pendingNotificationTtlMs;
+        const expired = this.pendingNotifications.filter((entry) => entry.receivedAt <= cutoff);
+        if (expired.length === 0)
+            return;
+        const expiredSet = new Set(expired);
+        this.pendingNotifications = this.pendingNotifications.filter((entry) => !expiredSet.has(entry));
+        for (const entry of expired) {
+            if (entry.terminal)
+                this.failBufferedOperation(entry, 'ttl-terminal-expired');
+            else
+                this.diagnoseBuffered(entry, 'ttl-expired');
+        }
+        this.schedulePendingExpiry();
+    }
+    schedulePendingExpiry() {
+        this.clearPendingTimer();
+        if (this.pendingNotifications.length === 0)
+            return;
+        const oldest = Math.min(...this.pendingNotifications.map((entry) => entry.receivedAt));
+        const delay = Math.max(0, oldest + this.pendingNotificationTtlMs - Date.now());
+        this.pendingNotificationTimer = setTimeout(() => {
+            this.pendingNotificationTimer = null;
+            this.expirePendingNotifications();
+            this.schedulePendingExpiry();
+        }, delay);
+        this.pendingNotificationTimer.unref();
+    }
+    clearPendingTimer() {
+        if (!this.pendingNotificationTimer)
+            return;
+        clearTimeout(this.pendingNotificationTimer);
+        this.pendingNotificationTimer = null;
+    }
+    failBufferedOperation(entry, reason) {
+        const error = new Error(`Pending Codex notification ${entry.method} could not be preserved (${reason})`);
+        let failed = false;
+        for (const scope of entry.candidateScopes) {
+            failed = this.failPendingOperation(scope, error) || failed;
+        }
+        if (!failed) {
+            for (const state of this.scopes.values()) {
+                if (state.pendingOperation) {
+                    failed = this.failPendingOperation(state.scope, error) || failed;
+                }
+            }
+        }
+        this.diagnoseBuffered(entry, failed ? reason : `${reason}-no-operation`);
+    }
+    diagnoseBuffered(entry, reason) {
+        this.emitUnrouted(entry.method, entry.params, reason);
+    }
+    removeBufferedForScope(scope) {
+        this.pendingNotifications = this.pendingNotifications.filter((entry) => {
+            entry.candidateScopes.delete(scope);
+            return entry.candidateScopes.size > 0;
+        });
+        this.schedulePendingExpiry();
+    }
+    hasPendingBinding() {
+        return [...this.scopes.values()].some((state) => state.pendingOperation?.kind === 'binding');
+    }
+    // ─── Transport and process lifecycle ─────────────
     rejectAllPending(reason) {
         if (this.pending.size === 0)
             return;
@@ -218,6 +1051,7 @@ export class CodexAppClient extends EventEmitter {
         this.pending.clear();
     }
     request(method, params) {
+        this.assertReusable();
         return new Promise((resolve, reject) => {
             const id = this.nextId++;
             this.pending.set(id, { resolve, reject });
@@ -242,54 +1076,46 @@ export class CodexAppClient extends EventEmitter {
             return false;
         }
     }
-    reasoningConfig() {
+    reasoningConfig(state) {
         return {
-            ...(this.effort ? { model_reasoning_effort: this.effort } : {}),
+            ...(state.effort ? { model_reasoning_effort: state.effort } : {}),
             model_reasoning_summary: 'detailed',
             hide_agent_reasoning: false,
             show_raw_agent_reasoning: true,
-            service_tier: this.fastMode ? 'fast' : 'default',
+            service_tier: state.fastMode ? 'fast' : 'default',
         };
     }
     handleLine(line) {
         if (!line.trim())
             return;
+        let msg;
         try {
-            const msg = JSON.parse(line);
-            if (msg.id != null && this.pending.has(msg.id)) {
-                const handler = this.pending.get(msg.id);
-                this.pending.delete(msg.id);
-                if (msg.error) {
-                    handler.reject(new Error(`JSON-RPC error ${msg.error.code}: ${msg.error.message}`));
-                }
-                else {
-                    handler.resolve(msg.result);
-                }
-                return;
-            }
-            if (msg.id != null && msg.method) {
-                this.handleServerRequest(msg.id, msg.method, msg.params || {});
-                return;
-            }
-            if (msg.method) {
-                if (msg.method === 'turn/started') {
-                    this.setActiveTurnId(msg.params?.turn?.id ?? null);
-                }
-                else if (msg.method === 'turn/completed') {
-                    this.setActiveTurnId(null);
-                }
-                this.emit('notification', msg.method, msg.params || {});
-                if (msg.method === 'error') {
-                    this.emit('server-error', msg.params || {});
-                }
-                else {
-                    this.emit(msg.method, msg.params || {});
-                }
-                return;
-            }
+            msg = JSON.parse(line);
         }
         catch {
             this.emit('parse_error', line);
+            return;
+        }
+        const id = msg['id'];
+        const method = typeof msg['method'] === 'string' ? msg['method'] : null;
+        if (id != null && typeof id === 'number' && this.pending.has(id)) {
+            const handler = this.pending.get(id);
+            this.pending.delete(id);
+            const error = this.recordField(msg, 'error');
+            if (error) {
+                handler.reject(new Error(`JSON-RPC error ${String(error['code'] ?? '')}: ${String(error['message'] ?? '')}`));
+            }
+            else {
+                handler.resolve(msg['result']);
+            }
+            return;
+        }
+        if (id != null && method) {
+            this.handleServerRequest(typeof id === 'number' || typeof id === 'string' ? id : String(id), method, this.recordField(msg, 'params') ?? {});
+            return;
+        }
+        if (method) {
+            this.routeNotification(method, this.recordField(msg, 'params') ?? {});
         }
     }
     handleServerRequest(id, method, params) {
@@ -307,19 +1133,74 @@ export class CodexAppClient extends EventEmitter {
         const result = declineResponses[method] || {};
         this.trySend({ jsonrpc: '2.0', id, result });
     }
-    setActiveTurnId(id) {
-        this.activeTurnId = id;
-        if (id && this.pendingInterrupt) {
-            this.pendingInterrupt = false;
-            void this.request('turn/interrupt', { threadId: this.threadId, turnId: id })
-                .catch((err) => {
-                if (!isTerminalInterruptRaceError(err)) {
-                    this.emit('interrupt-failed', err);
-                }
-            });
+    async sendInterrupt(state, turnId) {
+        try {
+            await this.request('turn/interrupt', { threadId: state.threadId, turnId });
+        }
+        catch (err) {
+            const error = err;
+            if (isTerminalInterruptRaceError(error))
+                return;
+            this.emit(`interrupt-failed:${state.scope}`, error);
+            throw error;
+        }
+    }
+    handleProcessError(err) {
+        if (!this.beginProcessDeath(`Process error: ${err.message}`))
+            return;
+        try {
+            this.emit('error', err);
+        }
+        finally {
+            this.finalizeProcessDeath();
+        }
+    }
+    handleProcessExit(code, signal) {
+        if (!this.beginProcessDeath('Process exited'))
+            return;
+        try {
+            this.emit('exit', code, signal);
+        }
+        finally {
+            this.finalizeProcessDeath();
         }
-        if (!id)
-            this.pendingInterrupt = false;
+    }
+    beginProcessDeath(reason) {
+        if (this.terminal)
+            return false;
+        this.terminal = true;
+        this.rejectAllPending(reason);
+        const error = new Error(reason);
+        for (const state of this.scopes.values()) {
+            if (state.pendingOperation && !state.pendingOperation.failed) {
+                state.pendingOperation.failed = error;
+                state.pendingOperation.reject(error);
+            }
+            state.operation = 'terminal';
+        }
+        return true;
+    }
+    finalizeProcessDeath() {
+        for (const scope of [...this.scopes.keys()])
+            this.removeScope(scope);
+        this.threadToScope.clear();
+        this.turnToScope.clear();
+        this.pendingNotifications = [];
+        this.scopedNotificationHandoffs.clear();
+        this.hostNotificationHandoff = { consumers: 0, replaying: false, buffer: [] };
+        this.clearPendingTimer();
+        this.scopeDisposers.clear();
+        this.removeAllListeners();
+    }
+    stringField(record, key) {
+        const value = record[key];
+        return typeof value === 'string' && value.length > 0 ? value : null;
+    }
+    recordField(record, key) {
+        const value = record[key];
+        return value !== null && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : null;
     }
 }
 //# sourceMappingURL=codex-app-client.js.map