@parall/codex-agent 1.42.0 → 1.43.0

package/dist/workspace.js

@@ -2,6 +2,406 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parse as parseToml } from 'smol-toml';
 import { BRIDGE_WORKSPACE_INSTRUCTIONS, PRLL_BEHAVIOR, PRLL_REFERENCE_GUIDE, buildIdentity, buildSkillReferences, writeSkillFiles, } from '@parall/agent-core';
+/**
+ * Config-lock timings, exported for tests.
+ *
+ * `staleMs` — a queue ticket untouched this long is treated as a crashed
+ * owner (live contenders refresh their ticket's mtime every `retryMs`, so
+ * the margin is ~400×). `waitMs` deliberately exceeds `staleMs`: a waiter
+ * facing a crashed head-of-queue outlasts the staleness threshold and skips
+ * it instead of falling through to a lockless write — the lockless fallback
+ * is a last resort, not a normal path.
+ */
+export const CONFIG_LOCK_TIMINGS = {
+    staleMs: 10_000,
+    waitMs: 15_000,
+    retryMs: 25,
+};
+// Reused wait signal: sleepSync fires every retryMs under contention, and a
+// fresh SharedArrayBuffer per call is avoidable allocation churn.
+const SLEEP_SIGNAL = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    Atomics.wait(SLEEP_SIGNAL, 0, 0, ms);
+}
+/**
+ * Advisory cross-process lock serializing `<codexHome>/config.toml`
+ * read-modify-write. On a local daemon machine every runtime_auth codex
+ * bridge child shares the operator's CODEX_HOME, and the daemon starts them
+ * together — without a lock, a whole-file rewrite working from a stale read
+ * can erase a trust entry another agent appended in between.
+ *
+ * Queue design (why not wx-create + steal): any scheme that renames or
+ * unlinks the SHARED lock path can, between its staleness check and the
+ * destructive op, hit a fresh lock that replaced the stale one — deleting a
+ * live holder's lock and overlapping critical sections (reproduced under
+ * 12-process contention). Here contenders queue in `config.toml.lock.d/`
+ * using Lamport's bakery protocol, and the smallest live ticket holds the
+ * lock. Two phases per enqueue: (1) create a `choosing-<token>` marker,
+ * (2) take seq = max(existing ticket seqs) + 1 and publish by atomically
+ * RENAMING the marker into `t-<seq>-<token>`. Evaluators wait while any
+ * live choosing marker exists, so a contender that read the queue but
+ * hasn't published yet can never be missed — the classic bakery guarantee.
+ * (A naive self-chosen timestamp order would race: a process descheduled
+ * between choosing its stamp and writing its ticket could insert itself
+ * before an already-running holder.) The rename-publish closes the
+ * stale-mid-choosing hole: once a frozen chooser's marker has been GC'd,
+ * its publish fails and it must re-enqueue fresh — it can never surface an
+ * old low seq under a holder elected in its absence. ENTRY is the same
+ * pattern: the elected head atomically renames its ticket into a
+ * `held-<entry-ts>-…` entry, racing any staleness eviction of that ticket
+ * on the same path — a contender revived at the staleness boundary loses
+ * the rename and re-enqueues rather than entering behind an eviction. The
+ * holder's freshness is embedded in the held name (atomic with entry), so
+ * evicting a holder needs no stat. Evaluators mirror the atomicity: after
+ * any GC attempt, or on a marker that vanished mid-scan, they take a fresh
+ * snapshot instead of electing from the old one. Ticket order is
+ * (seq, token), identical for every observer.
+ *
+ * No process ever mutates a shared path: release unlinks only the caller's
+ * own ticket, and the only cross-process destructive op is GC of entries
+ * untouched for `staleMs` — safe because live contenders refresh their
+ * ticket's mtime every `retryMs`, and names embed a per-acquisition random
+ * token so they are never reused (no identity switch on unlink).
+ *
+ * Residual (documented, not fixable without OS-level flock, which Node core
+ * does not expose): a HOLDER frozen inside `fn` for longer than `staleMs`
+ * looks crashed, gets evicted, and the next head may overlap it — `fn` is a
+ * millisecond-scale sync config write, 400× within margin. Freezes anywhere
+ * else (mid-choosing, at entry) are safe: the atomic renames fail after an
+ * eviction and the process re-enqueues. On `waitMs` timeout
+ * the mutation proceeds without the lock (warn) — blocking would wedge
+ * bridge startup. The lock coordinates bridge processes only; codex itself
+ * does not observe it, which is why bridge writes to a shared config are
+ * additionally kept rare (the trust write is a no-op after the first boot
+ * per workspace, and runtime_auth agents never write the provider block)
+ * and whole-file writes are atomic (temp + rename) so codex never reads a
+ * truncated file.
+ *
+ * Exported for tests.
+ */
+export function withConfigLock(codexHome, log, fn) {
+    const queueDir = path.join(codexHome, 'config.toml.lock.d');
+    let ticketName = bakeryEnqueue(queueDir);
+    let ticketPath = ticketName ? path.join(queueDir, ticketName) : '';
+    let acquired = false;
+    let heldPath = '';
+    const deadline = Date.now() + CONFIG_LOCK_TIMINGS.waitMs;
+    while (ticketName && Date.now() < deadline) {
+        let names;
+        try {
+            names = fs.readdirSync(queueDir).sort();
+        }
+        catch {
+            break; // dir vanished under us — lockless fallback
+        }
+        if (!names.includes(ticketName)) {
+            // Our ticket was GC'd (we looked frozen) or wiped — re-run the full
+            // bakery enqueue rather than silently proceeding without a position.
+            ticketName = bakeryEnqueue(queueDir);
+            if (!ticketName)
+                break;
+            ticketPath = path.join(queueDir, ticketName);
+            continue;
+        }
+        const now = Date.now();
+        let rescan = false; // snapshot invalidated — re-readdir before electing
+        let blocked = false; // a live chooser/holder is ahead of us
+        let head;
+        for (const name of names) {
+            const entryPath = path.join(queueDir, name);
+            if (name.startsWith('held-')) {
+                // The holder's freshness is embedded in the name at entry time
+                // (atomic with the entry rename), so there is no stat window here.
+                const enteredAt = Number.parseInt(name.slice(5, 20), 10);
+                if (Number.isFinite(enteredAt) && now - enteredAt > CONFIG_LOCK_TIMINGS.staleMs) {
+                    // Holder frozen inside fn beyond staleMs — the documented
+                    // residual. Evict and rescan.
+                    try {
+                        fs.unlinkSync(entryPath);
+                    }
+                    catch {
+                        // released or GC'd concurrently
+                    }
+                    rescan = true;
+                    break;
+                }
+                blocked = true; // live holder — the lock is taken
+                break;
+            }
+            let mtimeMs;
+            try {
+                mtimeMs = fs.statSync(entryPath).mtimeMs;
+            }
+            catch {
+                // The entry vanished between readdir and stat — it did not merely
+                // leave, it may have TRANSITIONED via an atomic rename this snapshot
+                // cannot see: a choosing marker into a published ticket, or a head
+                // ticket into a live held entry (caught overlapping under the
+                // 12-process barrier test when this path skipped tickets). Never
+                // elect from a snapshot that missed a transition — rescan.
+                rescan = true;
+                break;
+            }
+            if (now - mtimeMs > CONFIG_LOCK_TIMINGS.staleMs) {
+                // Crashed contender (live ones refresh every retryMs; choosing is
+                // microsecond-scale). Unique never-reused names make this unlink
+                // safe — it cannot hit a different file than the one just observed.
+                try {
+                    fs.unlinkSync(entryPath);
+                }
+                catch {
+                    // Lost to a concurrent GC — or to the owner's atomic rename
+                    // (marker → ticket publish, or ticket → held entry).
+                }
+                // Whether the unlink won or lost, the snapshot no longer reflects
+                // the queue (a stale marker may have become a live ticket) — rescan
+                // instead of electing from stale names.
+                rescan = true;
+                break;
+            }
+            // Sorted names put `choosing-*` before `held-*` before `t-*`, so
+            // blockers are seen before any head candidate.
+            if (name.startsWith('choosing-')) {
+                blocked = true;
+                break;
+            }
+            if (name.startsWith('t-')) {
+                head = name;
+                break;
+            }
+            // Foreign file in the queue dir — ignore it.
+        }
+        if (rescan)
+            continue; // GC/publish made progress; take a fresh snapshot
+        if (!blocked && head === ticketName) {
+            // ENTRY is an atomic rename of our own ticket into a `held-<now>-…`
+            // entry. It races any GC eviction of the ticket on the same path, so
+            // exactly one side wins: if a GC saw us stale at the boundary and
+            // evicted first, our rename fails and we re-enqueue instead of
+            // entering — a revived contender can never slip into the critical
+            // section behind an eviction. The entry timestamp rides in the name,
+            // atomic with the transition itself.
+            CONFIG_LOCK_TEST_HOOKS.beforeTicketEntry?.();
+            const heldName = `held-${String(Date.now()).padStart(15, '0')}-${ticketName.slice(2)}`;
+            const candidateHeldPath = path.join(queueDir, heldName);
+            try {
+                fs.renameSync(ticketPath, candidateHeldPath);
+            }
+            catch {
+                continue; // evicted at the boundary — the missing-ticket branch re-enqueues
+            }
+            heldPath = candidateHeldPath;
+            acquired = true;
+            break;
+        }
+        try {
+            const t = new Date();
+            fs.utimesSync(ticketPath, t, t); // keep our ticket visibly live
+        }
+        catch {
+            // ticket missing — the next iteration re-enqueues
+        }
+        sleepSync(CONFIG_LOCK_TIMINGS.retryMs);
+    }
+    if (!acquired) {
+        log?.warn(`could not acquire ${queueDir}; writing config.toml without lock`);
+        // Leave the queue before writing lockless so our abandoned ticket does
+        // not block other contenders for another staleMs.
+        if (ticketName) {
+            try {
+                fs.unlinkSync(ticketPath);
+            }
+            catch {
+                // already GC'd
+            }
+        }
+    }
+    try {
+        fn();
+    }
+    finally {
+        if (acquired) {
+            try {
+                fs.unlinkSync(heldPath); // own unique name — no identity race
+            }
+            catch {
+                // evicted by a contender that saw us frozen inside fn — nothing to release
+            }
+            // The queue dir is deliberately NEVER removed: a contender may have
+            // finished mkdir but not yet created its choosing marker, and
+            // deleting the dir in that gap would send it down the lockless
+            // fallback. An empty config.toml.lock.d on disk is expected.
+        }
+    }
+}
+/**
+ * Test-only scheduling hooks for deterministic race tests. Production code
+ * never sets these; tests use them to pause a contender at the two points
+ * where another process can act in between (barrier files stand in for the
+ * OS scheduler).
+ */
+export const CONFIG_LOCK_TEST_HOOKS = {};
+/**
+ * Bakery enqueue: announce with a choosing marker, take
+ * seq = max(visible tickets) + 1, then PUBLISH BY RENAMING THE MARKER INTO
+ * THE TICKET. The rename is the linchpin against the stale-mid-choosing
+ * race: if this process froze after creating the marker and a contender
+ * GC'd it as stale (allowing others to elect and enter), the rename fails
+ * with ENOENT — the stale seq is discarded and we re-enqueue under a fresh
+ * token. Publishing and retiring the marker are one atomic step, so at no
+ * instant can an evaluator observe "no marker, and no ticket either" for an
+ * in-flight enqueue.
+ *
+ * Returns the ticket name, or null when the queue dir is unusable (caller
+ * falls back to a lockless warn-logged write).
+ */
+function bakeryEnqueue(queueDir) {
+    // A GC'd marker aborts the attempt; retry under a FRESH token so names
+    // are never reused. Being GC'd requires a >staleMs freeze mid-choosing,
+    // so two spare attempts are already generous.
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const token = `${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+        const markerPath = path.join(queueDir, `choosing-${token}`);
+        try {
+            fs.mkdirSync(queueDir, { recursive: true });
+            CONFIG_LOCK_TEST_HOOKS.beforeChoosingMarker?.();
+            fs.writeFileSync(markerPath, '', { flag: 'wx' });
+        }
+        catch {
+            return null;
+        }
+        try {
+            let maxSeq = 0;
+            for (const name of fs.readdirSync(queueDir)) {
+                if (!name.startsWith('t-'))
+                    continue;
+                const seq = Number.parseInt(name.slice(2, 12), 10);
+                if (Number.isFinite(seq) && seq > maxSeq)
+                    maxSeq = seq;
+            }
+            const ticketName = `t-${String(maxSeq + 1).padStart(10, '0')}-${token}`;
+            const ticketPath = path.join(queueDir, ticketName);
+            CONFIG_LOCK_TEST_HOOKS.beforeTicketPublish?.();
+            fs.renameSync(markerPath, ticketPath);
+            try {
+                // The ticket inherits the marker's mtime; refresh it so a slow
+                // choose does not hand evaluators a stale-at-birth ticket. Runs
+                // before our first head evaluation, so if a GC wins the race on the
+                // stale-born ticket we simply re-enqueue — never elect on it.
+                const t = new Date();
+                fs.utimesSync(ticketPath, t, t);
+            }
+            catch {
+                // GC'd already — the eval loop re-enqueues on the missing ticket.
+            }
+            return ticketName;
+        }
+        catch (err) {
+            // Retire our marker if it still exists (e.g. readdir failed).
+            try {
+                fs.unlinkSync(markerPath);
+            }
+            catch {
+                // already renamed or GC'd
+            }
+            if (err.code === 'ENOENT')
+                continue; // marker GC'd — fresh token
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Whole-file config writes go through temp + rename so a concurrent reader
+ * (including codex itself, which does not observe the advisory lock) never
+ * sees a truncated file. The trust-append path intentionally keeps
+ * appendFileSync — O_APPEND is atomic for these small writes and cannot
+ * clobber a concurrent append.
+ *
+ * The rename targets the file's REAL path: `config.toml` managed by a
+ * dotfiles setup is often a symlink, and renaming onto the link path would
+ * replace the link with a regular file while the real target keeps the old
+ * content. The temp file is born 0600 (never a world-readable window, even
+ * pre-chmod) and created with `wx` so a colliding path is never truncated;
+ * an existing file's mode is then restored explicitly (chmod, not
+ * open-mode, so umask cannot mask bits off), while a brand-new config stays
+ * at the restrictive 0600.
+ */
+function writeConfigAtomic(filePath, content) {
+    const realPath = resolveWriteTarget(filePath);
+    let mode;
+    try {
+        mode = fs.statSync(realPath).mode & 0o777;
+    }
+    catch {
+        // New file — keep the restrictive 0600 creation mode.
+    }
+    const tmpPath = `${realPath}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+    let tmpCreated = false;
+    try {
+        fs.writeFileSync(tmpPath, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        tmpCreated = true;
+        if (mode !== undefined)
+            fs.chmodSync(tmpPath, mode);
+        fs.renameSync(tmpPath, realPath);
+    }
+    catch (err) {
+        // Clean up only what THIS call put on disk: on a wx EEXIST the path
+        // belongs to someone else and must not be unlinked. (A create that
+        // failed mid-write still left our file — code ≠ EEXIST — so it is
+        // removed.)
+        if (tmpCreated || err.code !== 'EEXIST') {
+            try {
+                fs.unlinkSync(tmpPath);
+            }
+            catch {
+                // tmp never made it to disk
+            }
+        }
+        throw err;
+    }
+}
+/**
+ * Follow symlinks (including dangling ones) to the path a write should land
+ * on. Never returns an unresolved symlink: a cycle or an over-deep chain
+ * throws instead, so the atomic rename can never silently replace a link.
+ */
+function resolveWriteTarget(filePath) {
+    try {
+        return fs.realpathSync(filePath);
+    }
+    catch (err) {
+        // ELOOP (cycle among existing links) and every other real error must
+        // surface; only a missing target falls through to the manual walk.
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    // Some component is missing — the path may still be a dangling symlink
+    // chain; walk it manually so the file is created where the links point.
+    const seen = new Set();
+    let p = path.resolve(filePath);
+    for (let depth = 0; depth < 40; depth++) {
+        if (seen.has(p)) {
+            throw new Error(`symlink cycle at ${p} while resolving ${filePath}`);
+        }
+        seen.add(p);
+        let link;
+        try {
+            link = fs.readlinkSync(p);
+        }
+        catch (err) {
+            const code = err.code;
+            // ENOENT (nothing here yet) and EINVAL (a real non-link file) are the
+            // two legitimate ends of a chain — create/replace at this path. Any
+            // other error is a real failure and must surface.
+            if (code === 'ENOENT' || code === 'EINVAL')
+                return p;
+            throw err;
+        }
+        p = path.resolve(path.dirname(p), link);
+    }
+    throw new Error(`symlink chain deeper than 40 while resolving ${filePath}`);
+}
 /**
  * Ensure the workspace directory is marked as trusted in the global Codex
  * config so that project-level `developer_instructions` are loaded at
@@ -13,6 +413,9 @@ import { BRIDGE_WORKSPACE_INSTRUCTIONS, PRLL_BEHAVIOR, PRLL_REFERENCE_GUIDE, bui
  * the bridge from starting.
  */
 export function ensureWorkspaceTrusted(codexHome, workspaceDir, log) {
+    withConfigLock(codexHome, log, () => ensureWorkspaceTrustedLocked(codexHome, workspaceDir, log));
+}
+function ensureWorkspaceTrustedLocked(codexHome, workspaceDir, log) {
     const configPath = path.join(codexHome, 'config.toml');
     const normalizedPath = path.resolve(workspaceDir);
     try {
@@ -37,8 +440,17 @@ export function ensureWorkspaceTrusted(codexHome, workspaceDir, log) {
             }
         }
         const projects = parsed?.projects;
-        if (projects?.[normalizedPath]?.trust_level === 'trusted')
+        const existingTrust = projects?.[normalizedPath]?.trust_level;
+        if (existingTrust === 'trusted')
+            return;
+        if (existingTrust !== undefined) {
+            // An explicit non-trusted value is a human decision — on a local
+            // runtime_auth daemon this file IS the operator's own ~/.codex config,
+            // and a workspace they deliberately marked untrusted must never be
+            // silently flipped by an agent. Leave it and surface the consequence.
+            log?.warn(`Codex config marks ${normalizedPath} as trust_level=${JSON.stringify(existingTrust)}; respecting the explicit decision — project-level developer_instructions will not load for this workspace`);
             return;
+        }
         // TOML basic-string keys require backslash and double-quote escaping.
         const escapedPath = normalizedPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
         const sectionHeader = `[projects."${escapedPath}"]`;
@@ -68,7 +480,7 @@ export function ensureWorkspaceTrusted(codexHome, workspaceDir, log) {
                         content.substring(0, afterHeader) + trustLine + '\n' + content.substring(afterHeader);
                 }
             }
-            fs.writeFileSync(configPath, content, 'utf8');
+            writeConfigAtomic(configPath, content);
         }
         else if (projects?.[normalizedPath] !== undefined) {
             // smol-toml found the section but indexOf missed it — the header
@@ -119,6 +531,9 @@ export function isParallProxyMode(env = process.env) {
  * Provider-managed: overwritten on every boot (env vars are the SSOT).
  */
 export function ensureParallProvider(codexHome, apiUrl, log) {
+    withConfigLock(codexHome, log, () => ensureParallProviderLocked(codexHome, apiUrl));
+}
+function ensureParallProviderLocked(codexHome, apiUrl) {
     const configPath = path.join(codexHome, 'config.toml');
     const baseUrl = apiUrl.replace(/\/$/, '') + '/api/llm/v1';
     try {
@@ -158,7 +573,7 @@ export function ensureParallProvider(codexHome, apiUrl, log) {
             content = content.trimEnd() + '\n\n' + providerBlock + '\n';
         }
         fs.mkdirSync(codexHome, { recursive: true });
-        fs.writeFileSync(configPath, content, 'utf8');
+        writeConfigAtomic(configPath, content);
     }
     catch (err) {
         throw new Error(`failed to write Parall provider config: ${String(err)}`);
@@ -170,21 +585,42 @@ function findSectionEnd(content, fromIndex) {
     const nextHeader = content.indexOf('\n[', fromIndex);
     return nextHeader === -1 ? content.length : nextHeader;
 }
-export function ensureCodexWorkspace(workspaceDir, log, agentIdentity) {
-    const systemPrompt = [
+// writeCodexSystemPrompt (re)writes the standing platform prompt surfaces:
+// .parall/system-prompt.md (human-inspectable copy) and the workspace
+// .codex/config.toml developer_instructions (what the CLI actually loads).
+// capabilityFragments are platform-derived capability declarations
+// (agents.capabilities[].fragment) — placed after the platform reference
+// guide, before skill references; empty/absent = no capability section.
+// Split out from ensureCodexWorkspace so the bridge can rewrite on
+// platform-config heat-update; the app-server reads workspace config at
+// process start, so the caller pairs a CHANGED fragment set with
+// adapter.requestProcessRestart(). 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.
+export function writeCodexSystemPrompt(workspaceDir, agentIdentity, capabilityFragments) {
+    const parts = [
         buildIdentity(agentIdentity),
         BRIDGE_WORKSPACE_INSTRUCTIONS,
         PRLL_BEHAVIOR,
         PRLL_REFERENCE_GUIDE,
-        buildSkillReferences(workspaceDir),
-    ].join('\n\n');
-    fs.mkdirSync(workspaceDir, { recursive: true });
+    ];
+    if (capabilityFragments && capabilityFragments.length > 0) {
+        parts.push(capabilityFragments.join('\n\n'));
+    }
+    parts.push(buildSkillReferences(workspaceDir));
+    const systemPrompt = parts.join('\n\n');
     const parallDir = path.join(workspaceDir, '.parall');
     fs.mkdirSync(parallDir, { recursive: true });
     fs.writeFileSync(path.join(parallDir, 'system-prompt.md'), systemPrompt, 'utf8');
-    writeSkillFiles(path.join(parallDir, 'skills'));
     const codexConfigDir = path.join(workspaceDir, '.codex');
     fs.mkdirSync(codexConfigDir, { recursive: true });
     const toml = `developer_instructions = """\n${systemPrompt.replace(/\\/g, '\\\\').replace(/"""/g, '\\"""')}\n"""\n`;
     fs.writeFileSync(path.join(codexConfigDir, 'config.toml'), toml, 'utf8');
 }
+export function ensureCodexWorkspace(workspaceDir, log, agentIdentity, capabilityFragments) {
+    fs.mkdirSync(workspaceDir, { recursive: true });
+    // Boot: let a write failure PROPAGATE (fatal) — startup must not proceed
+    // without the platform prompt. The refresh path tolerates failure.
+    writeCodexSystemPrompt(workspaceDir, agentIdentity, capabilityFragments);
+    writeSkillFiles(path.join(workspaceDir, '.parall', 'skills'));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/codex-agent",
-  "version": "1.42.0",
+  "version": "1.43.0",
   "description": "Codex CLI bridge runtime for self-hosted Parall agents",
   "license": "MIT",
   "repository": {
@@ -26,9 +26,9 @@
   ],
   "dependencies": {
     "smol-toml": "^1.6.1",
-    "@parall/agent-core": "1.42.0",
-    "@parall/cli": "1.42.0",
-    "@parall/sdk": "1.42.0"
+    "@parall/agent-core": "1.43.0",
+    "@parall/cli": "1.43.0",
+    "@parall/sdk": "1.43.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/dispatch.ts

@@ -1,6 +1,7 @@
 import { execSync, 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,
@@ -37,6 +38,14 @@ type CodexAppServerAdapterOptions = Pick<
   contextFilePath?: string;
   contextDirPath?: string;
   useParallProvider?: boolean;
+  /**
+   * Channel-capability shim directory (agent-core's capabilityBinDir),
+   * prepended to the subprocess PATH unconditionally. The DIRECTORY is
+   * constant for the bridge's lifetime; its CONTENT tracks capability
+   * grants, so a grant or revocation reaches even a long-lived app-server
+   * on its next shell command — no respawn needed.
+   */
+  capabilityBinDir?: string;
 };
 
 type TurnEventEnvelope =
@@ -174,6 +183,7 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       );
     }
 
+    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
@@ -453,6 +463,28 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     return null;
   }
 
+  /**
+   * Lazily restart the app-server before the NEXT turn: the workspace
+   * config.toml (developer_instructions, carrying capability fragments) is
+   * loaded at process start, so a changed fragment set needs a respawn to
+   * reach the prompt. Deferred to the next dispatch with no active turns —
+   * never kills an in-flight turn; thread state survives via thread/resume.
+   */
+  requestProcessRestart(): void {
+    this.restartRequested = true;
+  }
+
+  private restartRequested = false;
+
+  private async applyPendingRestart(log?: GatewayLogger): Promise<void> {
+    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',
+    );
+    await this.stop();
+  }
+
   async stop() {
     this.stopping = true;
     const proc = this.proc;
@@ -462,6 +494,12 @@ export class CodexAppServerAdapter implements DispatchAdapter {
     this.initialized = false;
     this.activeTurnIds.clear();
     this.pendingInjections.clear();
+    // Resume markers are process-local facts. Clear them HERE, synchronously:
+    // the old child's close callback sees the replaced refs and skips its
+    // cleanup as stale, so a marker surviving stop() would make the next
+    // dispatch treat the persisted thread as already resumed in the NEW
+    // process and lose conversation continuity when turn/start rejects.
+    this.resumedThreadIds.clear();
     if (client) client.dispose(new Error('adapter stopped'));
     if (proc && proc.exitCode === null && proc.signalCode === null) {
       if (!IS_WIN32 || !proc.pid || !killWin32Tree(proc.pid)) {
@@ -515,6 +553,22 @@ export class CodexAppServerAdapter implements DispatchAdapter {
       FORCE_COLOR: '0',
       NO_COLOR: '1',
     };
+    // Channel-capability shims resolve ahead of any globally-installed CLI of
+    // the same name (the shim owns auth; the real binary is found further
+    // down the PATH by the shim itself). On Windows env keys are
+    // case-insensitive and the host key is usually `Path`; after the
+    // plain-object spread a literal `PATH` write would SPLIT the key
+    // (undefined which wins in the child), so reuse the parent's casing. On
+    // POSIX keys are case-SENSITIVE — match `PATH` exactly.
+    if (this.opts.capabilityBinDir) {
+      const pathKey = IS_WIN32
+        ? (Object.keys(env).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH')
+        : 'PATH';
+      const existing = env[pathKey];
+      env[pathKey] = existing
+        ? `${this.opts.capabilityBinDir}${path.delimiter}${existing}`
+        : this.opts.capabilityBinDir;
+    }
     if (this.opts.contextFilePath) {
       env.PRLL_CONTEXT_FILE = this.opts.contextFilePath;
     }