@lyupro/codex-bridge 0.5.5 → 0.6.1

package/src/home/hooks/shell-write-intent.mjs

@@ -32,40 +32,40 @@ function addPath(paths, value) {
     && !paths.includes(candidate)) paths.push(candidate);
 }
 
-function tokens(segment) {
-  return segment.match(/"(?:\\.|[^"])*"|'[^']*'|[^\s]+/g) ?? [];
-}
-
-// A `>` inside a quoted argument is text, not a redirect. The 2026-08-28 worktree-lock refusal
-// named `#'` from `sed -E 's#(A ).*#\1<redacted>#'` because this scan previously read raw text.
-function quotedCharacters(command) {
-  const quoted = new Uint8Array(command.length);
-  let quote = null;
-  for (let index = 0; index < command.length; index += 1) {
-    const character = command[index];
-    if (quote === "'") {
-      if (character === "'") quote = null;
-      else quoted[index] = 1;
-    } else if (quote === '"') {
-      if (character === '\\' && index + 1 < command.length) {
-        quoted[index] = 1;
-        quoted[index + 1] = 1;
-        index += 1;
-      } else if (character === '"') quote = null;
-      else quoted[index] = 1;
-    } else if (character === '\\' && index + 1 < command.length) {
-      index += 1;
-    } else if (character === "'" || character === '"') {
-      quote = character;
-      quoted[index] = 1;
-    }
-  }
-  return quote ? null : quoted;
-}
-
-function positional(args) {
-  return args.filter((arg) => !arg.startsWith('-'));
-}
+function tokens(segment) {
+  return segment.match(/"(?:\\.|[^"])*"|'[^']*'|[^\s]+/g) ?? [];
+}
+
+// A `>` inside a quoted argument is text, not a redirect. The 2026-08-28 worktree-lock refusal
+// named `#'` from `sed -E 's#(A ).*#\1<redacted>#'` because this scan previously read raw text.
+function quotedCharacters(command) {
+  const quoted = new Uint8Array(command.length);
+  let quote = null;
+  for (let index = 0; index < command.length; index += 1) {
+    const character = command[index];
+    if (quote === "'") {
+      if (character === "'") quote = null;
+      else quoted[index] = 1;
+    } else if (quote === '"') {
+      if (character === '\\' && index + 1 < command.length) {
+        quoted[index] = 1;
+        quoted[index + 1] = 1;
+        index += 1;
+      } else if (character === '"') quote = null;
+      else quoted[index] = 1;
+    } else if (character === '\\' && index + 1 < command.length) {
+      index += 1;
+    } else if (character === "'" || character === '"') {
+      quote = character;
+      quoted[index] = 1;
+    }
+  }
+  return quote ? null : quoted;
+}
+
+function positional(args) {
+  return args.filter((arg) => !arg.startsWith('-'));
+}
 
 /**
  * Strip the directory and the Windows executable suffix before matching the command name.
@@ -103,23 +103,28 @@ function heredoc(command) {
       || /[\\/]/.test(value)
       || /(?:^|[\\/])[^\\/]+\.[A-Za-z0-9_-]+$/.test(value)) addPath(paths, value);
   }
-  return { header: header[1], paths, writes: true };
+  return { shell, paths, writes: true };
 }
 
 /** Returns `{ writes, paths }` for the deliberately obvious write forms this guard recognises. */
 export function shellWriteIntent(command) {
   if (typeof command !== 'string' || !command.trim()) return { writes: false, paths: [] };
   const paths = [];
-  const document = heredoc(command);
-  const shell = document?.header ?? command;
-  let writes = document?.writes ?? false;
-  const quoted = quotedCharacters(shell);
-
-  for (const match of shell.matchAll(/(?<![<>=])(?:\d*)>>?(?![=>&])\s*("(?:\\.|[^"])*"|'[^']*'|[^\s;|&]+)/g)) {
-    if (quoted && quoted[match.index]) continue;
-    writes = true;
-    addPath(paths, match[1]);
-  }
+  const document = heredoc(command);
+  // The document body is prose until an interpreter makes it code. Reading `header` here while
+  // heredoc() returned `shell` meant the whole command, body included, went through shell parsing
+  // whenever the writer was plain `cat`: on 2026-09-06 the lock refused four harmless commands,
+  // the last of them because a sentence in a task file said "Do not touch the installer" and
+  // `touch` is in COMMANDS, so every following word became a write target under the repository.
+  const shell = document?.shell ?? command;
+  let writes = document?.writes ?? false;
+  const quoted = quotedCharacters(shell);
+
+  for (const match of shell.matchAll(/(?<![<>=])(?:\d*)>>?(?![=>&])\s*("(?:\\.|[^"])*"|'[^']*'|[^\s;|&]+)/g)) {
+    if (quoted && quoted[match.index]) continue;
+    writes = true;
+    addPath(paths, match[1]);
+  }
 
   // A real output redirect identifies the writer's destination. Body text is only evidence when
   // the interpreter itself is the writer, as in the 2026-08-16 python heredoc incident.

package/src/home/lib/agents.mjs

@@ -0,0 +1,15 @@
+/**
+ * Defines each delegated agent's role, wall-clock budget, write access and result file.
+ *
+ * The three agents were listed four times: twice in run-config.mjs for budgets and models,
+ * once in codex-args.mjs for role lookup, and once in order-gate.mjs for guarded names.
+ * Adding an agent could silently leave one copy behind. Shared data lives here so config
+ * and hooks can read one registry without importing reply formatting or creating a cycle.
+ */
+export const AGENTS = {
+  'codex-scout': { role: 'scout', budget: 15, writes: false, result: 'result.json' },
+  'codex-build': { role: 'build', budget: 25, writes: true, result: 'result.json' },
+  'codex-review': { role: 'review', budget: 20, writes: false, result: 'review.json' },
+};
+
+export const agentRole = (agent) => AGENTS[agent]?.role;

package/src/home/lib/config-edit.mjs

@@ -0,0 +1,159 @@
+/**
+ * Plan_56 D27: persist only the operator's edit, never the reader's merged defaults.
+ * Keep unrelated JSON text intact: normalization on read is not permission to rewrite it.
+ * Plan_56 D40/D41: caller-side reads lost edits during catalogue waits. Transform fresh bytes
+ * here and retry if they change. Plan_56 D44: three separate model-set processes all reported
+ * success while one edit vanished; hold the shared lock across transforms, retries, and publish.
+ * Transformers may run three times, so network work belongs before this boundary.
+ */
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { BRAND_CONFIG_PATH } from './brand-home.mjs';
+import { parseJsonText } from './json-file.mjs';
+import { validateRunConfig } from './config-validate.mjs';
+import { withFileLock } from './file-lock.mjs';
+
+function replaceValue(file, raw, key, value) {
+  // The shared reader has already checked JSON syntax; tokens locate top-level value spans.
+  const tokens = [...raw.matchAll(/"(?:\\[\s\S]|[^"\\])*"|[{}[\],:]|[^\s{}[\],:]+/g)];
+  const replacements = [];
+  let lastEnd = tokens[0].index + 1;
+  for (let index = 1; index < tokens.length - 1;) {
+    const name = parseJsonText(file, tokens[index][0]);
+    const start = index + 2;
+    let end = start;
+    if (tokens[start][0] === '{' || tokens[start][0] === '[') {
+      let depth = 1;
+      while (depth > 0) {
+        end += 1;
+        if (tokens[end][0] === '{' || tokens[end][0] === '[') depth += 1;
+        if (tokens[end][0] === '}' || tokens[end][0] === ']') depth -= 1;
+      }
+    }
+    lastEnd = tokens[end].index + tokens[end][0].length;
+    if (name === key) replacements.push([tokens[start].index, lastEnd]);
+    index = end + 2;
+  }
+  if (replacements.length) {
+    for (const [start, end] of replacements.reverse()) {
+      raw = raw.slice(0, start) + indented(raw, start, value) + raw.slice(end);
+    }
+    return raw;
+  }
+  const newline = raw.includes('\r\n') ? '\r\n' : '\n';
+  const trailing = raw.slice(lastEnd, tokens.at(-1).index);
+  const addition = `${tokens.length > 2 ? ',' : ''}${newline}  ${JSON.stringify(key)}: `
+    + value.replaceAll('\n', `${newline}  `)
+    + (trailing.includes('\n') ? '' : newline);
+  return raw.slice(0, lastEnd) + addition + raw.slice(lastEnd);
+}
+
+/**
+ * A serialized object knows its own shape but not how deep it is being pasted, so every line
+ * after the first came out flush against the margin: writing a role profile left `"models"`
+ * indented by two and its `"build"` by none. The file stayed valid JSON and became unreadable
+ * for the operator who edits it by hand, which is the audience this whole path exists for.
+ */
+function indented(raw, start, value) {
+  const lineStart = raw.lastIndexOf('\n', start) + 1;
+  const indent = /^[ \t]*/.exec(raw.slice(lineStart, start))[0];
+  const newline = raw.includes('\r\n') ? '\r\n' : '\n';
+  return indent ? value.replaceAll('\n', `${newline}${indent}`) : value;
+}
+
+async function readBytes(file) {
+  try {
+    return await fs.readFile(file);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return null;
+  }
+}
+
+function readBytesSync(file) {
+  try {
+    return fsSync.readFileSync(file);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return null;
+  }
+}
+
+export async function editRunConfig(key, transform, file = BRAND_CONFIG_PATH) {
+  const reset = key !== null && typeof key === 'object' && !Array.isArray(key)
+    && key.reset === true && Object.keys(key).length === 1 && transform === undefined;
+  if (!reset && (typeof key !== 'string' || !key || typeof transform !== 'function')) {
+    throw new Error('Config edit requires a non-empty string key and a transformer function or { reset: true }');
+  }
+  const directory = path.dirname(file);
+  const created = await fs.mkdir(directory, { recursive: true });
+  try {
+    return await withFileLock(`${file}.lock`, async () => {
+      let collision;
+      for (let attempt = 0; attempt < 3; attempt += 1) {
+        const original = await readBytes(file);
+        const raw = original === null ? '{}\n' : original.toString('utf8');
+        const parsed = parseJsonText(file, raw);
+        let text;
+        if (reset) {
+          text = '{}\n';
+        } else {
+          if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            validateRunConfig(file, parsed);
+          }
+          const value = await transform(Object.hasOwn(parsed, key) ? parsed[key] : undefined);
+          validateRunConfig(file, { ...parsed, [key]: value });
+          text = replaceValue(file, raw, key, JSON.stringify(value, null, 2));
+        }
+        // Validate the exact bytes to be persisted, before even creating a temporary file (D27).
+        const config = validateRunConfig(file, parseJsonText(file, text));
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomUUID()}.tmp`);
+        const handle = await fs.open(temporary, 'wx');
+        try {
+          await handle.writeFile(text, 'utf8');
+          await handle.close();
+          // Comparing and publishing must be one step. Awaiting between them hands the event loop to
+          // a sibling edit, and a live probe of three concurrent `model set` calls lost one of them
+          // silently: every comparison passed before the first rename ran. Synchronous calls leave no
+          // suspension point between the two, so a competing edit is seen by whoever compares second.
+          const current = readBytesSync(file);
+          if (original === null ? current !== null : current === null || !original.equals(current)) {
+            await fs.rm(temporary, { force: true });
+            continue;
+          }
+          fsSync.renameSync(temporary, file);
+          return config;
+        } catch (error) {
+          await handle.close().catch(() => {});
+          await fs.rm(temporary, { force: true });
+          // Windows refuses the rename outright when another process is publishing onto the same name
+          // at that instant: two concurrent `model set` calls returned EPERM here on a live probe, and
+          // one operator edit was lost with the file system's wording instead of an answer. A collision
+          // is retried like a byte change; a lasting one is reported in its own words, not as drift.
+          if ((error.code === 'EPERM' || error.code === 'EBUSY') && attempt < 2) {
+            collision = error;
+            continue;
+          }
+          throw error;
+        }
+      }
+      if (collision) throw collision;
+      throw new Error(`${file}: config kept changing under the edit; nothing was written. Run the command again.`);
+    });
+  } catch (error) {
+    // D44 needs the parent before validation to lock even a new config. Undo only empty parents
+    // this call created, preserving D27's refusal contract and anything a competing writer added.
+    if (created) {
+      // Windows mkdir returns a namespaced path; compare that form on both sides of the boundary.
+      const boundary = path.toNamespacedPath(path.resolve(created));
+      for (let current = path.toNamespacedPath(path.resolve(directory));
+        current === boundary || current.startsWith(`${boundary}${path.sep}`); current = path.dirname(current)) {
+        try { await fs.rmdir(current); } catch { break; }
+      }
+    }
+    throw error;
+  }
+}

package/src/home/lib/config-validate.mjs

@@ -0,0 +1,227 @@
+/** Shared by reading and editing so Plan_56 D27 cannot persist an unreadable config. */
+import { AGENTS } from './agents.mjs';
+
+const BUDGET_KEY = 'budgets';
+export const ROLES = Object.values(AGENTS).map(({ role }) => role);
+const RETENTION_KEY = 'retention';
+const RETENTION_FIELDS = ['enabled', 'days'];
+const DEFAULT_RETENTION = { enabled: true, days: 30 };
+
+/**
+ * Files the surrounding tooling writes on its own, in any repository a run touches.
+ *
+ * A run is graded by comparing the worktree either side of it, which silently assumes the
+ * run is the only writer. It is not: OMC rewrites .omc/ and Claude Code rewrites its own
+ * caches while Codex works, and on 2026-08-02 an honest run was failed for
+ * “out-of-scope changes: .omc/project-memory.json” — a file Codex never opened. These paths are
+ * therefore attributed to the environment rather than to the run. They are not hidden: the
+ * reply and meta.json list them separately, so a run that really did edit them is still visible.
+ */
+export const DEFAULT_ENVIRONMENT_PATHS = [
+  '.omc/**',
+  '.claude/settings.local.json',
+  // Claude Code's own state, which only exists when the repository under a run is ~/.claude.
+  'mcp-needs-auth-cache.json',
+  'plugins/installed_plugins.json',
+  'plugins/known_marketplaces.json',
+];
+
+/** Off means the flag is passed to Codex as `--disable <key>`. */
+export const DEFAULTS = {
+  hooks: false,
+  plugins: false,
+  models: {},
+  budgets: Object.fromEntries(Object.values(AGENTS).map(({ role, budget }) => [role, budget])),
+  retention: DEFAULT_RETENTION,
+  environmentPaths: DEFAULT_ENVIRONMENT_PATHS,
+  answerLanguage: 'English',
+};
+
+/** Booleans the operator flips from the command line; structured keys are edited in the file. */
+export const SWITCH_KEYS = ['hooks', 'plugins'];
+export const LIST_KEYS = ['environmentPaths'];
+export const OBJECT_KEYS = ['models'];
+/**
+ * A role is configured as a pair, not as a model alone: reasoning depth is half of what a
+ * model is worth. A cheap model at its default depth is a different worker from the same
+ * model at "max", and pinning only the name would have silently kept every run at the
+ * fallback depth the dispatcher happens to pass.
+ */
+const PROFILE_KEYS = ['model', 'effort', 'speed'];
+// Plan_56 D24: delegated runs check form offline; model and speed commands check catalogue
+// support on write, keeping network access out of the config reader used at every run start.
+/**
+ * The language a run answers in. Left to the model it followed the task, the surrounding docs or
+ * its own default: an English order came back in Russian, and artifacts of one project ended up in
+ * two languages. English is the default because the package is read by strangers.
+ */
+const STRING_KEYS = ['answerLanguage'];
+const KEYS = [...SWITCH_KEYS, ...LIST_KEYS, ...OBJECT_KEYS, ...STRING_KEYS, BUDGET_KEY, RETENTION_KEY];
+
+function readRetention(file, value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(
+      `${file}: key “${RETENTION_KEY}” must be an object with enabled and days, not ${JSON.stringify(value)}`,
+    );
+  }
+  for (const key of Object.keys(value)) {
+    if (!RETENTION_FIELDS.includes(key)) {
+      throw new Error(
+        `${file}: key “${RETENTION_KEY}” has unknown field “${key}”. ` +
+          `Only ${RETENTION_FIELDS.join(', ')} are allowed`,
+      );
+    }
+  }
+  if (typeof value.enabled !== 'boolean') {
+    throw new Error(
+      `${file}: key “${RETENTION_KEY}.enabled” must be true or false, not ${JSON.stringify(value.enabled)}`,
+    );
+  }
+  // Plan_17 step 4 does not read days when disabled, so stale values cannot revive deletion after
+  // the step 3 incident where a copied default silently turned cleanup back on.
+  if (!value.enabled) return { enabled: false };
+  if (typeof value.days !== 'number' || !Number.isFinite(value.days) || value.days <= 0) {
+    throw new Error(
+      `${file}: key “${RETENTION_KEY}.days” must be a positive number of days, not ${JSON.stringify(value.days)}`,
+    );
+  }
+  return { enabled: true, days: value.days };
+}
+
+/**
+ * A run gets a hard wall-clock budget, because the caller's timeout is not a run contract:
+ * on 2026-08-03 one order restarted six times and spent 170,293 accounted tokens while four
+ * killed callers left their Codex processes and token spend unrecorded.
+ */
+function readBudgets(file, value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(
+      `${file}: key “${BUDGET_KEY}” must be an object keyed by ${ROLES.join(', ')}, ` +
+        `each holding a positive number of minutes, not ${JSON.stringify(value)}`,
+    );
+  }
+  const budgets = { ...DEFAULTS.budgets };
+  for (const [role, minutes] of Object.entries(value)) {
+    if (!ROLES.includes(role)) {
+      throw new Error(
+        `${file}: key “${BUDGET_KEY}” has unknown role “${role}”. ` +
+          `Only ${ROLES.join(', ')} are allowed`,
+      );
+    }
+    if (typeof minutes === 'string' && !minutes.trim()) {
+      throw new Error(
+        `${file}: key “${BUDGET_KEY}.${role}” is empty; remove the field to use the default ` +
+          `(${DEFAULTS.budgets[role]} minutes), or give it a positive number of minutes`,
+      );
+    }
+    if (typeof minutes !== 'number' || !Number.isFinite(minutes) || minutes <= 0) {
+      throw new Error(
+        `${file}: key “${BUDGET_KEY}.${role}” must be a positive number of minutes, ` +
+          `not ${JSON.stringify(minutes)}`,
+      );
+    }
+    budgets[role] = minutes;
+  }
+  return budgets;
+}
+
+export function validateRunConfig(file, parsed) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${file} must contain an object like {"hooks": false, "plugins": false}`);
+  }
+  const config = { ...DEFAULTS };
+  for (const [key, value] of Object.entries(parsed)) {
+    if (!KEYS.includes(key)) {
+      throw new Error(`${file}: unknown key “${key}”. Only ${KEYS.join(', ')} are allowed`);
+    }
+    if (STRING_KEYS.includes(key)) {
+      if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(
+          `${file}: key “${key}” must be a non-empty string, not ${JSON.stringify(value)}. ` +
+            `Remove the key to keep the default (${DEFAULTS[key]}).`,
+        );
+      }
+      config[key] = value.trim();
+      continue;
+    }
+    if (key === BUDGET_KEY) {
+      config[key] = readBudgets(file, value);
+      continue;
+    }
+    if (key === RETENTION_KEY) {
+      config[key] = readRetention(file, value);
+      continue;
+    }
+    if (LIST_KEYS.includes(key)) {
+      if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new Error(
+          `${file}: key “${key}” must be a list of string patterns, not ${JSON.stringify(value)}. ` +
+            'An empty list means “the environment writes nothing”; an absent key uses the default.',
+        );
+      }
+      config[key] = value.map((item) => item.trim()).filter(Boolean);
+      continue;
+    }
+    if (OBJECT_KEYS.includes(key)) {
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(
+          `${file}: key “${key}” must be an object keyed by ${ROLES.join(', ')}, ` +
+            `each holding {"model": "...", "effort": "..."}, not ${JSON.stringify(value)}`,
+        );
+      }
+      const models = {};
+      for (const [role, profile] of Object.entries(value)) {
+        if (!ROLES.includes(role)) {
+          throw new Error(
+            `${file}: key “${key}” has unknown role “${role}”. Only ${ROLES.join(', ')} are allowed`,
+          );
+        }
+        if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
+          throw new Error(
+            `${file}: key “${key}.${role}” must be an object like ` +
+              `{"model": "...", "effort": "..."}, not ${JSON.stringify(profile)}`,
+          );
+        }
+        const resolved = {};
+        for (const [field, fieldValue] of Object.entries(profile)) {
+          if (!PROFILE_KEYS.includes(field)) {
+            throw new Error(
+              `${file}: key “${key}.${role}” has unknown field “${field}”. ` +
+                `Only ${PROFILE_KEYS.join(', ')} are allowed`,
+            );
+          }
+          if (typeof fieldValue !== 'string') {
+            throw new Error(
+              `${file}: key “${key}.${role}.${field}” must be a string, not ${JSON.stringify(fieldValue)}`,
+            );
+          }
+          const trimmed = fieldValue.trim();
+          // A field written as an empty string is a mistake, not an absence: dropping it silently
+          // would send the run to another profile's depth past every check below.
+          if (!trimmed) {
+            throw new Error(
+              `${file}: key “${key}.${role}.${field}” is empty; remove the field to fall back, ` +
+                'or give it a value',
+            );
+          }
+          resolved[field] = trimmed;
+        }
+        for (const field of ['effort', 'speed']) {
+          if (resolved[field] && /\s/.test(resolved[field])) {
+            throw new Error(
+              `${file}: key “${key}.${role}.${field}” must be a non-empty single word with no whitespace`,
+            );
+          }
+        }
+        if (Object.keys(resolved).length) models[role] = resolved;
+      }
+      config[key] = models;
+      continue;
+    }
+    if (typeof value !== 'boolean') {
+      throw new Error(`${file}: key “${key}” must be true or false, not ${JSON.stringify(value)}`);
+    }
+    config[key] = value;
+  }
+  return config;
+}

package/src/home/lib/file-lock.mjs

@@ -0,0 +1,76 @@
+/**
+ * Plan_56 D44: three concurrent model-set processes lost an edit after every byte comparison
+ * passed. Reuse the registry's Windows-hardened lock so both writers share one exclusion contract.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+function waitForLock(delayMs) {
+  return new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+/**
+ * A lock nobody released is worse than no lock: interrupting an install left the file behind and
+ * every later install and uninstall died on it until someone deleted it by hand (reproduced
+ * 2026-08-04). An owner update takes milliseconds, so a lock older than the staleness window
+ * belongs to a process that is gone.
+ */
+async function dropStaleLock(lockPath, staleMs) {
+  try {
+    const { mtimeMs } = await fs.stat(lockPath);
+    if (Date.now() - mtimeMs < staleMs) return false;
+    await fs.rm(lockPath, { force: true });
+    return true;
+  } catch {
+    // Vanished or unreadable — let the next open() decide rather than guess here.
+    return false;
+  }
+}
+
+/**
+ * Windows answers a taken lock with three different codes, and only one of them is EEXIST. A file
+ * whose last handle closed while a delete was pending stays visible but refuses to be opened:
+ * `open(..., 'wx')` comes back EPERM, and a file another process still holds comes back EBUSY.
+ * Treating those as fatal is what made `tests/cli/rules-owners.test.mjs` fail twice on 2026-08-11
+ * with EPERM on the lock file — the suite went red over a lock that was simply busy for one more
+ * millisecond. All three mean the same thing to a caller waiting for a lock: not yours yet.
+ */
+const LOCK_TAKEN_CODES = new Set(['EEXIST', 'EPERM', 'EBUSY']);
+
+/** Exported so the retry contract is asserted directly; the race itself reproduces only by luck. */
+export function isLockTaken(err) {
+  return LOCK_TAKEN_CODES.has(err?.code);
+}
+
+async function acquireFileLock(lockPath, { retries, delayMs, staleMs, description }) {
+  await fs.mkdir(path.dirname(lockPath), { recursive: true });
+  let lastTaken;
+  for (let attempt = 0; attempt < retries; attempt += 1) {
+    try {
+      const handle = await fs.open(lockPath, 'wx');
+      return { handle, lockPath };
+    } catch (err) {
+      if (!isLockTaken(err)) throw err;
+      lastTaken = err;
+      if (!(await dropStaleLock(lockPath, staleMs))) await waitForLock(delayMs);
+    }
+  }
+  // The code is part of the message: a timeout on EPERM points at a delete that never completed,
+  // a timeout on EEXIST at an owner that never released.
+  throw new Error(
+    `timed out waiting for ${description} lock: ${lockPath} (last attempt: ${lastTaken.code})`,
+    { cause: lastTaken },
+  );
+}
+
+export async function withFileLock(lockPath, action, {
+  retries = 200, delayMs = 5, staleMs = 30_000, description = 'file',
+} = {}) {
+  const lock = await acquireFileLock(lockPath, { retries, delayMs, staleMs, description });
+  try {
+    return await action();
+  } finally {
+    await lock.handle.close().catch(() => {});
+    await fs.rm(lock.lockPath, { force: true }).catch(() => {});
+  }
+}

package/src/home/lib/meta/reply.mjs

@@ -1,9 +1,9 @@
 /**
  * Renders the reply lines a dispatcher is allowed to return, one format per agent.
  *
- * AGENTS is the registry of the three dispatchers: for each one it names the result file
- * that run writes, how to tell that file is filled in, and which of the three reply
- * strategies below renders it. FAIL and LIMIT bypass the per-agent strategy — a run that
+ * AGENTS adds reply strategies to the shared agent registry: for each one it describes how
+ * to tell the result file is filled in and which of the three reply strategies below
+ * renders it. FAIL and LIMIT bypass the per-agent strategy — a run that
  * produced nothing has nothing agent-specific left to say.
  *
  * The lines built here ARE the reply. Agents forward this text verbatim instead of
@@ -11,6 +11,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { AGENTS as AGENT_DEFINITIONS } from '../agents.mjs';
 import { changedPaths, line, readJson, readText } from './paths.mjs';
 import { splitRunChanges } from './environment.mjs';
 import { scoutCoverage } from './verdict.mjs';
@@ -47,17 +48,17 @@ function retentionReply(runDir) {
 
 export const AGENTS = {
   'codex-scout': {
-    result: 'result.json',
+    ...AGENT_DEFINITIONS['codex-scout'],
     filled: (r) => Boolean(String(r?.answer || '').trim()),
     reply: scoutReply,
   },
   'codex-build': {
-    result: 'result.json',
+    ...AGENT_DEFINITIONS['codex-build'],
     filled: (r) => Boolean(String(r?.summary || '').trim()),
     reply: buildReply,
   },
   'codex-review': {
-    result: 'review.json',
+    ...AGENT_DEFINITIONS['codex-review'],
     filled: (r) => Boolean(String(r?.verdict || '').trim()),
     reply: reviewReply,
   },

package/src/home/lib/run-codex.mjs

@@ -11,7 +11,7 @@
  *   --effort    reasoning effort, passed to Codex as given (default: medium)
  *   --verify    verification command, codex-build only (e.g. "npm test")
  *   --scope     comma-separated globs the run may edit, codex-build only (required there)
- *   --mode      uncommitted | base:<branch> | commit:<sha>, codex-review only
+ *   --changeset uncommitted | base:<branch> | commit:<sha>, codex-review only
  *   --continue  acknowledge that this repo+slug already has runs (required if it does)
  *
  * The operator's task text arrives verbatim through stdin or --task-file.