@parall/codex-agent 1.44.0 → 1.46.0

package/dist/dispatch.js

@@ -1,11 +1,14 @@
-import { execSync, spawn } from 'node:child_process';
+import { 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 { 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 { normalizeApprovalPolicy, normalizeSandbox } from './config.js';
-import { EventMapper } from './event-mapping.js';
+import { MainThreadInstructionsRefresher, } from './instructions-refresh.js';
 import { JsonRpcStdioClient } from './jsonrpc-client.js';
+import { answerServerRequest } from './server-requests.js';
+import { TurnSink } from './turn-sink.js';
 /**
  * Bridge driver backed by `codex app-server --listen stdio://`.
  *
@@ -20,21 +23,6 @@ import { JsonRpcStdioClient } from './jsonrpc-client.js';
  * 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) {
-    if (!/[\s"&|^<>()]/.test(arg))
-        return arg;
-    return `"${arg.replace(/"/g, '""')}"`;
-}
-function killWin32Tree(pid) {
-    try {
-        execSync(`taskkill /T /F /PID ${pid}`, { windowsHide: true, stdio: 'ignore' });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 export class CodexAppServerAdapter {
     opts;
     client = null;
@@ -45,7 +33,22 @@ export class CodexAppServerAdapter {
     activeTurnIds = new Map();
     pendingInjections = new Map();
     resumedThreadIds = new Set();
+    /** Threads whose reconcile compaction is in flight — tap-only traffic. */
+    reconcilingThreadIds = new Set();
+    /**
+     * 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.
+     */
+    mainLaneQuarantined = false;
+    notificationTaps = new Set();
+    instructionsRefresher;
     stopping = false;
+    lastUnroutedNotificationWarnAt = 0;
     /**
      * Store an active turn sink keyed by threadId. If a sink already exists for
      * the same threadId, log a warning and fail the existing sink — this
@@ -65,12 +68,41 @@ export class CodexAppServerAdapter {
     }
     constructor(opts) {
         this.opts = opts;
+        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) {
+        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.
+     */
+    notifyTapsDisposed(reason) {
+        for (const tap of this.notificationTaps) {
+            try {
+                tap('error', { message: reason });
+            }
+            catch {
+                // Taps must never break teardown.
+            }
+        }
     }
     updateConfig(config) {
         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, body) {
         const client = this.client;
@@ -102,8 +134,23 @@ export class CodexAppServerAdapter {
         if (!threadId)
             return;
         const sink = this.activeTurns.get(threadId);
-        if (!sink)
+        // 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();
     }
@@ -126,69 +173,85 @@ export class CodexAppServerAdapter {
             }
             (this.opts.log ?? context.log)?.warn?.(`pending steer invalidated (subprocess died); falling through to normal dispatch`);
         }
-        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);
-        let threadId = this.opts.sessionManager.getThreadId(sessionKey);
-        if (!threadId) {
-            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)}` };
+        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;
             }
         }
-        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.
+        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();
+        }
+        const log = this.opts.log ?? context.log;
+        let client;
+        let threadId;
+        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;
             try {
-                threadId = await this.openThread(client, { resumeId: threadId });
-                this.opts.sessionManager.recordThreadId(sessionKey, threadId);
-                this.resumedThreadIds.add(threadId);
+                opened = await this.openDispatchTarget(sessionKey, isMainSession, log);
             }
-            catch (err) {
-                log?.warn?.(`thread/resume failed (${errToString(err)}); attempting one-shot fresh-thread start`);
-                let freshThreadId;
-                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;
+            finally {
+                this.openingDispatches -= 1;
             }
+            if (!opened.ok) {
+                yield { type: 'error', message: opened.message };
+                return;
+            }
+            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');
+                this.requestProcessRestart();
+                continue;
+            }
+            break;
         }
         const sink = new TurnSink();
         this.setActiveTurn(threadId, sink, log);
@@ -267,8 +330,33 @@ export class CodexAppServerAdapter {
                     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;
                 try {
                     freshThreadId = await this.openThread(client, { resumeId: undefined });
@@ -308,7 +396,7 @@ export class CodexAppServerAdapter {
                 // 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;
             }
@@ -360,6 +448,109 @@ export class CodexAppServerAdapter {
             }
         }
     }
+    /**
+     * 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.
+     */
+    async openDispatchTarget(sessionKey, isMainSession, log) {
+        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;
+                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;
+        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) {
         // Codex app-server does not expose a branch-point API; fork scope prefix
         // provides the behavioral fallback for this runtime.
@@ -377,10 +568,23 @@ export class CodexAppServerAdapter {
             const forkParams = {
                 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) {
@@ -408,21 +612,33 @@ export class CodexAppServerAdapter {
         return null;
     }
     /**
-     * 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() {
         this.restartRequested = true;
     }
     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.
+     */
+    openingDispatches = 0;
     async applyPendingRestart(log) {
-        if (!this.restartRequested || this.activeTurns.size > 0)
+        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');
+        (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)');
         await this.stop();
     }
     async stop() {
@@ -440,6 +656,10 @@ export class CodexAppServerAdapter {
         // 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) {
@@ -461,6 +681,7 @@ export class CodexAppServerAdapter {
             this.proc = null;
             this.initialized = false;
             this.resumedThreadIds.clear();
+            this.instructionsRefresher.clearThreadState();
         }
         if (this.initialized && this.client)
             return;
@@ -482,6 +703,7 @@ export class CodexAppServerAdapter {
         // 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
         // preserves the user's real dotfiles for any subprocess Codex spawns
@@ -548,6 +770,24 @@ export class CodexAppServerAdapter {
             }
         });
         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 ?? {});
+            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));
         try {
@@ -596,6 +836,9 @@ export class CodexAppServerAdapter {
         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;
@@ -617,6 +860,14 @@ export class CodexAppServerAdapter {
             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) {
@@ -641,6 +892,17 @@ export class CodexAppServerAdapter {
         return threadId;
     }
     routeNotification(method, params) {
+        // 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.
@@ -653,8 +915,25 @@ export class CodexAppServerAdapter {
             return;
         }
         const sink = this.activeTurns.get(threadId);
-        if (!sink)
+        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
         // before the turn_end sentinel so the dispatch loop can yield them.
@@ -667,117 +946,6 @@ export class CodexAppServerAdapter {
         }
     }
 }
-/** Per-turn buffered sink backed by an unbounded promise queue. */
-class TurnSink {
-    mapper = new EventMapper();
-    queue = [];
-    resolver = null;
-    closed = false;
-    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;
-        });
-    }
-    close() {
-        this.closed = true;
-        const r = this.resolver;
-        this.resolver = null;
-        r?.({ kind: 'turn_end' });
-    }
-}
-function ensureGitRepo(workingDirectory) {
-    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.
-    }
-}
-function buildTurnInput(body, images) {
-    return [
-        { type: 'text', text: body },
-        ...images.map((image) => ({ type: 'localImage', path: image.localPath })),
-    ];
-}
-function extractThreadId(result) {
-    if (!result || typeof result !== 'object')
-        return undefined;
-    const r = result;
-    if (typeof r.threadId === 'string')
-        return r.threadId;
-    const thread = r.thread;
-    if (thread && typeof thread.id === 'string')
-        return thread.id;
-    return undefined;
-}
-function extractTurnId(result) {
-    if (!result || typeof result !== 'object')
-        return undefined;
-    const r = result;
-    if (typeof r.turnId === 'string')
-        return r.turnId;
-    const turn = r.turn;
-    if (turn && typeof turn.id === 'string')
-        return turn.id;
-    return undefined;
-}
-function extractThreadIdFromNotification(params) {
-    if (!params || typeof params !== 'object')
-        return undefined;
-    const p = params;
-    if (typeof p.threadId === 'string')
-        return p.threadId;
-    const thread = p.thread;
-    if (thread && typeof thread.id === 'string')
-        return thread.id;
-    const meta = (p._meta ?? p.meta);
-    if (meta && typeof meta.threadId === 'string')
-        return meta.threadId;
-    return undefined;
-}
 function errToString(err) {
     if (err instanceof Error)
         return err.message;