@lyupro/codex-bridge 0.1.0

package/src/run-config.mjs

@@ -0,0 +1,302 @@
+#!/usr/bin/env node
+/**
+ * Reads and edits the environment switches of a delegated Codex run:
+ *   node run-config.mjs                # show current state
+ *   node run-config.mjs hooks on       # let the operator's hooks run
+ *   node run-config.mjs plugins off    # keep plugins out of the run
+ *   node run-config.mjs reset          # back to defaults (both off)
+ *
+ * Why a switch at all: hooks and plugins from ~/.codex are the operator's interactive
+ * setup, and a delegated run has no business inheriting it — a failing oh-my-codex `Stop`
+ * hook once made Codex quarantine .omx/state/session.json instead of doing the job. But
+ * "never" is the wrong contract too: some plugin may turn out to be exactly what a run
+ * needs. So the default is off, and turning it back on is one command rather than an edit
+ * to run-codex.mjs.
+ *
+ * The file is optional. Its absence is the default, not an error; a malformed one is an
+ * error, because a typo must not silently change how runs behave.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+export const CONFIG_PATH = path.join(HERE, 'run-config.json');
+
+const BUDGET_KEY = 'budgets';
+const BUDGET_MODES = ['scout', 'build', 'review'];
+const DEFAULT_BUDGETS = { scout: 15, build: 25, review: 20 };
+
+/**
+ * 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: DEFAULT_BUDGETS,
+  environmentPaths: DEFAULT_ENVIRONMENT_PATHS,
+  answerLanguage: 'English',
+};
+
+/** Booleans the operator flips from the command line; structured keys are edited in the file. */
+const SWITCH_KEYS = ['hooks', 'plugins'];
+const LIST_KEYS = ['environmentPaths'];
+const OBJECT_KEYS = ['models'];
+const MODEL_KEYS = ['scout', 'build', 'review'];
+/**
+ * A mode 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'];
+export const ALLOWED_EFFORTS = Object.freeze(['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);
+/**
+ * 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];
+
+/**
+ * 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 ${BUDGET_MODES.join(', ')}, ` +
+        `each holding a positive number of minutes, not ${JSON.stringify(value)}`,
+    );
+  }
+  const budgets = { ...DEFAULT_BUDGETS };
+  for (const [mode, minutes] of Object.entries(value)) {
+    if (!BUDGET_MODES.includes(mode)) {
+      throw new Error(
+        `${file}: key “${BUDGET_KEY}” has unknown mode “${mode}”. ` +
+          `Only ${BUDGET_MODES.join(', ')} are allowed`,
+      );
+    }
+    if (typeof minutes === 'string' && !minutes.trim()) {
+      throw new Error(
+        `${file}: key “${BUDGET_KEY}.${mode}” is empty; remove the field to use the default ` +
+          `(${DEFAULT_BUDGETS[mode]} 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}.${mode}” must be a positive number of minutes, ` +
+          `not ${JSON.stringify(minutes)}`,
+      );
+    }
+    budgets[mode] = minutes;
+  }
+  return budgets;
+}
+
+export function readRunConfig(file = CONFIG_PATH) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch {
+    return { ...DEFAULTS };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `${file} cannot be parsed as JSON (${err.message}). Fix or delete the file — without it, ` +
+        'the default mode applies: hooks and plugins are disabled.',
+    );
+  }
+  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 (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 ${MODEL_KEYS.join(', ')}, ` +
+            `each holding {"model": "...", "effort": "..."}, not ${JSON.stringify(value)}`,
+        );
+      }
+      const models = {};
+      for (const [mode, profile] of Object.entries(value)) {
+        if (!MODEL_KEYS.includes(mode)) {
+          throw new Error(
+            `${file}: key “${key}” has unknown mode “${mode}”. Only ${MODEL_KEYS.join(', ')} are allowed`,
+          );
+        }
+        if (!profile || typeof profile !== 'object' || Array.isArray(profile)) {
+          throw new Error(
+            `${file}: key “${key}.${mode}” 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}.${mode}” has unknown field “${field}”. ` +
+                `Only ${PROFILE_KEYS.join(', ')} are allowed`,
+            );
+          }
+          if (typeof fieldValue !== 'string') {
+            throw new Error(
+              `${file}: key “${key}.${mode}.${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}.${mode}.${field}” is empty; remove the field to fall back, ` +
+                'or give it a value',
+            );
+          }
+          resolved[field] = trimmed;
+        }
+        if (resolved.effort && /\s/.test(resolved.effort)) {
+          throw new Error(
+            `${file}: key “${key}.${mode}.effort” must be a single word; ` +
+              `allowed values: ${ALLOWED_EFFORTS.join(', ')}`,
+          );
+        }
+        if (resolved.effort && !ALLOWED_EFFORTS.includes(resolved.effort)) {
+          throw new Error(
+            `${file}: key “${key}.${mode}.effort” must be one of: ` +
+              `${ALLOWED_EFFORTS.join(', ')}; got ${JSON.stringify(resolved.effort)}`,
+          );
+        }
+        if (Object.keys(resolved).length) models[mode] = 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;
+}
+
+export function writeRunConfig(config, file = CONFIG_PATH) {
+  fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
+}
+
+/** Flags for `codex exec`: a switch that is off becomes an explicit --disable. */
+export const disableFlags = (config) =>
+  SWITCH_KEYS.filter((key) => !config[key]).flatMap((key) => ['--disable', key]);
+
+const state = (config) => [
+  ...SWITCH_KEYS.map(
+    (key) => `${key}: ${config[key] ? 'on — operator extensions enabled' : 'off — disabled for the run'}`,
+  ),
+  `environmentPaths: ${(config.environmentPaths || []).length} patterns — changes in them are ` +
+    'treated as environment work, not run work',
+  `models: ${MODEL_KEYS.map((key) => {
+    const profile = config.models?.[key];
+    if (!profile?.model && !profile?.effort) return `${key}: default — chosen by Codex`;
+    const model = profile.model || 'default model';
+    return `${key}: ${model}${profile.effort ? ` at ${profile.effort} effort` : ''}`;
+  }).join('; ')}`,
+  `budgets: ${BUDGET_MODES.map((mode) => `${mode}: ${config.budgets?.[mode] ?? DEFAULT_BUDGETS[mode]} minutes`).join('; ')}`,
+];
+
+function main(argv) {
+  const [key, value] = argv;
+
+  if (!key) {
+    const config = readRunConfig();
+    console.log([...state(config), `File: ${CONFIG_PATH}`].join('\n'));
+    return 0;
+  }
+
+  if (key === 'reset') {
+    writeRunConfig({ ...DEFAULTS });
+    console.log([...state(DEFAULTS), `Reset to defaults · ${CONFIG_PATH}`].join('\n'));
+    return 0;
+  }
+
+  if (!SWITCH_KEYS.includes(key)) {
+    const known = LIST_KEYS.includes(key)
+      ? `“${key}” is a pattern list, not a switch: edit it directly in ${CONFIG_PATH}`
+      : OBJECT_KEYS.includes(key)
+        ? `“${key}” is configured in the file, not as a switch: edit it directly in ${CONFIG_PATH}`
+        : `unknown switch “${key}”. Allowed: ${SWITCH_KEYS.join(', ')}, reset`;
+    console.error(`run-config: ${known}`);
+    return 2;
+  }
+  if (value !== 'on' && value !== 'off') {
+    console.error(`run-config: value must be on or off, received “${value ?? '(empty)'}”`);
+    return 2;
+  }
+
+  const config = { ...readRunConfig(), [key]: value === 'on' };
+  writeRunConfig(config);
+  console.log([...state(config), `File: ${CONFIG_PATH}`].join('\n'));
+  return 0;
+}
+
+const invokedDirectly =
+  process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+if (invokedDirectly) {
+  try {
+    process.exit(main(process.argv.slice(2)));
+  } catch (err) {
+    console.error(`run-config: ${err.message}`);
+    process.exit(2);
+  }
+}

package/src/runner/args.mjs

@@ -0,0 +1,111 @@
+/**
+ * Reads the command line of a run and refuses it before anything is spent.
+ *
+ * Every check here happens before the run folder exists and before a single token of someone
+ * else's quota is touched, and every refusal is an exit code rather than a message: a
+ * dispatcher branches on it.
+ */
+import path from 'node:path';
+import { AGENTS } from '../write-meta.mjs';
+import { ALLOWED_EFFORTS } from '../run-config.mjs';
+
+export function die(message) {
+  console.error(`run-codex: ${message}`);
+  process.exit(2);
+}
+
+// Flags that carry no value. A value is accepted only in its explicit yes/no spellings;
+// anything else stops the run. The permissive reading this replaces — "not 0/false/no means
+// yes" — turned the prompt's own placeholder text (`--continue "<only if the orchestrator provided
+// continue>"`) into a silent opt-in, and a real run started on someone else's quota. A flag
+// whose whole point is that a human decided it must never be switched on by a leftover
+// template.
+const BOOLEAN_FLAGS = new Set(['continue']);
+const REPEATABLE_FLAGS = new Set(['question']);
+const BOOLEAN_YES = /^(1|true|yes)$/i;
+const BOOLEAN_NO = /^(0|false|no)$/i;
+
+export function parseArgs(argv) {
+  const opts = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const key = argv[i];
+    if (!key.startsWith('--')) die(`unexpected argument: ${key}`);
+    const name = key.slice(2);
+    const value = argv[i + 1];
+    if (BOOLEAN_FLAGS.has(name)) {
+      if (value !== undefined && !value.startsWith('--')) {
+        if (!BOOLEAN_YES.test(value) && !BOOLEAN_NO.test(value)) {
+          die(
+            `--${name} takes no value, or one of 1/true/yes/0/false/no; got ${JSON.stringify(value)}. ` +
+              'A placeholder left in from the prompt template is not consent.',
+          );
+        }
+        opts[name] = BOOLEAN_YES.test(value);
+        i += 1;
+      } else {
+        opts[name] = true;
+      }
+      continue;
+    }
+    // A flag name where a value belongs means the value was left out: `--question --continue`
+    // otherwise records `--continue` as the question and passes every later check.
+    if (value === undefined || value.startsWith('--')) die(`missing value for ${key}`);
+    if (REPEATABLE_FLAGS.has(name)) {
+      if (!opts.questions) opts.questions = [];
+      opts.questions.push(value);
+      i += 1;
+      continue;
+    }
+    opts[name] = value;
+    i += 1;
+  }
+  if (!opts.agent) die('--agent is required');
+  if (!AGENTS[opts.agent]) die(`unknown --agent ${opts.agent}`);
+  opts.orderId = String(opts['order-id'] ?? '').trim();
+  if (!opts.orderId) {
+    die(
+      '--order-id is required: the orchestrator issues the order label and the runner will not invent one. ' +
+        'A repeat of the same order should come back with --continue. If this appeared right after a package update, ' +
+        'the installed dispatcher prompts are stale and need npm run dev:install (local dev) or codex-bridge update.',
+    );
+  }
+  if (opts.agent === 'codex-scout') {
+    if (!opts.questions?.length) {
+      die(
+        '--question is required for codex-scout: repeat it once for every sub-question the orchestrator gave. ' +
+          'The runner will not infer questions from the task text; no quota was spent.',
+      );
+    }
+    if (opts.questions.some((question) => !String(question).trim())) {
+      die('--question must not be empty for codex-scout; no quota was spent');
+    }
+  }
+  const allowedEfforts = ALLOWED_EFFORTS.join(', ');
+  // Left unset when not given, rather than defaulted here: the mode's configured profile is
+  // what fills the gap, and a default applied this early would always win over it.
+  if (opts.effort !== undefined && /\s/.test(opts.effort)) {
+    die(`--effort must be a single word; allowed values: ${allowedEfforts}`);
+  }
+  if (opts.effort !== undefined && !ALLOWED_EFFORTS.includes(opts.effort)) {
+    die(`--effort must be one of: ${allowedEfforts}; got ${JSON.stringify(opts.effort)}`);
+  }
+  opts.repo = path.resolve(opts.repo || process.cwd());
+  opts.slug = (opts.slug || opts.agent.replace(/^codex-/, '')).replace(/[^A-Za-z0-9._-]+/g, '-');
+  opts.mode = opts.mode || 'uncommitted';
+  // A writing run without a declared scope is how `!Plans/*.md` got edited by a run that was
+  // told in prose not to touch them: prose does not bind, a file list does. Required rather
+  // than defaulted to "everything", and checked here — before the folder exists and before a
+  // single token of someone else's quota is spent.
+  opts.scopePatterns = String(opts.scope || '')
+    .split(',')
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (opts.agent === 'codex-build' && !opts.scopePatterns.length) {
+    die(
+      '--scope is required for codex-build: comma-separated globs relative to the repo root, ' +
+        'e.g. --scope "packages/event-calendar/**,apps/orchestrator/src/maestro/calendar-refresh.ts". ' +
+        'Anything outside the list is off limits and fails the run.',
+    );
+  }
+  return opts;
+}

package/src/runner/attach.mjs

@@ -0,0 +1,111 @@
+/** Finds a live run for an order and waits for its verdict when a repeated launcher call attaches. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { exitCodeFor, writeFailure, chainRuns } from '../write-meta.mjs';
+
+// The attach call is the only process that waits for a worker it did not spawn. Keeping that
+// wait here leaves the launcher free to return before a caller's time ceiling kills it.
+const POLL_MS = 500;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export const readJsonFile = (file) => {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Is this pid still running? EPERM means the process exists and belongs to someone else,
+ * which for our purposes is alive. Same reading write-meta.mjs uses — two answers to "is
+ * this run still going" would be one answer too many.
+ */
+export const alive = (pid) => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+};
+
+/** Blocks until the worker's reply exists, or until the worker is provably gone without one. */
+export async function waitForReply(runDir, workerPid) {
+  const replyPath = path.join(runDir, 'reply.txt');
+  let pollsSinceDeath = 0;
+  for (;;) {
+    if (fs.existsSync(replyPath)) return fs.readFileSync(replyPath, 'utf8').replace(/\s+$/, '');
+    // A dead worker will never write it. Two extra polls before believing that: the pid is
+    // released around the same moment as the last write, and the order is not guaranteed.
+    if (alive(workerPid)) {
+      pollsSinceDeath = 0;
+    } else {
+      pollsSinceDeath += 1;
+      if (pollsSinceDeath > 2) return null;
+    }
+    await sleep(POLL_MS);
+  }
+}
+
+/**
+ * Attach to the run this order already has, returning null when this call must start one.
+ *
+ * What counts as "not finished yet" is the absence of reply.txt, not the absence of meta.json.
+ * The artifact order is meta.json first, reply.txt last, so between the two there is a moment
+ * where the verdict exists and the run is not closed — judged by meta.json, a repeat arriving in
+ * that window would be refused and sent to the --continue gate instead of being answered. The
+ * promise being kept here is that repeating the command is always safe, and a promise with a
+ * window in it is not one. markAbandoned() closes dead runs with FAIL before the gate, so this
+ * path only covers a live run that has not recorded a verdict yet.
+ *
+ * A repeat that arrives after the verdict is answered from disk rather than refused, for the same
+ * reason. `--continue` is the one case that must not attach: it is the orchestrator saying it read
+ * the previous reply and wants another pass.
+ */
+export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, isContinue } = {}) {
+  if (isContinue) return null;
+  const runs = chain || chainRuns(runsRoot, repo, slug, taskHash, orderId);
+  const sameOrder = runs
+    .map((run) => ({ run, status: readJsonFile(path.join(runsRoot, run, 'status.json')) }))
+    .filter(({ status }) => status && String(status.order_id ?? '') === String(orderId ?? ''));
+
+  const answered = sameOrder.find(({ run }) => fs.existsSync(path.join(runsRoot, run, 'reply.txt')));
+  if (answered) {
+    const runDir = path.join(runsRoot, answered.run);
+    console.log(`ATTACH=${runDir} started=${answered.status.started_at}`);
+    console.log(fs.readFileSync(path.join(runDir, 'reply.txt'), 'utf8').replace(/\s+$/, ''));
+    return exitCodeFor(readJsonFile(path.join(runDir, 'meta.json'))?.status);
+  }
+
+  const candidate = sameOrder.find(({ status }) => alive(status.pid));
+  if (!candidate) return null;
+
+  const runDir = path.join(runsRoot, candidate.run);
+  console.log(`ATTACH=${runDir} started=${candidate.status.started_at}`);
+  const replyText = await waitForReply(runDir, candidate.status.pid);
+  if (replyText !== null) {
+    console.log(replyText);
+    return exitCodeFor(readJsonFile(path.join(runDir, 'meta.json'))?.status);
+  }
+
+  // Preserve the existing outcome if a worker dies after this attach begins. Dead runs are
+  // excluded above; assigning an abandoned verdict is pass 2 of Plan_11 and remains separate.
+  const meta = readJsonFile(path.join(runDir, 'meta.json'));
+  if (meta) {
+    console.log(
+      [
+        `${meta.status} — ${meta.reason || 'verdict recorded, worker process response not saved'}`,
+        `Run: ${runDir}`,
+      ].join('\n'),
+    );
+    return exitCodeFor(meta.status);
+  }
+  const { reply } = writeFailure(runDir, candidate.status.agent, 'run worker process died without recording a verdict', [
+    `Log: ${path.join(runDir, 'raw.log')}`,
+    'Any Codex changes remain in the tree — check them with git status',
+  ]);
+  console.log(reply);
+  return 1;
+}