@parall/codex-agent 1.45.0 → 1.46.0

package/src/session-manager.ts

@@ -5,6 +5,22 @@ import type { ForkSessionHandle } from '@parall/agent-core';
 type PersistedThread = {
   runtimeKey: string;
   threadId: string;
+  /**
+   * sha256 (hex) of the platform instructions last known EFFECTIVE on the
+   * main thread — i.e. present in the thread's model-visible initial context:
+   * recorded when the thread is started (thread/start bakes them in) or after
+   * a compaction rebuilt the context from the resumed configuration. NOT
+   * recorded on resume alone — resume updates the canonical configuration
+   * but leaves the model-visible context untouched (see
+   * instructions-refresh.ts). ONE exception weakens the "proven visible"
+   * reading: a legacy state file (no sha) ADOPTS the current prompt as
+   * baseline without a compaction — there the sha means "assumed baseline,
+   * converges at the next change or organic compaction", not verified
+   * delivery. Absent on state files from before this tracking existed.
+   * Dropped whenever the thread id changes (an effectiveness fact is
+   * per-thread).
+   */
+  effectiveInstructionsSha?: string;
 };
 
 type Logger = { warn(message: string): void };
@@ -17,6 +33,7 @@ type Logger = { warn(message: string): void };
  */
 export class CodexSessionManager {
   private readonly threadIds = new Map<string, string>();
+  private readonly effectiveInstructionsShas = new Map<string, string>();
 
   constructor(
     readonly mainSessionKey: string,
@@ -35,9 +52,47 @@ export class CodexSessionManager {
   }
 
   recordThreadId(sessionKey: string, threadId: string) {
+    // An effective-instructions sha is a fact about one specific thread.
+    // Recording a DIFFERENT thread id under the same session invalidates it;
+    // re-recording the same id (the resume path) must preserve it, or every
+    // bridge restart would trigger a redundant refresh.
+    if (this.threadIds.get(sessionKey) !== threadId) {
+      this.effectiveInstructionsShas.delete(sessionKey);
+    }
     this.threadIds.set(sessionKey, threadId);
     if (sessionKey === this.mainSessionKey) {
-      this.persist(threadId);
+      this.persist();
+    }
+  }
+
+  /**
+   * Record a freshly-STARTED thread together with the sha of the
+   * instructions baked into it — one atomic state-file write. Two separate
+   * writes (thread id, then sha) would leave a crash window whose survivor
+   * looks exactly like a pre-tracking legacy file, and the reconcile path
+   * deliberately does NOT compact legacy state — a stale thread would then
+   * be recorded as carrying instructions it never saw.
+   */
+  recordStartedThread(sessionKey: string, threadId: string, effectiveSha: string | undefined) {
+    this.threadIds.set(sessionKey, threadId);
+    if (effectiveSha) {
+      this.effectiveInstructionsShas.set(sessionKey, effectiveSha);
+    } else {
+      this.effectiveInstructionsShas.delete(sessionKey);
+    }
+    if (sessionKey === this.mainSessionKey) {
+      this.persist();
+    }
+  }
+
+  getEffectiveInstructionsSha(sessionKey: string): string | undefined {
+    return this.effectiveInstructionsShas.get(sessionKey);
+  }
+
+  recordEffectiveInstructionsSha(sessionKey: string, sha: string) {
+    this.effectiveInstructionsShas.set(sessionKey, sha);
+    if (sessionKey === this.mainSessionKey) {
+      this.persist();
     }
   }
 
@@ -50,11 +105,13 @@ export class CodexSessionManager {
 
   cleanupFork(sessionKey: string) {
     this.threadIds.delete(sessionKey);
+    this.effectiveInstructionsShas.delete(sessionKey);
   }
 
   /** Clear the main thread id when app-server rejects it (stale / deleted). */
   clearMainThread() {
     this.threadIds.delete(this.mainSessionKey);
+    this.effectiveInstructionsShas.delete(this.mainSessionKey);
     try {
       fs.rmSync(this.stateFilePath, { force: true });
     } catch (error) {
@@ -74,6 +131,15 @@ export class CodexSessionManager {
         parsed.threadId.trim()
       ) {
         this.threadIds.set(this.mainSessionKey, parsed.threadId.trim());
+        if (
+          typeof parsed.effectiveInstructionsSha === 'string' &&
+          parsed.effectiveInstructionsSha.trim()
+        ) {
+          this.effectiveInstructionsShas.set(
+            this.mainSessionKey,
+            parsed.effectiveInstructionsSha.trim(),
+          );
+        }
       }
     } catch (error) {
       if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
@@ -84,7 +150,9 @@ export class CodexSessionManager {
     }
   }
 
-  private persist(threadId: string) {
+  private persist() {
+    const threadId = this.threadIds.get(this.mainSessionKey);
+    if (!threadId) return;
     // Atomic write: truncate-in-place risks leaving a half-written / zero-byte
     // state file if the process dies between `open(O_TRUNC)` and the final
     // fsync. Since this file is the sole source of cross-restart `resume`
@@ -94,10 +162,10 @@ export class CodexSessionManager {
     try {
       fs.mkdirSync(path.dirname(this.stateFilePath), { recursive: true });
       const tmpPath = `${this.stateFilePath}.tmp`;
-      fs.writeFileSync(
-        tmpPath,
-        JSON.stringify({ runtimeKey: this.mainSessionKey, threadId }, null, 2),
-      );
+      const state: PersistedThread = { runtimeKey: this.mainSessionKey, threadId };
+      const effectiveSha = this.effectiveInstructionsShas.get(this.mainSessionKey);
+      if (effectiveSha) state.effectiveInstructionsSha = effectiveSha;
+      fs.writeFileSync(tmpPath, JSON.stringify(state, null, 2));
       fs.renameSync(tmpPath, this.stateFilePath);
     } catch (error) {
       this.logger?.warn(

package/src/turn-sink.ts

@@ -45,4 +45,10 @@ export class TurnSink {
     this.resolver = null;
     r?.({ kind: 'turn_end' });
   }
+
+  /** True once close() ran — the sink's terminal state (queued envelopes may
+   * still drain via next()). */
+  get isClosed(): boolean {
+    return this.closed;
+  }
 }

package/src/workspace.ts

@@ -563,12 +563,11 @@ function systemPromptCopyPath(workspaceDir: string): string {
 // guide, before skill references; empty/absent = no capability section.
 // Split out from ensureCodexWorkspace so the bridge can rebuild the prompt on
 // a platform-config heat-update and hand the new value to
-// adapter.updateConfig, which carries it into the NEXT thread/start. A thread
-// that is already open keeps the instructions it was started with — codex
-// bakes them into the thread at start and neither thread/resume nor
-// thread/fork replaces them (verified against a live 0.144.1 app-server; the
-// retired workspace-config channel behaved identically). See
-// docs/tech-debt/codex-persisted-thread-prompt-refresh.md.
+// adapter.updateConfig. Delivery to threads is the adapter's job: baked into
+// new threads at thread/start; converged onto the persisted main thread via
+// the lazy restart's fresh-process thread/resume (canonical configuration)
+// plus an explicit compaction (model-visible context) — see
+// src/instructions-refresh.ts for the two-plane semantics.
 // Throws on failure BY DESIGN — at boot the prompt is mandatory, so a write
 // failure must fail startup loudly; the refresh hot path wraps this in
 // try/catch and retries next refresh.