@lyupro/codex-bridge 0.5.1 → 0.5.2

package/src/{hooks → home/hooks}/worktree-lock.mjs

@@ -10,9 +10,9 @@
  */
 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 { formatSilence, heartbeatAge } from '../lib/heartbeat.mjs';
+import { WRITE_TOOLS } from '../lib/hook-definitions.mjs';
+import { runsRoot } from '../lib/runner/runs-root.mjs';
 import { allLiveRuns, normalizePath } from './live-runs.mjs';
 
 const WRITE_TOOL_NAMES = new Set(WRITE_TOOLS);

package/src/home/lib/dispatcher-order.mjs

@@ -0,0 +1,36 @@
+/** Reads and compares the order identity carried between dispatcher hook boundaries. */
+import fs from 'node:fs';
+import { parseJsonText } from './json-file.mjs';
+import { extractValue } from './required-inputs.mjs';
+
+/** The transcript is diagnostic evidence; malformed or unavailable evidence must fail open. */
+export function transcriptOrderId(transcriptPath) {
+  try {
+    const firstEntry = fs.readFileSync(transcriptPath, 'utf8').split(/\r?\n/, 1)[0];
+    const transcriptEntry = parseJsonText(transcriptPath, firstEntry);
+    const content = transcriptEntry?.message?.content;
+    const promptText = typeof content === 'string'
+      ? content
+      : Array.isArray(content)
+        ? content.filter((part) => part?.type === 'text').map((part) => part.text).join('\n')
+        : '';
+    return String(extractValue(promptText, 'order id') || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+/** On 2026-08-15 another order's saved reply was returned as the current run's verdict. */
+export function runOrderMismatch(orderedOrderId, runStatus, runDir) {
+  const ordered = String(orderedOrderId ?? '').trim();
+  const recorded = String(runStatus?.order_id ?? '').trim();
+  if (!ordered || !recorded || ordered === recorded) return null;
+  return {
+    reason: `Contract violated: the dispatcher was ordered order id ${JSON.stringify(ordered)}, ` +
+      `but run folder ${runDir} records order_id ${JSON.stringify(recorded)}. Run the ordered ` +
+      'order id and return that run\'s stdout verbatim.',
+    observed: `The dispatcher transcript orders ${JSON.stringify(ordered)}, but status.json in ` +
+      `${runDir} records order_id=${JSON.stringify(recorded)}. Run the ordered order id and ` +
+      `return that run's stdout verbatim.`,
+  };
+}

package/src/{hook-definitions.mjs → home/lib/hook-definitions.mjs}

@@ -5,7 +5,7 @@
  * subagent, and the first host that renames it would leave a registered hook listening for a
  * tool that never fires — silence indistinguishable from approval, which is the exact failure
  * the gate exists to end. `cli/manifest.mjs` builds the settings matcher from SUBAGENT_TOOLS
- * and `src/hooks/order-gate.mjs` recognises the same names, so a matcher can never drift away
+ * and `src/home/hooks/order-gate.mjs` recognises the same names, so a matcher can never drift away
  * from what the hook actually checks.
  */
 

package/src/home/lib/host-refusal.mjs

@@ -0,0 +1,20 @@
+/** Recognises whether a dispatcher reply contains every required part of a host refusal. */
+
+const ORDER_ID_PATTERNS = [
+  /--order-id(?:=|\s+)[`"']?([a-z0-9][a-z0-9._-]*)/i,
+  /\border[\s_-]*id\s*(?::|=)\s*[`"']?([a-z0-9][a-z0-9._-]*)/i,
+  /\border[\s_-]*id\s+[`"']([^`"']+)[`"']/i,
+];
+
+export function recognizeHostRefusal(reply) {
+  const text = String(reply ?? '');
+  const declaresFailure = /(^|\n)\s*`*FAIL\b/i.test(text);
+  const namesOrderId = ORDER_ID_PATTERNS.some((pattern) => pattern.test(text));
+  const namesInstallRemedy = /\bcodex-bridge\s+install\b/i.test(text);
+  const missing = [
+    ...(!declaresFailure ? ['FAIL declaration'] : []),
+    ...(!namesOrderId ? ['order id'] : []),
+    ...(!namesInstallRemedy ? ['codex-bridge install remedy'] : []),
+  ];
+  return { recognized: missing.length === 0, declaresFailure, namesOrderId, namesInstallRemedy, missing };
+}

package/src/{json-file.mjs → home/lib/json-file.mjs}

@@ -7,7 +7,7 @@
 import fs from 'node:fs';
 import fsp from 'node:fs/promises';
 
-function parseJson(file, raw) {
+export function parseJsonText(file, raw) {
   const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
   try {
     return JSON.parse(text);
@@ -17,14 +17,14 @@ function parseJson(file, raw) {
 }
 
 export async function readJsonFile(file) {
-  return parseJson(file, await fsp.readFile(file, 'utf8'));
+  return parseJsonText(file, await fsp.readFile(file, 'utf8'));
 }
 
 export async function readJsonFileWithRaw(file) {
   const raw = await fsp.readFile(file, 'utf8');
-  return { raw, value: parseJson(file, raw) };
+  return { raw, value: parseJsonText(file, raw) };
 }
 
 export function readJsonFileSync(file) {
-  return parseJson(file, fs.readFileSync(file, 'utf8'));
+  return parseJsonText(file, fs.readFileSync(file, 'utf8'));
 }

package/src/{meta → home/lib/meta}/paths.mjs

@@ -10,7 +10,26 @@ import fs from 'node:fs';
 import { readJsonFileSync } from '../json-file.mjs';
 
 /** One line, no newlines, bounded length — a five-line reply must stay five lines. */
-export const line = (value, max = 200) => String(value ?? '').replace(/\s+/g, ' ').trim().slice(0, max);
+export const line = (value, max = 200) => {
+  const text = String(value ?? '').replace(/\s+/g, ' ').trim();
+  if (text.length <= max) return text;
+
+  const ellipsis = '...';
+  if (max <= ellipsis.length) return text.slice(0, Math.max(0, max));
+
+  const contentLimit = max - ellipsis.length;
+  const boundary = text.lastIndexOf(' ', contentLimit);
+  // `All 298 tests pass` once became `All 29`; a reply must omit a whole word, not corrupt it.
+  // Retreating to a space is the whole fix, and it is enough on its own: what survives ends
+  // where a word ended. Dropping a trailing number here as well cost `All 298 12345678 rest`
+  // its 298 — a number that fitted whole — because the digit test compared the limit rather
+  // than the point the text was actually cut at.
+  if (boundary > 0) return `${text.slice(0, boundary)}${ellipsis}`;
+
+  // No space to retreat to: the limit lands inside a single long word. Only here can the cut
+  // land mid-number, so only here is a partial number dropped.
+  return `${text.slice(0, contentLimit).replace(/\d+$/, '')}${ellipsis}`;
+};
 
 export const readText = (file) => {
   try {

package/src/{meta → home/lib/meta}/reply.mjs

@@ -108,7 +108,7 @@ function buildReply(ctx) {
     : paths || 'worktree untouched';
   const retention = retentionReply(ctx.runDir);
   return [
-    `OK — ${line(r.summary, 160)}`,
+    `OK — ${line(r.summary, 300)}`,
     `Files: ${touchedPaths.length} changed · ${files}`,
     // Only when something outside the run wrote to the tree. Subtracting those paths from the
     // verdict without naming them would hide a real edit behind a pattern.

package/src/{meta → home/lib/meta}/verdict.mjs

@@ -356,7 +356,7 @@ export function resolveStatus({ resultOk, exit, agent, result, runDir, events })
       // Hooks on is the known cause of this exact failure, so the reason says so instead
       // of leaving the operator to rediscover it from the log.
       const hooks = readJson(path.join(runDir, 'env.json'))?.hooks
-        ? ' (hooks are enabled in run-config.json — a likely cause)'
+        ? ' (hooks are enabled in config.json — a likely cause)'
         : '';
       return { status: 'FAIL', reason: `${verdict.reason}${hooks}` };
     }

package/src/{no-self-execution.mjs → home/lib/no-self-execution.mjs}

@@ -2,12 +2,17 @@
  * Keeps the dispatcher's first rule identical across all three prompts.
  * On 2026-08-06 codex-build wrote 19 files using the Claude quota, which is why a failed
  * delegation must end in an explicit failure instead of inviting the dispatcher to continue.
+ *
+ * The runner is named here by its command, never by its file. This block used to say "start a run
+ * through run-codex.mjs", and on 2026-08-15 a dispatcher refused by the host did exactly that:
+ * called the file by absolute path, then through PowerShell, then asked its operator to grant a
+ * permission rule on it. The prompt was not merely failing to forbid the detour — it was naming it.
  */
 const NO_SELF_EXECUTION = `## No self-execution
 
-Your only job is to start a run through \`run-codex.mjs\` and report its result; you are not the one who performs the task.
+Your only job is to start a run with the \`codex-bridge run\` command and report its result; you are not the one who performs the task.
 
-- If \`run-codex.mjs\` is missing, does not start, exits without \`RUN=\`/\`ATTACH=\`, or the run fails to begin for any reason, immediately return \`FAIL — could not start the Codex run: <reason>\` and stop.
+- If the command is missing, is refused, does not start, exits without \`RUN=\`/\`ATTACH=\`, or the run fails to begin for any reason, immediately return \`FAIL — could not start the Codex run: <reason>\` and stop. Never reach for the runner file by path, an interpreter, or another shell to get around it.
 - Performing the task yourself when the run could not be started is prohibited: do not read code, write files, or fix tests. Doing it yourself spends the Claude Max quota on exactly what the delegation existed to avoid, and does so silently.
 - Claiming "files were created" without a run that actually happened is prohibited under all circumstances. No run, no result.
 

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