@parall/codex-agent 1.42.0 → 1.43.0

package/src/index.ts

@@ -3,11 +3,13 @@
 import * as os from 'node:os';
 import {
   ParallAgentGateway,
+  capabilityBinDir,
   createPlatformConfigManager,
   createLogger,
   createOtelLogger,
   childLogger,
   deriveModelIsPin,
+  materializeChannelCapabilities,
   resolveRuntimeModel,
   parseShutdownDeadlineMs,
   parseForkDeadlineMs,
@@ -34,6 +36,7 @@ import {
   ensureParallProvider,
   ensureWorkspaceTrusted,
   isParallProxyMode,
+  writeCodexSystemPrompt,
 } from './workspace.js';
 
 const log = createLogger('codex-agent');
@@ -88,11 +91,11 @@ async function main() {
       ensureParallProvider(config.codexHome, config.apiUrl, agentLog);
       agentLog.info('parall custom provider configured (Responses API HTTP/SSE mode)');
     }
-    ensureCodexWorkspace(config.workspaceDir, agentLog, {
+    const agentIdentity = {
       userId: agentUserId,
       displayName: me.display_name,
       description: me.agent_profile?.description ?? undefined,
-    });
+    };
     const runtimeKey = config.runtimeKey || buildCodexRuntimeKey(agentUserId);
     const mainContextFilePath = contextFilePathForSession(config.stateDir, runtimeKey);
     const sessionStateFilePath = sessionStateFilePathForRuntime(config.stateDir, runtimeKey);
@@ -111,6 +114,21 @@ async function main() {
       log: agentLog,
     });
     const platformDefaults = await configMgr.fetch();
+    // Channel capabilities: ONE call materializes the local artifacts (the
+    // lark-cli auth shim under capabilityBinDir) and yields the system-prompt
+    // fragments, so declaration and shim can never diverge within a refresh.
+    // No freshness gate — a stale (LKG-cached) declaration fail-closes at the
+    // mint endpoint, which re-evaluates the grant on every token request.
+    const applyChannelCapabilities = () => {
+      const caps = configMgr.capabilities();
+      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.
+    const bootCapabilityFragments = applyChannelCapabilities();
+    let lastCapabilityFragments = bootCapabilityFragments.join('\n\n');
+    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
@@ -143,6 +161,7 @@ async function main() {
       contextFilePath: mainContextFilePath,
       contextDirPath: dispatchContextDirPath(config.stateDir),
       useParallProvider,
+      capabilityBinDir: capabilityBinDir(config.stateDir),
     });
 
     // Shared by onConfigUpdate + onSessionReady. /agents/me is only consumed as
@@ -172,6 +191,23 @@ 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).
+      const fragments = applyChannelCapabilities();
+      const joinedFragments = fragments.join('\n\n');
+      let promptWritten = true;
+      try {
+        writeCodexSystemPrompt(config.workspaceDir, agentIdentity, fragments);
+      } catch (err) {
+        promptWritten = false;
+        agentLog.warn(`system prompt refresh write failed (retrying next refresh): ${String(err)}`);
+      }
+      if (promptWritten && joinedFragments !== lastCapabilityFragments) {
+        lastCapabilityFragments = joinedFragments;
+        adapter.requestProcessRestart();
+      }
     };
 
     const gateway = new ParallAgentGateway({
@@ -196,6 +232,9 @@ async function main() {
       },
       dispatchAdapter: adapter,
       log: agentLog,
+      // Live capability view for hint routing: the channel reply hint points
+      // at the vendor CLI only while the grant is active.
+      getCapabilityKeys: () => configMgr.capabilities().map((c) => c.key),
       shutdownDeadlineMs: parseShutdownDeadlineMs(process.env.PRLL_SHUTDOWN_DEADLINE_MS),
       forkDeadlineMs: parseForkDeadlineMs(process.env.PRLL_FORK_DEADLINE_MS),
       dispatchDeadlineMs: parseDispatchDeadlineMs(process.env.PRLL_DISPATCH_DEADLINE_MS),

package/src/workspace.ts

@@ -11,6 +11,399 @@ import {
 } from '@parall/agent-core';
 import type { AgentIdentity } 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: number): void {
+  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: string,
+  log: { warn: (msg: string) => void } | undefined,
+  fn: () => void,
+): void {
+  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: string[];
+    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: string | undefined;
+    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: number;
+      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: {
+  beforeChoosingMarker?: () => void;
+  beforeTicketPublish?: () => void;
+  beforeTicketEntry?: () => void;
+} = {};
+
+/**
+ * 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: string): string | null {
+  // 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 as NodeJS.ErrnoException).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: string, content: string): void {
+  const realPath = resolveWriteTarget(filePath);
+  let mode: number | undefined;
+  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 as NodeJS.ErrnoException).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: string): string {
+  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 as NodeJS.ErrnoException).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<string>();
+  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: string;
+    try {
+      link = fs.readlinkSync(p);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).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
@@ -25,6 +418,14 @@ export function ensureWorkspaceTrusted(
   codexHome: string,
   workspaceDir: string,
   log?: { warn: (msg: string) => void },
+): void {
+  withConfigLock(codexHome, log, () => ensureWorkspaceTrustedLocked(codexHome, workspaceDir, log));
+}
+
+function ensureWorkspaceTrustedLocked(
+  codexHome: string,
+  workspaceDir: string,
+  log?: { warn: (msg: string) => void },
 ): void {
   const configPath = path.join(codexHome, 'config.toml');
   const normalizedPath = path.resolve(workspaceDir);
@@ -52,7 +453,20 @@ export function ensureWorkspaceTrusted(
     }
 
     const projects = parsed?.projects as Record<string, Record<string, unknown>> | undefined;
-    if (projects?.[normalizedPath]?.trust_level === 'trusted') return;
+    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, '\\"');
@@ -82,7 +496,7 @@ export function ensureWorkspaceTrusted(
             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
       // uses non-canonical TOML formatting. Appending would create a
@@ -138,6 +552,10 @@ export function ensureParallProvider(
   apiUrl: string,
   log?: { warn: (msg: string) => void },
 ): void {
+  withConfigLock(codexHome, log, () => ensureParallProviderLocked(codexHome, apiUrl));
+}
+
+function ensureParallProviderLocked(codexHome: string, apiUrl: string): void {
   const configPath = path.join(codexHome, 'config.toml');
   const baseUrl = apiUrl.replace(/\/$/, '') + '/api/llm/v1';
 
@@ -178,7 +596,7 @@ export function ensureParallProvider(
     }
 
     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)}`);
   }
@@ -191,29 +609,56 @@ function findSectionEnd(content: string, fromIndex: number): number {
   return nextHeader === -1 ? content.length : nextHeader;
 }
 
-export function ensureCodexWorkspace(
+// 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: string,
-  log?: { warn: (msg: string) => void },
   agentIdentity?: AgentIdentity,
+  capabilityFragments?: string[],
 ): void {
-  const systemPrompt = [
+  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: string,
+  log?: { warn: (msg: string) => void },
+  agentIdentity?: AgentIdentity,
+  capabilityFragments?: string[],
+): void {
+  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'));
+}