@lyupro/codex-bridge 0.5.0 → 0.5.2

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

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { readJsonFileSync } from '../json-file.mjs';
 import { IDENTITY_DEAD, IDENTITY_FOREIGN, processAlive, processIdentity } from '../process-identity.mjs';
 import { exitCodeFor, writeFailure, chainRuns } from '../write-meta.mjs';
+import { conflictingOrderOwner, runsForOrder } from './order-owner.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.
@@ -11,12 +12,38 @@ const POLL_MS = 500;
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
 // The 2026-08-10_220535_plan25-2-install-table-two-roots incident showed that ATTACH alone
-// can be mistaken for this pass; state the previous run and the fact that no work was started.
-function announceAttach(runDir, startedAt) {
-  console.log(`ATTACH=${runDir} started=${startedAt}`);
+// can be mistaken for this pass. Distinguish a saved answer from a live run whose verdict is
+// still pending so provenance is truthful while preserving the guarantee that no work restarted.
+function announceSavedReply(runDir, orderId, startedAt) {
+  console.log(`ATTACH=${runDir} order-id=${orderId} started=${startedAt}`);
   console.log(`This is the answer of the previous run started at ${startedAt}; no new work was started.`);
 }
 
+function announceLiveAttach(runDir, orderId, startedAt) {
+  console.log(`ATTACH=${runDir} order-id=${orderId} started=${startedAt}`);
+  console.log(
+    `Attached to the run already in progress since ${startedAt}; no new work was started, and this invocation is waiting for its verdict.`,
+  );
+}
+
+function elapsedSince(startedAt) {
+  const elapsedSeconds = Math.max(0, Math.floor((Date.now() - Date.parse(startedAt)) / 1000));
+  if (!Number.isFinite(elapsedSeconds)) return 'unknown';
+  const hours = Math.floor(elapsedSeconds / 3600);
+  const minutes = Math.floor((elapsedSeconds % 3600) / 60);
+  const seconds = elapsedSeconds % 60;
+  if (hours) return `${hours}h ${minutes}m`;
+  if (minutes) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
+function announcePending(runDir, orderId, startedAt) {
+  console.log(`ATTACH=${runDir} order-id=${orderId} started=${startedAt}`);
+  console.log(
+    `Run is still in progress; elapsed ${elapsedSince(startedAt)}. Repeat the same command without --no-wait later to wait for its verdict.`,
+  );
+}
+
 export const readJsonFile = (file) => {
   try {
     return readJsonFileSync(file);
@@ -77,12 +104,24 @@ export async function waitForReply(runDir, workerPid, status = {}) {
  * 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 } = {}) {
+export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, isContinue, noWait } = {}) {
   if (isContinue) return null;
   const runs = chain || chainRuns(runsRoot, repo, slug, taskHash, orderId);
-  const sameOrder = runs
+  const runRecords = runs
     .map((run) => ({ run, status: readJsonFile(path.join(runsRoot, run, 'status.json')) }))
-    .filter(({ status }) => status && String(status.order_id ?? '') === String(orderId ?? ''));
+    .filter(({ status }) => status);
+  const sameOrder = runsForOrder(runRecords, orderId);
+
+  const owner = conflictingOrderOwner(runRecords, orderId, taskHash);
+  if (owner) {
+    const ownerDir = path.join(runsRoot, owner.run);
+    console.log(
+      `Order id collision: ${JSON.stringify(String(orderId ?? ''))} already belongs to run folder ${ownerDir} ` +
+        `(slug ${owner.status.slug}, started_at ${owner.status.started_at}) with a different task. ` +
+        'Pass a new --order-id, or pass --continue if this really is another pass of the same order.',
+    );
+    return 2;
+  }
 
   // The run an order is currently about is its newest one, and the chain arrives oldest first.
   // Reading it from the end is the whole point: `--continue` adds a second run under the same
@@ -93,7 +132,7 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
     const entry = sameOrder[i];
     const dir = path.join(runsRoot, entry.run);
     if (fs.existsSync(path.join(dir, 'reply.txt'))) {
-      announceAttach(dir, entry.status.started_at);
+      announceSavedReply(dir, orderId, entry.status.started_at);
       console.log(fs.readFileSync(path.join(dir, 'reply.txt'), 'utf8').replace(/\s+$/, ''));
       return exitCodeFor(readJsonFile(path.join(dir, 'meta.json'))?.status);
     }
@@ -102,10 +141,20 @@ export async function attach({ runsRoot, repo, slug, taskHash, orderId, chain, i
       break;
     }
   }
-  if (!candidate) return null;
+  if (!candidate) {
+    if (!noWait) return null;
+    console.log(`No run exists for order id ${JSON.stringify(String(orderId ?? ''))}; --no-wait never starts a new run.`);
+    return 4;
+  }
 
   const runDir = path.join(runsRoot, candidate.run);
-  announceAttach(runDir, candidate.status.started_at);
+  // On 2026-08-13 a killed waiting call became an invented FAIL over a run already finished OK.
+  // A distinct call outcome lets the dispatcher inspect disk without mistaking pending for failure.
+  if (noWait) {
+    announcePending(runDir, orderId, candidate.status.started_at);
+    return 4;
+  }
+  announceLiveAttach(runDir, orderId, candidate.status.started_at);
   const replyText = await waitForReply(runDir, candidate.status.pid, candidate.status);
   if (replyText !== null) {
     console.log(replyText);

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/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,
-  },
-}));