@parall/codex-agent 1.44.0 → 1.45.0

package/src/dispatch.ts

@@ -1,10 +1,8 @@
-import { execSync, spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {
   appendPreparedLocalAttachmentRefs,
-  ensureLocalAttachmentGitExclude,
   pinLocalAttachmentPaths,
 } from '@parall/agent-core/internal/attachment-input';
 import type { PreparedLocalImage } from '@parall/agent-core/internal/attachment-input';
@@ -17,11 +15,18 @@ import type {
   GatewayLogger,
   RuntimeEvent,
 } from '@parall/agent-core';
+import { IS_WIN32, ensureGitRepo, killWin32Tree, quoteWin32Arg } from './app-server-process.js';
+import {
+  buildTurnInput,
+  extractThreadId,
+  extractThreadIdFromNotification,
+  extractTurnId,
+} from './app-server-protocol.js';
 import type { CodexAgentConfig } from './config.js';
 import { normalizeApprovalPolicy, normalizeSandbox } from './config.js';
-import { EventMapper } from './event-mapping.js';
 import { JsonRpcStdioClient } from './jsonrpc-client.js';
 import type { CodexSessionManager } from './session-manager.js';
+import { TurnSink } from './turn-sink.js';
 
 type CodexAppServerAdapterOptions = Pick<
   CodexAgentConfig,
@@ -46,13 +51,28 @@ type CodexAppServerAdapterOptions = Pick<
    * on its next shell command — no respawn needed.
    */
   capabilityBinDir?: string;
+  /**
+   * Platform system prompt, delivered per-thread via the app-server's typed
+   * top-level `developerInstructions` param — the ONLY delivery channel. It
+   * replaces the legacy workspace `.codex/config.toml` + global trust entry,
+   * which coupled the prompt to codex's interactive workspace-trust concept
+   * and made the bridge write into the operator's own config on shared homes.
+   *
+   * Where it lands, live-probed on 0.144.1 — the CLI accepts the param on all
+   * three entrypoints but only `thread/start` APPLIES it (instructions are
+   * baked into the thread there). `thread/resume` keeps the thread's own copy;
+   * `thread/fork` inherits the parent's. The bridge sends it on all three
+   * anyway: a failed resume falls back to thread/start on the same params, and
+   * a future CLI that honors it then needs no bridge change.
+   *
+   * Consequence: updateConfig() changes what the NEXT thread/start sends; it
+   * cannot re-instruct an already-persisted thread. Inherited from the retired
+   * channel, not introduced —
+   * docs/tech-debt/codex-persisted-thread-prompt-refresh.md.
+   */
+  developerInstructions?: string;
 };
 
-type TurnEventEnvelope =
-  | { kind: 'runtime'; event: RuntimeEvent }
-  | { kind: 'turn_end'; threadId?: string }
-  | { kind: 'error'; message: string };
-
 /**
  * Bridge driver backed by `codex app-server --listen stdio://`.
  *
@@ -67,22 +87,6 @@ type TurnEventEnvelope =
  * main + fork can interleave turns on the same stdio pipe. We route
  * notifications by threadId the server stamps on every item/turn event.
  */
-const IS_WIN32 = process.platform === 'win32';
-
-function quoteWin32Arg(arg: string): string {
-  if (!/[\s"&|^<>()]/.test(arg)) return arg;
-  return `"${arg.replace(/"/g, '""')}"`;
-}
-
-function killWin32Tree(pid: number): boolean {
-  try {
-    execSync(`taskkill /T /F /PID ${pid}`, { windowsHide: true, stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 export class CodexAppServerAdapter implements DispatchAdapter {
   private client: JsonRpcStdioClient | null = null;
   private proc: ChildProcessWithoutNullStreams | null = null;
@@ -116,10 +120,16 @@ export class CodexAppServerAdapter implements DispatchAdapter {
 
   constructor(private readonly opts: CodexAppServerAdapterOptions) {}
 
-  updateConfig(config: { model?: string | null; reasoningEffort?: string | null }): void {
+  updateConfig(config: {
+    model?: string | null;
+    reasoningEffort?: string | null;
+    developerInstructions?: string | null;
+  }): void {
     if (config.model !== undefined) this.opts.model = config.model ?? undefined;
     if (config.reasoningEffort !== undefined)
       this.opts.reasoningEffort = config.reasoningEffort ?? undefined;
+    if (config.developerInstructions !== undefined)
+      this.opts.developerInstructions = config.developerInstructions ?? undefined;
   }
 
   async enqueueDuringDispatch(sessionKey: string, body: string): Promise<boolean> {
@@ -436,6 +446,11 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       if (this.opts.useParallProvider) {
         forkParams.modelProvider = 'parall';
       }
+      if (this.opts.developerInstructions) {
+        // Accepted, but the fork inherits the parent's instructions instead —
+        // so it carries the platform prompt either way. See the option doc.
+        forkParams.developerInstructions = this.opts.developerInstructions;
+      }
       if (this.opts.model) forkParams.model = this.opts.model;
       if (this.opts.reasoningEffort) {
         // Raw config.toml key — see openThread for the snake_case rationale.
@@ -464,11 +479,14 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   }
 
   /**
-   * Lazily restart the app-server before the NEXT turn: the workspace
-   * config.toml (developer_instructions, carrying capability fragments) is
-   * loaded at process start, so a changed fragment set needs a respawn to
-   * reach the prompt. Deferred to the next dispatch with no active turns —
-   * never kills an in-flight turn; thread state survives via thread/resume.
+   * Lazily restart the app-server before the NEXT turn, so a subprocess that
+   * has been running since before a capability change starts clean. Deferred
+   * to the next dispatch with no active turns — never kills an in-flight turn;
+   * thread state survives via thread/resume.
+   *
+   * 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.
    */
   requestProcessRestart(): void {
     this.restartRequested = true;
@@ -480,7 +498,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     if (!this.restartRequested || this.activeTurns.size > 0) return;
     this.restartRequested = false;
     (log ?? this.opts.log)?.info?.(
-      'restarting codex app-server to pick up updated developer_instructions',
+      'restarting codex app-server after a capability change (new threads pick up the refreshed developerInstructions; an already-persisted thread keeps its own)',
     );
     await this.stop();
   }
@@ -693,6 +711,13 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       commonParams.modelProvider = 'parall';
     }
     commonParams.sandbox = normalizeSandbox(this.opts.sandbox);
+    if (this.opts.developerInstructions) {
+      // Typed top-level param (camelCase), NOT a raw config.toml override —
+      // trust-independent, so the platform prompt loads regardless of any codex
+      // workspace-trust state. thread/start applies it; thread/resume keeps the
+      // thread's own copy. Sent on both — see the option doc.
+      commonParams.developerInstructions = this.opts.developerInstructions;
+    }
     if (this.opts.model) commonParams.model = this.opts.model;
     if (this.opts.reasoningEffort) {
       // The nested `config` object is raw config.toml overrides and keeps the
@@ -747,114 +772,6 @@ export class CodexAppServerAdapter implements DispatchAdapter {
   }
 }
 
-/** Per-turn buffered sink backed by an unbounded promise queue. */
-class TurnSink {
-  readonly mapper = new EventMapper();
-  private readonly queue: TurnEventEnvelope[] = [];
-  private resolver: ((value: TurnEventEnvelope) => void) | null = null;
-  private closed = false;
-
-  push(envelope: TurnEventEnvelope) {
-    if (this.closed) return;
-    if (this.resolver) {
-      const r = this.resolver;
-      this.resolver = null;
-      r(envelope);
-      return;
-    }
-    this.queue.push(envelope);
-  }
-
-  next(): Promise<TurnEventEnvelope> {
-    // Drain any queued envelopes first, even after close(). Otherwise a final
-    // error envelope enqueued right before close() (e.g. by
-    // handleSubprocessClose) is silently dropped because the consumer would
-    // see turn_end before it.
-    const pending = this.queue.shift();
-    if (pending) return Promise.resolve(pending);
-    if (this.closed) {
-      return Promise.resolve({ kind: 'turn_end' });
-    }
-    return new Promise((resolve) => {
-      this.resolver = resolve;
-    });
-  }
-
-  close() {
-    this.closed = true;
-    const r = this.resolver;
-    this.resolver = null;
-    r?.({ kind: 'turn_end' });
-  }
-}
-
-function ensureGitRepo(workingDirectory: string): void {
-  fs.mkdirSync(workingDirectory, { recursive: true });
-  // Only `git init` if the workspace isn't already inside any git repo. A
-  // bare existsSync(.git) check would miss the common case of a user pointing
-  // PRLL_WORKSPACE_DIR at a subdirectory of their existing project,
-  // and silently creating a nested repo there would mangle their layout.
-  try {
-    execSync('git rev-parse --is-inside-work-tree', { cwd: workingDirectory, stdio: 'pipe' });
-    ensureLocalAttachmentGitExclude(workingDirectory);
-    return;
-  } catch {
-    // Not inside a repo — fall through to init.
-  }
-  const env = {
-    ...process.env,
-    GIT_AUTHOR_NAME: 'parall-codex-agent',
-    GIT_AUTHOR_EMAIL: 'agent@parall.local',
-    GIT_COMMITTER_NAME: 'parall-codex-agent',
-    GIT_COMMITTER_EMAIL: 'agent@parall.local',
-  };
-  try {
-    execSync('git init', { cwd: workingDirectory, stdio: 'pipe', env });
-    execSync('git commit --allow-empty -m init', { cwd: workingDirectory, stdio: 'pipe', env });
-    ensureLocalAttachmentGitExclude(workingDirectory);
-  } catch {
-    // Non-fatal: codex app-server may still accept a bare directory. Let it raise at turn time.
-  }
-}
-
-type CodexTurnInput = { type: 'text'; text: string } | { type: 'localImage'; path: string };
-
-function buildTurnInput(body: string, images: PreparedLocalImage[]): CodexTurnInput[] {
-  return [
-    { type: 'text', text: body },
-    ...images.map((image) => ({ type: 'localImage' as const, path: image.localPath })),
-  ];
-}
-
-function extractThreadId(result: unknown): string | undefined {
-  if (!result || typeof result !== 'object') return undefined;
-  const r = result as Record<string, unknown>;
-  if (typeof r.threadId === 'string') return r.threadId;
-  const thread = r.thread as Record<string, unknown> | undefined;
-  if (thread && typeof thread.id === 'string') return thread.id;
-  return undefined;
-}
-
-function extractTurnId(result: unknown): string | undefined {
-  if (!result || typeof result !== 'object') return undefined;
-  const r = result as Record<string, unknown>;
-  if (typeof r.turnId === 'string') return r.turnId;
-  const turn = r.turn as Record<string, unknown> | undefined;
-  if (turn && typeof turn.id === 'string') return turn.id;
-  return undefined;
-}
-
-function extractThreadIdFromNotification(params: unknown): string | undefined {
-  if (!params || typeof params !== 'object') return undefined;
-  const p = params as Record<string, unknown>;
-  if (typeof p.threadId === 'string') return p.threadId;
-  const thread = p.thread as Record<string, unknown> | undefined;
-  if (thread && typeof thread.id === 'string') return thread.id;
-  const meta = (p._meta ?? p.meta) as Record<string, unknown> | undefined;
-  if (meta && typeof meta.threadId === 'string') return meta.threadId;
-  return undefined;
-}
-
 function errToString(err: unknown): string {
   if (err instanceof Error) return err.message;
   return String(err);

package/src/index.ts

@@ -34,7 +34,6 @@ import { CodexSessionManager } from './session-manager.js';
 import {
   ensureCodexWorkspace,
   ensureParallProvider,
-  ensureWorkspaceTrusted,
   isParallProxyMode,
   writeCodexSystemPrompt,
 } from './workspace.js';
@@ -85,7 +84,6 @@ async function main() {
     const agentUserId = me.id;
     const agentLog = childLogger(activeLog, agentUserId);
     activeLog = agentLog;
-    ensureWorkspaceTrusted(config.codexHome, config.workspaceDir, agentLog);
     const useParallProvider = isParallProxyMode();
     if (useParallProvider) {
       ensureParallProvider(config.codexHome, config.apiUrl, agentLog);
@@ -124,11 +122,19 @@ async function main() {
       materializeChannelCapabilities(config.stateDir, caps, agentLog);
       return caps.map((c) => c.fragment);
     };
-    // Assemble the workspace AFTER the first config fetch so
-    // developer_instructions carries the capability declarations from boot.
+    // Assemble the workspace AFTER the first config fetch so the platform
+    // prompt carries the capability declarations from boot.
     const bootCapabilityFragments = applyChannelCapabilities();
     let lastCapabilityFragments = bootCapabilityFragments.join('\n\n');
-    ensureCodexWorkspace(config.workspaceDir, agentLog, agentIdentity, bootCapabilityFragments);
+    // Platform instructions are delivered per-thread via the app-server's
+    // developerInstructions param — no workspace config file, no dependence
+    // on codex's workspace-trust state, no writes to the operator's config.
+    const developerInstructions = ensureCodexWorkspace(
+      config.workspaceDir,
+      agentLog,
+      agentIdentity,
+      bootCapabilityFragments,
+    );
     // Model precedence: operator PIN (override) > env > server FLOOR. The server
     // now says which it is via model_is_pin (deriveModelIsPin presence-gates the
     // dual-read: old servers omit it → fall back to model_management). A PIN beats
@@ -162,6 +168,7 @@ async function main() {
       contextDirPath: dispatchContextDirPath(config.stateDir),
       useParallProvider,
       capabilityBinDir: capabilityBinDir(config.stateDir),
+      developerInstructions,
     });
 
     // Shared by onConfigUpdate + onSessionReady. /agents/me is only consumed as
@@ -191,15 +198,30 @@ async function main() {
         model: resolveRuntimeModel(isPin, updated.model, config.model) ?? null,
         reasoningEffort: updated.thinkingEffort ?? config.reasoningEffort ?? null,
       });
-      // Capability heat-update: re-materialize shims + rewrite the prompt
-      // surfaces. The write is refresh-tolerant (warn + retry next refresh);
-      // only a SUCCESSFUL write with a changed fragment set schedules the
-      // lazy app-server restart (developer_instructions loads at spawn).
+      // Capability heat-update: re-materialize shims + rebuild the prompt.
+      // The write is refresh-tolerant (warn + retry next refresh); only a
+      // SUCCESSFUL rebuild with a changed fragment set schedules the lazy
+      // app-server restart.
+      //
+      // 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.
       const fragments = applyChannelCapabilities();
       const joinedFragments = fragments.join('\n\n');
       let promptWritten = true;
       try {
-        writeCodexSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+        const refreshedPrompt = writeCodexSystemPrompt(
+          config.workspaceDir,
+          agentIdentity,
+          fragments,
+        );
+        adapter.updateConfig({ developerInstructions: refreshedPrompt });
       } catch (err) {
         promptWritten = false;
         agentLog.warn(`system prompt refresh write failed (retrying next refresh): ${String(err)}`);

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.',
+  );
+}