@parall/codex-agent 1.44.0 → 1.46.0

package/src/dispatch.ts

@@ -1,13 +1,6 @@
-import { execSync, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { type ChildProcessWithoutNullStreams, spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {
-  appendPreparedLocalAttachmentRefs,
-  ensureLocalAttachmentGitExclude,
-  pinLocalAttachmentPaths,
-} from '@parall/agent-core/internal/attachment-input';
-import type { PreparedLocalImage } from '@parall/agent-core/internal/attachment-input';
 import type {
   CleanupForkOpts,
   DispatchAdapter,
@@ -17,11 +10,29 @@ import type {
   GatewayLogger,
   RuntimeEvent,
 } from '@parall/agent-core';
+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,
+  extractThreadIdFromNotification,
+  extractTurnId,
+} from './app-server-protocol.js';
 import type { CodexAgentConfig } from './config.js';
 import { normalizeApprovalPolicy, normalizeSandbox } from './config.js';
-import { EventMapper } from './event-mapping.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';
 
 type CodexAppServerAdapterOptions = Pick<
   CodexAgentConfig,
@@ -46,13 +57,31 @@ type CodexAppServerAdapterOptions = Pick<
    * on its next shell command — no respawn needed.
    */
   capabilityBinDir?: string;
+  /**
+   * Platform system prompt, delivered per-thread via the app-server's typed
+   * top-level `developerInstructions` param — the ONLY delivery channel. It
+   * replaces the legacy workspace `.codex/config.toml` + global trust entry,
+   * 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 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 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;
 };
 
-type TurnEventEnvelope =
-  | { kind: 'runtime'; event: RuntimeEvent }
-  | { kind: 'turn_end'; threadId?: string }
-  | { kind: 'error'; message: string };
-
 /**
  * Bridge driver backed by `codex app-server --listen stdio://`.
  *
@@ -67,22 +96,6 @@ type TurnEventEnvelope =
  * main + fork can interleave turns on the same stdio pipe. We route
  * notifications by threadId the server stamps on every item/turn event.
  */
-const IS_WIN32 = process.platform === 'win32';
-
-function quoteWin32Arg(arg: string): string {
-  if (!/[\s"&|^<>()]/.test(arg)) return arg;
-  return `"${arg.replace(/"/g, '""')}"`;
-}
-
-function killWin32Tree(pid: number): boolean {
-  try {
-    execSync(`taskkill /T /F /PID ${pid}`, { windowsHide: true, stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export class CodexAppServerAdapter implements DispatchAdapter {
   private client: JsonRpcStdioClient | null = null;
   private proc: ChildProcessWithoutNullStreams | null = null;
@@ -92,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
@@ -114,12 +142,47 @@ 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);
+  }
 
-  updateConfig(config: { model?: string | null; reasoningEffort?: string | null }): void {
+  /**
+   * 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;
+    reasoningEffort?: string | null;
+    developerInstructions?: string | null;
+  }): void {
     if (config.model !== undefined) this.opts.model = config.model ?? undefined;
     if (config.reasoningEffort !== undefined)
       this.opts.reasoningEffort = config.reasoningEffort ?? undefined;
+    if (config.developerInstructions !== undefined)
+      this.opts.developerInstructions = config.developerInstructions ?? undefined;
   }
 
   async enqueueDuringDispatch(sessionKey: string, body: string): Promise<boolean> {
@@ -148,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();
   }
@@ -183,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();
@@ -322,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 });
@@ -363,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;
       }
@@ -416,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.
@@ -432,10 +666,23 @@ 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';
       }
+      if (this.opts.developerInstructions) {
+        // Accepted, but the fork inherits the parent's instructions instead —
+        // so it carries the platform prompt either way. See the option doc.
+        forkParams.developerInstructions = this.opts.developerInstructions;
+      }
       if (this.opts.model) forkParams.model = this.opts.model;
       if (this.opts.reasoningEffort) {
         // Raw config.toml key — see openThread for the snake_case rationale.
@@ -464,11 +711,17 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   }
 
   /**
-   * Lazily restart the app-server before the NEXT turn: the workspace
-   * config.toml (developer_instructions, carrying capability fragments) is
-   * loaded at process start, so a changed fragment set needs a respawn to
-   * reach the prompt. Deferred to the next dispatch with no active turns —
-   * never kills an in-flight turn; thread state survives via thread/resume.
+   * Lazily restart the app-server before the NEXT turn, so a subprocess that
+   * has been running since before a capability change starts clean. Deferred
+   * to the next dispatch with no active turns — never kills an in-flight turn;
+   * thread state survives via thread/resume.
+   *
+   * 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;
@@ -476,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 to pick up updated developer_instructions',
+      '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();
   }
@@ -500,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)) {
@@ -521,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;
@@ -540,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
@@ -613,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));
@@ -668,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;
@@ -693,6 +984,14 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       commonParams.modelProvider = 'parall';
     }
     commonParams.sandbox = normalizeSandbox(this.opts.sandbox);
+    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 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;
     if (this.opts.reasoningEffort) {
       // The nested `config` object is raw config.toml overrides and keeps the
@@ -719,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.
@@ -732,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
@@ -747,113 +1073,9 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   }
 }
 
-/** Per-turn buffered sink backed by an unbounded promise queue. */
-class TurnSink {
-  readonly mapper = new EventMapper();
-  private readonly queue: TurnEventEnvelope[] = [];
-  private resolver: ((value: TurnEventEnvelope) => void) | null = null;
-  private closed = false;
-
-  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;
-    });
-  }
-
-  close() {
-    this.closed = true;
-    const r = this.resolver;
-    this.resolver = null;
-    r?.({ kind: 'turn_end' });
-  }
-}
-
-function ensureGitRepo(workingDirectory: string): void {
-  fs.mkdirSync(workingDirectory, { recursive: true });
-  // Only `git init` if the workspace isn't already inside any git repo. A
-  // bare existsSync(.git) check would miss the common case of a user pointing
-  // PRLL_WORKSPACE_DIR at a subdirectory of their existing project,
-  // and silently creating a nested repo there would mangle their layout.
-  try {
-    execSync('git rev-parse --is-inside-work-tree', { cwd: workingDirectory, stdio: 'pipe' });
-    ensureLocalAttachmentGitExclude(workingDirectory);
-    return;
-  } catch {
-    // Not inside a repo — fall through to init.
-  }
-  const env = {
-    ...process.env,
-    GIT_AUTHOR_NAME: 'parall-codex-agent',
-    GIT_AUTHOR_EMAIL: 'agent@parall.local',
-    GIT_COMMITTER_NAME: 'parall-codex-agent',
-    GIT_COMMITTER_EMAIL: 'agent@parall.local',
-  };
-  try {
-    execSync('git init', { cwd: workingDirectory, stdio: 'pipe', env });
-    execSync('git commit --allow-empty -m init', { cwd: workingDirectory, stdio: 'pipe', env });
-    ensureLocalAttachmentGitExclude(workingDirectory);
-  } catch {
-    // Non-fatal: codex app-server may still accept a bare directory. Let it raise at turn time.
-  }
-}
-
-type CodexTurnInput = { type: 'text'; text: string } | { type: 'localImage'; path: string };
-
-function buildTurnInput(body: string, images: PreparedLocalImage[]): CodexTurnInput[] {
-  return [
-    { type: 'text', text: body },
-    ...images.map((image) => ({ type: 'localImage' as const, path: image.localPath })),
-  ];
-}
-
-function extractThreadId(result: unknown): string | undefined {
-  if (!result || typeof result !== 'object') return undefined;
-  const r = result as Record<string, unknown>;
-  if (typeof r.threadId === 'string') return r.threadId;
-  const thread = r.thread as Record<string, unknown> | undefined;
-  if (thread && typeof thread.id === 'string') return thread.id;
-  return undefined;
-}
-
-function extractTurnId(result: unknown): string | undefined {
-  if (!result || typeof result !== 'object') return undefined;
-  const r = result as Record<string, unknown>;
-  if (typeof r.turnId === 'string') return r.turnId;
-  const turn = r.turn as Record<string, unknown> | undefined;
-  if (turn && typeof turn.id === 'string') return turn.id;
-  return undefined;
-}
-
-function extractThreadIdFromNotification(params: unknown): string | undefined {
-  if (!params || typeof params !== 'object') return undefined;
-  const p = params as Record<string, unknown>;
-  if (typeof p.threadId === 'string') return p.threadId;
-  const thread = p.thread as Record<string, unknown> | undefined;
-  if (thread && typeof thread.id === 'string') return thread.id;
-  const meta = (p._meta ?? p.meta) as Record<string, unknown> | undefined;
-  if (meta && typeof meta.threadId === 'string') return meta.threadId;
-  return undefined;
-}
+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;