@lyupro/codex-bridge 0.6.9 → 0.6.11

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

@@ -0,0 +1,84 @@
+/**
+ * Holds one kernel claim per project run store and exact order id during preparation.
+ * Plan_60 D4/D4c: on 2026-09-24 two launchers started 2.8 seconds apart with one order id
+ * and both ran and billed; a kernel-held claim queues preparation and dies with its holder.
+ */
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import {
+  acquireKernelLock, directoryDigest, kernelLockAddress, kernelLockStrategy,
+} from '../kernel-lock.mjs';
+import { parseJsonText } from '../json-file.mjs';
+import { chainRuns, readJson } from '../write-meta.mjs';
+
+// Plan_60 D4/D4c: preparation takes seconds; expiry must refuse rather than permit double billing.
+export const ORDER_CLAIM_TIMING = Object.freeze({ waitMs: 60_000, retryMs: 100, answerTimeoutMs: 1_000 });
+
+export function orderClaimAddress(projectRunsRoot, orderId, platform = process.platform) {
+  if (typeof orderId !== 'string' || orderId.length === 0) {
+    throw new TypeError('orderId must be a non-empty string');
+  }
+  // Plan_60 A4 r5: owner matching is case-sensitive; retries must retain the exact order id.
+  const digest = directoryDigest(projectRunsRoot, { suffix: orderId });
+  if (digest === null) throw new Error(`project runs folder does not exist: ${projectRunsRoot}`);
+  if (kernelLockStrategy(platform) === null) return null;
+  return kernelLockAddress('order', digest, platform);
+}
+
+export async function acquireOrderClaim({
+  projectRunsRoot, orderId, role, platform = process.platform,
+  timing = ORDER_CLAIM_TIMING, createServer,
+}) {
+  if (role !== 'launcher' && role !== 'worker') {
+    throw new TypeError('role must be launcher or worker');
+  }
+  const address = orderClaimAddress(projectRunsRoot, orderId, platform);
+  if (address === null) return { claimed: false, unsupported: true, release: async () => {} };
+  const holder = { pid: process.pid, role, orderId, token: randomUUID() };
+  const result = await acquireKernelLock({
+    address, holder, ...timing, parseAnswer: parseClaimHolder, label: 'order claim', createServer,
+  });
+  if (result.held) return { claimed: true, release: result.release };
+  return { claimed: false, busy: true, holder: result.holder };
+}
+
+export function parseClaimHolder(line) {
+  try {
+    const holder = parseJsonText('<order claim holder>', line);
+    if (holder === null || typeof holder !== 'object') return null;
+    if (!Number.isInteger(holder.pid) || holder.pid <= 0) return null;
+    if (holder.role !== 'launcher' && holder.role !== 'worker') return null;
+    for (const key of ['orderId', 'token', 'acquiredAt']) {
+      if (typeof holder[key] !== 'string' || holder[key].length === 0) return null;
+    }
+    return holder;
+  } catch {
+    return null;
+  }
+}
+
+// Plan_60 D4/D4c: a holder answer diagnoses contention but cannot authorize anything.
+export function orderClaimHolderText(holder) {
+  return holder === null
+    ? 'a process that did not answer (unverified)'
+    : `${holder.role} pid ${holder.pid} since ${holder.acquiredAt}`;
+}
+
+export function orderClaimBusyText(orderId, holder) {
+  return `order id "${orderId}" is being launched by ${orderClaimHolderText(holder)}; repeat the same command later — `
+    + 'it attaches to that run instead of starting another. The run folder was not created; quota was not spent.';
+}
+
+/**
+ * Plan_60 D4, 2026-09-24: macOS has no kernel claim, so re-read just before registration.
+ * This shrinks the double-billing window to milliseconds and never waits on another launch.
+ */
+export function unclaimedRaceRefusal({ projectRunsRoot, repoRoot, slug, taskHash, orderId, grantRun, chainBefore }) {
+  const chain = chainRuns(projectRunsRoot, repoRoot, slug, taskHash, orderId, grantRun);
+  const before = new Set(chainBefore);
+  const appeared = chain.find((run) => !before.has(run)
+    && readJson(path.join(projectRunsRoot, run, 'status.json'))?.order_id === orderId);
+  if (!appeared) return null;
+  return `another launch of order id "${orderId}" registered ${appeared} while this one was preparing; `
+    + 'repeat the same command — it attaches to that run. The run folder was not created; quota was not spent.';
+}

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

@@ -0,0 +1,30 @@
+/** Normalises one order's values into runner options, whatever channel carried them (Plan_63 D5). */
+import path from 'node:path';
+
+export function orderOptions(agentType, order, { cwd = process.cwd() } = {}) {
+  const options = { orderId: (order.get('order id') ?? '').trim() };
+  const problems = [];
+  // Left unset when absent: the role's configured profile fills the gap, and a default here would always win.
+  // Plan_56 step 3 leaves effort support to the live catalogue and Codex at run start.
+  if (order.has('effort')) {
+    options.effort = order.get('effort');
+    if (!options.effort || /\s/.test(options.effort)) {
+      problems.push({ label: 'effort',
+        reason: `must be a non-empty single word with no whitespace; got ${JSON.stringify(options.effort)}` });
+    }
+  }
+  options.repo = path.resolve(order.get('repository') || cwd);
+  options.slug = (order.get('slug') || options.orderId).replace(/[^A-Za-z0-9._-]+/g, '-');
+  // Plan_29 incident: a generic slug let an honest order inherit a days-old chain.
+  if (!/[A-Za-z0-9]/.test(options.slug)) {
+    problems.push({ label: order.has('slug') ? 'slug' : 'order id',
+      reason: `produces an unusable run folder name after sanitization: ${JSON.stringify(options.slug)} must contain a letter or digit.` });
+  }
+  options.changeset = order.get('changeset') || 'uncommitted';
+  const declaredScopePatterns = (order.get('scope') || '').split(',').map((p) => p.trim()).filter(Boolean);
+  options.scopeNewPatterns = (order.get('scope new') || '').split(',').map((p) => p.trim()).filter(Boolean);
+  // Plan_27 keeps ordinary patterns strict: only paths named explicitly as new may be absent.
+  options.scopePatterns = [...declaredScopePatterns, ...options.scopeNewPatterns];
+  if (order.has('phase')) options.phase = order.get('phase');
+  return { options, problems };
+}

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

@@ -1,4 +1,6 @@
 /** Keeps the runner and producer hook on one definition of which task owns an order id. */
+import { TASK_HASH_SCHEME } from '../meta/chain.mjs';
+import { orderInputName } from '../order-schema.mjs';
 
 const byStartThenName = (left, right) => {
   const leftAt = String(left.status.started_at || '');
@@ -26,3 +28,20 @@ export function conflictingOrderOwner(runs, orderId, taskHash) {
   const incomingHash = String(taskHash ?? '').trim().toLowerCase();
   return ownerHash && incomingHash && ownerHash !== incomingHash ? owner : null;
 }
+
+export function ownerPredatesHashScheme(owner) {
+  return owner.status.task_hash_scheme !== TASK_HASH_SCHEME;
+}
+
+export function orderOwnerConflictText(owner, ownerDir, orderId) {
+  const identity = `Order id collision: ${JSON.stringify(String(orderId ?? ''))} already belongs to run folder ${ownerDir} ` +
+    `(slug ${owner.status.slug}, started_at ${owner.status.started_at})`;
+  // Plan_75 D5, 2026-10-03: an old hash cannot prove that a repeated order is a different task.
+  if (ownerPredatesHashScheme(owner)) {
+    return `${identity}, recorded before the task header (hash scheme ${TASK_HASH_SCHEME}), so its task cannot be compared. ` +
+      `Its answer is already on disk in that folder (codex-bridge read "${ownerDir}"). ` +
+      'Another pass of that order needs a continue:/retry: header line; a new task needs a new order id.';
+  }
+  return `${identity} with a different task. Use a new order id (${orderInputName('order id')}), or a continue:/retry: header line ` +
+    'if this is another pass of that order.';
+}

package/src/home/lib/runner/pass-gate.mjs

@@ -0,0 +1,111 @@
+/**
+ * Decides, before anything is registered, whether a call attaches to an existing run of its order,
+ * is a granted continuation, or is a refused repeat.
+ *
+ * Moved out of launcher.mjs unchanged (Plan_75 P0): the launcher sat at the 400-line gate, and the
+ * 2026-10-03 TradeForge advise that died on model capacity showed this gate needs a retry path.
+ * It is handed no run directory, so like preflight.mjs it cannot leave a folder behind a refusal.
+ */
+import path from 'node:path';
+import { chainRuns, startedRuns, taskFingerprint, readJson } from '../write-meta.mjs';
+import { die } from './args.mjs';
+import { EXIT } from './exit-codes.mjs';
+import { attach } from './attach.mjs';
+import { continuationRefusal, retryRefusal, readyGrantLines } from './continuation.mjs';
+import { advisorTaskOrRefuse } from './advise-carry.mjs';
+import { scopeRunRefusal } from './preflight.mjs';
+import { orderInputName } from '../order-schema.mjs';
+
+export async function passGate({ opts, taskText, header, projectRunsRoot, repoRoot, beforeWait }) {
+  // 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 an impossible scope.
+  const taskHash = taskFingerprint(taskText);
+  const grant = header.grant;
+  // OW-040, 2026-09-30: only a retry repeats failed scope without spending advise's continuation.
+  if (opts.agent === 'codex-advisor' && opts.phase === 'scope' && opts.continue && grant?.kind !== 'retry') {
+    die(`codex-advisor ${orderInputName('phase')} scope refuses ${orderInputName('continue')}: a scope pass is never continued, and continuing one ` +
+      "spends the order's single continuation that its advise phase needs. Action: repeat the scope under a new order id " +
+      `without ${orderInputName('continue')} and without a continue: grant, then run advise as that order's continuation; a ` +
+      'scope run that failed is repeated with a `retry:` grant instead. The run folder was not created; quota was not spent.');
+  }
+  let continuationGrant = grant?.kind === 'continue' ? grant : null;
+  const retryOf = grant?.kind === 'retry' ? grant.run : null;
+  const chain = chainRuns(projectRunsRoot, repoRoot, opts.slug, taskHash, opts.orderId, grant?.run);
+  const startedChain = startedRuns(projectRunsRoot, chain);
+  const attachExistingRun = () => attach({
+    runsRoot: projectRunsRoot, repo: repoRoot, slug: opts.slug, taskHash, orderId: opts.orderId, chain,
+    grantRun: continuationGrant?.run, isContinue: opts.continue, noWait: opts.noWait,
+    retryRun: retryOf ?? undefined, beforeWait,
+  });
+  let attachedExitCode = opts.continue ? await attachExistingRun() : null;
+  if (attachedExitCode !== null) return { exitCode: attachedExitCode };
+
+  // The 2026-08-10_220535_plan25-2-install-table-two-roots incident exposed this ordering: an
+  // invalid grant must refuse before attach can print an older run's verdict (Plan_63 D8: the
+  // grant alone means continuation, so "grant without flag" no longer exists).
+  // 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 continuation calls attach first because their grant is spent.
+  if (grant?.kind === 'retry') {
+    const retryError = retryRefusal(projectRunsRoot, startedChain, opts.continue, opts.orderId, grant);
+    if (retryError) die(retryError);
+    const namedStatus = readJson(path.join(projectRunsRoot, grant.run, 'status.json'));
+    // A run written before phases existed has none; for every agent but the advisor that is 'default'.
+    const phaseOf = (value) => String(value ?? '').trim() || 'default';
+    if (namedStatus.agent !== opts.agent || phaseOf(namedStatus.phase) !== phaseOf(opts.phase)) {
+      die(`a retry repeats the named run's own agent and phase: ${namedStatus.agent}/${namedStatus.phase}. ` +
+        'The run folder was not created; quota was not spent.');
+    }
+    // Plan_75 D4, TradeForge capacity incident: retry advise against its original successful scope.
+    continuationGrant = String(namedStatus.continued_from ?? '').trim()
+      ? { run: namedStatus.continued_from, reason: grant.reason } : null;
+  } else {
+    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, EXIT.FAIL);
+  // 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;
+
+  // 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 { exitCode: attachedExitCode };
+
+  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(
+      `${orderInputName('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 ${orderInputName('continue')} if you are finishing ` +
+        `the same task; changing ${orderInputName('slug')} with the same task text does not stop it being a repeat. ` +
+        `${readyGrantLines(projectRunsRoot, startedChain)} ` +
+        'The run folder was not created; quota was not spent.',
+    );
+  }
+
+  return { taskHash, chain, startedChain, continuationGrant, advisorTask, retryOf };
+}

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

@@ -6,13 +6,30 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { advisorTaskRefusal } from '../meta/advisor-task.mjs';
+import { unavailableRows } from '../meta/reply.mjs';
 import { activeRunDetails, readJson } from '../write-meta.mjs';
-import { codexUnavailableReason } from './codex-cmd.mjs';
+import { probeCodexAvailability } from './codex-availability.mjs';
 import { agentRole } from '../agents.mjs';
 import { die } from './args.mjs';
+import { orderInputName } from '../order-schema.mjs';
+
+/** Plan_60 D2: only conclusive evidence says UNAVAILABLE; an unclear probe stays an ordinary refusal. */
+export async function codexAvailabilityRefusal({ probe = probeCodexAvailability } = {}) {
+  const result = await probe();
+  if (result.state === 'available') return null;
+  const unavailable = result.state === 'missing' || result.state === 'logged-out';
+  const rows = unavailable ? unavailableRows(result.detail) : [
+    `Codex CLI unavailable: ${result.detail}`,
+    'Operator check: codex --version (and codex login if authorization is rejected)',
+  ];
+  return {
+    unavailable,
+    text: [...rows, 'The run folder was not created; quota was not spent.'].join('\n'),
+  };
+}
 
 /** Plan_59 D5/D6: settle design authority before any probe can spend quota. */
-export function taskPreflight({ agent, taskText }) {
+export function taskPreflight({ agent, taskText, header }) {
   const freeRefusal = (reason) => ({
     refusal: `${reason}\nThe run folder was not created; quota was not spent.`,
   });
@@ -21,13 +38,8 @@ export function taskPreflight({ agent, taskText }) {
     return reason ? freeRefusal(reason) : { refusal: null };
   }
   if (agent !== 'codex-build') return { refusal: null };
-  const lines = taskText.split(/\r\n|\n|\r/)
-    .flatMap((line) => {
-      const match = line.match(/^\s*(?:-\s+)?advice\s*:\s*(.*?)\s*$/i);
-      return match ? [match[1]] : [];
-    });
-  const advice = lines[0];
-  if (lines.length === 1) {
+  const advice = header.advice;
+  if (advice !== null) {
     if (['mechanical', 'revert', 'docs-only', 'test-only'].includes(advice)) {
       return { refusal: null, advice };
     }
@@ -44,7 +56,8 @@ export function taskPreflight({ agent, taskText }) {
       }
     }
   }
-  return freeRefusal('codex-build requires exactly one advice: line: mechanical | revert | docs-only | test-only ' +
+  return freeRefusal('codex-build requires the task file to start with the header line `advice: <value>`, where the ' +
+    'value is mechanical | revert | docs-only | test-only ' +
     'or an absolute path to an existing advisor run directory whose meta.json says agent codex-advisor, ' +
     'phase advise, status OK. ' +
     'An order that invents a construction needs a second opinion first; only work with no design choice may skip it.');
@@ -70,24 +83,17 @@ export function scopeRunRefusal({ agent, phase, runsRoot, grantRun }) {
 
 /** D2: phase mistakes must refuse before even the sandbox probe can spend quota. */
 export function resolveRunPhase({ agent, phase, continue: isContinue }, budgets) {
-  // OW-040, 2026-09-30: continuing a failed scope spent the order's only continuation and blocked advise.
-  if (agent === 'codex-advisor' && phase === 'scope' && isContinue) {
-    die('codex-advisor --phase scope refuses --continue: a scope pass is never continued, and continuing one ' +
-      "spends the order's single continuation that its advise phase needs. Action: repeat the scope under a new order id " +
-      "without --continue and without a continue: grant, then run advise as that order's continuation. The run folder " +
-      'was not created; quota was not spent.');
-  }
   // Plan_59 D7: phase 2 must retain the scope run's predictions before quota is spent.
   if (agent === 'codex-advisor' && phase === 'advise' && !isContinue) {
-    die('codex-advisor --phase advise requires --continue: phase 2 continues the scope run of the same order ' +
+    die(`codex-advisor ${orderInputName('phase')} advise requires a ${orderInputName('continue')} grant naming the scope run: phase 2 continues the scope run of the same order ` +
       'so it can settle the risks phase 1 predicted. The run folder was not created; quota was not spent.');
   }
   const phases = budgets[agentRole(agent)];
   const names = Object.keys(phases);
   if (phase === undefined && names.length === 1 && names[0] === 'default') return 'default';
   if (phase !== undefined && Object.hasOwn(phases, phase)) return phase;
-  die(`${phase === undefined ? '--phase is required' : `undeclared --phase ${JSON.stringify(phase)}`} ` +
-    `for ${agent}. Action: pass --phase <name>; allowed phases: ${names.join(', ')}. ` +
+  die(`${phase === undefined ? `${orderInputName('phase')} is required` : `undeclared ${orderInputName('phase')} ${JSON.stringify(phase)}`} ` +
+    `for ${agent}. Action: pass ${orderInputName('phase')} <name>; allowed phases: ${names.join(', ')}. ` +
     'The run folder was not created; quota was not spent.');
 }
 
@@ -107,13 +113,5 @@ export function preflightRefusal({ agent, projectRunsRoot, repoRoot }) {
     ].join('\n');
   }
 
-  const why = codexUnavailableReason();
-  if (why !== null) {
-    return [
-      `Codex CLI unavailable: ${why}`,
-      'Operator check: codex --version (and codex login if authorization is rejected)',
-      'The run folder was not created; quota was not spent.',
-    ].join('\n');
-  }
   return null;
 }

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

@@ -10,6 +10,7 @@
 import { DEFAULTS } from '../run-config.mjs';
 import { RUN_ENV } from './run-env.mjs';
 import { advisorSchema, schemaFor } from './schemas.mjs';
+import { QUESTION_KIND } from './question-kind.mjs';
 
 function boundedArrayRules(schema, path = '') {
   if (schema.type === 'object') {
@@ -93,8 +94,12 @@ ${
     : `- Put one object in answers with question_id "Q1": analysis in answer, references in evidence.
 - The top-level answer is the same response summarized in 2-4 sentences.`
 }
-- Base the response on what you read; support every fact with a \`path:line\` reference in where.
-- If facts are missing, list them in unknowns; do not make them up.
+- Base the response on what you read; support every fact about the code with a \`path:line\` reference in where.
+${questions.some((question) => question?.kind === QUESTION_KIND.STARTUP_CONTEXT)
+    ? `- A sub-question marked [context-only] asks about what this run was handed at startup
+  (task, instructions, schema, environment), not about the repository. Answer it from that context,
+  cite evidence as \`startup:<source>\`, and never cite a repository \`path:line\` you did not read
+  with a command — that fails the run.\n` : ''}- If facts are missing, list them in unknowns; do not make them up.
 - report_markdown is a full markdown report with sections: “Response” (2-4 sentences),
   “How it works” (required: prose analysis ${questions.length ? 'for each sub-question' : 'of the mechanism'},
   grounded in the code), “Findings” (fact / location / confidence table), “Missing information”.`,

package/src/home/lib/runner/question-kind.mjs

@@ -0,0 +1,41 @@
+/**
+ * Classifies orderer-marked scout questions and refuses malformed markers before quota is spent.
+ * Plan_60 D1: only the orderer knows whether a question concerns handed startup context or code;
+ * the scout cannot choose its own kind, and startup context currently fails without a command.
+ */
+export const CONTEXT_ONLY_MARKER = '[context-only]';
+export const QUESTION_KIND = Object.freeze({
+  STARTUP_CONTEXT: 'startup-context',
+  CODE_REQUIRED: 'code-required',
+});
+
+export function questionKindRefusal(texts = []) {
+  for (const [index, text] of texts.entries()) {
+    const tokens = text.matchAll(/\[\s*context[\s_-]*only\s*\]/gi);
+    for (const token of tokens) {
+      if (token.index !== 0 || token[0] !== CONTEXT_ONLY_MARKER) {
+        return `Q${index + 1} has an invalid context-only marker in ${JSON.stringify(text)}`;
+      }
+    }
+    if (text.startsWith(CONTEXT_ONLY_MARKER)) {
+      const question = text.slice(CONTEXT_ONLY_MARKER.length);
+      if (!/^\s/.test(question) || !question.trim()) {
+        return `Q${index + 1} has an invalid context-only marker in ${JSON.stringify(text)}`;
+      }
+    }
+  }
+  return null;
+}
+
+export function questionsFromTexts(texts = []) {
+  const refusal = questionKindRefusal(texts);
+  if (refusal) throw new Error(refusal);
+  return texts.map((text, index) => {
+    const marked = text.startsWith(CONTEXT_ONLY_MARKER);
+    return {
+      id: `Q${index + 1}`,
+      text: marked ? text.slice(CONTEXT_ONLY_MARKER.length).replace(/^\s+/, '') : text,
+      kind: marked ? QUESTION_KIND.STARTUP_CONTEXT : QUESTION_KIND.CODE_REQUIRED,
+    };
+  });
+}

package/src/home/lib/runner/run-env.mjs

@@ -13,6 +13,7 @@
  * falling back — a typo must not decide what environment a run gets.
  */
 import { readRunConfig, disableFlags } from '../run-config.mjs';
+import { EXIT } from './exit-codes.mjs';
 
 /**
  * The switches as read (they go to env.json) and the flags they turn into (they go to
@@ -33,6 +34,6 @@ export function loadRunEnv() {
     CLEAN_ENV = disableFlags(RUN_ENV);
   } catch (err) {
     console.log(`FAIL — ${err.message}\nRun was not started; quota was not spent`);
-    process.exit(1);
+    process.exit(EXIT.FAIL);
   }
 }

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

@@ -85,7 +85,7 @@ export async function probeSandbox({
 
   const version = await attempt('version', ['--version']);
   if (version.error || version.signal || version.status !== 0) {
-    // codexUnavailableReason() owns the refusal for an unavailable CLI, in the same pre-flight pass.
+    // codexAvailabilityRefusal() owns the refusal for an unavailable CLI, earlier in the same pre-flight pass.
     return finish('inconclusive', 'Codex CLI is unavailable.');
   }
   return finish('dead', 'The Codex sandbox on this host cannot start a process.');

package/src/home/lib/runner/scope-check.mjs

@@ -8,6 +8,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { listRepositoryPaths } from './git-paths.mjs';
 import { globToRegExp, normalizePath, SERVICE_RE } from '../meta/paths.mjs';
+import { orderInputName } from '../order-schema.mjs';
 
 // Directories a self-walk must never descend into. Only reached when the repository has no git:
 // with git present the file list comes from the repository itself, which already knows what is
@@ -81,11 +82,22 @@ function structuralRefusal(repoRoot, pattern) {
   return null;
 }
 
-function noMatchRefusal(pattern) {
+function noMatchRefusal(pattern, repoRoot, gitListed) {
+  // OW-042: order plan72-r3-b1-live-thresholds-20261001 ran from a folder outside git, the walk missed a tracked
+  // file, and the refusal claimed the file did not exist. A walked folder is not the repository git would list.
+  if (gitListed === false) {
+    return {
+      pattern,
+      reason: `does not match any existing path under ${repoRoot}; ` +
+        'git could not list that folder as a repository, so it was walked instead',
+      action: `start the run from the repository root (cd into it, or pass ${orderInputName('repository')} <repository root>); ` +
+        'if this folder is the intended one, correct the pattern',
+    };
+  }
   return {
     pattern,
     reason: 'does not match any existing path in the repository',
-    action: 'correct the pattern or declare an intentionally new path with --scope-new',
+    action: `correct the pattern or declare an intentionally new path with ${orderInputName('scope new')}`,
   };
 }
 
@@ -127,7 +139,8 @@ function walkPaths(repoRoot) {
  * process instead of a walk and cannot wander into `.git` or a dependency tree.
  */
 function matchingPaths(repoRoot, matchers) {
-  const candidates = listRepositoryPaths(repoRoot) ?? walkPaths(repoRoot);
+  const listed = listRepositoryPaths(repoRoot);
+  const candidates = listed ?? walkPaths(repoRoot);
   const matched = new Set();
   for (const candidate of candidates) {
     for (const matcher of matchers) {
@@ -137,7 +150,7 @@ function matchingPaths(repoRoot, matchers) {
     }
     if (matched.size === matchers.length) break;
   }
-  return matched;
+  return { matched, gitListed: listed !== null };
 }
 
 function patternList(value, label) {
@@ -158,14 +171,18 @@ export function validateScope(repoRoot, patterns, scopeNewPatterns = []) {
   const declared = patternList(patterns, 'patterns');
   const newPaths = patternList(scopeNewPatterns, 'scopeNewPatterns');
   const allPatterns = [...declared, ...newPaths];
+  const newPathKeys = new Set(newPaths.map((pattern) => normalizePath(pattern)));
 
+  // The label is decided by `scope new:` membership, not list position: orderOptions() merges every
+  // `scope new:` pattern into the declared list, so position named `scope:` for a directory given only to `scope new:`
+  // (OW-042 B1, caught on the live runner 2026-10-04 after the unit test passed separate lists).
   for (const pattern of allPatterns) {
+    const label = newPathKeys.has(normalizePath(pattern)) ? 'scope new' : 'scope';
     const refusal = structuralRefusal(repoRoot, pattern);
-    if (refusal) return { pattern, ...refusal };
-    if (!pattern) return noMatchRefusal(pattern);
+    if (refusal) return { pattern, label, ...refusal };
+    if (!pattern) return { ...noMatchRefusal(pattern), label };
   }
 
-  const newPathKeys = new Set(newPaths.map((pattern) => normalizePath(pattern)));
   const required = allPatterns.filter((pattern) => !newPathKeys.has(normalizePath(pattern)));
   if (!required.length) return null;
 
@@ -174,23 +191,25 @@ export function validateScope(repoRoot, patterns, scopeNewPatterns = []) {
     matchers = required.map((pattern) => ({ pattern, regexp: globToRegExp(pattern) }));
   } catch (error) {
     return {
-      pattern: required[0].pattern,
+      pattern: required[0],
+      label: 'scope',
       reason: `could not parse the pattern: ${error.message}`,
       action: 'correct the pattern and retry',
     };
   }
 
-  let matched;
+  let matches;
   try {
-    matched = matchingPaths(repoRoot, matchers);
+    matches = matchingPaths(repoRoot, matchers);
   } catch (error) {
     if (error.code !== 'ERR_GIT_PATH_NOT_UTF8') throw error;
     return {
       pattern: required[0],
+      label: 'scope',
       reason: error.message,
       action: 'rename the non-UTF-8 file using a UTF-8 file name and retry',
     };
   }
-  const missing = matchers.find((matcher) => !matched.has(matcher.pattern));
-  return missing ? noMatchRefusal(missing.pattern) : null;
+  const missing = matchers.find((matcher) => !matches.matched.has(matcher.pattern));
+  return missing ? { ...noMatchRefusal(missing.pattern, repoRoot, matches.gitListed), label: 'scope' } : null;
 }

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

@@ -1,26 +1,48 @@
 /**
- * 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.
+ * Settles the order header, task, sub-questions and verification command from the document,
+ * 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.
+ * Plan_63 D1/D8: transport arguments carry no order fields; file and stdin share this boundary.
  */
 import { die, readTaskDocument } from './args.mjs';
+import { questionKindRefusal } from './question-kind.mjs';
+import { orderFromHeader, orderInputName, renderOrderProblems } from '../order-schema.mjs';
+import { orderOptions } from './order-options.mjs';
 
-export function settleTaskInput(opts) {
-  const { task, questions: fileQuestions, verify: fileVerify } = readTaskDocument(opts);
-  opts.questions ??= fileQuestions.length ? fileQuestions : undefined;
-  opts.verify ??= fileVerify;
+export function settleTaskInput(opts, { cwd = process.cwd() } = {}) {
+  const { task, header, questions: fileQuestions, verify: fileVerify } = readTaskDocument(opts);
+  const { order, problems } = orderFromHeader(opts.agent, header);
+  if (problems.length) {
+    die(renderOrderProblems(opts.agent, problems));
+  }
+  const normalized = orderOptions(opts.agent, order, { cwd });
+  if (normalized.problems.length) {
+    die(normalized.problems.map(({ label, reason }) => `${orderInputName(label)} ${reason}`).join('\n'));
+  }
+  Object.assign(opts, normalized.options);
+  opts.continue = Boolean(header.grant);
+  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. ' +
+        'under a `Questions` heading in the task document. ' +
         'The runner will not infer questions from the task text; no quota was spent.',
     );
   }
-  return task;
+  if (opts.agent === 'codex-scout') {
+    const refusal = questionKindRefusal(opts.questions);
+    if (refusal) {
+      die(
+        `${refusal}; the marker is exactly [context-only] followed by a space and the question; no quota was spent.`,
+      );
+    }
+  }
+  if (opts.noWait && opts.continue) {
+    die(`--no-wait cannot be combined with a ${orderInputName(header.grant.kind)} grant: ` +
+      'checking an existing run must never authorize a new one.');
+  }
+  return { task, header };
 }