@parall/codex-agent 1.45.0 → 1.46.0

package/dist/dispatch.js

@@ -2,10 +2,12 @@ import { 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 { IS_WIN32, ensureGitRepo, killWin32Tree, quoteWin32Arg } from './app-server-process.js';
+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 { 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://`.
@@ -31,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
@@ -51,6 +68,33 @@ 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)
@@ -90,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();
     }
@@ -114,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);
@@ -255,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 });
@@ -296,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;
             }
@@ -348,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.
@@ -365,6 +568,14 @@ 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';
@@ -406,19 +617,28 @@ export class CodexAppServerAdapter {
      * 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() {
         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 after a capability change (new threads pick up the refreshed developerInstructions; an already-persisted thread keeps its own)');
+        (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() {
@@ -436,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) {
@@ -457,6 +681,7 @@ export class CodexAppServerAdapter {
             this.proc = null;
             this.initialized = false;
             this.resumedThreadIds.clear();
+            this.instructionsRefresher.clearThreadState();
         }
         if (this.initialized && this.client)
             return;
@@ -478,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
@@ -544,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 {
@@ -592,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;
@@ -616,8 +863,9 @@ export class CodexAppServerAdapter {
         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)
@@ -644,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.
@@ -656,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.

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import * as os from 'node:os';
-import { ParallAgentGateway, capabilityBinDir, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, materializeChannelCapabilities, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, initAgentTelemetry, } from '@parall/agent-core';
+import { ParallAgentGateway, capabilityBinDir, configureHttpKeepAlive, createPlatformConfigManager, createLogger, createOtelLogger, childLogger, deriveModelIsPin, materializeChannelCapabilities, resolveRuntimeModel, parseShutdownDeadlineMs, parseForkDeadlineMs, parseDispatchDeadlineMs, parseProviderConfig, clearAllProviderCreds, llmSource, initAgentTelemetry, } from '@parall/agent-core';
 import { ApiError, ParallClient, ParallWs } from '@parall/sdk';
 import { buildCodexRuntimeKey, contextFilePathForSession, dispatchContextDirPath, resolveCodexAgentConfig, resolveWsUrl, sessionStateFilePathForRuntime, stepIdFilePathForSession, } from './config.js';
 import { CodexAppServerAdapter } from './dispatch.js';
@@ -38,6 +38,8 @@ function resolveProviderEnv() {
     }
 }
 async function main() {
+    // Before any fetch: long-lived HTTP connections for every bridge→api call.
+    configureHttpKeepAlive();
     const telemetry = await initAgentTelemetry('parall-codex-agent', 'codex');
     activeLog = createOtelLogger('agent', 'codex-agent');
     try {
@@ -155,13 +157,13 @@ async function main() {
             //
             // What each half of the refresh actually reaches: the shim dir on PATH
             // makes the granted TOOL work on the agent's next shell command, live,
-            // no restart needed. The refreshed PROMPT reaches the next thread that
-            // gets STARTED — codex bakes developerInstructions into a thread at
-            // thread/start and neither resume nor fork replaces them (live-probed on
-            // 0.144.1; the retired workspace-config channel had the same limitation).
-            // So an agent with a long-lived persisted thread keeps the older fragment
-            // text in its prompt until that thread is replaced —
-            // docs/tech-debt/codex-persisted-thread-prompt-refresh.md.
+            // no restart needed. The refreshed PROMPT reaches (a) every thread
+            // started from here on (thread/start bakes it in), and (b) the
+            // persisted main thread on its next safe dispatch: the restart below
+            // makes the next open a fresh-process thread/resume, which applies the
+            // new value to the thread's canonical configuration, and the adapter
+            // then compacts the thread so the model-visible context is rebuilt from
+            // it (two-plane semantics: src/instructions-refresh.ts).
             const fragments = applyChannelCapabilities();
             const joinedFragments = fragments.join('\n\n');
             let promptWritten = true;