@lyupro/codex-bridge 0.6.9 → 0.6.11

package/src/home/lib/runner/launcher.mjs

@@ -2,9 +2,8 @@
  * The half the caller can kill: every preparation and every refusal that costs no quota,
  * then the spawn of the worker and the immediate return; a repeated call waits for the reply.
  *
- * The order it leaves for the worker is worker.json in the run folder — after the split that file
- * is the only connection between the two halves. Its shape and the reason for every field live in
- * worker-order.mjs, which writes it.
+ * worker.json in the run folder is the only connection between the two halves after the split.
+ * worker-order.mjs writes it and owns its shape and the reason for every field.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -15,22 +14,21 @@ import {
   writeStatus,
   markAbandoned,
   abandonedBranchDrift,
-  chainRuns,
-  startedRuns,
-  taskFingerprint,
-  readJson,
 } from '../write-meta.mjs';
-import { attach } from './attach.mjs';
+import { TASK_HASH_SCHEME } from '../meta/chain.mjs';
+import { orderInputName } from '../order-schema.mjs';
+import { EXIT } from './exit-codes.mjs';
+import { passGate } from './pass-gate.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 { advisorTaskOrRefuse, adviseSection } from './advise-carry.mjs';
+import { questionsFromTexts, QUESTION_KIND } from './question-kind.mjs';
+import { adviseSection } from './advise-carry.mjs';
 import { schemaFor } from './schemas.mjs';
 import { INSTRUCTIONS } from './prompts.mjs';
-import { git, headSha, branchName, worktreeSnapshot, reviewScope } from './git-state.mjs';
+import { git, branchName, worktreeSnapshot, reviewScope } from './git-state.mjs';
+import { writeBuildBefore } from './build-evidence.mjs';
 import { agentRole } from '../agents.mjs';
 import { codexArgs, runProfile } from './codex-args.mjs';
 import { writeWorkerOrder } from './worker-order.mjs';
@@ -41,15 +39,16 @@ import { cleanupRetention } from '../retention.mjs';
 import { renderConventions } from './conventions.mjs';
 import { validateScope } from './scope-check.mjs';
 import { probeSandbox, sandboxRefusal } from './sandbox-probe.mjs';
-import { preflightRefusal, resolveRunPhase, scopeRunRefusal, taskPreflight } from './preflight.mjs';
+import { acquireOrderClaim, orderClaimBusyText, unclaimedRaceRefusal } from './order-claim.mjs';
+import {
+  codexAvailabilityRefusal, preflightRefusal, resolveRunPhase, taskPreflight,
+} from './preflight.mjs';
 
 /**
  * The worker is this same program re-invoked as `--worker <runDir>`, so the path spawned
  * 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 }));
 
 const stamp = () => {
   const d = new Date();
@@ -87,308 +86,269 @@ export const runDirPath = (root, slug, runStamp = stamp()) => {
 
 /**
  * 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
+ * refusal that costs nothing: bad arguments, an open chain without a `continue:` grant, a busy
  * worktree, a dead Codex sandbox, a missing Codex CLI. All 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(argv = process.argv.slice(2)) {
   loadRunEnv();
   const opts = parseArgs(argv);
+  const { task: taskText, header } = settleTaskInput(opts);
   opts.phase = resolveRunPhase(opts, RUN_ENV.budgets);
-  const taskText = settleTaskInput(opts);
   // Plan_59 D5/D6: blind choices and design authority must be checked before the paid probe.
-  const taskGate = taskPreflight({ agent: opts.agent, taskText });
-  if (taskGate.refusal) die(taskGate.refusal, 1);
+  const taskGate = taskPreflight({ agent: opts.agent, taskText, header });
+  if (taskGate.refusal) die(taskGate.refusal, EXIT.FAIL);
   const topLevel = git(opts.repo, ['rev-parse', '--show-toplevel']);
   const isGitRepo = topLevel.status === 0;
   const repoRoot = isGitRepo ? topLevel.stdout.trim() : opts.repo;
   // Plan_27 moved impossible scope failures ahead of the run directory: an absolute pattern had
   // already cost 18 minutes before the verdict could prove it matched nothing.
-  // Every agent, not only the writing one: a pattern that cannot match gives a scout empty coverage
-  // instead of an answer. Only codex-build may declare a not-yet-existing path, so only its scope
-  // carries --scope-new; for the other two the list is empty and every pattern must match.
+  // Plan_63 D6: only codex-build's header accepts `scope:` and `scope new:`; for the other agents both
+  // lists are empty and the check passes. Only paths named in `scope new:` may be absent.
   const scopeRefusal = validateScope(repoRoot, opts.scopePatterns, opts.scopeNewPatterns);
   if (scopeRefusal) {
     die(
-      `--scope pattern ${JSON.stringify(scopeRefusal.pattern)} refused: ${scopeRefusal.reason}. ` +
+      `${orderInputName(scopeRefusal.label)} pattern ${JSON.stringify(scopeRefusal.pattern)} refused: ` +
+        `${scopeRefusal.reason}. ` +
         `Action: ${scopeRefusal.action}. The run folder was not created; quota was not spent.`,
     );
   }
   const projectRunsRoot = resolveProjectRunsDir(runsRoot(), repoRoot).dir;
+  // Plan_60 D4c, 2026-09-24: two launchers of one order both billed. The claim comes before markAbandoned, or a
+  // contender could close a run whose worker is admitting itself and start a second paid one.
+  const claim = await acquireOrderClaim({ projectRunsRoot, orderId: opts.orderId, role: 'launcher' });
+  if (claim.busy) die(orderClaimBusyText(opts.orderId, claim.holder), EXIT.FAIL);
+  try {
+    // Folders left behind by a runner that was killed mid-run get an explicit state before
+    // anything else happens. One order produced four of them, and without this pass an
+    // abandoned folder is indistinguishable from a run still working: neither has meta.json.
+    // The snapshot is passed in because meta/ makes no git calls of its own: it is the only way an
+    // abandoned run can be closed with the files it left behind rather than with a bare label.
+    markAbandoned(projectRunsRoot, isGitRepo ? worktreeSnapshot(repoRoot) : undefined);
 
-  // Folders left behind by a runner that was killed mid-run get an explicit state before
-  // anything else happens. One order produced four of them, and without this pass an
-  // abandoned folder is indistinguishable from a run still working: neither has meta.json.
-  // The snapshot is passed in because meta/ makes no git calls of its own: it is the only way an
-  // abandoned run can be closed with the files it left behind rather than with a bare label.
-  markAbandoned(projectRunsRoot, isGitRepo ? worktreeSnapshot(repoRoot) : undefined);
-
-  if (isGitRepo) {
-    const drift = abandonedBranchDrift(projectRunsRoot, repoRoot, branchName(repoRoot));
-    if (drift) {
-      die(
-        `repository is detached after abandoned run ${drift.run}, which recorded branch ${drift.branch}. ` +
-          `Return with: git checkout ${drift.branch}. No run folder was created and no quota was spent.`,
-      );
+    if (isGitRepo) {
+      const drift = abandonedBranchDrift(projectRunsRoot, repoRoot, branchName(repoRoot));
+      if (drift) {
+        die(
+          `repository is detached after abandoned run ${drift.run}, which recorded branch ${drift.branch}. ` +
+            `Return with: git checkout ${drift.branch}. No run folder was created and no quota was spent.`,
+        );
+      }
     }
-  }
 
-  // A second pass at the same task is a real need — after a timeout or a LIMIT the work has
-  // to be finished — so it is allowed and made visible rather than forbidden. What is
-  // forbidden is repeating by accident: the orchestrator saw the previous reply, the runner
-  // did not, so only the orchestrator can decide there is something left to finish.
-  //
-  // The task is identified by its text as well as by its slug, because the slug is chosen by
-  // whoever repeats the run: on 2026-08-02 a dispatcher whose launcher was killed restarted
-  // the identical order as `<slug>-v2` and spent 46k on it. Refused before the folder exists,
-  // like --scope.
-  const taskHash = taskFingerprint(taskText);
-  const chain = chainRuns(projectRunsRoot, repoRoot, opts.slug, taskHash, opts.orderId);
-  const startedChain = startedRuns(projectRunsRoot, chain);
-  const continuationGrant = parseContinuationGrant(taskText);
-  const attachExistingRun = () => attach({
-    runsRoot: projectRunsRoot, repo: repoRoot, slug: opts.slug, taskHash, orderId: opts.orderId, chain,
-    grantRun: continuationGrant?.run, isContinue: opts.continue, noWait: opts.noWait,
-  });
-  let attachedExitCode = opts.continue ? await attachExistingRun() : null;
-  if (attachedExitCode !== null) return attachedExitCode;
+    // The pass gate lives in pass-gate.mjs, Plan_75 P0.
+    const gate = await passGate({ opts, taskText, header, projectRunsRoot, repoRoot, beforeWait: claim.release });
+    if ('exitCode' in gate) return gate.exitCode;
+    const { taskHash, chain, startedChain, continuationGrant, advisorTask, retryOf } = gate;
 
-  // The 2026-08-10_220535_plan25-2-install-table-two-roots incident exposed this ordering:
-  // a grant without its flag must refuse before attach can print an older run's verdict.
-  // markAbandoned() ran before this gate, so a dead runner already has meta.json with FAIL.
-  // A run without a verdict can therefore only still be in flight; ordinary repeats go through
-  // attach() after this gate. Repeated --continue calls attach first because their grant is spent.
-  const continuationError = continuationRefusal(
-    projectRunsRoot,
-    startedChain,
-    opts.continue,
-    opts.orderId,
-    continuationGrant,
-  );
-  if (continuationError) die(continuationError);
-  // Plan_59 D14: the grant is valid by now; an advise pass may continue only an OK scope run.
-  const scopeRun = continuationGrant &&
-    scopeRunRefusal({ agent: opts.agent, phase: opts.phase, runsRoot: projectRunsRoot, grantRun: continuationGrant.run });
-  if (scopeRun) die(scopeRun, 1);
-  // Plan_59 D22: the advise snapshot is read before the folder exists, so a broken scope result refuses for free.
-  const advisorTask = opts.agent === 'codex-advisor' ? advisorTaskOrRefuse({ taskText, phase: opts.phase, runsRoot: projectRunsRoot, grantRun: continuationGrant?.run }) : null;
+    // Plan_60 D2: a missing or signed-out Codex answers UNAVAILABLE (exit 5) before the paid sandbox probe.
+    const availability = await codexAvailabilityRefusal();
+    if (availability?.unavailable) { process.stdout.write(`${availability.text}\n`); return EXIT.UNAVAILABLE; }
+    if (availability) die(availability.text, EXIT.FAIL);
+    // Review 2026-09-17: probe before the busy check so it sees writers that registered while the slow
+    // probe waited; the dead refusal stays before retention to preserve old run artifacts.
+    const sandboxProbe = await probeSandbox({ agent: opts.agent, repo: repoRoot });
+    if (sandboxProbe.outcome === 'dead') die(sandboxRefusal(sandboxProbe));
 
-  // One order produced six Codex runs on 2026-08-03 because the caller's time ceiling made it
-  // restart the synchronous launcher. A live same-order run is now the repeat target: attach
-  // before creating a folder, probing Codex or spending another token.
-  if (!opts.continue) attachedExitCode = await attachExistingRun();
-  if (attachedExitCode !== null) return attachedExitCode;
+    // Everything that can refuse without touching the tree is asked here, after the probe so the
+    // busy check sees writers that registered while it waited, and before makeRunDir below: on
+    // 2026-09-19 a busy refusal left its folder inside ~/.claude and the live run's witness spent
+    // every tool call demanding the orchestrator revert a directory the tool itself had created.
+    // Exit 1, not the usage code 2: the order was correct, the host or the tree was not.
+    const preflightError = preflightRefusal({ agent: opts.agent, projectRunsRoot, repoRoot });
+    if (preflightError) die(preflightError, EXIT.FAIL);
 
-  if (startedChain.length && !opts.continue) {
-    const last = startedChain[startedChain.length - 1];
-    const lastSlug = String(readJson(path.join(projectRunsRoot, last, 'status.json'))?.slug || '');
-    const renamed = lastSlug && lastSlug.toLowerCase() !== String(opts.slug).toLowerCase();
-    die(
-      `--continue is required: ${
-        renamed
-          ? `this task already ran in this repository under the name “${lastSlug}”`
-          : `runs for task “${opts.slug}” already exist in this repository`
-      } (${startedChain.length}), latest: ${path.join(projectRunsRoot, last)}. ` +
-        'A repeat run is allowed, but the orchestrator decides, not the runner: it read the ' +
-        'previous response and knows whether work remains. Add --continue if you are finishing ' +
-        'the same task; changing --slug with the same task text does not stop it being a repeat. ' +
-        'The run folder was not created; quota was not spent.',
-    );
-  }
+    let retention = null;
+    try {
+      retention = cleanupRetention(projectRunsRoot, RUN_ENV?.retention);
+    } catch {
+      // Plan_17 step 4 makes retention advisory housekeeping: one broken filesystem call must never
+      // block a new run.
+      retention = null;
+    }
+
+    if (claim.unsupported) {
+      const text = unclaimedRaceRefusal({
+        projectRunsRoot, repoRoot, slug: opts.slug, taskHash, orderId: opts.orderId,
+        grantRun: header.grant?.run, chainBefore: chain,
+      });
+      if (text) die(text, EXIT.FAIL);
+    }
+    const runDir = makeRunDir(runDirPath(projectRunsRoot, opts.slug));
+    setRun(runDir, opts.agent);
 
-  // Review 2026-09-17: the slow probe widened the window between the busy check and registration.
-  // Probe first so the busy check sees writers that registered while it waited.
-  // Keep dead refusal before retention to preserve old run artifacts.
-  const sandboxProbe = await probeSandbox({ agent: opts.agent, repo: repoRoot });
-  if (sandboxProbe.outcome === 'dead') die(sandboxRefusal(sandboxProbe));
+    // Written before the worker can start. From here on a killed runner leaves a folder that
+    // says what it was and whose pid to check, instead of a folder that says nothing — the run
+    // itself takes 20-25 minutes, far longer than the caller's default timeout, so being killed
+    // mid-run is the normal way for this to end, not the exotic one.
+    //
+    // `pid` is the launcher's only until the worker exists, and the worker's from then on:
+    // activeRun(), markAbandoned() and the reply guard all read `pid` as "the process whose
+    // death means this run is abandoned", and after the spawn that process is the worker.
+    writeStatus(runDir, {
+      state: 'running',
+      pid: process.pid,
+      launcher_pid: process.pid,
+      process_started_at: performance.timeOrigin,
+      agent: opts.agent,
+      slug: opts.slug,
+      order_id: opts.orderId,
+      phase: opts.phase,
+      ...(taskGate.advice === undefined ? {} : { advice: taskGate.advice }),
+      // Fingerprint of the order, so a later run of the same task finds this one whatever it
+      // calls itself. Written here, before Codex starts, like everything the chain reads.
+      task_hash: taskHash,
+      task_hash_scheme: TASK_HASH_SCHEME,
+      repo: repoRoot,
+      started_at: new Date().toISOString(),
+      // Which run of this task started the chain — the base every later pass is measured
+      // against. Absent means this is the first pass.
+      ...(startedChain.length ? { continues: startedChain[0] } : {}),
+      // `continued_from` is the exact run the orchestrator named; `continues` above remains the chain base.
+      ...(continuationGrant ? { continued_from: continuationGrant.run } : {}),
+      // Plan_75: the repeated failed run; pass accounting skips runs carrying it.
+      ...(retryOf ? { retry_of: retryOf } : {}),
+      ...(retention ? { retention } : {}),
+      sandbox_probe: sandboxProbe,
+    });
 
-  // Everything that can refuse without touching the tree is asked here, after the probe so the
-  // busy check sees writers that registered while it waited, and before makeRunDir below: on
-  // 2026-09-19 a busy refusal left its folder inside ~/.claude and the live run's witness spent
-  // every tool call demanding the orchestrator revert a directory the tool itself had created.
-  // Exit 1, not the usage code 2: the order was correct, the host or the tree was not.
-  const preflightError = preflightRefusal({ agent: opts.agent, projectRunsRoot, repoRoot });
-  if (preflightError) die(preflightError, 1);
+    // 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} order-id=${opts.orderId}`);
 
-  let retention = null;
-  try {
-    retention = cleanupRetention(projectRunsRoot, RUN_ENV?.retention);
-  } catch {
-    // Plan_17 step 4 makes retention advisory housekeeping: one broken filesystem call must never
-    // block a new run.
-    retention = null;
-  }
+    const scope = opts.agent === 'codex-review' ? reviewScope(repoRoot, opts.changeset) : null;
+    if (scope) {
+      fs.writeFileSync(
+        path.join(runDir, 'scope.txt'),
+        `${scope.label}\n${scope.diffCommand}\n${scope.files.join('\n')}\n`,
+      );
+    }
 
-  const runDir = makeRunDir(runDirPath(projectRunsRoot, opts.slug));
-  setRun(runDir, opts.agent);
+    // The sub-questions this run will be graded against come only from the task document's
+    // `Questions` section. They are written before the task is assembled so the prompt and verdict
+    // read the same ordered list, including a valid one-question order.
+    const questions = opts.agent === 'codex-scout' ? questionsFromTexts(opts.questions) : [];
+    if (opts.agent === 'codex-scout') {
+      fs.writeFileSync(path.join(runDir, 'questions.json'), `${JSON.stringify(questions, null, 2)}\n`);
+    }
+    if (advisorTask) {
+      fs.writeFileSync(path.join(runDir, 'advisor-task.json'), `${JSON.stringify(advisorTask, null, 2)}\n`);
+    }
 
-  // Written before the worker can start. From here on a killed runner leaves a folder that
-  // says what it was and whose pid to check, instead of a folder that says nothing — the run
-  // itself takes 20-25 minutes, far longer than the caller's default timeout, so being killed
-  // mid-run is the normal way for this to end, not the exotic one.
-  //
-  // `pid` is the launcher's only until the worker exists, and the worker's from then on:
-  // activeRun(), markAbandoned() and the reply guard all read `pid` as "the process whose
-  // death means this run is abandoned", and after the spawn that process is the worker.
-  writeStatus(runDir, {
-    state: 'running',
-    pid: process.pid,
-    launcher_pid: process.pid,
-    process_started_at: performance.timeOrigin,
-    agent: opts.agent,
-    slug: opts.slug,
-    order_id: opts.orderId,
-    phase: opts.phase,
-    ...(taskGate.advice === undefined ? {} : { advice: taskGate.advice }),
-    // Fingerprint of the order, so a later run of the same task finds this one whatever it
-    // calls itself. Written here, before Codex starts, like everything the chain reads.
-    task_hash: taskHash,
-    repo: repoRoot,
-    started_at: new Date().toISOString(),
-    // Which run of this task started the chain — the base every later pass is measured
-    // against. Absent means this is the first pass.
-    ...(startedChain.length ? { continues: startedChain[0] } : {}),
-    // `continued_from` is the exact run the orchestrator named; `continues` above remains the chain base.
-    ...(continuationGrant ? { continued_from: continuationGrant.run } : {}),
-    ...(retention ? { retention } : {}),
-    sandbox_probe: sandboxProbe,
-  });
+    if (opts.agent === 'codex-build') {
+      fs.writeFileSync(path.join(runDir, 'scope.txt'), `${opts.scopePatterns.join('\n')}\n`);
+    }
 
-  // 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} order-id=${opts.orderId}`);
+    // Which environment this run actually got. Without it a replay months later cannot tell
+    // whether the operator's hooks were in play, and that is the first question a run that
+    // wandered off task raises.
+    fs.writeFileSync(path.join(runDir, 'env.json'), `${JSON.stringify(RUN_ENV, null, 2)}\n`);
 
-  const scope = opts.agent === 'codex-review' ? reviewScope(repoRoot, opts.changeset) : null;
-  if (scope) {
+    // The extra sections carry the two things prose could not enforce: what has to be answered,
+    // and what may be edited. Both also go to disk as questions.json / scope.txt, so the verdict
+    // is computed from the same list Codex was handed, not from a second reading of the wording.
+    const sections = [`## Operator task (verbatim)\n\n${taskText}`];
+    const scopeResults = adviseSection(advisorTask);
+    if (scopeResults) sections.push(scopeResults);
+    if (questions.length) {
+      sections.push(
+        [
+          '## Sub-questions, each requires a separate response',
+          '',
+          questions.map((q) =>
+            `${q.id}${q.kind === QUESTION_KIND.STARTUP_CONTEXT ? ' [context-only]' : ''}: ${q.text}`).join('\n'),
+          '',
+          'A missed sub-question fails the run; a response containing only coordinates counts as missed.',
+        ].join('\n'),
+      );
+    }
+    if (opts.agent === 'codex-build') {
+      sections.push(
+        [
+          '## Scope (hard boundary)',
+          '',
+          'Only these may be changed:',
+          opts.scopePatterns.map((p) => `- ${p}`).join('\n'),
+          '',
+          'Do not touch any file outside this list — even if it blocks the work or looks broken.',
+          'Put the obstacle in leftovers instead of changing the file. The touched worktree is',
+          'checked against this list after the run.',
+        ].join('\n'),
+      );
+    }
+    const conventions = renderConventions(repoRoot);
+    if (conventions) sections.push(conventions);
+    sections.push(`## Instructions for Codex\n\n${INSTRUCTIONS[opts.agent](opts, scope, questions)}`);
+    fs.writeFileSync(path.join(runDir, 'task.md'), `${sections.join('\n\n')}\n`);
     fs.writeFileSync(
-      path.join(runDir, 'scope.txt'),
-      `${scope.label}\n${scope.diffCommand}\n${scope.files.join('\n')}\n`,
+      path.join(runDir, 'schema.json'),
+      `${JSON.stringify(schemaFor(opts.agent, opts.phase), null, 2)}\n`,
     );
-  }
 
-  // The sub-questions this run will be graded against come only from the orchestrator's
-  // repeatable flags. They are written before the task is assembled so the prompt and verdict
-  // read the same ordered list, including a valid one-question order.
-  const questions = opts.agent === 'codex-scout' ? questionsFromFlags(opts.questions) : [];
-  if (opts.agent === 'codex-scout') {
-    fs.writeFileSync(path.join(runDir, 'questions.json'), `${JSON.stringify(questions, null, 2)}\n`);
-  }
-  if (advisorTask) fs.writeFileSync(path.join(runDir, 'advisor-task.json'), `${JSON.stringify(advisorTask, null, 2)}\n`);
+    if (opts.agent === 'codex-build') writeBuildBefore({ runDir, repoRoot, isGitRepo });
 
-  if (opts.agent === 'codex-build') {
-    fs.writeFileSync(path.join(runDir, 'scope.txt'), `${opts.scopePatterns.join('\n')}\n`);
-  }
+    // The worker's entire order, on disk. Not passed as arguments: the launcher may be gone
+    // when the worker needs to know what it is doing, and a folder that explains itself is
+    // also the only way to read a run back months later.
+    const codexArgv = codexArgs({ ...opts, repo: repoRoot }, runDir, isGitRepo);
+    const unsafe = process.platform === 'win32' ? unsafeForCmd(codexArgv) : undefined;
+    if (unsafe) {
+      const { reply } = writeFailure(
+        runDir,
+        opts.agent,
+        `argument cannot be passed through cmd.exe (contains % or "): ${unsafe}`,
+        ['Codex was not started; quota was not spent'],
+        true,
+      );
+      console.log(reply);
+      return EXIT.FAIL;
+    }
+    writeWorkerOrder(runDir, {
+      agent: opts.agent,
+      slug: opts.slug,
+      orderId: opts.orderId,
+      repo: repoRoot,
+      isGitRepo,
+      launcherPid: process.pid,
+      phase: opts.phase,
+      budgetMinutes: RUN_ENV.budgets[agentRole(opts.agent)][opts.phase],
+      scopeNew: opts.scopeNewPatterns,
+      profile: runProfile({ ...opts, repo: repoRoot }),
+      args: codexArgv,
+    });
 
-  // Which environment this run actually got. Without it a replay months later cannot tell
-  // whether the operator's hooks were in play, and that is the first question a run that
-  // wandered off task raises.
-  fs.writeFileSync(path.join(runDir, 'env.json'), `${JSON.stringify(RUN_ENV, null, 2)}\n`);
+    // detached + unref + no stdio: the worker leaves the caller's process group, so a Ctrl+C
+    // or a timeout kill aimed at the dispatcher's shell does not reach it, and it holds no
+    // pipe that could fill up and stall once nobody is reading.
+    const worker = spawn(process.execPath, [RUNNER_ENTRY, '--worker', runDir], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      cwd: repoRoot,
+    });
+    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 EXIT.FAIL;
+    worker.unref();
+    writeStatus(runDir, { pid: worker.pid, runner_pid: worker.pid, process_started_at: null });
 
-  // The extra sections carry the two things prose could not enforce: what has to be answered,
-  // and what may be edited. Both also go to disk as questions.json / scope.txt, so the verdict
-  // is computed from the same list Codex was handed, not from a second reading of the wording.
-  const sections = [`## Operator task (verbatim)\n\n${taskText}`];
-  const scopeResults = adviseSection(advisorTask);
-  if (scopeResults) sections.push(scopeResults);
-  if (questions.length) {
-    sections.push(
-      [
-        '## Sub-questions, each requires a separate response',
-        '',
-        questions.map((q) => `${q.id}: ${q.text}`).join('\n'),
-        '',
-        'A missed sub-question fails the run; a response containing only coordinates counts as missed.',
-      ].join('\n'),
+    console.log(
+      `STARTED agent=${opts.agent} slug=${opts.slug} order-id=${opts.orderId} worker-pid=${worker.pid}`,
     );
-  }
-  if (opts.agent === 'codex-build') {
-    sections.push(
-      [
-        '## Scope (hard boundary)',
-        '',
-        'Only these may be changed:',
-        opts.scopePatterns.map((p) => `- ${p}`).join('\n'),
-        '',
-        'Do not touch any file outside this list — even if it blocks the work or looks broken.',
-        'Put the obstacle in leftovers instead of changing the file. The touched worktree is',
-        'checked against this list after the run.',
-      ].join('\n'),
-    );
-  }
-  const conventions = renderConventions(repoRoot);
-  if (conventions) sections.push(conventions);
-  sections.push(`## Instructions for Codex\n\n${INSTRUCTIONS[opts.agent](opts, scope, questions)}`);
-  fs.writeFileSync(path.join(runDir, 'task.md'), `${sections.join('\n\n')}\n`);
-  fs.writeFileSync(
-    path.join(runDir, 'schema.json'),
-    `${JSON.stringify(schemaFor(opts.agent, opts.phase), null, 2)}\n`,
-  );
-
-  if (opts.agent === 'codex-build') {
-    fs.writeFileSync(path.join(runDir, 'head-before.txt'), `${isGitRepo ? headSha(repoRoot) : ''}\n`);
-    fs.writeFileSync(path.join(runDir, 'branch-before.txt'), `${isGitRepo ? branchName(repoRoot) : ''}\n`);
-    fs.writeFileSync(path.join(runDir, 'git-before.txt'), git(repoRoot, ['-c', 'core.quotepath=false', 'status', '--porcelain']).stdout || '');
-    fs.writeFileSync(path.join(runDir, 'state-before.txt'), worktreeSnapshot(repoRoot));
-  }
-
-  // The worker's entire order, on disk. Not passed as arguments: the launcher may be gone
-  // when the worker needs to know what it is doing, and a folder that explains itself is
-  // also the only way to read a run back months later.
-  const codexArgv = codexArgs({ ...opts, repo: repoRoot }, runDir, isGitRepo);
-  const unsafe = process.platform === 'win32' ? unsafeForCmd(codexArgv) : undefined;
-  if (unsafe) {
-    const { reply } = writeFailure(
-      runDir,
-      opts.agent,
-      `argument cannot be passed through cmd.exe (contains % or "): ${unsafe}`,
-      ['Codex was not started; quota was not spent'],
-      true,
+    console.log(
+      `To get the verdict, repeat the identical command with the same ${orderInputName('order id')}; it will attach to this run and will not start a second run.`,
     );
-    console.log(reply);
-    return 1;
+    return EXIT.OK;
+  } finally {
+    // Plan_60 D4c: release on refusals too; a registered worker must be able to claim admission.
+    await claim.release();
   }
-  writeWorkerOrder(runDir, {
-    agent: opts.agent,
-    slug: opts.slug,
-    orderId: opts.orderId,
-    repo: repoRoot,
-    isGitRepo,
-    launcherPid: process.pid,
-    phase: opts.phase,
-    budgetMinutes: RUN_ENV.budgets[agentRole(opts.agent)][opts.phase],
-    scopeNew: opts.scopeNewPatterns,
-    profile: runProfile({ ...opts, repo: repoRoot }),
-    args: codexArgv,
-  });
-
-  // detached + unref + no stdio: the worker leaves the caller's process group, so a Ctrl+C
-  // or a timeout kill aimed at the dispatcher's shell does not reach it, and it holds no
-  // pipe that could fill up and stall once nobody is reading.
-  const worker = spawn(process.execPath, [RUNNER_ENTRY, '--worker', runDir], {
-    detached: true,
-    stdio: 'ignore',
-    windowsHide: true,
-    cwd: repoRoot,
-  });
-  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 });
-
-  console.log(
-    `STARTED agent=${opts.agent} slug=${opts.slug} order-id=${opts.orderId} worker-pid=${worker.pid}`,
-  );
-  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.',
-  );
-  return 0;
 }