@parall/codex-agent 1.44.0 → 1.46.0

package/src/legacy-workspace-config-migration.ts

@@ -0,0 +1,296 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * One-shot migration for workspaces last bootstrapped by a pre-protocol-delivery
+ * bridge.
+ *
+ * Those generations (every released bridge up to and including v1.44.0) injected
+ * the system prompt by writing `<workspace>/.codex/config.toml`
+ * (`developer_instructions`) and marking the workspace trusted in the operator's
+ * global codex config. Instructions now ride the app-server's per-thread
+ * `developerInstructions` param, so a leftover bridge-authored file would DOUBLE
+ * the instructions on any workspace codex still considers trusted.
+ *
+ * Deleting a file in someone's workspace is the destructive direction, so the
+ * gate is fail-closed: we remove ONLY what is provably the retired bridge's own
+ * artifact, and preserve (with a warning) everything else. A duplicated prompt
+ * is a degraded agent; a deleted operator file is lost work.
+ *
+ * WHY THIS IS ONE-SHOT AND NOT MERELY IDEMPOTENT. The authorship proof is
+ * `.parall/system-prompt.md`, and the bridge REWRITES that file on every boot.
+ * So it is legacy-era evidence exactly once: on the first protocol-delivery boot,
+ * before anything overwrites it. A gate that merely re-ran each boot would, from
+ * boot 2 on, be comparing the legacy config against a prompt THIS bridge wrote —
+ * evidence it manufactured itself. That is not hypothetical: prompt assembly is
+ * deterministic, so a file the first boot explicitly preserved as "not provably
+ * ours" can match on the next boot and be silently deleted, contradicting the
+ * warning the operator was just given. Fail-closed has to hold across the whole
+ * migration lifecycle, not per function call.
+ *
+ * Hence a versioned, one-way CLAIM (`.parall/legacy-workspace-config-migration.v1`),
+ * created atomically (`wx`) BEFORE any prompt write:
+ *   - exactly one boot ever wins the claim — it alone may delete;
+ *   - every later boot (and every concurrent loser) skips, silently, forever;
+ *   - a claim that cannot be persisted FAILS the boot before the proof is
+ *     overwritten, so a retry still has real evidence;
+ *   - a boot that dies mid-migration leaves the claim behind, so the file is
+ *     preserved forever rather than re-judged against fabricated evidence.
+ *
+ * The whole module is dead code once no workspace can still hold a pre-#1866
+ * artifact — sunset conditions in
+ * docs/tech-debt/codex-legacy-workspace-config-shim.md.
+ */
+
+/** Relative location of the retired bridge's workspace config. */
+const LEGACY_CONFIG_RELPATH = ['.codex', 'config.toml'];
+
+/**
+ * The one-way claim. Versioned: a future migration gets its own sentinel rather
+ * than reusing (or re-arming) this one.
+ */
+const MIGRATION_SENTINEL_RELPATH = ['.parall', 'legacy-workspace-config-migration.v1'];
+
+export function legacyWorkspaceConfigPath(workspaceDir: string): string {
+  return path.join(workspaceDir, ...LEGACY_CONFIG_RELPATH);
+}
+
+export function migrationSentinelPath(workspaceDir: string): string {
+  return path.join(workspaceDir, ...MIGRATION_SENTINEL_RELPATH);
+}
+
+/**
+ * Byte-exact reconstruction of the retired serializer. Verified identical across
+ * every released bridge that wrote this file (v1.37.0 … v1.44.0 — the line is
+ * byte-for-byte the same in all of them), so a single reconstruction covers the
+ * whole legacy fleet. The deletion gate compares raw bytes against this: it must
+ * never drift.
+ */
+export function legacyWorkspaceConfigToml(prompt: string): string {
+  return `developer_instructions = """\n${prompt.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""')}\n"""\n`;
+}
+
+/**
+ * The PRE-OVERWRITE `.parall/system-prompt.md`. The retired bridge wrote the
+ * reference copy and the config from the SAME string in the same call, so a byte
+ * match against `legacyWorkspaceConfigToml(prompt)` is what identifies our own
+ * artifact.
+ *
+ * `absent` (ENOENT — the bridge never bootstrapped this workspace) and
+ * `unreadable` (it is there, but an I/O error hid it) both mean "cannot prove
+ * ownership, so do not delete" — but they are different facts, and reporting the
+ * second as the first tells the operator the wrong reason for a preserved file.
+ */
+export type AuthorshipProof =
+  | { kind: 'present'; prompt: string }
+  | { kind: 'absent' }
+  | { kind: 'unreadable' };
+
+/**
+ * What the filesystem says about the legacy config. Gathered by the executor;
+ * the classifier below sees nothing else — no fs, no clock, no env.
+ */
+export type LegacyConfigFacts = {
+  /** lstat of the legacy path — never a stat: a symlink must not be followed. `null` = ENOENT. */
+  entry: { isPlainFile: boolean; hardLinks: number } | null;
+  /** Raw bytes of the legacy file. `null` = not a plain file, or unreadable. */
+  rawContent: string | null;
+  proof: AuthorshipProof;
+};
+
+export type LegacyConfigVerdict =
+  | { action: 'none' }
+  | { action: 'remove' }
+  | { action: 'preserve'; reason: PreserveReason };
+
+export type PreserveReason =
+  /** Symlink (a dotfiles arrangement) or a directory — unlink-by-path would sever the operator's link. */
+  | 'not-a-plain-file'
+  /** Extra hard links: the same inode is reachable from a path we know nothing about. */
+  | 'extra-hard-links'
+  /** No `.parall/system-prompt.md` from a previous boot — no proof can exist. */
+  | 'no-authorship-proof'
+  /** The proof copy exists but could not be read, so ownership cannot be evaluated. */
+  | 'authorship-proof-unreadable'
+  /** Could not read the legacy config's own bytes, so the proof cannot be applied. */
+  | 'config-unreadable'
+  /** Bytes differ from what the retired bridge would have written (operator-authored, comments, hand-edited). */
+  | 'content-mismatch';
+
+/**
+ * Pure. Decides the fate of the legacy config from filesystem facts alone.
+ *
+ * The only path to `remove` is: plain regular file + exactly one hard link + a
+ * pre-overwrite reference copy exists + raw bytes are EXACTLY the retired
+ * serializer's output for that reference prompt. Every other combination
+ * preserves — including value-level near-misses (an operator file carrying the
+ * same `developer_instructions` value plus a comment would be destroyed together
+ * with the comment by a value-level compare).
+ */
+export function classifyLegacyWorkspaceConfig(facts: LegacyConfigFacts): LegacyConfigVerdict {
+  const { entry, rawContent, proof } = facts;
+  if (!entry) return { action: 'none' };
+  if (!entry.isPlainFile) return { action: 'preserve', reason: 'not-a-plain-file' };
+  if (entry.hardLinks !== 1) return { action: 'preserve', reason: 'extra-hard-links' };
+  if (proof.kind === 'absent') return { action: 'preserve', reason: 'no-authorship-proof' };
+  if (proof.kind === 'unreadable') {
+    return { action: 'preserve', reason: 'authorship-proof-unreadable' };
+  }
+  if (rawContent === null) return { action: 'preserve', reason: 'config-unreadable' };
+  if (rawContent !== legacyWorkspaceConfigToml(proof.prompt)) {
+    return { action: 'preserve', reason: 'content-mismatch' };
+  }
+  return { action: 'remove' };
+}
+
+const PRESERVE_DETAIL: Record<PreserveReason, string> = {
+  'not-a-plain-file':
+    'it is a symlink or directory, not a plain file the bridge could have written',
+  'extra-hard-links': 'the file has more than one hard link, so another path shares this inode',
+  'no-authorship-proof':
+    'this workspace has no .parall/system-prompt.md from a previous boot, so nothing here can be proven ours',
+  'authorship-proof-unreadable':
+    'the .parall/system-prompt.md authorship proof exists but could not be read, so ownership cannot be evaluated',
+  'config-unreadable': 'its own bytes could not be read, so authorship cannot be proven',
+  'content-mismatch': 'its bytes are not what the retired bridge would have written',
+};
+
+const SENTINEL_BODY = `Parall codex bridge — one-shot workspace migration record (v1)
+
+The legacy workspace-config cleanup has been CLAIMED for this workspace. Only the
+boot that created this file was allowed to remove a bridge-authored
+.codex/config.toml, and only under a byte-exact authorship proof.
+
+While this file exists the bridge will NEVER auto-remove .codex/config.toml again.
+Deleting this file does not safely re-arm the migration: the evidence it relied on
+(.parall/system-prompt.md as written by a pre-protocol-delivery bridge) has since
+been overwritten by this bridge, so a re-run could mistake a prompt it wrote itself
+for legacy evidence and delete a file that is not ours.
+
+If a stale .codex/config.toml is still present, remove it by hand.
+`;
+
+export type MigrationClaim = 'claimed' | 'already-claimed';
+
+/**
+ * Atomically take the one-way claim. `wx` makes this a single filesystem
+ * operation, so concurrent boots cannot both win.
+ *
+ * THROWS if the claim cannot be persisted (EACCES, EIO, EROFS …). That is
+ * deliberate and load-bearing: the caller runs this BEFORE overwriting
+ * `.parall/system-prompt.md`, so a boot that cannot record its claim must die
+ * with the legacy evidence still intact rather than proceed to manufacture a
+ * prompt that a later boot would mistake for that evidence.
+ */
+export function claimLegacyWorkspaceConfigMigration(workspaceDir: string): MigrationClaim {
+  const sentinel = migrationSentinelPath(workspaceDir);
+  // The module owns its own sentinel, directory included — a caller that has not
+  // created `.parall` yet must still get a real claim, not an ENOENT throw.
+  fs.mkdirSync(path.dirname(sentinel), { recursive: true });
+  try {
+    fs.writeFileSync(sentinel, SENTINEL_BODY, { flag: 'wx' });
+    return 'claimed';
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'EEXIST') return 'already-claimed';
+    throw err;
+  }
+}
+
+/**
+ * The migration lifecycle: claim, then — only if we won the claim — read the
+ * proof and clean up.
+ *
+ * `readProof` is a THUNK, not a value, and that is the whole point. Reading the
+ * proof is not free of side effects: an unreadable `.parall/system-prompt.md`
+ * warns. Passed as an already-evaluated argument, that warning fires before the
+ * claim is even checked — so an already-claimed later boot, or a concurrent
+ * loser, would emit a migration warning about a decision it is not making. The
+ * thunk makes "only the winner touches the proof" a property of the type rather
+ * than of the caller's evaluation order.
+ *
+ * The caller still owns `.parall/system-prompt.md` and must hand over the
+ * PRE-OVERWRITE copy: the winner evaluates the thunk here, before anything
+ * writes a new prompt.
+ *
+ * A boot that does not win the claim returns silently — it must not delete, it
+ * must not read, and it must not warn: the winner may be deleting the very file
+ * it would warn about, and a stale warning about a file that is already gone is
+ * exactly the misleading diagnostic this module exists to avoid.
+ */
+export function runLegacyWorkspaceConfigMigration(
+  workspaceDir: string,
+  readProof: () => AuthorshipProof,
+  log?: { warn: (msg: string) => void },
+): void {
+  if (claimLegacyWorkspaceConfigMigration(workspaceDir) === 'already-claimed') return;
+  cleanupLegacyWorkspaceConfig(workspaceDir, readProof(), log);
+}
+
+/**
+ * Filesystem execution for the one boot that holds the claim. Reads the facts,
+ * asks the classifier, applies the verdict.
+ *
+ * Never throws: a workspace that cannot be migrated must still boot. Every
+ * non-ENOENT problem warns.
+ */
+function cleanupLegacyWorkspaceConfig(
+  workspaceDir: string,
+  proof: AuthorshipProof,
+  log?: { warn: (msg: string) => void },
+): void {
+  const configPath = legacyWorkspaceConfigPath(workspaceDir);
+
+  let entry: fs.Stats;
+  try {
+    entry = fs.lstatSync(configPath);
+  } catch (err) {
+    // Only ENOENT means "nothing to clean up". Anything else (EACCES, EIO, …)
+    // leaves an unverifiable file behind — surface it rather than silently
+    // treating it as absent.
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      log?.warn(`could not inspect legacy workspace codex config ${configPath}: ${String(err)}`);
+    }
+    return;
+  }
+
+  const isPlainFile = entry.isFile();
+  let rawContent: string | null = null;
+  if (isPlainFile) {
+    try {
+      rawContent = fs.readFileSync(configPath, 'utf8');
+    } catch (err) {
+      // Read failure → rawContent stays null → the classifier preserves
+      // ('config-unreadable'). Log the cause here; the verdict warning follows.
+      log?.warn(`could not read legacy workspace codex config ${configPath}: ${String(err)}`);
+    }
+  }
+
+  const verdict = classifyLegacyWorkspaceConfig({
+    entry: { isPlainFile, hardLinks: entry.nlink },
+    rawContent,
+    proof,
+  });
+
+  if (verdict.action === 'none') return;
+
+  if (verdict.action === 'remove') {
+    try {
+      fs.unlinkSync(configPath);
+    } catch (err) {
+      // ENOENT here means the file went away between our lstat and this unlink
+      // — a second bridge booting the same workspace (rapid daemon respawn) got
+      // there first. That is exactly the end state we wanted, so it is not a
+      // failure: warning "could not remove" about a file that is already gone
+      // would send the operator after nothing. Concurrent migrations converge.
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') return;
+      log?.warn(`could not remove legacy workspace codex config ${configPath}: ${String(err)}`);
+    }
+    return;
+  }
+
+  log?.warn(
+    `leaving ${configPath} in place — ${PRESERVE_DETAIL[verdict.reason]}, so it is not provably ` +
+      "the retired bridge's own artifact. Codex loads it for trusted workspaces IN ADDITION to " +
+      'the platform instructions; remove it manually if it is a stale artifact.',
+  );
+}

package/src/server-requests.ts

@@ -0,0 +1,40 @@
+/**
+ * Answers for codex app-server server→client requests.
+ *
+ * The bridge runs headless with `approvalPolicy: "never"`, so approval-shaped
+ * requests should not occur — but the protocol allows the app-server to send
+ * them (e.g. a thread that fell back to `on-request`), and an unanswered
+ * request parks its turn until the dispatch deadline. Every known
+ * approval-shaped method is answered with an explicit denial; unknown methods
+ * get a method-not-found error from the JSON-RPC layer (`undefined` here).
+ *
+ * Wire shapes verified against codex-rs 0.144.1
+ * (`app-server-protocol/src/protocol/common.rs` server_request_definitions):
+ * - v2 `item/commandExecution/requestApproval` / `item/fileChange/requestApproval`
+ *   respond `{ decision }` with camelCase variants — `decline` denies but lets
+ *   the turn continue (vs `cancel`, which also interrupts the turn).
+ * - legacy v1 `execCommandApproval` / `applyPatchApproval` (SendUserTurn-era,
+ *   unused by this bridge) respond `{ decision }` with snake_case
+ *   ReviewDecision values.
+ */
+const APPROVAL_DENIALS: Record<string, unknown> = {
+  'item/commandExecution/requestApproval': { decision: 'decline' },
+  'item/fileChange/requestApproval': { decision: 'decline' },
+  // NOT listed: `item/permissions/requestApproval` — its response shape is a
+  // permission GRANT (no deny variant), so denial is correctly expressed by
+  // the -32601 error fallback.
+  execCommandApproval: { decision: 'denied' },
+  applyPatchApproval: { decision: 'denied' },
+};
+
+/**
+ * Returns the response payload for a server request, or `undefined` when the
+ * method is not one we can meaningfully answer (the JSON-RPC client then
+ * replies -32601, which also unblocks the app-server). Own-property lookup
+ * only — a method named like an Object.prototype member (`toString`,
+ * `constructor`) must fall through to -32601, not return an inherited
+ * function that would serialize into a result-less frame.
+ */
+export function answerServerRequest(method: string): unknown | undefined {
+  return Object.hasOwn(APPROVAL_DENIALS, method) ? APPROVAL_DENIALS[method] : undefined;
+}

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

@@ -0,0 +1,54 @@
+import type { RuntimeEvent } from '@parall/agent-core';
+import { EventMapper } from './event-mapping.js';
+
+export type TurnEventEnvelope =
+  | { kind: 'runtime'; event: RuntimeEvent }
+  | { kind: 'turn_end'; threadId?: string }
+  | { kind: 'error'; message: string };
+
+/** Per-turn buffered sink backed by an unbounded promise queue. */
+export 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' });
+  }
+
+  /** True once close() ran — the sink's terminal state (queued envelopes may
+   * still drain via next()). */
+  get isClosed(): boolean {
+    return this.closed;
+  }
+}