@lyupro/codex-bridge 0.5.1 → 0.5.3

package/src/{runner → home/lib/runner}/launcher.mjs

@@ -31,6 +31,7 @@ import { attach } from './attach.mjs';
 import { setRun } from './run-context.mjs';
 import { loadRunEnv, RUN_ENV } from './run-env.mjs';
 import { parseArgs, die } from './args.mjs';
+import { settleTaskInput } from './task-input.mjs';
 import { parseContinuationGrant } from '../required-inputs.mjs';
 import { continuationRefusal } from './continuation.mjs';
 import { SCHEMAS } from './schemas.mjs';
@@ -48,7 +49,6 @@ import { validateScope } from './scope-check.mjs';
  * below is the CLI entry one level up — not this module, which has no command line of its own.
  */
 const RUNNER_ENTRY = fileURLToPath(new URL('../run-codex.mjs', import.meta.url));
-
 export const questionsFromFlags = (questionTexts = []) =>
   questionTexts.map((text, i) => ({ id: `Q${i + 1}`, text }));
 
@@ -63,7 +63,7 @@ const stamp = () => {
  * otherwise overwrite each other's task.md, log and result — and a status could then be
  * computed from another run's artifacts.
  */
-function makeRunDir(base) {
+export function makeRunDir(base) {
   fs.mkdirSync(path.dirname(base), { recursive: true });
   for (let n = 2, dir = base; ; n += 1) {
     try {
@@ -76,19 +76,26 @@ function makeRunDir(base) {
   }
 }
 
+export const runDirPath = (root, slug, runStamp = stamp()) => {
+  // `2026-08-13_235525_2026-08-13_plan4-6g-ceiling-scope` duplicated the order date. Only the
+  // directory copy is stripped: the slug stored in status.json stays verbatim, because a run
+  // with neither order_id nor task_hash is found by its stored slug alone (meta/chain.mjs).
+  const stripped = String(slug).replace(/^\d{4}-\d{2}-\d{2}[_-]/, '');
+  // An order id that is nothing but a date would otherwise name a folder ending in `_`.
+  const directorySlug = stripped || String(slug);
+  return path.join(root, `${runStamp}_${directorySlug}`);
+};
+
 /**
  * Everything a run needs before a single token of someone else's quota is spent, and every
  * refusal that costs nothing: bad arguments, an open chain without --continue, a busy
  * worktree, a missing Codex CLI. All of it happens here, in the process the caller is free
  * to kill — so a killed caller can only ever interrupt a run that was already paid for.
  */
-export async function launcher() {
+export async function launcher(argv = process.argv.slice(2)) {
   loadRunEnv();
-
-  const opts = parseArgs(process.argv.slice(2));
-  const taskText = fs.readFileSync(0, 'utf8').trim();
-  if (!taskText) die('task text on stdin is empty');
-
+  const opts = parseArgs(argv);
+  const taskText = settleTaskInput(opts);
   const topLevel = git(opts.repo, ['rev-parse', '--show-toplevel']);
   const isGitRepo = topLevel.status === 0;
   const repoRoot = isGitRepo ? topLevel.stdout.trim() : opts.repo;
@@ -162,8 +169,9 @@ export async function launcher() {
     orderId: opts.orderId,
     chain,
     isContinue: opts.continue,
+    noWait: opts.noWait,
   });
-  if (attachedExitCode !== null) process.exit(attachedExitCode);
+  if (attachedExitCode !== null) return attachedExitCode;
 
   if (startedChain.length && !opts.continue) {
     const last = startedChain[startedChain.length - 1];
@@ -196,7 +204,7 @@ export async function launcher() {
     retention = null;
   }
 
-  const runDir = makeRunDir(path.join(projectRunsRoot, `${stamp()}_${opts.slug}`));
+  const runDir = makeRunDir(runDirPath(projectRunsRoot, opts.slug));
   setRun(runDir, opts.agent);
 
   // Written before Codex is even probed. From here on a killed runner leaves a folder that
@@ -230,7 +238,7 @@ export async function launcher() {
 
   // Printed before anything can go wrong: even a dispatcher that dies mid-run leaves the
   // orchestrator with a folder to look into.
-  console.log(`RUN=${runDir}`);
+  console.log(`RUN=${runDir} order-id=${opts.orderId}`);
 
   // Before requireCodex, so a blocked run costs nothing at all.
   if (busy) {
@@ -245,7 +253,7 @@ export async function launcher() {
       true,
     );
     console.log(reply);
-    process.exit(1);
+    return 1;
   }
 
   requireCodex(runDir, opts.agent);
@@ -334,7 +342,7 @@ export async function launcher() {
       true,
     );
     console.log(reply);
-    process.exit(1);
+    return 1;
   }
   fs.writeFileSync(
     path.join(runDir, 'worker.json'),
@@ -347,7 +355,7 @@ export async function launcher() {
         is_git_repo: isGitRepo,
         launcher_pid: process.pid,
         // The mode's wall-clock budget, resolved here and never re-read by the worker: a run
-        // that consulted run-config.json twice could end up honouring two different limits.
+        // that consulted config.json twice could end up honouring two different limits.
         budget_minutes: RUN_ENV?.budgets?.[runMode(opts.agent)],
         scope_new: opts.scopeNewPatterns,
         args: codexArgv,
@@ -366,13 +374,17 @@ export async function launcher() {
     windowsHide: true,
     cwd: repoRoot,
   });
-  worker.on('error', (err) => {
-    const { reply } = writeFailure(runDir, opts.agent, `run worker process failed to start: ${err.message}`, [
-      'Codex was not started; quota was not spent',
-    ], true);
-    console.log(reply);
-    process.exit(1);
+  const started = await new Promise((resolve) => {
+    worker.once('spawn', () => resolve(true));
+    worker.once('error', (err) => {
+      const { reply } = writeFailure(runDir, opts.agent, `run worker process failed to start: ${err.message}`, [
+        'Codex was not started; quota was not spent',
+      ], true);
+      console.log(reply);
+      resolve(false);
+    });
   });
+  if (!started) return 1;
   worker.unref();
   writeStatus(runDir, { pid: worker.pid, runner_pid: worker.pid, process_started_at: null });
 
@@ -382,5 +394,5 @@ export async function launcher() {
   console.log(
     'To get the verdict, repeat the identical command with the same --order-id; it will attach to this run and will not start a second run.',
   );
-  process.exit(0);
+  return 0;
 }

package/src/home/lib/runner/order-owner.mjs

@@ -0,0 +1,28 @@
+/** Keeps the runner and producer hook on one definition of which task owns an order id. */
+
+const byStartThenName = (left, right) => {
+  const leftAt = String(left.status.started_at || '');
+  const rightAt = String(right.status.started_at || '');
+  if (leftAt !== rightAt) return leftAt < rightAt ? -1 : 1;
+  if (String(left.run) === String(right.run)) return 0;
+  return String(left.run) < String(right.run) ? -1 : 1;
+};
+
+export function runsForOrder(runs, orderId) {
+  const wantedOrderId = String(orderId ?? '');
+  if (!wantedOrderId) return [];
+  return runs
+    .filter(({ status }) => String(status?.order_id ?? '') === wantedOrderId)
+    .sort(byStartThenName);
+}
+
+/**
+ * On 2026-08-15 plan42-run3 reused plan42-run2's order id and received run2's verdict.
+ * Compare only known fingerprints so runs predating task_hash remain fail-open.
+ */
+export function conflictingOrderOwner(runs, orderId, taskHash) {
+  const owner = runsForOrder(runs, orderId).at(-1);
+  const ownerHash = String(owner?.status.task_hash ?? '').trim().toLowerCase();
+  const incomingHash = String(taskHash ?? '').trim().toLowerCase();
+  return ownerHash && incomingHash && ownerHash !== incomingHash ? owner : null;
+}

package/src/{runner → home/lib/runner}/run-env.mjs

@@ -9,7 +9,7 @@
  * fixture ran the task and cost 23k.
  *
  * Not hardcoded, because "never" is the wrong contract: `node run-config.mjs hooks on`
- * turns either of them back on. A broken run-config.json stops the run instead of quietly
+ * turns either of them back on. A broken config.json stops the run instead of quietly
  * falling back — a typo must not decide what environment a run gets.
  */
 import { readRunConfig, disableFlags } from '../run-config.mjs';

package/src/home/lib/runner/sandbox-flags.mjs

@@ -0,0 +1,27 @@
+/**
+ * Platform flags a delegated run needs before its sandbox can start a process at all.
+ *
+ * codex-cli 0.149.0 on Windows runs sandboxed commands under a restricted token, and which token
+ * it builds is `windows.sandbox` — `elevated` or `unelevated`. The unelevated form refuses
+ * CreateProcess outright: every command the model tries comes back as
+ * `Rejected("… rejected: blocked by policy")` before the process exists. That setting lives in the
+ * operator's own config.toml, which `--ignore-user-config` deliberately drops, so on 2026-08-23
+ * every codex-scout and codex-review run died without reading a single file while codex-build
+ * kept working — not because writing is exempt, but because it is the one agent that does not pass
+ * `--ignore-user-config` and so inherited the operator's key by luck. Four probes on the installed
+ * CLI, differing by this flag alone, separate the two: with the key a run prints its command output
+ * and exits 0, without it both read-only AND workspace-write are refused.
+ *
+ * Naming the flag here keeps the isolation intact — a run still ignores the operator's config —
+ * and stops the package from depending on a line in a personal file it does not own.
+ *
+ * The value carries no quotes on purpose: unsafeForCmd() refuses any argument containing `"`,
+ * because the whole command line goes through cmd.exe. Codex parses `elevated` as a bare TOML
+ * literal, and rejects an unknown variant loudly, so the unquoted form is checked, not assumed.
+ */
+export const WINDOWS_SANDBOX = ['-c', 'windows.sandbox=elevated'];
+
+/** Empty off Windows: no other platform has this setting, and passing it would be an error. */
+export function platformSandboxArgs(platform = process.platform) {
+  return platform === 'win32' ? [...WINDOWS_SANDBOX] : [];
+}

package/src/home/lib/runner/task-file.mjs

@@ -0,0 +1,92 @@
+/**
+ * Parses the task document without knowing how it reached the runner.
+ *
+ * The 2026-08-15 permission-rule incident showed that model-written questions and verification
+ * commands cannot safely travel through a shell command line. Recognised sections keep that free
+ * text in the file while the headingless form preserves every existing task file.
+ */
+
+const SECTION_HEADING = /^ {0,3}(#{1,6})[ \t]+(.+?)[ \t]*$/;
+const LIST_ITEM = /^\s*(?:[-*]|\d+\.)[ \t]+(.+?)\s*$/;
+const SECTION_NAMES = new Map([
+  ['task', 'task'],
+  ['questions', 'questions'],
+  ['verify', 'verify'],
+]);
+
+/**
+ * A heading, its level, and the section it opens when the runner recognises its text.
+ *
+ * The level is what closes a section. Treating every unrecognised heading as ordinary content
+ * made the first task file written against this format unreadable: a `## Constraints` heading
+ * after `## Verify` was swallowed into the verification command, and the document was refused
+ * for holding more than one command. A sibling or shallower heading ends the section it follows;
+ * only a deeper one belongs to it.
+ */
+function headingFrom(line) {
+  const match = SECTION_HEADING.exec(line);
+  if (!match) return undefined;
+  const text = match[2].replace(/[ \t]+#+[ \t]*$/, '').trim().toLowerCase();
+  return { level: match[1].length, section: SECTION_NAMES.get(text) };
+}
+
+function sectionFrom(line) {
+  return headingFrom(line)?.section;
+}
+
+export function parseTaskDocument(text) {
+  const lines = String(text).split(/\r?\n/);
+  const hasSections = lines.some((line) => sectionFrom(line) !== undefined);
+  if (!hasSections) return { task: String(text).trim(), questions: [], verify: undefined };
+
+  const taskLines = [];
+  const questionLines = [];
+  const verifyLines = [];
+  let section = 'task';
+  let sectionLevel = 0;
+  let sawQuestions = false;
+  let sawVerify = false;
+
+  for (const line of lines) {
+    const heading = headingFrom(line);
+    if (heading?.section !== undefined) {
+      section = heading.section;
+      sectionLevel = heading.level;
+      if (section === 'questions') sawQuestions = true;
+      if (section === 'verify') sawVerify = true;
+      continue;
+    }
+    // An unrecognised heading at the section's own level or above ends it; the heading itself is
+    // part of the task statement from there on. A deeper heading stays inside the section.
+    if (heading && section !== 'task' && heading.level <= sectionLevel) {
+      section = 'task';
+      sectionLevel = 0;
+    }
+    if (section === 'questions') questionLines.push(line);
+    else if (section === 'verify') verifyLines.push(line);
+    else taskLines.push(line);
+  }
+
+  const questions = [];
+  for (const line of questionLines) {
+    if (!line.trim()) continue;
+    const item = LIST_ITEM.exec(line);
+    if (!item) {
+      throw new Error(`Questions section contains a non-list line: ${JSON.stringify(line.trim())}`);
+    }
+    questions.push(item[1].trim());
+  }
+  if (sawQuestions && !questions.length) throw new Error('Questions section is empty');
+
+  const verifyContent = verifyLines.filter((line) => line.trim());
+  if (sawVerify && !verifyContent.length) throw new Error('Verify section is empty');
+  if (verifyContent.length > 1) {
+    throw new Error('Verify section must contain exactly one non-empty line');
+  }
+
+  return {
+    task: taskLines.join('\n').trim(),
+    questions,
+    verify: sawVerify ? verifyContent[0].trim() : undefined,
+  };
+}

package/src/home/lib/runner/task-input.mjs

@@ -0,0 +1,26 @@
+/**
+ * Settles the order's task, sub-questions and verification command from the two channels that
+ * can carry them, and refuses before a run folder or a paid process can exist.
+ *
+ * Kept apart from the launcher because it is the one place that has seen both channels: argument
+ * parsing runs before the task file has been read, and the file is read without knowing which
+ * flags were passed. Deciding it in either of them alone is how a scout order carrying its
+ * questions in the file got refused for not passing --question.
+ */
+import { die, readTaskDocument } from './args.mjs';
+
+export function settleTaskInput(opts) {
+  const { task, questions: fileQuestions, verify: fileVerify } = readTaskDocument(opts);
+  opts.questions ??= fileQuestions.length ? fileQuestions : undefined;
+  opts.verify ??= fileVerify;
+  // Still before the run folder exists and before a token of someone else's quota is touched,
+  // which is where every refusal of this kind belongs.
+  if (opts.agent === 'codex-scout' && !opts.questions?.length) {
+    die(
+      'a sub-question is required for codex-scout: put one Markdown list item per sub-question ' +
+        'under a `Questions` heading in the task file, or repeat --question for manual calls. ' +
+        'The runner will not infer questions from the task text; no quota was spent.',
+    );
+  }
+  return task;
+}

package/src/{runner → home/lib/runner}/worker.mjs

@@ -6,7 +6,7 @@
  * `repo`, `agent`, `args`, `is_git_repo`, `budget_minutes`. Written there: those five plus
  * `slug`, `launcher_pid` and `scope_new`, which nothing here needs but a run folder read back
  * months later does. The launcher must write the selected mode's budget into worker.json before
- * spawning this half, so the worker never re-reads run-config.json and one run cannot acquire two
+ * spawning this half, so the worker never re-reads config.json and one run cannot acquire two
  * configurations.
  * Neither side may change the shape alone.
  */

package/src/home/lib/shell-unsafe.mjs

@@ -0,0 +1,26 @@
+/** Plan_19 had to repair drift between duplicated CLI spellings, so shell-unsafe sequences must never be listed anywhere else. */
+
+export const SHELL_UNSAFE_SEQUENCES = Object.freeze([
+  '`',
+  '$(',
+  '${',
+  '&&',
+  '||',
+  '|',
+  ';',
+]);
+
+/** Returns the first forbidden sequence in reading order, preferring a compound operator at a tie. */
+export function firstShellUnsafeSequence(value) {
+  const text = String(value);
+  let first = null;
+  let firstIndex = -1;
+  for (const sequence of SHELL_UNSAFE_SEQUENCES) {
+    const index = text.indexOf(sequence);
+    if (index !== -1 && (firstIndex === -1 || index < firstIndex)) {
+      first = sequence;
+      firstIndex = index;
+    }
+  }
+  return first;
+}

package/src/{write-meta.mjs → home/lib/write-meta.mjs}

@@ -30,7 +30,18 @@ import { writeStatus } from './meta/run-state.mjs';
 import { resolveStatus } from './meta/verdict.mjs';
 import { AGENTS, failReply, limitReply } from './meta/reply.mjs';
 
-const RUNNER_VERSION = readJsonFileSync(new URL('../package.json', import.meta.url)).version;
+function readRunnerVersion() {
+  try {
+    return readJsonFileSync(new URL('../package.json', import.meta.url)).version;
+  } catch (error) {
+    // package.json is the one file npm requires outside the literal home image. The installed
+    // image has it beside lib/, while the repository has src/home between the module and manifest.
+    if (error.code !== 'ENOENT') throw error;
+    return readJsonFileSync(new URL('../../../package.json', import.meta.url)).version;
+  }
+}
+
+const RUNNER_VERSION = readRunnerVersion();
 
 export { expandDeclared, globToRegExp, readJson } from './meta/paths.mjs';
 export { chainBaseline, chainRuns, taskFingerprint } from './meta/chain.mjs';

package/src/hooks/order-gate.mjs

@@ -1,73 +0,0 @@
-#!/usr/bin/env node
-/**
- * PreToolUse gate for the Codex dispatchers (codex-scout / codex-build / codex-review).
- *
- * The runner rejects a dispatcher immediately when order id (and scope for codex-build) is
- * absent, but the old requirement lived only in the prompt read by the dispatcher. The caller
- * therefore had no enforced place to provide it and codex-build died before doing work. This
- * gate checks the producer's task text while it can still be corrected.
- *
- * Input is Claude Code's hook JSON on stdin. The last payload is retained for diagnostics so a
- * future host schema change can be inspected instead of guessed at. Any uncertain shape passes
- * silently because a diagnostic guard must never break an unrelated tool call.
- */
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { diagnoseInput, missingInputs } from '../required-inputs.mjs';
-import { SUBAGENT_TOOLS } from '../hook-definitions.mjs';
-
-const HOME = os.homedir();
-const LOG_DIR = path.join(HOME, '.claude', 'logs');
-const GUARDED = new Set(['codex-scout', 'codex-build', 'codex-review']);
-/**
- * Both spellings of the subagent-launching tool, from the same list the installer builds its
- * matcher from. Recognising only the name this host happens to use would make the gate silent
- * on every other host, and a gate that is silent for an unknown reason is worse than none.
- */
-const SUBAGENT_TOOL_NAMES = new Set(SUBAGENT_TOOLS);
-
-const pass = () => process.exit(0);
-
-let input;
-try {
-  input = JSON.parse(fs.readFileSync(0, 'utf8'));
-} catch {
-  pass();
-}
-
-try {
-  fs.mkdirSync(LOG_DIR, { recursive: true });
-  fs.writeFileSync(path.join(LOG_DIR, 'codex-order-gate.last.json'), `${JSON.stringify(input, null, 2)}\n`);
-} catch {
-  // Diagnostics are a convenience, never a reason to fail the turn.
-}
-
-if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
-if (!SUBAGENT_TOOL_NAMES.has(input.tool_name)) pass();
-
-const toolInput = input.tool_input;
-if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
-if (!GUARDED.has(toolInput.subagent_type) || typeof toolInput.prompt !== 'string') pass();
-
-const missing = missingInputs(toolInput.subagent_type, toolInput.prompt);
-if (!missing.length) pass();
-
-const reason = [
-  'Order gate denied the Agent call because required dispatcher input(s) are missing or still placeholders.',
-  'Write each value in tool_input.prompt using `label: value` before launching the dispatcher:',
-  ...missing.flatMap((entry) => {
-    const lines = [`- ${entry.label}: ${entry.explanation} Example: \`${entry.example}\`.`];
-    const diagnosis = diagnoseInput(toolInput.prompt, entry.label);
-    if (diagnosis) lines.push(`  found \`${diagnosis.line}\`, ${diagnosis.reason}`);
-    return lines;
-  }),
-].join('\n');
-
-process.stdout.write(JSON.stringify({
-  hookSpecificOutput: {
-    hookEventName: 'PreToolUse',
-    permissionDecision: 'deny',
-    permissionDecisionReason: reason,
-  },
-}));

package/src/hooks/worktree-lock.mjs

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-/**
- * PreToolUse lock for file-writing tools in the Claude Code host.
- *
- * A live codex-build runner snapshots its repository before and after editing. Letting the
- * orchestrator write during that window folds unrelated work into the runner's result, exactly
- * as the 2026-08-05 incident did. This hook denies only a recognised file path inside a live
- * build run's repository; every malformed or unreadable input passes so diagnostics never break
- * unrelated host work.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { formatSilence, heartbeatAge } from '../heartbeat.mjs';
-import { WRITE_TOOLS } from '../hook-definitions.mjs';
-import { runsRoot } from '../runner/runs-root.mjs';
-import { allLiveRuns, normalizePath } from './live-runs.mjs';
-
-const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS);
-const pass = () => process.exit(0);
-
-let input;
-try {
-  input = JSON.parse(fs.readFileSync(0, 'utf8'));
-} catch {
-  pass();
-}
-
-if (!input || typeof input !== 'object' || Array.isArray(input)) pass();
-if (!WRITE_TOOL_NAMES.has(input.tool_name)) pass();
-
-const toolInput = input.tool_input;
-if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) pass();
-const pathField = input.tool_name === 'NotebookEdit' ? 'notebook_path' : 'file_path';
-const rawPath = toolInput[pathField];
-if (typeof rawPath !== 'string' || !rawPath.trim()) pass();
-
-let targetPath;
-try {
-  if (path.isAbsolute(rawPath)) targetPath = rawPath;
-  else if (typeof input.cwd === 'string' && input.cwd.trim()) targetPath = path.resolve(input.cwd, rawPath);
-  else pass();
-} catch {
-  pass();
-}
-
-const target = normalizePath(targetPath);
-if (!target) pass();
-
-let liveRuns;
-try {
-  liveRuns = allLiveRuns(runsRoot());
-} catch {
-  pass();
-}
-const owner = liveRuns.find(({ status }) => {
-  if (status.agent !== 'codex-build') return false;
-  const repository = normalizePath(status.repo);
-  return Boolean(repository) && (target === repository || target.startsWith(`${repository}/`));
-});
-if (!owner) pass();
-
-const { status, dir } = owner;
-process.stdout.write(JSON.stringify({
-  hookSpecificOutput: {
-    hookEventName: 'PreToolUse',
-    permissionDecision: 'deny',
-    permissionDecisionReason: `Worktree lock denied ${input.tool_name}: ${targetPath} is inside repository `
-      + `${status.repo}, held by live run folder ${dir} (agent ${status.agent}, slug ${status.slug}). `
-      // "Working, last progress X ago" rather than "silent for X": this hook only ever denies a
-      // run whose heartbeat is still fresh — a stale one is not live here and the edit passes. The
-      // first live probe printed "silent for 10 seconds" next to a stop command on a perfectly
-      // healthy run, which reads as "it hung, kill it" and would cost the operator 20 minutes of
-      // work they meant to keep.
-      + `It is working; last progress ${formatSilence(heartbeatAge(dir))} ago. `
-      + `To take the repository back before it finishes: codex-bridge stop ${path.basename(dir)}.`,
-  },
-}));