@lyupro/codex-bridge 0.5.1 → 0.5.3

package/src/{required-inputs.mjs → home/lib/required-inputs.mjs}

@@ -1,3 +1,6 @@
+import path from 'node:path';
+import { firstShellUnsafeSequence } from './shell-unsafe.mjs';
+
 /**
  * Defines the inputs the orchestrator must give each Codex dispatcher.
  *
@@ -20,6 +23,26 @@ export const CONTINUATION_INPUT = Object.freeze({
   conditional: 'when --continue is passed',
 });
 
+/**
+ * The task statement reaches the runner as a file because every other channel puts the invocation
+ * back into the multi-line form that no permission rule can cover — a heredoc on stdin, or a
+ * quoted argument the shell mangles. The orchestrator writes that file with its own file tool,
+ * which never crosses the shell at all.
+ *
+ * It is listed as a required input, not merely explained in the prompt body, because the rendered
+ * summary is the ONLY part of this contract the orchestrator ever reads. Left out of the list, a
+ * dispatcher that was given no path filled the gap itself: on 2026-08-15 codex-build wrote the file
+ * with `cat > … << 'EOF'` and earned exactly the permission window the file was introduced to end.
+ * The 2026-08-15 relative-path incident also made the repository cwd silently choose a different
+ * task.md, so both the producer gate and runner use this cross-platform absolute-path contract.
+ */
+export const TASK_FILE_INPUT = Object.freeze({
+  label: 'task file',
+  source: 'the orchestrator',
+  explanation: 'Absolute path to a file holding the task statement verbatim, written by the orchestrator with its file tool. The dispatcher passes it as --task-file and never creates, reads or rewrites it: writing it from the shell reintroduces the permission prompt this flag exists to remove. Given no path, start the runner without the flag and return its refusal.',
+  example: 'C:/Users/me/AppData/Local/Temp/claude/<session>/scratchpad/task-plan-13.md',
+});
+
 export const REQUIRED_INPUTS = Object.freeze({
   'codex-scout': freezeEntries([
     {
@@ -28,6 +51,7 @@ export const REQUIRED_INPUTS = Object.freeze({
       explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
       example: 'plan-13-scout-20260804',
     },
+    TASK_FILE_INPUT,
     CONTINUATION_INPUT,
   ]),
   'codex-build': freezeEntries([
@@ -41,8 +65,9 @@ export const REQUIRED_INPUTS = Object.freeze({
       label: 'scope',
       source: 'the orchestrator',
       explanation: 'Comma-separated globs relative to the repository root, listing every file the run may touch — including each caller of what changes, not only the file being edited. Anything outside the list fails the run.',
-      example: 'src/runner/**,tests/runner/**',
+      example: 'src/home/lib/runner/**,tests/runner/**',
     },
+    TASK_FILE_INPUT,
     CONTINUATION_INPUT,
   ]),
   'codex-review': freezeEntries([
@@ -52,6 +77,7 @@ export const REQUIRED_INPUTS = Object.freeze({
       explanation: 'The label this order is known by. Repeating a call with the same label joins the run already in flight and costs no quota; a different piece of work needs a new label, never a reused one.',
       example: 'plan-13-review-20260804',
     },
+    TASK_FILE_INPUT,
     CONTINUATION_INPUT,
   ]),
 });
@@ -63,6 +89,11 @@ function cleanValue(value) {
   return value.trim().replace(/^([`'\"])(.*)\1$/, '$2').trim();
 }
 
+export function isAbsoluteTaskFilePath(value) {
+  const cleaned = cleanValue(value);
+  return path.posix.isAbsolute(cleaned) || path.win32.isAbsolute(cleaned);
+}
+
 export function isPlaceholder(value) {
   const cleaned = cleanValue(value);
   if (!cleaned) return true;
@@ -110,7 +141,12 @@ export function diagnoseInput(promptText, label) {
   if (candidateLine === undefined) return null;
 
   const value = extractValue(candidateLine, label);
-  if (value !== null && !isPlaceholder(value)) return null;
+  if (value !== null && !isPlaceholder(value)) {
+    if (label === TASK_FILE_INPUT.label && !isAbsoluteTaskFilePath(value)) {
+      return { line: readableDiagnosisLine(candidateLine), reason: `value \`${value}\` is not an absolute path` };
+    }
+    return null;
+  }
 
   const line = readableDiagnosisLine(candidateLine);
   if (value !== null && isPlaceholder(value)) {
@@ -156,9 +192,24 @@ export function requiredInputsFor(agentType) {
 /** Returns required entries whose value is absent or is still an obvious template placeholder. */
 export function missingInputs(agentType, promptText) {
   const prompt = typeof promptText === 'string' ? promptText : '';
-  return requiredInputsFor(agentType).filter(
-    (entry) => !entry.conditional && isPlaceholder(extractValue(prompt, entry.label)),
-  );
+  return requiredInputsFor(agentType).filter((entry) => {
+    if (entry.conditional) return false;
+    const value = extractValue(prompt, entry.label);
+    if (isPlaceholder(value)) return true;
+    return entry === TASK_FILE_INPUT && !isAbsoluteTaskFilePath(value);
+  });
+}
+
+/** Finds labelled command-line values that would disable the host's standing permission. */
+export function shellUnsafeInputs(agentType, promptText) {
+  const prompt = typeof promptText === 'string' ? promptText : '';
+  return requiredInputsFor(agentType).flatMap((entry) => {
+    if (entry.conditional) return [];
+    const value = extractValue(prompt, entry.label);
+    if (value === null || isPlaceholder(value)) return [];
+    const sequence = firstShellUnsafeSequence(value);
+    return sequence === null ? [] : [{ entry, sequence }];
+  });
 }
 
 /** Renders the compact contract the orchestrator sees while choosing a dispatcher. */

package/src/{retention.mjs → home/lib/retention.mjs}

@@ -1,7 +1,7 @@
 /** Owns the transport list and age decision shared by automatic and manual cleanup. */
 import fs from 'node:fs';
 import path from 'node:path';
-import { liveRuns, normalizePath } from './hooks/live-runs.mjs';
+import { liveRuns, normalizePath } from '../hooks/live-runs.mjs';
 
 // Plan_17 step 3 found one order's copied list and age default diverging on the same day. Keeping
 // the transport boundary here prevents automatic cleanup from eating accounting files.

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

@@ -2,6 +2,7 @@
 /**
  * Runs one delegated Codex job end to end:
  *   node run-codex.mjs --agent <codex-scout|codex-build|codex-review> [options] < task.txt
+ *   codex-bridge run --agent <codex-scout|codex-build|codex-review> [options] --task-file task.txt
  *
  * Options:
  *   --agent     codex-scout | codex-build | codex-review   (required)
@@ -13,7 +14,7 @@
  *   --mode      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 on stdin, verbatim.
+ * The operator's task text arrives verbatim through stdin or --task-file.
  *
  * Why this is a script and not a list of steps inside an agent prompt: a prompt can be
  * silently not followed, and twice it wasn't — one dispatcher reviewed the diff itself
@@ -51,6 +52,7 @@ import { writeFailure } from './write-meta.mjs';
 import { setWorkerDir, getRun, emitReply } from './runner/run-context.mjs';
 import { launcher } from './runner/launcher.mjs';
 import { worker } from './runner/worker.mjs';
+import { RunnerUsageError } from './runner/args.mjs';
 
 export { parseArgs } from './runner/args.mjs';
 export { runsPrefixInside, worktreeSnapshot } from './runner/git-state.mjs';
@@ -58,8 +60,6 @@ export { runsPrefixInside, worktreeSnapshot } from './runner/git-state.mjs';
 // `--worker <runDir>` and nothing else: the worker takes its whole order from worker.json in
 // that folder, so a half-parsed command line cannot make the two halves disagree about which
 // run they are working on.
-const WORKER_DIR = process.argv[2] === '--worker' ? process.argv[3] : null;
-
 /**
  * Only a direct call is a run. Imported — which is how the tests reach parseArgs(),
  * runsPrefixInside() and worktreeSnapshot() — this file must do nothing at all: no argument
@@ -69,8 +69,6 @@ const WORKER_DIR = process.argv[2] === '--worker' ? process.argv[3] : null;
 const invokedDirectly =
   process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
 
-setWorkerDir(WORKER_DIR);
-
 // A crash of the runner itself still has to read as a FAIL, and that FAIL still has to
 // be backed by meta.json — otherwise there would be a second path by which a reply
 // exists without an artifact behind it, which is the whole failure mode this design
@@ -79,7 +77,7 @@ setWorkerDir(WORKER_DIR);
 // One handler, here, for both halves: it has to catch a crash whichever branch below is
 // running, and a second registration inside launcher.mjs or worker.mjs would be a second
 // answer to the same question.
-if (invokedDirectly) {
+export function installRunnerCrashBoundary() {
   process.on('uncaughtException', (err) => {
     const { dir: currentRun, agent: currentAgent } = getRun();
     if (currentRun) {
@@ -104,10 +102,40 @@ if (invokedDirectly) {
   });
 }
 
-if (invokedDirectly) {
-  if (WORKER_DIR) {
-    worker(WORKER_DIR);
-  } else {
-    launcher();
+/**
+ * The package command and the historical file entry both cross this boundary. Keeping argv
+ * explicit prevents the public command from reconstructing or normalizing runner flags, while
+ * the worker sentinel remains private to the direct file invocation spawned by launcher.mjs.
+ */
+export async function runCodex(argv) {
+  const workerDir = argv[0] === '--worker' ? argv[1] : null;
+  setWorkerDir(workerDir);
+  try {
+    if (workerDir) return worker(workerDir);
+    return await launcher(argv);
+  } catch (err) {
+    if (err instanceof RunnerUsageError) return err.exitCode;
+    throw err;
   }
 }
+
+/**
+ * Both public entry forms must terminate through the runner's FAIL reply. The 2026-08-15
+ * package-command incident let launcher rejections escape to the CLI usage handler, making a
+ * runner crash indistinguishable from a refusal with exit 2.
+ */
+export async function runCodexCommand(argv) {
+  installRunnerCrashBoundary();
+  try {
+    return await runCodex(argv);
+  } catch (err) {
+    queueMicrotask(() => { throw err; });
+    return new Promise(() => {});
+  }
+}
+
+if (invokedDirectly) {
+  runCodexCommand(process.argv.slice(2)).then((exitCode) => {
+    if (exitCode !== undefined) process.exitCode = exitCode;
+  });
+}

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

@@ -22,7 +22,7 @@ import { fileURLToPath } from 'node:url';
 import { readJsonFileSync } from './json-file.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
-export const CONFIG_PATH = path.join(HERE, 'run-config.json');
+export const CONFIG_PATH = path.join(HERE, '..', 'config.json');
 
 const BUDGET_KEY = 'budgets';
 const BUDGET_MODES = ['scout', 'build', 'review'];
@@ -117,7 +117,7 @@ export function retentionNotice(config) {
     const days = config.retention.days;
     return {
       enabled: true,
-      text: `Automatic cleanup is ON — run transport older than ${days} days is removed to reclaim disk space. Accounting and reports are never touched. Change or disable: retention in run-config.json.`,
+      text: `Automatic cleanup is ON — run transport older than ${days} days is removed to reclaim disk space. Accounting and reports are never touched. Change or disable: retention in config.json.`,
     };
   }
   return {

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

@@ -5,14 +5,65 @@
  * else's quota is touched, and every refusal is an exit code rather than a message: a
  * dispatcher branches on it.
  */
+import fs from 'node:fs';
 import path from 'node:path';
 import { AGENTS } from '../write-meta.mjs';
 import { ALLOWED_EFFORTS } from '../run-config.mjs';
-import { requiredInputsFor } from '../required-inputs.mjs';
+import { isAbsoluteTaskFilePath, requiredInputsFor } from '../required-inputs.mjs';
+import { firstShellUnsafeSequence } from '../shell-unsafe.mjs';
+import { parseTaskDocument } from './task-file.mjs';
+
+export class RunnerUsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.exitCode = 2;
+  }
+}
 
 export function die(message) {
   console.error(`run-codex: ${message}`);
-  process.exit(2);
+  throw new RunnerUsageError(message);
+}
+
+export function readTaskDocument(opts) {
+  const stdinText = process.stdin.isTTY ? '' : fs.readFileSync(0, 'utf8');
+  if (opts['task-file'] !== undefined) {
+    if (stdinText.trim()) {
+      die('task text was supplied through both stdin and --task-file; choose exactly one channel');
+    }
+    const taskFile = opts['task-file'];
+    // The 2026-08-15 incident resolved a relative order against the repository cwd and ran an
+    // unrelated task.md. Refuse the supplied value instead of silently selecting another file.
+    if (!isAbsoluteTaskFilePath(taskFile)) {
+      die(`--task-file must be an absolute path; got ${JSON.stringify(taskFile)}`);
+    }
+    let fileText;
+    try {
+      fileText = fs.readFileSync(taskFile, 'utf8');
+    } catch (err) {
+      die(`task file from --task-file could not be read: ${err.message}`);
+    }
+    if (!fileText.trim()) die(`task file from --task-file is empty: ${taskFile}`);
+    let document;
+    try {
+      document = parseTaskDocument(fileText);
+    } catch (err) {
+      die(`${taskFile}: ${err.message}`);
+    }
+    if (document.questions.length && opts.questions?.length) {
+      die('questions were supplied through both --question and the task file; choose exactly one channel');
+    }
+    if (document.verify !== undefined && opts.verify !== undefined) {
+      die('verification command was supplied through both --verify and the task file; choose exactly one channel');
+    }
+    return document;
+  }
+  if (!stdinText.trim()) die('task text on stdin is empty');
+  try {
+    return parseTaskDocument(stdinText);
+  } catch (err) {
+    die(err.message);
+  }
 }
 
 function requiredInput(agentType, label) {
@@ -25,8 +76,21 @@ function requiredInput(agentType, label) {
 // 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 BOOLEAN_FLAGS = new Set(['continue', 'no-wait']);
 const REPEATABLE_FLAGS = new Set(['question']);
+// Plan_42 keeps free text in the task file because these command-line values otherwise disable
+// the host's standing permission before the runner can spend quota.
+const SHELL_CHECKED_FLAGS = Object.freeze([
+  'order-id',
+  'slug',
+  'scope',
+  'scope-new',
+  'repo',
+  'agent',
+  'effort',
+  'mode',
+  'task-file',
+]);
 const BOOLEAN_YES = /^(1|true|yes)$/i;
 const BOOLEAN_NO = /^(0|false|no)$/i;
 
@@ -64,9 +128,23 @@ export function parseArgs(argv) {
     opts[name] = value;
     i += 1;
   }
+  for (const name of SHELL_CHECKED_FLAGS) {
+    if (opts[name] === undefined) continue;
+    const sequence = firstShellUnsafeSequence(opts[name]);
+    if (sequence !== null) {
+      die(
+        `--${name} contains forbidden shell sequence ${JSON.stringify(sequence)}; ` +
+          'put free text in the task file and pass only a short command-line value.',
+      );
+    }
+  }
   if (!opts.agent) die('--agent is required');
   if (!AGENTS[opts.agent]) die(`unknown --agent ${opts.agent}`);
   opts.orderId = String(opts['order-id'] ?? '').trim();
+  opts.noWait = Boolean(opts['no-wait']);
+  if (opts.noWait && opts.continue) {
+    die('--no-wait cannot be combined with --continue: checking an existing run must never authorize a new one.');
+  }
   if (!opts.orderId) {
     const orderInput = requiredInput(opts.agent, 'order id');
     die(
@@ -77,13 +155,11 @@ export function parseArgs(argv) {
     );
   }
   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())) {
+    // The requirement itself moved to the launcher, which is the first point that has seen both
+    // sources: questions now arrive either as flags or as a section of the task file, and this
+    // check runs before either file or stdin has been read. Only the shape of a supplied flag is
+    // still judged here.
+    if (opts.questions?.some((question) => !String(question).trim())) {
       die('--question must not be empty for codex-scout; no quota was spent');
     }
   }

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);