@parall/codex-agent 1.45.0 → 1.47.0

package/src/dispatch.ts

@@ -1,11 +1,6 @@
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import * as path from 'node:path';
-import {
-  appendPreparedLocalAttachmentRefs,
-  pinLocalAttachmentPaths,
-} from '@parall/agent-core/internal/attachment-input';
-import type { PreparedLocalImage } from '@parall/agent-core/internal/attachment-input';
 import type {
   CleanupForkOpts,
   DispatchAdapter,
@@ -15,7 +10,12 @@ import type {
   GatewayLogger,
   RuntimeEvent,
 } from '@parall/agent-core';
-import { IS_WIN32, ensureGitRepo, killWin32Tree, quoteWin32Arg } from './app-server-process.js';
+import type { PreparedLocalImage } from '@parall/agent-core/internal/attachment-input';
+import {
+  appendPreparedLocalAttachmentRefs,
+  pinLocalAttachmentPaths,
+} from '@parall/agent-core/internal/attachment-input';
+import { ensureGitRepo, IS_WIN32, killWin32Tree, quoteWin32Arg } from './app-server-process.js';
 import {
   buildTurnInput,
   extractThreadId,
@@ -24,7 +24,13 @@ import {
 } from './app-server-protocol.js';
 import type { CodexAgentConfig } from './config.js';
 import { normalizeApprovalPolicy, normalizeSandbox } from './config.js';
+import {
+  MainThreadInstructionsRefresher,
+  type NotificationTap,
+  type RefreshOutcome,
+} from './instructions-refresh.js';
 import { JsonRpcStdioClient } from './jsonrpc-client.js';
+import { answerServerRequest } from './server-requests.js';
 import type { CodexSessionManager } from './session-manager.js';
 import { TurnSink } from './turn-sink.js';
 
@@ -58,19 +64,22 @@ type CodexAppServerAdapterOptions = Pick<
    * which coupled the prompt to codex's interactive workspace-trust concept
    * and made the bridge write into the operator's own config on shared homes.
    *
-   * Where it lands, live-probed on 0.144.1 — the CLI accepts the param on all
-   * three entrypoints but only `thread/start` APPLIES it (instructions are
-   * baked into the thread there). `thread/resume` keeps the thread's own copy;
-   * `thread/fork` inherits the parent's. The bridge sends it on all three
-   * anyway: a failed resume falls back to thread/start on the same params, and
-   * a future CLI that honors it then needs no bridge change.
+   * Where it lands on 0.144.1: `thread/start` bakes it in (canonical AND
+   * model-visible at once); a fresh-process `thread/resume` updates only the
+   * thread's CANONICAL configuration (a resume of a still-running thread
+   * ignores every override); `thread/fork` inherits the parent's; compaction
+   * rebuilds the model-visible context from the canonical configuration.
    *
-   * Consequence: updateConfig() changes what the NEXT thread/start sends; it
-   * cannot re-instruct an already-persisted thread. Inherited from the retired
-   * channel, not introduced —
-   * docs/tech-debt/codex-persisted-thread-prompt-refresh.md.
+   * Consequence: updateConfig() changes what the NEXT thread open sends; for
+   * the persisted main thread, the lazy restart's fresh-process resume plus
+   * one explicit compaction converge both planes before the next turn — the
+   * full two-plane semantics and evidence live in instructions-refresh.ts.
    */
   developerInstructions?: string;
+  /** Override the compaction wait budget for the instructions refresh (tests). */
+  instructionsCompactTimeoutMs?: number;
+  /** Override the post-interrupt grace for the instructions refresh (tests). */
+  instructionsInterruptGraceMs?: number;
 };
 
 /**
@@ -96,7 +105,22 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   private readonly activeTurnIds = new Map<string, string>();
   private readonly pendingInjections = new Map<string, number>();
   private readonly resumedThreadIds = new Set<string>();
+  /** Threads whose reconcile compaction is in flight — tap-only traffic. */
+  private readonly reconcilingThreadIds = new Set<string>();
+  /**
+   * Set when a stalled compaction left (possibly) a zombie turn on the main
+   * thread. Until the subprocess ACTUALLY restarts, main-lane redrives must
+   * not open/compact/turn-start the thread: re-entering the zombie process
+   * lets a second compaction's watcher misattribute the zombie's close as a
+   * plain failure, dropping the stalled marker and re-arming the
+   * fresh-thread rotation this state exists to prevent. Cleared where the
+   * zombie dies: subprocess teardown.
+   */
+  private mainLaneQuarantined = false;
+  private readonly notificationTaps = new Set<NotificationTap>();
+  private readonly instructionsRefresher: MainThreadInstructionsRefresher;
   private stopping = false;
+  private lastUnroutedNotificationWarnAt = 0;
 
   /**
    * Store an active turn sink keyed by threadId. If a sink already exists for
@@ -118,7 +142,36 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.activeTurns.set(threadId, sink);
   }
 
-  constructor(private readonly opts: CodexAppServerAdapterOptions) {}
+  constructor(private readonly opts: CodexAppServerAdapterOptions) {
+    this.instructionsRefresher = new MainThreadInstructionsRefresher({
+      sessionManager: opts.sessionManager,
+      log: opts.log,
+      compactTimeoutMs: opts.instructionsCompactTimeoutMs,
+      interruptGraceMs: opts.instructionsInterruptGraceMs,
+    });
+  }
+
+  /** Register a listener for every server notification; returns unregister. */
+  addNotificationTap(tap: NotificationTap): () => void {
+    this.notificationTaps.add(tap);
+    return () => this.notificationTaps.delete(tap);
+  }
+
+  /**
+   * Tell tap waiters the subprocess is gone so they abort immediately —
+   * no further notifications will ever arrive, and a waiter left to its
+   * own timeout would stall its dispatch for the full compaction budget.
+   * Mirrors the global-error broadcast routeNotification does for sinks.
+   */
+  private notifyTapsDisposed(reason: string): void {
+    for (const tap of this.notificationTaps) {
+      try {
+        tap('error', { message: reason });
+      } catch {
+        // Taps must never break teardown.
+      }
+    }
+  }
 
   updateConfig(config: {
     model?: string | null;
@@ -158,7 +211,22 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     const threadId = this.opts.sessionManager.getThreadId(sessionKey);
     if (!threadId) return;
     const sink = this.activeTurns.get(threadId);
-    if (!sink) return;
+    // Idempotence guard (DispatchAdapter contract): the deadline timer and
+    // the lane-flow error path can both abort the same dispatch before the
+    // generator's cleanup empties activeTurns — keying on the sink's own
+    // terminal state makes the repeat a full no-op (one turn/interrupt on
+    // the wire, not two) and also dedupes against dispose/process-exit
+    // having already closed the sink.
+    if (!sink || sink.isClosed) return;
+    // Best-effort runtime-side stop: closing only the local sink leaves the
+    // app-server turn running (or parked on a server request) after the
+    // gateway has abandoned the dispatch.
+    const turnId = this.activeTurnIds.get(threadId);
+    if (turnId && this.client && !this.client.isDisposed()) {
+      this.client
+        .sendRequest('turn/interrupt', { threadId, turnId })
+        .catch((err) => this.opts.log?.warn?.(`turn/interrupt failed: ${errToString(err)}`));
+    }
     sink.push({ kind: 'error', message: 'dispatch deadline exceeded' });
     sink.close();
   }
@@ -193,68 +261,92 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       );
     }
 
-    await this.applyPendingRestart(context.log);
-    await this.ensureStarted(context.log);
-    // After ensureStarted resolves the subprocess could still die before we
-    // capture the client (handleSubprocessClose nulls this.client). Yield a
-    // clean error event instead of relying on a non-null assertion that would
-    // throw a TypeError on the next sendRequest call.
-    const client = this.client;
-    if (!client) {
-      yield {
-        type: 'error',
-        message: 'Codex app-server not available (subprocess died during dispatch start)',
-      };
-      return;
-    }
-    const log = this.opts.log ?? context.log;
     const isMainSession = this.opts.sessionManager.isMain(sessionKey);
+    if (isMainSession && this.mainLaneQuarantined) {
+      // Try the pending restart now — it may have been deferred behind an
+      // active fork turn when the quarantine was raised. If it still cannot
+      // run, fail this redrive WITHOUT touching the thread.
+      await this.applyPendingRestart(context.log);
+      if (this.mainLaneQuarantined) {
+        const quarantinedThreadId = this.opts.sessionManager.getThreadId(sessionKey);
+        if (quarantinedThreadId) {
+          yield {
+            type: 'runtime_session',
+            runtimeSessionId: quarantinedThreadId,
+            runtimeLaneKey: sessionKey,
+          };
+        }
+        yield {
+          type: 'error',
+          message:
+            'main lane quarantined after a stalled compaction; the subprocess restart is still deferred behind an active turn — the thread is retained and this dispatch will be redriven',
+        };
+        return;
+      }
+    }
+    const liveThreadId = isMainSession
+      ? this.opts.sessionManager.getThreadId(sessionKey)
+      : undefined;
+    if (
+      liveThreadId &&
+      this.opts.developerInstructions &&
+      this.resumedThreadIds.has(liveThreadId) &&
+      this.instructionsRefresher.canonicalFor(liveThreadId) !== this.opts.developerInstructions
+    ) {
+      // Live thread opened with an older prompt: compacting now would
+      // rebuild that STALE text, so bounce the subprocess — only a
+      // fresh-process resume updates the canonical configuration. The
+      // platform-config refresh normally schedules this restart itself;
+      // this guard makes convergence independent of that ordering.
+      this.requestProcessRestart();
+    }
 
-    let threadId = this.opts.sessionManager.getThreadId(sessionKey);
-    if (!threadId) {
+    const log = this.opts.log ?? context.log;
+    let client!: JsonRpcStdioClient;
+    let threadId!: string;
+    let reconcileStalled = false;
+    for (let attempt = 0; ; attempt++) {
+      await this.applyPendingRestart(context.log);
+      // Opening counts as active work for restart gating (see
+      // applyPendingRestart): the main-session reconcile can run a real
+      // 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 {
-        threadId = await this.openThread(client, { resumeId: undefined });
-        this.opts.sessionManager.recordThreadId(sessionKey, threadId);
-        // Mark this freshly-started thread as already live in the current
-        // app-server process. Without this, the second dispatch after a cold
-        // start would enter the thread/resume branch below for a thread this
-        // process just created — and if the server treats resume-of-just-
-        // created-thread as an attach-to-detached-thread operation, it could
-        // fail the resume path and replace the thread, losing the first turn.
-        this.resumedThreadIds.add(threadId);
-      } catch (err) {
-        yield { type: 'error', message: `Codex thread/start failed: ${errToString(err)}` };
+        opened = await this.openDispatchTarget(sessionKey, isMainSession, log);
+      } finally {
+        this.openingDispatches -= 1;
+      }
+      if (!opened.ok) {
+        yield { type: 'error', message: opened.message };
         return;
       }
-    } else if (isMainSession && !this.resumedThreadIds.has(threadId)) {
-      // We have a persisted threadId from a previous bridge run — resume it.
-      // Mirror the deferred-clear pattern from the turn/start retry below: only
-      // discard the persisted id once a fresh-thread start has actually
-      // succeeded, so a transient resume failure (network/timeout/upstream
-      // hiccup) doesn't permanently throw away the prior conversation context.
-      try {
-        threadId = await this.openThread(client, { resumeId: threadId });
-        this.opts.sessionManager.recordThreadId(sessionKey, threadId);
-        this.resumedThreadIds.add(threadId);
-      } catch (err) {
-        log?.warn?.(
-          `thread/resume failed (${errToString(err)}); attempting one-shot fresh-thread start`,
+      client = opened.client;
+      threadId = opened.threadId;
+      reconcileStalled = opened.reconcile === 'stalled';
+      // Re-check convergence AFTER the async open/reconcile work: on the cold
+      // path (spawn + resume + compaction) that window is seconds, and a
+      // platform-config update landing inside it would otherwise run this
+      // turn on the prompt captured at open time. One bounded retry loops
+      // back through the restart path with the newer prompt. If the restart
+      // stays deferred (a fork turn is active) or a second update lands
+      // during the retry, the turn proceeds and the next dispatch converges —
+      // an update after this point is equivalent to one arriving mid-turn.
+      if (
+        isMainSession &&
+        attempt === 0 &&
+        this.opts.developerInstructions &&
+        this.instructionsRefresher.canonicalFor(threadId) !== this.opts.developerInstructions
+      ) {
+        log?.info?.(
+          'platform instructions changed while the dispatch was opening the thread; bouncing the subprocess to converge before this turn',
         );
-        let freshThreadId: string;
-        try {
-          freshThreadId = await this.openThread(client, { resumeId: undefined });
-        } catch (innerErr) {
-          yield {
-            type: 'error',
-            message: `Codex thread/start failed after resume error (persisted thread retained): ${errToString(innerErr)}`,
-          };
-          return;
-        }
-        this.opts.sessionManager.clearMainThread();
-        this.opts.sessionManager.recordThreadId(sessionKey, freshThreadId);
-        this.resumedThreadIds.add(freshThreadId);
-        threadId = freshThreadId;
+        this.requestProcessRestart();
+        continue;
       }
+      break;
     }
 
     const sink = new TurnSink();
@@ -332,10 +424,35 @@ export class CodexAppServerAdapter implements DispatchAdapter {
           yield { type: 'error', message: `Codex turn/start failed: ${message}` };
           return;
         }
+        if (reconcileStalled) {
+          // A stalled compaction may STILL be running on this thread — a
+          // busy-thread rejection here is expected, not evidence of a stale
+          // thread, and the fresh-thread retry below would ROTATE the
+          // persisted main thread (continuity loss). Quarantine the main
+          // lane (redrives must not touch the thread until the subprocess
+          // actually restarts — a deferred restart would otherwise send the
+          // NEXT dispatch back into the zombie, where a second compaction's
+          // watcher can misattribute the zombie's close as a plain failure
+          // and lose the stalled marker) and bounce the subprocess.
+          this.mainLaneQuarantined = true;
+          this.requestProcessRestart();
+          this.activeTurns.delete(threadId);
+          yield {
+            type: 'runtime_session',
+            runtimeSessionId: threadId,
+            runtimeLaneKey: sessionKey,
+          };
+          yield {
+            type: 'error',
+            message: `Codex turn/start failed after a stalled compaction (thread retained; subprocess will restart): ${message}`,
+          };
+          return;
+        }
         log?.warn?.(
           `turn/start on thread ${threadId} failed (${message}); attempting one-shot fresh-thread retry`,
         );
         this.activeTurns.delete(threadId);
+        const sentInstructions = this.opts.developerInstructions;
         let freshThreadId: string;
         try {
           freshThreadId = await this.openThread(client, { resumeId: undefined });
@@ -373,7 +490,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
         // Retry accepted — the original thread really was unusable. Now safe
         // to discard the old persisted id and persist the fresh one.
         this.opts.sessionManager.clearMainThread();
-        this.opts.sessionManager.recordThreadId(sessionKey, freshThreadId);
+        this.instructionsRefresher.recordBaked(sessionKey, freshThreadId, sentInstructions);
         this.resumedThreadIds.add(freshThreadId);
         threadId = freshThreadId;
       }
@@ -426,6 +543,113 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     }
   }
 
+  /**
+   * Bring the app-server up and open (start or resume) the thread for this
+   * dispatch, then reconcile the main thread's EFFECTIVE instructions plane.
+   * Extracted from dispatch() so the convergence re-check there can loop back
+   * through the restart path without duplicating the open logic. Errors are
+   * returned, not thrown — the generator yields them as runtime events.
+   */
+  private async openDispatchTarget(
+    sessionKey: string,
+    isMainSession: boolean,
+    log?: GatewayLogger,
+  ): Promise<OpenDispatchOutcome> {
+    try {
+      await this.ensureStarted(log);
+    } catch (err) {
+      // Spawn/handshake failures surface as a clean error event like every
+      // other open failure, instead of rejecting the dispatch generator.
+      return { ok: false, message: `Codex app-server failed to start: ${errToString(err)}` };
+    }
+    // After ensureStarted resolves the subprocess could still die before we
+    // capture the client (handleSubprocessClose nulls this.client). Return a
+    // clean error instead of relying on a non-null assertion that would
+    // throw a TypeError on the next sendRequest call.
+    const client = this.client;
+    if (!client) {
+      return {
+        ok: false,
+        message: 'Codex app-server not available (subprocess died during dispatch start)',
+      };
+    }
+
+    let threadId = this.opts.sessionManager.getThreadId(sessionKey);
+    if (!threadId) {
+      try {
+        // Capture what openThread will send in the same tick as the call, so
+        // the recorded canonical/effective values can never reflect a NEWER
+        // instructions text swapped in by updateConfig() mid-flight.
+        const sentInstructions = this.opts.developerInstructions;
+        threadId = await this.openThread(client, { resumeId: undefined });
+        // recordBaked persists thread id + effective sha in ONE write.
+        this.instructionsRefresher.recordBaked(sessionKey, threadId, sentInstructions);
+        // Mark this freshly-started thread as already live in the current
+        // app-server process. Without this, the second dispatch after a cold
+        // start would enter the thread/resume branch below for a thread this
+        // process just created — and if the server treats resume-of-just-
+        // created-thread as an attach-to-detached-thread operation, it could
+        // fail the resume path and replace the thread, losing the first turn.
+        this.resumedThreadIds.add(threadId);
+      } catch (err) {
+        return { ok: false, message: `Codex thread/start failed: ${errToString(err)}` };
+      }
+    } else if (isMainSession && !this.resumedThreadIds.has(threadId)) {
+      // We have a persisted threadId from a previous bridge run — resume it.
+      // Mirror the deferred-clear pattern from the turn/start retry in
+      // dispatch(): only discard the persisted id once a fresh-thread start
+      // has actually succeeded, so a transient resume failure (network/
+      // timeout/upstream hiccup) doesn't permanently throw away the prior
+      // conversation context.
+      const sentInstructions = this.opts.developerInstructions;
+      try {
+        threadId = await this.openThread(client, { resumeId: threadId });
+        this.opts.sessionManager.recordThreadId(sessionKey, threadId);
+        this.instructionsRefresher.recordResumed(threadId, sentInstructions);
+        this.resumedThreadIds.add(threadId);
+      } catch (err) {
+        log?.warn?.(
+          `thread/resume failed (${errToString(err)}); attempting one-shot fresh-thread start`,
+        );
+        let freshThreadId: string;
+        try {
+          freshThreadId = await this.openThread(client, { resumeId: undefined });
+        } catch (innerErr) {
+          return {
+            ok: false,
+            message: `Codex thread/start failed after resume error (persisted thread retained): ${errToString(innerErr)}`,
+          };
+        }
+        this.opts.sessionManager.clearMainThread();
+        this.instructionsRefresher.recordBaked(sessionKey, freshThreadId, sentInstructions);
+        this.resumedThreadIds.add(freshThreadId);
+        threadId = freshThreadId;
+      }
+    }
+
+    let reconcile: RefreshOutcome | undefined;
+    if (isMainSession) {
+      // Converge the EFFECTIVE plane before the turn starts (posture incl.
+      // the stalled exception: instructions-refresh.ts). Cheap compare when
+      // nothing changed; one thread/compact/start when the last-known
+      // effective instructions differ from the thread's canonical config.
+      this.reconcilingThreadIds.add(threadId);
+      try {
+        reconcile = await this.instructionsRefresher.reconcileAfterOpen({
+          client,
+          taps: this,
+          sessionKey,
+          threadId,
+          log,
+        });
+      } finally {
+        this.reconcilingThreadIds.delete(threadId);
+      }
+    }
+
+    return { ok: true, client, threadId, reconcile };
+  }
+
   getBranchPoint(_sessionKey: string): string | undefined {
     // Codex app-server does not expose a branch-point API; fork scope prefix
     // provides the behavioral fallback for this runtime.
@@ -442,6 +666,14 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       const forkParams: Record<string, unknown> = {
         threadId: parentThreadId,
         ephemeral: true,
+        // Forks must inherit the bridge's approval/sandbox contract. thread/fork
+        // does NOT inherit them from the parent thread — omitting them falls
+        // back to codex defaults (on-request approval, workspace-write), and an
+        // escalated command then emits an approval request the headless bridge
+        // can only deny, killing the fork's ability to run privileged commands
+        // the main session runs freely.
+        approvalPolicy: normalizeApprovalPolicy(this.opts.approvalPolicy),
+        sandbox: normalizeSandbox(this.opts.sandbox),
       };
       if (this.opts.useParallProvider) {
         forkParams.modelProvider = 'parall';
@@ -484,9 +716,12 @@ export class CodexAppServerAdapter implements DispatchAdapter {
    * to the next dispatch with no active turns — never kills an in-flight turn;
    * thread state survives via thread/resume.
    *
-   * A restart does NOT re-instruct an already-persisted thread — see the
-   * `developerInstructions` option doc. The capability shim dir on PATH is what
-   * makes a grant/revocation effective immediately.
+   * For the persisted main thread this restart is also the CANONICAL half of
+   * the instructions refresh: only a fresh-process thread/resume applies the
+   * updated developerInstructions to the thread's configuration (a resume of
+   * a still-running thread ignores it). The EFFECTIVE half is the explicit
+   * compaction in instructions-refresh.ts. The capability shim dir on PATH is
+   * what makes a grant/revocation's TOOLS effective immediately.
    */
   requestProcessRestart(): void {
     this.restartRequested = true;
@@ -494,11 +729,18 @@ export class CodexAppServerAdapter implements DispatchAdapter {
 
   private restartRequested = false;
 
+  /**
+   * Dispatches currently inside their open/reconcile phase — real work on
+   * the subprocess (thread open, possibly a compaction turn) that predates
+   * any TurnSink registration, so activeTurns alone cannot gate the restart.
+   */
+  private openingDispatches = 0;
+
   private async applyPendingRestart(log?: GatewayLogger): Promise<void> {
-    if (!this.restartRequested || this.activeTurns.size > 0) return;
+    if (!this.restartRequested || this.activeTurns.size > 0 || this.openingDispatches > 0) return;
     this.restartRequested = false;
     (log ?? this.opts.log)?.info?.(
-      'restarting codex app-server after a capability change (new threads pick up the refreshed developerInstructions; an already-persisted thread keeps its own)',
+      '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)',
     );
     await this.stop();
   }
@@ -518,6 +760,10 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     // dispatch treat the persisted thread as already resumed in the NEW
     // process and lose conversation continuity when turn/start rejects.
     this.resumedThreadIds.clear();
+    this.instructionsRefresher.clearThreadState();
+    // The (possible) zombie compaction turn dies with the subprocess.
+    this.mainLaneQuarantined = false;
+    this.notifyTapsDisposed('Codex app-server stopped');
     if (client) client.dispose(new Error('adapter stopped'));
     if (proc && proc.exitCode === null && proc.signalCode === null) {
       if (!IS_WIN32 || !proc.pid || !killWin32Tree(proc.pid)) {
@@ -539,6 +785,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       this.proc = null;
       this.initialized = false;
       this.resumedThreadIds.clear();
+      this.instructionsRefresher.clearThreadState();
     }
     if (this.initialized && this.client) return;
     if (this.startPromise) return this.startPromise;
@@ -558,6 +805,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     // previous stop() — otherwise handleSubprocessClose would mislabel the next
     // unexpected exit as "during graceful stop".
     this.stopping = false;
+    this.instructionsRefresher.resetForNewSubprocess();
     ensureGitRepo(this.opts.workspaceDir);
 
     // Only steer Codex's own state via CODEX_HOME. Leaving HOME untouched
@@ -631,6 +879,28 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       }
     });
     client.setNotificationHandler((method, params) => this.routeNotification(method, params));
+    // Server→client requests (approvals, elicitations) can never be answered
+    // interactively by a headless bridge, but each one MUST get a response —
+    // the app-server parks the requesting turn until one arrives. Known
+    // approval methods get an explicit denial; anything else falls through to
+    // the client's method-not-found error. With approvalPolicy "never" these
+    // should not occur at all, so surface every occurrence at warn.
+    client.setServerRequestHandler((method, params) => {
+      const denial = answerServerRequest(method);
+      // Log stable identifiers only — approval params carry command lines /
+      // file changes / patch content that must not reach stderr or OTLP.
+      const p = (params ?? {}) as Record<string, unknown>;
+      const ids = ['threadId', 'turnId', 'itemId', 'callId']
+        .filter((k) => typeof p[k] === 'string')
+        .map((k) => `${k}=${p[k]}`)
+        .join(' ');
+      (log ?? this.opts.log)?.warn?.(
+        `answering app-server request "${method}" with ${
+          denial === undefined ? 'method-not-found error' : 'denial'
+        } (headless bridge cannot approve)${ids ? ` [${ids}]` : ''}`,
+      );
+      return denial === undefined ? undefined : { result: denial };
+    });
 
     proc.once('close', (code, signal) => this.handleSubprocessClose(proc, code, signal, log));
     proc.once('error', (err) => this.handleSubprocessClose(proc, null, null, log, err));
@@ -686,6 +956,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.activeTurnIds.clear();
     this.pendingInjections.clear();
     this.resumedThreadIds.clear();
+    this.instructionsRefresher.clearThreadState();
+    this.mainLaneQuarantined = false;
+    this.notifyTapsDisposed(`Codex app-server ${reason}`);
     this.client = null;
     this.proc = null;
     this.initialized = false;
@@ -714,8 +987,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     if (this.opts.developerInstructions) {
       // Typed top-level param (camelCase), NOT a raw config.toml override —
       // trust-independent, so the platform prompt loads regardless of any codex
-      // workspace-trust state. thread/start applies it; thread/resume keeps the
-      // thread's own copy. Sent on both — see the option doc.
+      // workspace-trust state. thread/start bakes it in; a fresh-process
+      // thread/resume applies it to the canonical configuration — see the
+      // option doc for the two-plane semantics.
       commonParams.developerInstructions = this.opts.developerInstructions;
     }
     if (this.opts.model) commonParams.model = this.opts.model;
@@ -744,6 +1018,16 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   }
 
   private routeNotification(method: string, params: unknown) {
+    // Taps observe the raw stream (instructions refresh awaits its compaction
+    // turn through one); the sink routing below is unaffected — including by
+    // a tap that throws, which must never break turn delivery.
+    for (const tap of this.notificationTaps) {
+      try {
+        tap(method, params);
+      } catch (err) {
+        this.opts.log?.warn?.(`notification tap threw: ${errToString(err)}`);
+      }
+    }
     const threadId = extractThreadIdFromNotification(params);
     if (!threadId) {
       // Surface server-initiated generic errors to every active turn.
@@ -757,7 +1041,24 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     }
 
     const sink = this.activeTurns.get(threadId);
-    if (!sink) return;
+    if (!sink) {
+      // A reconciling thread's compaction turn is INTENTIONALLY tap-only —
+      // it runs before any TurnSink exists. Warning here would pollute every
+      // successful instructions refresh and burn the shared rate-limit
+      // window that exists to surface REAL orphaned turns.
+      if (this.reconcilingThreadIds.has(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
+      // side would see indefinite silence, so keep the drop visible
+      // (rate-limited: these arrive per-delta during an orphaned turn).
+      const now = Date.now();
+      if (now - this.lastUnroutedNotificationWarnAt > 10_000) {
+        this.lastUnroutedNotificationWarnAt = now;
+        this.opts.log?.warn?.(`dropping notification "${method}" for unknown thread ${threadId}`);
+      }
+      return;
+    }
 
     // For turn/completed we still run the mapper first — it emits a
     // RuntimeEvent error if `turn.status === "failed"`. Enqueue those events
@@ -772,6 +1073,10 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   }
 }
 
+type OpenDispatchOutcome =
+  | { ok: true; client: JsonRpcStdioClient; threadId: string; reconcile?: RefreshOutcome }
+  | { ok: false; message: string };
+
 function errToString(err: unknown): string {
   if (err instanceof Error) return err.message;
   return String(err);