@parall/codex-agent 1.58.2 → 1.60.0

package/dist/session-manager.js

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

package/dist/turn-sink.d.ts

@@ -10,13 +10,15 @@ export type TurnEventEnvelope = {
     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 declare class TurnSink {
     private readonly noteActivity?;
     readonly mapper: EventMapper;
     private readonly queue;
-    private resolver;
-    private closed;
     constructor(noteActivity?: (() => void) | undefined);
     touchActivity(): void;
     push(envelope: TurnEventEnvelope): void;

package/dist/turn-sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-sink.d.ts","sourceRoot":"","sources":["../src/turn-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,mEAAmE;AACnE,qBAAa,QAAQ;IAMP,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAL1C,QAAQ,CAAC,MAAM,cAAqB;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAqD;IACrE,OAAO,CAAC,MAAM,CAAS;gBAEM,YAAY,CAAC,GAAE,MAAM,IAAI,aAAA;IAEtD,aAAa;IAIb,IAAI,CAAC,QAAQ,EAAE,iBAAiB;IAWhC,IAAI,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAelC,KAAK;IAOL;kCAC8B;IAC9B,IAAI,QAAQ,IAAI,OAAO,CAEtB;CACF"}
+{"version":3,"file":"turn-sink.d.ts","sourceRoot":"","sources":["../src/turn-sink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC;;;;GAIG;AACH,qBAAa,QAAQ;IAIP,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAH1C,QAAQ,CAAC,MAAM,cAAqB;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;gBAEhC,YAAY,CAAC,GAAE,MAAM,IAAI,aAAA;IAEtD,aAAa;IAIb,IAAI,CAAC,QAAQ,EAAE,iBAAiB;IAI1B,IAAI,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAKxC,KAAK;IAIL;kCAC8B;IAC9B,IAAI,QAAQ,IAAI,OAAO,CAEtB;CACF"}

package/dist/turn-sink.js

@@ -1,11 +1,14 @@
+import { AsyncQueue } from '@parall/agent-core/internal/async-queue';
 import { EventMapper } from './event-mapping.js';
-/** 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 {
     noteActivity;
     mapper = new EventMapper();
-    queue = [];
-    resolver = null;
-    closed = false;
+    queue = new AsyncQueue();
     constructor(noteActivity) {
         this.noteActivity = noteActivity;
     }
@@ -13,40 +16,18 @@ export class TurnSink {
         this.noteActivity?.();
     }
     push(envelope) {
-        if (this.closed)
-            return;
-        if (this.resolver) {
-            const r = this.resolver;
-            this.resolver = null;
-            r(envelope);
-            return;
-        }
         this.queue.push(envelope);
     }
-    next() {
-        // 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() {
+        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() {
-        return this.closed;
+        return this.queue.isClosed;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/codex-agent",
-  "version": "1.58.2",
+  "version": "1.60.0",
   "description": "Codex CLI bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -25,9 +25,9 @@
     "src"
   ],
   "dependencies": {
-    "@parall/agent-core": "1.58.2",
-    "@parall/cli": "1.58.2",
-    "@parall/sdk": "1.58.2"
+    "@parall/cli": "1.60.0",
+    "@parall/agent-core": "1.60.0",
+    "@parall/sdk": "1.60.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/app-server-protocol.ts

@@ -34,6 +34,43 @@ export function extractTurnId(result: unknown): string | undefined {
   return undefined;
 }
 
+/**
+ * The `thread` object a `thread/started` notification carries. Subagent
+ * threads (`spawn_agent`) report `threadSource: "subAgent"` plus the parent
+ * thread and the agent's nickname/role; other fields are tolerated absent.
+ */
+export type CodexThreadInfo = {
+  id: string;
+  parentThreadId?: string;
+  source?: string;
+  nickname?: string;
+  role?: string;
+};
+
+export function extractThreadInfo(params: unknown): CodexThreadInfo | undefined {
+  if (!params || typeof params !== 'object') return undefined;
+  const p = params as Record<string, unknown>;
+  const thread = (p.thread && typeof p.thread === 'object' ? p.thread : p) as Record<
+    string,
+    unknown
+  >;
+  const id =
+    typeof thread.id === 'string'
+      ? thread.id
+      : typeof p.threadId === 'string'
+        ? p.threadId
+        : undefined;
+  if (!id) return undefined;
+  const str = (value: unknown) => (typeof value === 'string' && value.trim() ? value : undefined);
+  return {
+    id,
+    parentThreadId: str(thread.parentThreadId),
+    source: str(thread.threadSource) ?? str(thread.source),
+    nickname: str(thread.agentNickname),
+    role: str(thread.agentRole),
+  };
+}
+
 export function extractThreadIdFromNotification(params: unknown): string | undefined {
   if (!params || typeof params !== 'object') return undefined;
   const p = params as Record<string, unknown>;

package/src/compact.ts

@@ -0,0 +1,132 @@
+import type { CompactOpts, CompactResult, GatewayLogger } from '@parall/agent-core';
+import type { OpenDispatchOutcome } from './dispatch.js';
+import {
+  CompactionStalledError,
+  type MainThreadInstructionsRefresher,
+  type NotificationTapSource,
+} from './instructions-refresh.js';
+import { JSON_RPC_METHOD_NOT_FOUND, JsonRpcError } from './jsonrpc-client.js';
+
+/**
+ * Idle auto-compact on the Codex bridge (idle-auto-compact-design.md §3.4):
+ * open the MAIN thread exactly the way a dispatch would (start/resume + the
+ * instructions reconcile), then run the unconditional compaction primitive
+ * as a tap-only turn — no TurnSink, no activeTurnIds entry, so it is neither
+ * a user turn nor a steer target (PFB-84 bookkeeping untouched). Outcomes
+ * follow the refresh path's posture: a stalled compaction quarantines the
+ * main lane and bounces the subprocess; -32601 latches unsupported for the
+ * subprocess lifetime.
+ *
+ * The host is the narrow slice of CodexAppServerAdapter this needs; the
+ * adapter's `compact()` is a thin delegate.
+ */
+export interface CodexCompactHost {
+  log?: GatewayLogger;
+  taps: NotificationTapSource;
+  refresher: Pick<
+    MainThreadInstructionsRefresher,
+    'isCompactUnsupported' | 'runCompaction' | 'recordCompacted'
+  >;
+  isMainSession(sessionKey: string): boolean;
+  isMainLaneQuarantined(): boolean;
+  /** Quarantine the main lane and request a subprocess restart (applied when free). */
+  quarantineAndBounce(log?: GatewayLogger): Promise<void>;
+  applyPendingRestart(log?: GatewayLogger): Promise<void>;
+  /** Open the main thread with restart gating (openingDispatches) held. */
+  openMainThread(sessionKey: string, log?: GatewayLogger): Promise<OpenDispatchOutcome>;
+  hasActiveTurn(threadId: string): boolean;
+  /** Run `fn` as tap-only work on the thread: restart-gated, no unrouted-notification warnings. */
+  withTapOnlyTurn<T>(threadId: string, fn: () => Promise<T>): Promise<T>;
+}
+
+export async function runCodexCompact(
+  host: CodexCompactHost,
+  { sessionKey, signal, log }: CompactOpts,
+): Promise<CompactResult> {
+  const logger = log ?? host.log;
+  if (!host.isMainSession(sessionKey)) {
+    return { status: 'unsupported', detail: 'compact is only supported on the main session' };
+  }
+  if (signal.aborted) return { status: 'timeout' };
+  if (host.isMainLaneQuarantined()) {
+    await host.applyPendingRestart(logger);
+    if (host.isMainLaneQuarantined()) {
+      return {
+        status: 'failed',
+        detail:
+          'main lane quarantined after a stalled compaction; the subprocess restart is still deferred behind an active turn',
+      };
+    }
+  }
+  if (host.refresher.isCompactUnsupported()) {
+    return {
+      status: 'unsupported',
+      detail: 'thread/compact/start not supported by this codex CLI',
+    };
+  }
+  await host.applyPendingRestart(logger);
+  const opened = await host.openMainThread(sessionKey, logger);
+  if (!opened.ok) return { status: 'failed', detail: opened.message };
+  if (opened.reconcile === 'stalled') {
+    // Same posture as dispatch(): the refresh compaction may still be
+    // running on the thread — never rotate it; quarantine and bounce.
+    await host.quarantineAndBounce(logger);
+    return {
+      status: 'timeout',
+      detail:
+        'instructions-refresh compaction stalled while opening the thread; subprocess bounced',
+    };
+  }
+  if (opened.reconcile === 'unsupported') {
+    return {
+      status: 'unsupported',
+      detail: 'thread/compact/start not supported by this codex CLI',
+    };
+  }
+  if (opened.reconcile === 'refreshed') {
+    // The open just ran a compaction of this very thread (instructions
+    // refresh) — the history is already folded; a second one is waste.
+    return { status: 'done', detail: 'compacted by the instructions refresh during open' };
+  }
+  if (signal.aborted) {
+    return { status: 'timeout', detail: 'budget elapsed while opening the thread' };
+  }
+  const { client, threadId } = opened;
+  if (host.hasActiveTurn(threadId)) {
+    return { status: 'failed', detail: 'a turn is active on the main thread' };
+  }
+  let stalled = false;
+  try {
+    return await host.withTapOnlyTurn(threadId, async () => {
+      try {
+        await host.refresher.runCompaction({ client, taps: host.taps, threadId, signal });
+        host.refresher.recordCompacted(sessionKey, threadId);
+        return { status: 'done' } as CompactResult;
+      } catch (err) {
+        if (err instanceof CompactionStalledError) {
+          // Budget elapsed (the gateway's abort or the refresher's own
+          // ceiling) and the turn ignored the interrupt: the compaction is
+          // torn down with the subprocess below.
+          stalled = true;
+          return { status: 'timeout', detail: errToString(err) };
+        }
+        if (err instanceof JsonRpcError && err.code === JSON_RPC_METHOD_NOT_FOUND) {
+          return { status: 'unsupported', detail: errToString(err) };
+        }
+        return { status: 'failed', detail: errToString(err) };
+      }
+    });
+  } finally {
+    if (stalled) {
+      // The compaction turn may still be running: quarantine the main lane
+      // and bounce the subprocess (deferred behind an active fork turn,
+      // retried by the next main dispatch) — exactly the dispatch posture.
+      await host.quarantineAndBounce(logger);
+    }
+  }
+}
+
+function errToString(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/dispatch.ts

@@ -3,14 +3,20 @@ import { randomUUID } from 'node:crypto';
 import * as path from 'node:path';
 import type {
   CleanupForkOpts,
+  CompactOpts,
+  CompactResult,
   DispatchAdapter,
+  DispatchInputLifecycle,
   DispatchOpts,
   ForkOpts,
   ForkSessionHandle,
   GatewayLogger,
+  RuntimeActivityEvent,
+  RuntimeBusyState,
   RuntimeEvent,
 } from '@parall/agent-core';
 import type { PreparedLocalImage } from '@parall/agent-core/internal/attachment-input';
+import { isRuntimeBusy, projectRuntimeEvent, RuntimeActivityPort } from '@parall/agent-core';
 import {
   appendPreparedLocalAttachmentRefs,
   pinLocalAttachmentPaths,
@@ -24,12 +30,16 @@ import {
 } from './app-server-protocol.js';
 import type { CodexAgentConfig } from './config.js';
 import { normalizeApprovalPolicy, normalizeSandbox } from './config.js';
+import { runCodexCompact } from './compact.js';
+import { ForeignThreadRegistry } from './foreign-threads.js';
+import { CodexInjectionRegistry } from './injection-registry.js';
 import {
   MainThreadInstructionsRefresher,
   type NotificationTap,
   type RefreshOutcome,
 } from './instructions-refresh.js';
 import { JsonRpcStdioClient } from './jsonrpc-client.js';
+import type { CodexRuntimeTurn } from './runtime-turn.js';
 import { answerServerRequest } from './server-requests.js';
 import type { CodexSessionManager } from './session-manager.js';
 import { buildThreadConfigOverrides } from './thread-config.js';
@@ -104,7 +114,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   private startPromise: Promise<void> | null = null;
   private readonly activeTurns = new Map<string, TurnSink>();
   private readonly activeTurnIds = new Map<string, string>();
-  private readonly pendingInjections = new Map<string, number>();
+  private readonly injections = new CodexInjectionRegistry();
   private readonly resumedThreadIds = new Set<string>();
   /** Threads whose reconcile compaction is in flight — tap-only traffic. */
   private readonly reconcilingThreadIds = new Set<string>();
@@ -122,6 +132,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   private readonly instructionsRefresher: MainThreadInstructionsRefresher;
   private stopping = false;
   private lastUnroutedNotificationWarnAt = 0;
+  /** Subagent threads and their runtime-initiated turns (foreign-threads.ts). */
+  private readonly foreignThreads: ForeignThreadRegistry;
+  private readonly activity: RuntimeActivityPort;
 
   /**
    * Store an active turn sink keyed by threadId. If a sink already exists for
@@ -150,6 +163,19 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       compactTimeoutMs: opts.instructionsCompactTimeoutMs,
       interruptGraceMs: opts.instructionsInterruptGraceMs,
     });
+    this.activity = new RuntimeActivityPort('CodexAppServerAdapter', opts.log);
+    this.foreignThreads = new ForeignThreadRegistry({
+      sessionManager: opts.sessionManager,
+      log: opts.log,
+      activity: this.activity,
+      // A restart deferred behind subagent work must not starve once it ends.
+      afterTurnClosed: () => {
+        if (!this.restartRequested) return;
+        void this.applyPendingRestart().catch((err) =>
+          this.opts.log?.warn?.(`deferred restart failed: ${errToString(err)}`),
+        );
+      },
+    });
   }
 
   /** Register a listener for every server notification; returns unregister. */
@@ -194,7 +220,13 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     });
   }
 
-  async enqueueDuringDispatch(sessionKey: string, body: string): Promise<boolean> {
+  async enqueueDuringDispatch(
+    sessionKey: string,
+    body: string,
+    inputLifecycle?: DispatchInputLifecycle,
+  ): Promise<boolean> {
+    // Identity is mandatory — the drain releases the injection by this key (injection-registry.ts).
+    if (!inputLifecycle) return false;
     const client = this.client;
     if (!client || client.isDisposed()) return false;
     const threadId = this.opts.sessionManager.getThreadId(sessionKey);
@@ -207,7 +239,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
         expectedTurnId: turnId,
         input: buildTurnInput(body, []),
       });
-      this.pendingInjections.set(sessionKey, (this.pendingInjections.get(sessionKey) ?? 0) + 1);
+      this.injections.register(sessionKey, inputLifecycle.deliveryKey);
       return true;
     } catch (err) {
       this.opts.log?.warn?.(`turn/steer failed: ${errToString(err)}`);
@@ -216,7 +248,8 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   }
 
   abortDispatch(sessionKey: string): void {
-    this.pendingInjections.delete(sessionKey);
+    // A torn-down turn owes nothing: the error complete releases its members for fresh turns.
+    this.injections.clear(sessionKey);
     const threadId = this.opts.sessionManager.getThreadId(sessionKey);
     if (!threadId) return;
     const sink = this.activeTurns.get(threadId);
@@ -240,8 +273,87 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     sink.close();
   }
 
+  /** Idle auto-compact (compact.ts): the compaction primitive as a tap-only main-thread turn. */
+  compact(opts: CompactOpts): Promise<CompactResult> {
+    return runCodexCompact(
+      {
+        log: this.opts.log,
+        taps: this,
+        refresher: this.instructionsRefresher,
+        isMainSession: (sessionKey) => this.opts.sessionManager.isMain(sessionKey),
+        isMainLaneQuarantined: () => this.mainLaneQuarantined,
+        quarantineAndBounce: async (log) => {
+          this.mainLaneQuarantined = true;
+          this.requestProcessRestart();
+          await this.applyPendingRestart(log);
+        },
+        applyPendingRestart: (log) => this.applyPendingRestart(log),
+        openMainThread: (sessionKey, log) =>
+          this.withOpening(() => this.openDispatchTarget(sessionKey, true, log)),
+        hasActiveTurn: (threadId) => this.activeTurns.has(threadId),
+        withTapOnlyTurn: async (threadId, fn) => {
+          this.reconcilingThreadIds.add(threadId);
+          try {
+            return await this.withOpening(fn);
+          } finally {
+            this.reconcilingThreadIds.delete(threadId);
+          }
+        },
+      },
+      opts,
+    );
+  }
+
+  /**
+   * Real work on the subprocess that predates any TurnSink (thread open,
+   * a tap-only compaction turn): counted so applyPendingRestart cannot
+   * stop() the subprocess out from under it.
+   */
+  private async withOpening<T>(fn: () => Promise<T>): Promise<T> {
+    this.openingDispatches += 1;
+    try {
+      return await fn();
+    } finally {
+      this.openingDispatches -= 1;
+    }
+  }
+
   hasPendingInjections(sessionKey: string): boolean {
-    return (this.pendingInjections.get(sessionKey) ?? 0) > 0;
+    return this.injections.hasPending(sessionKey);
+  }
+
+  hasUnsettledInjections(sessionKey: string): boolean {
+    return this.injections.hasUnsettled(sessionKey);
+  }
+
+  acknowledgeDiscardedInjection(sessionKey: string, deliveryKey: string): void {
+    this.injections.markDrained(sessionKey, deliveryKey);
+  }
+
+  // --- runtime-initiated work -------------------------------------------------
+
+  subscribeRuntimeActivity(handler: (event: RuntimeActivityEvent) => void): () => void {
+    return this.activity.subscribe(handler);
+  }
+
+  /**
+   * Busy = a dispatch turn, a dispatch opening its thread (possibly running
+   * the instructions-refresh compaction turn), or a subagent thread's turn
+   * is executing. Live subagent threads between turns are reported as
+   * background work, not busy.
+   */
+  isBusy(): boolean {
+    return isRuntimeBusy(this.busyState());
+  }
+
+  busyState(): RuntimeBusyState {
+    return {
+      activeTurns:
+        this.activeTurns.size +
+        (this.openingDispatches > 0 || this.reconcilingThreadIds.size > 0 ? 1 : 0) +
+        this.foreignThreads.openTurns(),
+      backgroundWork: this.foreignThreads.size,
+    };
   }
 
   async *dispatch({
@@ -249,27 +361,12 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     bodyForAgent,
     sessionKey,
     context,
+    inputLifecycle,
     noteActivity,
   }: DispatchOpts): AsyncIterable<RuntimeEvent> {
-    const pending = this.pendingInjections.get(sessionKey) ?? 0;
-    if (pending > 0) {
-      this.pendingInjections.delete(sessionKey);
-      const threadId = this.opts.sessionManager.getThreadId(sessionKey);
-      if (threadId && this.client && !this.client.isDisposed()) {
-        (this.opts.log ?? context.log)?.info?.(
-          `${pending} steer injection(s) already sent; skipping turn/start`,
-        );
-        yield {
-          type: 'runtime_session',
-          runtimeSessionId: threadId,
-          runtimeLaneKey: sessionKey,
-        };
-        return;
-      }
-      (this.opts.log ?? context.log)?.warn?.(
-        `pending steer invalidated (subprocess died); falling through to normal dispatch`,
-      );
-    }
+    // This dispatch drains the injected copies it lists; it ALWAYS runs its own
+    // turn — never skipped on outstanding injections (PFB-84, injection-registry.ts).
+    if (inputLifecycle) this.injections.markDrained(sessionKey, inputLifecycle.deliveryKey);
 
     const isMainSession = this.opts.sessionManager.isMain(sessionKey);
     if (isMainSession && this.mainLaneQuarantined) {
@@ -322,13 +419,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       // compaction turn BEFORE any TurnSink exists, and a concurrent fork
       // dispatch hitting a pending restart in that window would otherwise
       // stop() the subprocess out from under it.
-      this.openingDispatches += 1;
-      let opened: OpenDispatchOutcome;
-      try {
-        opened = await this.openDispatchTarget(sessionKey, isMainSession, log);
-      } finally {
-        this.openingDispatches -= 1;
-      }
+      const opened = await this.withOpening(() =>
+        this.openDispatchTarget(sessionKey, isMainSession, log),
+      );
       if (!opened.ok) {
         yield { type: 'error', message: opened.message };
         return;
@@ -519,39 +612,20 @@ export class CodexAppServerAdapter implements DispatchAdapter {
           sawTurnEnd = true;
           break;
         }
-        if (envelope.kind === 'error') {
-          yield { type: 'error', message: envelope.message };
-          continue;
-        }
-        const runtimeEvent = envelope.event;
-        if (runtimeEvent.type === 'error') {
-          yield runtimeEvent;
-          continue;
-        }
-        if (runtimeEvent.type === 'runtime_session') {
-          yield runtimeEvent;
-          continue;
-        }
-        if (runtimeEvent.type === 'text') {
-          // Layer 0 symmetric output contract: Codex's plain text is never
-          // projected as a chat message. Outbound messages must come from the
-          // agent explicitly invoking `@parall/cli messages send` / `dm` via
-          // the shell/exec tool. Text events are still yielded so agent-core
-          // records them as suppressed session steps for audit.
-          yield { ...runtimeEvent, project: false, groupKey };
-          continue;
-        }
-        if (runtimeEvent.type === 'turn_outcome') {
-          // Turn-boundary summary — no groupKey, passed through as-is.
-          yield runtimeEvent;
-          continue;
-        }
-        yield { ...runtimeEvent, groupKey };
+        // Layer 0 symmetric output contract (projectRuntimeEvent): Codex's
+        // plain text is never projected as a chat message — outbound
+        // messages come from the agent invoking `parall messages send` /
+        // `dm`; text is still yielded as a suppressed audit step.
+        yield projectRuntimeEvent(
+          envelope.kind === 'error' ? { type: 'error', message: envelope.message } : envelope.event,
+          groupKey,
+        );
       }
     } finally {
       releasePreparedAttachments();
       this.activeTurns.delete(threadId!);
       this.activeTurnIds.delete(threadId!);
+      this.injections.settleAll(sessionKey); // the turn consumed (or lost) everything steered into it
       if (!sawTurnEnd) {
         sink.close();
       }
@@ -754,7 +828,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   private openingDispatches = 0;
 
   private async applyPendingRestart(log?: GatewayLogger): Promise<void> {
-    if (!this.restartRequested || this.activeTurns.size > 0 || this.openingDispatches > 0) return;
+    // isBusy folds in subagent turns: a capability change must not SIGTERM
+    // the app-server under a running spawn_agent thread.
+    if (!this.restartRequested || this.isBusy()) return;
     this.restartRequested = false;
     (log ?? this.opts.log)?.info?.(
       'restarting codex app-server after a capability change (the fresh-process thread/resume applies the refreshed developerInstructions to the persisted thread configuration; the model-visible context is reconciled before the next turn)',
@@ -770,7 +846,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.client = null;
     this.initialized = false;
     this.activeTurnIds.clear();
-    this.pendingInjections.clear();
+    this.injections.clear();
     // Resume markers are process-local facts. Clear them HERE, synchronously:
     // the old child's close callback sees the replaced refs and skips its
     // cleanup as stale, so a marker surviving stop() would make the next
@@ -780,6 +856,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.instructionsRefresher.clearThreadState();
     // The (possible) zombie compaction turn dies with the subprocess.
     this.mainLaneQuarantined = false;
+    // Subagent threads die with the app-server: end their open turns
+    // (runtime_crash) and close their child sessions before the client goes.
+    this.foreignThreads.dropAll('lost: Codex app-server stopped');
     this.notifyTapsDisposed('Codex app-server stopped');
     if (client) client.dispose(new Error('adapter stopped'));
     if (proc && proc.exitCode === null && proc.signalCode === null) {
@@ -797,7 +876,8 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       }
       this.activeTurns.clear();
       this.activeTurnIds.clear();
-      this.pendingInjections.clear();
+      this.injections.clear();
+      this.foreignThreads.dropAll('lost: Codex app-server disposed');
       this.client = null;
       this.proc = null;
       this.initialized = false;
@@ -977,10 +1057,11 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     }
     this.activeTurns.clear();
     this.activeTurnIds.clear();
-    this.pendingInjections.clear();
+    this.injections.clear();
     this.resumedThreadIds.clear();
     this.instructionsRefresher.clearThreadState();
     this.mainLaneQuarantined = false;
+    this.foreignThreads.dropAll(`lost: Codex app-server ${reason}`);
     this.notifyTapsDisposed(`Codex app-server ${reason}`);
     this.client = null;
     this.proc = null;
@@ -1073,6 +1154,10 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       // successful instructions refresh and burn the shared rate-limit
       // window that exists to surface REAL orphaned turns.
       if (this.reconcilingThreadIds.has(threadId)) return;
+      // Subagent threads and their turns are runtime-initiated work: routed
+      // into their own sinks and surfaced to the gateway as child-session
+      // turns instead of being dropped.
+      if (this.foreignThreads.route(method, params, threadId)) return;
       // Notifications for a thread with no registered sink are dropped. A
       // sustained stream of these means a turn is running that nothing is
       // consuming (threadId mismatch, sink torn down early) — the dispatch
@@ -1104,7 +1189,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   }
 }
 
-type OpenDispatchOutcome =
+export type OpenDispatchOutcome =
   | { ok: true; client: JsonRpcStdioClient; threadId: string; reconcile?: RefreshOutcome }
   | { ok: false; message: string };