@parall/codex-agent 1.58.2 → 1.60.0

package/src/foreign-threads.ts

@@ -0,0 +1,187 @@
+import type { GatewayLogger, RuntimeActivityPort } from '@parall/agent-core';
+import { extractThreadInfo } from './app-server-protocol.js';
+import { CodexRuntimeTurn } from './runtime-turn.js';
+import type { CodexSessionManager } from './session-manager.js';
+import type { TurnEventEnvelope } from './turn-sink.js';
+
+/**
+ * Threads the app-server runs that no dispatch opened — `spawn_agent`
+ * subagent threads (`thread/started` with `threadSource: "subAgent"`), or a
+ * thread whose turn showed up with no `thread/started` (bridge restarted
+ * mid-subagent). Each is a child session of its parent thread's session;
+ * every `turn/started`…`turn/completed` on it is a RuntimeInitiatedTurn
+ * (runtime-initiated-turns-design.md §5).
+ */
+export type ForeignThread = {
+  threadId: string;
+  sessionKey: string;
+  parentThreadId?: string;
+  parentSessionKey: string;
+  nickname?: string;
+  role?: string;
+  turn?: CodexRuntimeTurn;
+};
+
+export type ForeignThreadHost = {
+  sessionManager: CodexSessionManager;
+  log?: GatewayLogger;
+  /** Turns opened and child sessions closed go to the gateway through it. */
+  activity: RuntimeActivityPort;
+  /** A subagent turn ended — a deferred restart may apply now. */
+  afterTurnClosed(): void;
+};
+
+export class ForeignThreadRegistry {
+  private readonly threads = new Map<string, ForeignThread>();
+
+  constructor(private readonly host: ForeignThreadHost) {}
+
+  /** Live (registered, not closed) subagent threads. */
+  get size(): number {
+    return this.threads.size;
+  }
+
+  openTurns(): number {
+    let count = 0;
+    for (const thread of this.threads.values()) if (thread.turn) count += 1;
+    return count;
+  }
+
+  /**
+   * Notifications for a thread no dispatch owns. Returns false when the
+   * caller should keep treating the frame as unroutable.
+   */
+  route(method: string, params: unknown, threadId: string): boolean {
+    if (method === 'thread/started') {
+      if (this.host.sessionManager.getSessionKey(threadId) || this.threads.has(threadId)) {
+        return true;
+      }
+      const info = extractThreadInfo(params);
+      // Only subagent spawns become child sessions; our own thread/start and
+      // thread/fork echoes (source appServer) are bound by their responses.
+      if (!info || info.source !== 'subAgent') return true;
+      this.register(info);
+      return true;
+    }
+    let thread = this.threads.get(threadId);
+    if (method === 'thread/closed' || method === 'thread/archived' || method === 'thread/deleted') {
+      if (!thread) return false;
+      this.close(thread, method.slice('thread/'.length));
+      return true;
+    }
+    if (!thread) {
+      // A turn on a thread we never saw start: our own thread without a
+      // sink is a genuine orphan (keep the warn); anything else is adopted
+      // under the main session (bridge restarted mid-subagent).
+      if (this.host.sessionManager.getSessionKey(threadId)) return false;
+      if (method !== 'turn/started' && method !== 'turn/completed' && !method.startsWith('item/')) {
+        return false;
+      }
+      thread = this.register({ id: threadId });
+    }
+    if (method === 'turn/started') {
+      if (thread.turn) thread.turn.touch();
+      else this.openTurn(thread);
+      return true;
+    }
+    if (!thread.turn) {
+      if (method !== 'turn/completed' && !method.startsWith('item/')) return true;
+      this.openTurn(thread);
+    }
+    const turn = thread.turn as CodexRuntimeTurn;
+    turn.sink.touchActivity();
+    for (const event of turn.sink.mapper.map(method, params)) {
+      turn.sink.push({ kind: 'runtime', event });
+    }
+    if (method === 'turn/completed') {
+      this.endTurn(thread, { kind: 'turn_end', threadId });
+      this.host.log?.info?.(
+        `runtime-initiated turn ${turn.groupKey} on subagent thread ${threadId} completed`,
+      );
+    }
+    return true;
+  }
+
+  /** Subagent threads die with the app-server: end open turns, close child sessions. */
+  dropAll(reason: string): void {
+    for (const thread of [...this.threads.values()]) {
+      this.close(thread, reason);
+    }
+  }
+
+  private register(info: {
+    id: string;
+    parentThreadId?: string;
+    nickname?: string;
+    role?: string;
+  }): ForeignThread {
+    // A subagent may itself spawn subagents: resolve the parent against the
+    // live foreign threads first, then main / fork threads, else main.
+    const parentSessionKey =
+      (info.parentThreadId
+        ? (this.threads.get(info.parentThreadId)?.sessionKey ??
+          this.host.sessionManager.getSessionKey(info.parentThreadId))
+        : undefined) ?? this.host.sessionManager.mainSessionKey;
+    const thread: ForeignThread = {
+      threadId: info.id,
+      sessionKey: `codex-sub:${info.id}`,
+      parentThreadId: info.parentThreadId,
+      parentSessionKey,
+      nickname: info.nickname,
+      role: info.role,
+    };
+    this.threads.set(info.id, thread);
+    this.host.log?.info?.(
+      `subagent thread ${info.id} registered (parent ${info.parentThreadId ?? 'unknown'} → ${parentSessionKey}${info.nickname ? `, ${info.nickname}` : ''}${info.role ? ` / ${info.role}` : ''}); ${this.threads.size} live`,
+    );
+    return thread;
+  }
+
+  private openTurn(thread: ForeignThread): void {
+    const turn = new CodexRuntimeTurn(
+      thread.sessionKey,
+      {
+        kind: 'subagent',
+        threadId: thread.threadId,
+        ...(thread.parentThreadId ? { parentThreadId: thread.parentThreadId } : {}),
+        ...(thread.nickname ? { nickname: thread.nickname } : {}),
+        ...(thread.role ? { role: thread.role } : {}),
+      },
+      {
+        parentSessionKey: thread.parentSessionKey,
+        onDetach: (reason) => {
+          if (thread.turn !== turn) return;
+          this.endTurn(thread, { kind: 'error', message: `subagent turn detached: ${reason}` });
+        },
+      },
+    );
+    thread.turn = turn;
+    this.host.log?.info?.(
+      `runtime-initiated turn ${turn.groupKey} opened on subagent thread ${thread.threadId}`,
+    );
+    this.host.activity.surfaceTurn(turn);
+  }
+
+  /** The thread's open turn is over: last envelope, sink closed, restart re-driven. */
+  private endTurn(thread: ForeignThread, last: TurnEventEnvelope): void {
+    const turn = thread.turn;
+    if (!turn) return;
+    thread.turn = undefined;
+    turn.sink.push(last);
+    turn.sink.close();
+    this.host.afterTurnClosed();
+  }
+
+  private close(thread: ForeignThread, reason: string): void {
+    if (this.threads.get(thread.threadId) !== thread) return;
+    this.threads.delete(thread.threadId);
+    this.endTurn(thread, {
+      kind: 'error',
+      message: `subagent thread ${thread.threadId} ${reason}`,
+    });
+    this.host.log?.info?.(
+      `subagent thread ${thread.threadId} ${reason}; ${this.threads.size} live`,
+    );
+    this.host.activity.emit({ kind: 'session_closed', sessionKey: thread.sessionKey, reason });
+  }
+}

package/src/index.ts

@@ -20,6 +20,7 @@ import {
   llmSource,
   identityFromMe,
   initAgentTelemetry,
+  resolveServiceVersion,
 } from '@parall/agent-core';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import {
@@ -74,7 +75,11 @@ function resolveProviderEnv(): void {
 async function main() {
   // Before any fetch: long-lived HTTP connections for every bridge→api call.
   configureHttpKeepAlive();
-  const telemetry = await initAgentTelemetry('parall-codex-agent', 'codex');
+  const telemetry = await initAgentTelemetry('parall-codex-agent', 'codex', {
+    apiUrl: process.env.PRLL_API_URL,
+    apiKey: process.env.PRLL_API_KEY,
+    serviceVersion: resolveServiceVersion(import.meta.url),
+  });
   activeLog = createOtelLogger('agent', 'codex-agent');
   try {
     resolveProviderEnv();
@@ -291,6 +296,12 @@ async function main() {
       onSessionStale: () => {
         sessionManager.clearMainThread();
       },
+      // The app-server outlives one dispatch (subagent threads keep running
+      // after the parent turn): stop it INSIDE the gateway's shutdown so the
+      // runtime turns it ends still land their steps and idle/close writes
+      // before the step and lifecycle flushes — the finally below runs after
+      // those windows have closed.
+      onBeforeDisconnect: () => adapter.stop(),
     });
 
     const abortController = new AbortController();

package/src/injection-registry.ts

@@ -0,0 +1,100 @@
+/**
+ * Bookkeeping for mid-turn steer injections (`turn/steer`), per session key.
+ *
+ * Codex gives no per-input runtime receipt: a successful `turn/steer` only
+ * says the app-server accepted the text into the running turn. So each
+ * injection carries two independent facts with two different owners:
+ *
+ *   - settled — the turn it was steered into has ended (the adapter's own
+ *     dispatch() generator closing on turn/completed, an interrupt, or the
+ *     subprocess dying). Only an UNSETTLED injection may hold a lane's
+ *     complete open (DispatchAdapter.hasUnsettledInjections).
+ *   - drained — the gateway consumed the buffered copy that backs it: either
+ *     the already-rendered drain branch (acknowledgeDiscardedInjection) or a
+ *     group dispatch() whose inputLifecycle lists the WorkItem. Until then the
+ *     copy still owes frame-boundary bookkeeping (hasPendingInjections).
+ *
+ * Entries are keyed by WorkItem id — the deliveryKey the gateway uses on both
+ * sides — never counted. The pre-PFB-84 design kept a per-session COUNT and
+ * made the next dispatch() skip turn/start while it was non-zero: a copy the
+ * gateway discarded without a dispatch() never decremented it, so the count
+ * leaked onto the NEXT unrelated message, whose dispatch then ran no turn and
+ * was complete(ok)-swept as no_action — the model never saw it.
+ */
+export class CodexInjectionRegistry {
+  private readonly sessions = new Map<string, Map<string, InjectionState>>();
+
+  /** Record a successful steer. `deliveryKey` may join several WorkItem ids with ','. */
+  register(sessionKey: string, deliveryKey: string): void {
+    let entries = this.sessions.get(sessionKey);
+    if (!entries) {
+      entries = new Map();
+      this.sessions.set(sessionKey, entries);
+    }
+    for (const id of splitDeliveryKey(deliveryKey)) {
+      if (!entries.has(id)) entries.set(id, { settled: false, drained: false });
+    }
+  }
+
+  /** The buffered copies behind these WorkItems drained (group dispatch or discard). */
+  markDrained(sessionKey: string, deliveryKey: string): void {
+    const entries = this.sessions.get(sessionKey);
+    if (!entries) return;
+    for (const id of splitDeliveryKey(deliveryKey)) {
+      const entry = entries.get(id);
+      if (!entry) continue;
+      entry.drained = true;
+      if (entry.settled) entries.delete(id);
+    }
+    if (entries.size === 0) this.sessions.delete(sessionKey);
+  }
+
+  /** The turn every injection of this session was steered into has ended. */
+  settleAll(sessionKey: string): void {
+    const entries = this.sessions.get(sessionKey);
+    if (!entries) return;
+    for (const [id, entry] of entries) {
+      entry.settled = true;
+      if (entry.drained) entries.delete(id);
+    }
+    if (entries.size === 0) this.sessions.delete(sessionKey);
+  }
+
+  /** An injection whose buffered copy has not drained yet (bookkeeping owed). */
+  hasPending(sessionKey: string): boolean {
+    const entries = this.sessions.get(sessionKey);
+    if (!entries) return false;
+    for (const entry of entries.values()) {
+      if (!entry.drained) return true;
+    }
+    return false;
+  }
+
+  /** An injection whose turn is still running (the only state that may defer a complete). */
+  hasUnsettled(sessionKey: string): boolean {
+    const entries = this.sessions.get(sessionKey);
+    if (!entries) return false;
+    for (const entry of entries.values()) {
+      if (!entry.settled) return true;
+    }
+    return false;
+  }
+
+  /** Drop every entry (turn aborted / subprocess gone): nothing is owed anymore. */
+  clear(sessionKey?: string): void {
+    if (sessionKey === undefined) {
+      this.sessions.clear();
+      return;
+    }
+    this.sessions.delete(sessionKey);
+  }
+}
+
+type InjectionState = { settled: boolean; drained: boolean };
+
+function splitDeliveryKey(deliveryKey: string): string[] {
+  return deliveryKey
+    .split(',')
+    .map((id) => id.trim())
+    .filter((id) => id.length > 0);
+}

package/src/instructions-refresh.ts

@@ -80,7 +80,7 @@ export type RefreshOutcome =
   // turn/start rejection rotate the persisted main thread in this state.
   | 'stalled';
 
-class CompactionStalledError extends Error {}
+export class CompactionStalledError extends Error {}
 
 export class MainThreadInstructionsRefresher {
   /**
@@ -188,23 +188,14 @@ export class MainThreadInstructionsRefresher {
       return 'adopted-baseline';
     }
     if (this.compactUnsupported) return 'unsupported';
-    // The waiter registers its notification tap BEFORE the request goes out:
-    // the response and the compaction-turn notifications can arrive in one
-    // stdout chunk, and the client's line loop dispatches notifications
-    // synchronously — a tap registered only after `await sendRequest` resolves
-    // (a queued microtask) would miss every one of them and hang on the
-    // timeout.
-    const compaction = this.watchForCompaction(client, taps, threadId);
     try {
-      await client.sendRequest('thread/compact/start', { threadId });
-      await compaction.done;
+      await this.runCompaction({ client, taps, threadId });
       this.opts.sessionManager.recordEffectiveInstructionsSha(sessionKey, canonicalSha);
       log?.info?.(
         `platform instructions refreshed on persisted thread ${threadId} (compaction rebuilt initial context from the resumed configuration)`,
       );
       return 'refreshed';
     } catch (err) {
-      compaction.cancel();
       if (err instanceof CompactionStalledError) {
         log?.warn?.(
           `platform instructions refresh stalled (${errToString(err)}); bouncing the subprocess before the next turn`,
@@ -212,7 +203,6 @@ export class MainThreadInstructionsRefresher {
         return 'stalled';
       }
       if (err instanceof JsonRpcError && err.code === JSON_RPC_METHOD_NOT_FOUND) {
-        this.compactUnsupported = true;
         log?.warn?.(
           'thread/compact/start not supported by this codex CLI; the persisted thread keeps its previous platform instructions until it is replaced or the CLI is upgraded (tools still refresh live via the capability shim dir)',
         );
@@ -225,6 +215,57 @@ export class MainThreadInstructionsRefresher {
     }
   }
 
+  /** True once this subprocess rejected thread/compact/start with -32601. */
+  isCompactUnsupported(): boolean {
+    return this.compactUnsupported;
+  }
+
+  /**
+   * The unconditional compaction primitive — one `thread/compact/start`
+   * awaited to its turn close — shared by the instructions refresh (which
+   * decides WHETHER to run it by sha) and the idle auto-compact (which runs
+   * it whenever the server asks). Throws like the refresh's inner path:
+   * CompactionStalledError past budget/abort + interrupt grace, JsonRpcError
+   * -32601 (also latches compactUnsupported for this subprocess), or a plain
+   * Error for a turn that closed without compacting.
+   */
+  async runCompaction(args: {
+    client: JsonRpcStdioClient;
+    taps: NotificationTapSource;
+    threadId: string;
+    signal?: AbortSignal;
+  }): Promise<void> {
+    const { client, taps, threadId, signal } = args;
+    // The waiter registers its notification tap BEFORE the request goes out:
+    // the response and the compaction-turn notifications can arrive in one
+    // stdout chunk, and the client's line loop dispatches notifications
+    // synchronously — a tap registered only after `await sendRequest` resolves
+    // (a queued microtask) would miss every one of them and hang on the
+    // timeout.
+    const compaction = this.watchForCompaction(client, taps, threadId, signal);
+    try {
+      await client.sendRequest('thread/compact/start', { threadId });
+      await compaction.done;
+    } catch (err) {
+      compaction.cancel();
+      if (err instanceof JsonRpcError && err.code === JSON_RPC_METHOD_NOT_FOUND) {
+        this.compactUnsupported = true;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * A compaction that completed outside the refresh path (idle auto-compact)
+   * rebuilt the model-visible context from the canonical configuration: the
+   * effective plane now equals whatever this process opened the thread with.
+   */
+  recordCompacted(sessionKey: string, threadId: string): void {
+    const canonical = this.canonicalByThread.get(threadId);
+    if (canonical === undefined) return;
+    this.opts.sessionManager.recordEffectiveInstructionsSha(sessionKey, sha256Hex(canonical));
+  }
+
   /**
    * Compaction runs as its own turn on the thread:
    *   turn/started → item/started{contextCompaction} →
@@ -250,6 +291,7 @@ export class MainThreadInstructionsRefresher {
     client: JsonRpcStdioClient,
     taps: NotificationTapSource,
     threadId: string,
+    signal?: AbortSignal,
   ): { done: Promise<void>; cancel: () => void } {
     const timeoutMs = this.opts.compactTimeoutMs ?? DEFAULT_COMPACT_TIMEOUT_MS;
     const graceMs = this.opts.interruptGraceMs ?? COMPACT_INTERRUPT_GRACE_MS;
@@ -261,17 +303,24 @@ export class MainThreadInstructionsRefresher {
       let settled = false;
       let unregister = () => {};
       let graceTimer: NodeJS.Timeout | undefined;
+      const onAbort = () => expire('aborted by the caller');
       const finish = (err?: Error) => {
         if (settled) return;
         settled = true;
         clearTimeout(timer);
         if (graceTimer) clearTimeout(graceTimer);
+        signal?.removeEventListener('abort', onAbort);
         unregister();
         if (err) reject(err);
         else resolve();
       };
-      const timer = setTimeout(() => {
+      // Budget exhausted (timer) or the caller aborted (idle auto-compact
+      // budget): interrupt best-effort and hold the grace for the turn to
+      // close; past it the turn may still be running → stalled.
+      const expire = (why: string) => {
+        if (settled || interrupted) return;
         interrupted = true;
+        clearTimeout(timer);
         if (compactionTurnId) {
           // Best-effort and non-lethal: an unanswered interrupt must expire
           // with the grace window, not arm the client's default assume-hung
@@ -288,12 +337,15 @@ export class MainThreadInstructionsRefresher {
           () =>
             finish(
               new CompactionStalledError(
-                `compaction did not complete within ${timeoutMs}ms (interrupt grace elapsed; the compaction turn may still be running)`,
+                `compaction did not complete (${why}; interrupt grace elapsed; the compaction turn may still be running)`,
               ),
             ),
           graceMs,
         );
-      }, timeoutMs);
+      };
+      const timer = setTimeout(() => expire(`within ${timeoutMs}ms`), timeoutMs);
+      if (signal?.aborted) onAbort();
+      else signal?.addEventListener('abort', onAbort, { once: true });
       // Cancellation resolves (never rejects): the caller cancels only when
       // the request itself already failed, and that error is what it reports.
       cancel = () => finish();
@@ -305,8 +357,28 @@ export class MainThreadInstructionsRefresher {
           // notifications can arrive after that; waiting out the timeout
           // would stall the dispatch for the full budget on a dead client.
           if (notificationThreadId === undefined || notificationThreadId === threadId) {
-            const msg = (params as { message?: unknown })?.message;
-            finish(new Error(`app-server error during compaction: ${String(msg ?? 'unknown')}`));
+            // v2 ErrorNotification: { threadId?, turnId?, error: { message,
+            // codexErrorInfo? }, willRetry }. The adapter's synthetic
+            // disposal broadcast still carries a top-level `message`.
+            const p = params as {
+              message?: unknown;
+              willRetry?: unknown;
+              error?: { message?: unknown; codexErrorInfo?: unknown };
+            };
+            // A retryable error keeps the turn alive — codex retries the
+            // model call itself and the compaction still completes or fails
+            // through turn/completed; bailing here would report a failure
+            // for a compaction that is still running.
+            if (p?.willRetry === true) return;
+            const msg = p?.error?.message ?? p?.message;
+            const info = p?.error?.codexErrorInfo;
+            const infoText =
+              info == null ? '' : ` (${typeof info === 'string' ? info : JSON.stringify(info)})`;
+            finish(
+              new Error(
+                `app-server error during compaction: ${String(msg ?? 'unknown')}${infoText}`,
+              ),
+            );
           }
           return;
         }
@@ -326,7 +398,7 @@ export class MainThreadInstructionsRefresher {
             finish(
               new Error(
                 interrupted
-                  ? `compaction did not complete within ${timeoutMs}ms (turn closed after interrupt)`
+                  ? 'compaction did not complete within budget (turn closed after interrupt)'
                   : `compaction turn ended without completing (status=${status ?? 'unknown'})`,
               ),
             );

package/src/runtime-turn.ts

@@ -0,0 +1,64 @@
+import {
+  projectRuntimeEvent,
+  type RuntimeEvent,
+  RuntimeTurnBase,
+  type RuntimeTurnTrigger,
+} from '@parall/agent-core';
+import { TurnSink } from './turn-sink.js';
+
+/**
+ * One turn of a thread the app-server runs that no dispatch started — a
+ * `spawn_agent` subagent thread. Its notifications are routed into `sink`
+ * by the adapter; the gateway drains `events` as a turn of the subagent's
+ * child session (the first event announces that session with its parent).
+ */
+export class CodexRuntimeTurn extends RuntimeTurnBase {
+  readonly sink: TurnSink;
+
+  constructor(
+    sessionKey: string,
+    readonly trigger: Extract<RuntimeTurnTrigger, { kind: 'subagent' }>,
+    private readonly opts: {
+      parentSessionKey?: string;
+      onDetach: (reason: string) => void;
+    },
+  ) {
+    super(sessionKey, trigger, opts.onDetach);
+    this.sink = new TurnSink(() => this.touch());
+  }
+
+  protected async *drain(): AsyncGenerator<RuntimeEvent> {
+    yield {
+      type: 'runtime_session',
+      runtimeSessionId: this.trigger.threadId,
+      runtimeLaneKey: this.sessionKey,
+      ...(this.opts.parentSessionKey ? { parentSessionKey: this.opts.parentSessionKey } : {}),
+    };
+    let sawError = false;
+    let sawOutcome = false;
+    while (true) {
+      const envelope = await this.sink.next();
+      if (envelope.kind === 'turn_end') {
+        // A real turn/completed carries its threadId; the sink's close()
+        // sentinel does not — the thread died or the bridge stopped.
+        if (envelope.threadId) return;
+        if (!sawError) {
+          yield {
+            type: 'error',
+            message: 'subagent turn ended without turn/completed',
+            groupKey: this.groupKey,
+          };
+        }
+        if (!sawOutcome) yield { type: 'turn_outcome', outcome: 'runtime_crash' };
+        return;
+      }
+      const event =
+        envelope.kind === 'error'
+          ? { type: 'error' as const, message: envelope.message }
+          : envelope.event;
+      if (event.type === 'error') sawError = true;
+      if (event.type === 'turn_outcome') sawOutcome = true;
+      yield projectRuntimeEvent(event, this.groupKey);
+    }
+  }
+}

package/src/session-manager.ts

@@ -51,6 +51,12 @@ export class CodexSessionManager {
     return this.threadIds.get(sessionKey);
   }
 
+  /** The session (main or fork) that owns a thread the bridge opened. */
+  getSessionKey(threadId: string): string | undefined {
+    for (const [sessionKey, id] of this.threadIds) if (id === threadId) return sessionKey;
+    return undefined;
+  }
+
   recordThreadId(sessionKey: string, threadId: string) {
     // An effective-instructions sha is a fact about one specific thread.
     // Recording a DIFFERENT thread id under the same session invalidates it;

package/src/turn-sink.ts

@@ -1,4 +1,5 @@
 import type { RuntimeEvent } from '@parall/agent-core';
+import { AsyncQueue } from '@parall/agent-core/internal/async-queue';
 import { EventMapper } from './event-mapping.js';
 
 export type TurnEventEnvelope =
@@ -6,12 +7,14 @@ export type TurnEventEnvelope =
   | { kind: 'turn_end'; threadId?: string }
   | { kind: 'error'; message: string };
 
-/** Per-turn buffered sink backed by an unbounded promise queue. */
+/**
+ * Per-turn buffered sink between notification routing and the turn's
+ * drain. Envelopes queued before close() still drain (a final error pushed
+ * by handleSubprocessClose must reach the consumer before turn_end).
+ */
 export class TurnSink {
   readonly mapper = new EventMapper();
-  private readonly queue: TurnEventEnvelope[] = [];
-  private resolver: ((value: TurnEventEnvelope) => void) | null = null;
-  private closed = false;
+  private readonly queue = new AsyncQueue<TurnEventEnvelope>();
 
   constructor(private readonly noteActivity?: () => void) {}
 
@@ -20,41 +23,21 @@ export class TurnSink {
   }
 
   push(envelope: TurnEventEnvelope) {
-    if (this.closed) return;
-    if (this.resolver) {
-      const r = this.resolver;
-      this.resolver = null;
-      r(envelope);
-      return;
-    }
     this.queue.push(envelope);
   }
 
-  next(): Promise<TurnEventEnvelope> {
-    // Drain any queued envelopes first, even after close(). Otherwise a final
-    // error envelope enqueued right before close() (e.g. by
-    // handleSubprocessClose) is silently dropped because the consumer would
-    // see turn_end before it.
-    const pending = this.queue.shift();
-    if (pending) return Promise.resolve(pending);
-    if (this.closed) {
-      return Promise.resolve({ kind: 'turn_end' });
-    }
-    return new Promise((resolve) => {
-      this.resolver = resolve;
-    });
+  async next(): Promise<TurnEventEnvelope> {
+    const result = await this.queue.next();
+    return result.done ? { kind: 'turn_end' } : result.value;
   }
 
   close() {
-    this.closed = true;
-    const r = this.resolver;
-    this.resolver = null;
-    r?.({ kind: 'turn_end' });
+    this.queue.close();
   }
 
   /** True once close() ran — the sink's terminal state (queued envelopes may
    * still drain via next()). */
   get isClosed(): boolean {
-    return this.closed;
+    return this.queue.isClosed;
   }
 }