@lyupro/codex-bridge 0.6.10 → 0.6.11

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
@@ -89,14 +90,14 @@ function noMatchRefusal(pattern, repoRoot, gitListed) {
       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 --repo <repository root>); ' +
+      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')}`,
   };
 }
 
@@ -172,14 +173,14 @@ export function validateScope(repoRoot, patterns, scopeNewPatterns = []) {
   const allPatterns = [...declared, ...newPaths];
   const newPathKeys = new Set(newPaths.map((pattern) => normalizePath(pattern)));
 
-  // The flag is decided by --scope-new membership, not list position: args.mjs merges every --scope-new
-  // pattern into the declared list, so position named --scope for a directory given only to --scope-new
+  // 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 flag = newPathKeys.has(normalizePath(pattern)) ? '--scope-new' : '--scope';
+    const label = newPathKeys.has(normalizePath(pattern)) ? 'scope new' : 'scope';
     const refusal = structuralRefusal(repoRoot, pattern);
-    if (refusal) return { pattern, flag, ...refusal };
-    if (!pattern) return { ...noMatchRefusal(pattern), flag };
+    if (refusal) return { pattern, label, ...refusal };
+    if (!pattern) return { ...noMatchRefusal(pattern), label };
   }
 
   const required = allPatterns.filter((pattern) => !newPathKeys.has(normalizePath(pattern)));
@@ -191,7 +192,7 @@ export function validateScope(repoRoot, patterns, scopeNewPatterns = []) {
   } catch (error) {
     return {
       pattern: required[0],
-      flag: '--scope',
+      label: 'scope',
       reason: `could not parse the pattern: ${error.message}`,
       action: 'correct the pattern and retry',
     };
@@ -204,11 +205,11 @@ export function validateScope(repoRoot, patterns, scopeNewPatterns = []) {
     if (error.code !== 'ERR_GIT_PATH_NOT_UTF8') throw error;
     return {
       pattern: required[0],
-      flag: '--scope',
+      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) => !matches.matched.has(matcher.pattern));
-  return missing ? { ...noMatchRefusal(missing.pattern, repoRoot, matches.gitListed), flag: '--scope' } : null;
+  return missing ? { ...noMatchRefusal(missing.pattern, repoRoot, matches.gitListed), label: 'scope' } : null;
 }

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

@@ -1,25 +1,34 @@
 /**
- * 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) {
+export function settleTaskInput(opts, { cwd = process.cwd() } = {}) {
   const { task, header, questions: fileQuestions, verify: fileVerify } = readTaskDocument(opts);
-  opts.questions ??= fileQuestions.length ? fileQuestions : undefined;
-  opts.verify ??= fileVerify;
+  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.',
     );
   }
@@ -31,5 +40,9 @@ export function settleTaskInput(opts) {
       );
     }
   }
+  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 };
 }

package/src/home/lib/subagent-model-env.mjs

@@ -0,0 +1,44 @@
+/** decides whether the host's subagent-model environment overrides a dispatcher's frontmatter pin
+ * Plan_67 D6 (b) and the host documentation facts recorded in its Council (2026-09-25):
+ * env moved below frontmatter in 2.1.251; FORCE=1 overrides it starting with 2.1.257.
+ * Unknown host versions are not evidence for a pre-start refusal.
+ */
+import { modelFamily } from './model-family.mjs';
+
+// Host contract facts, not package versions or volatile model identifiers (Plan_67 D6 (b)).
+export const FRONTMATTER_PRECEDENCE_VERSION = '2.1.251';
+export const SUBAGENT_MODEL_FORCE_VERSION = '2.1.257';
+
+function versionParts(value) {
+  if (typeof value !== 'string' || !/^\d+\.\d+\.\d+(?:\.\d+)*$/.test(value)) return null;
+  return value.split('.').map(BigInt);
+}
+
+function compareVersions(left, right) {
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    const difference = (left[index] ?? 0n) - (right[index] ?? 0n);
+    if (difference !== 0n) return difference < 0n ? -1 : 1;
+  }
+  return 0;
+}
+
+export function envOverridesPin({ env, hostVersion }) {
+  const model = env.CLAUDE_CODE_SUBAGENT_MODEL;
+  if (typeof model !== 'string' || model.length === 0) return false;
+  const version = versionParts(hostVersion);
+  if (version === null) return false;
+  return compareVersions(version, versionParts(FRONTMATTER_PRECEDENCE_VERSION)) < 0
+    || (env.CLAUDE_CODE_SUBAGENT_MODEL_FORCE === '1'
+      && compareVersions(version, versionParts(SUBAGENT_MODEL_FORCE_VERSION)) >= 0);
+}
+
+export function envModelProblem({ env, hostVersion, pinFamily }) {
+  if (!envOverridesPin({ env, hostVersion })) return null;
+  const model = env.CLAUDE_CODE_SUBAGENT_MODEL;
+  const family = modelFamily(model);
+  if (family === null || pinFamily === null || family === pinFamily) return null;
+  return `Order gate denied the Agent call because CLAUDE_CODE_SUBAGENT_MODEL=${JSON.stringify(model)} `
+    + `overrides the installed dispatcher pin ${pinFamily} on host ${hostVersion}. `
+    + `Unset CLAUDE_CODE_SUBAGENT_MODEL or set it to the pinned family ${pinFamily}. `
+    + 'The run folder was not created; quota was not spent.';
+}

package/src/home/lib/task-header.mjs

@@ -1,127 +1,158 @@
-/**
- * Reads the orchestrator's metadata header at the top of a task file — the one place a grant or an
- * advice line may stand.
- *
- * Plan_75 D5: on 2026-10-03 20:42 wrapped prose in a task file began a line with `continue:`, and
- * the runner, which looked for grants on any line, refused the order over its own prose. Grants and
- * advice had two parsers and the task hash a third rule; this module is the single reader, and a
- * line below the header that still looks like real metadata is refused rather than silently obeyed
- * or silently ignored.
- */
-import path from 'node:path';
-import { splitGrantValue } from './required-inputs.mjs';
-
-const BARE_RUN = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/;
-const MISPLACED_GRANT = /^[A-Za-z0-9._-]+(?:$| — | - |:)/;
-
-function validateGrant(value) {
-  const grant = splitGrantValue(value);
-  return grant && BARE_RUN.test(grant.run)
-    ? null
-    : 'grant must name a bare run folder (not . or ..) and a non-placeholder reason';
-}
-
-function descriptor(label, validate, misplaced) {
-  const spellings = [`${label}[ \\t]*[:=]`];
-  for (const wrapper of ['\\*', '_', '`', '\\*\\*', '__']) {
-    spellings.push(`${wrapper}${label}${wrapper}[ \\t]*[:=]`);
-    spellings.push(`${wrapper}${label}[ \\t]*[:=]${wrapper}`);
-  }
-  return Object.freeze({
-    label,
-    validate,
-    misplaced,
-    shape: new RegExp(
-      // Plan_75 D5: try a wrapper before treating its first star as a list marker.
-      `^[ \\t]*(?:[-*][ \\t]*)??(?:${spellings.join('|')})[ \\t]*(.*?)[ \\t]*$`,
-      'i',
-    ),
-    repairHint: `move it into the header at the top of the file, spelled ${label}: <value>; `
-      + 'if it is an example, quote it with > or reword it inside a sentence',
-  });
-}
-
-// Plan_75 D5, 2026-10-03 20:42: one registry prevents wrapped task prose becoming a grant.
-const LABELS = Object.freeze([
-  // Plan_75 D5: empty advice closes the strict header but must still explain the missing value.
-  descriptor('advice', (value) => value.trim() && !/[\r\n]/.test(value)
-    ? null : 'advice value must be non-empty and single line',
-  (value) => !value || /^\S+$/.test(value)
-    || path.posix.isAbsolute(value) || path.win32.isAbsolute(value)),
-  descriptor('continue', validateGrant, (value) => MISPLACED_GRANT.test(value)),
-  descriptor('retry', validateGrant, (value) => MISPLACED_GRANT.test(value)),
-]);
-
-const HEADER_LINE = new RegExp(`^(${LABELS.map(({ label }) => label).join('|')}):[ \\t]*(\\S.*?)[ \\t]*$`);
-
-export function parseTaskHeader(text) {
-  const lines = text.replace(/^\uFEFF/, '').split(/\r\n|\n|\r/);
-  const fields = {};
-  const entries = [];
-  const problems = [];
-  let headerEnd = 0;
-
-  for (const line of lines) {
-    const match = line.match(HEADER_LINE);
-    if (!match) break;
-    const [, label, value] = match;
-    const entry = { label, value, lineNo: headerEnd + 1, line };
-    if (Object.hasOwn(fields, label)) {
-      problems.push({ lineNo: entry.lineNo, line, reason: `duplicate ${label} label` });
-    } else {
-      fields[label] = value;
-    }
-    entries.push(entry);
-    headerEnd++;
-  }
-
-  // Plan_75 D5: conflicting authorization is a label-presence error even if a value is invalid.
-  if (Object.hasOwn(fields, 'continue') && Object.hasOwn(fields, 'retry')) {
-    const conflict = entries.find(({ label }) => label === 'retry');
-    problems.push({
-      lineNo: conflict.lineNo,
-      line: conflict.line,
-      reason: 'continue and retry cannot both be present; keep exactly one grant label',
-    });
-  }
-
-  let grant = null;
-  let advice = null;
-  for (const entry of entries) {
-    const definition = LABELS.find(({ label }) => label === entry.label);
-    const reason = definition.validate(entry.value);
-    if (reason) {
-      problems.push({ lineNo: entry.lineNo, line: entry.line, reason: `${entry.label}: ${reason}` });
-    } else if (entry.value !== fields[entry.label]) {
-      continue;
-    } else if (entry.label === 'advice') {
-      advice ??= entry.value;
-    } else {
-      grant ??= { kind: entry.label, ...splitGrantValue(entry.value) };
-    }
-  }
-
-  // Plan_75 D5, 2026-10-03 20:42: fences are examples, not an escape from the misplaced guard.
-  for (let index = headerEnd; index < lines.length; index++) {
-    for (const definition of LABELS) {
-      const match = lines[index].match(definition.shape);
-      if (!match || !definition.misplaced(match[1])) continue;
-      const reason = match[1] ? `misplaced ${definition.label} metadata`
-        : `${definition.label} value must be non-empty and single line`;
-      problems.push({
-        lineNo: index + 1,
-        line: lines[index],
-        reason: `${reason}; ${definition.repairHint}`,
-      });
-    }
-  }
-
-  problems.sort((a, b) => a.lineNo - b.lineNo);
-  return { fields, grant, advice, body: lines.slice(headerEnd).join('\n'), problems };
-}
-
-export function taskHeaderRefusal(parsed) {
-  if (!parsed.problems.length) return null;
-  return parsed.problems.map(({ lineNo, line, reason }) => `line ${lineNo}: ${reason}: ${line}`)
-    .concat('The run folder was not created; quota was not spent.').join('\n');
-}
+/**
+ * Reads the orchestrator's metadata header at the top of a task file — the one place a grant or an
+ * advice line may stand.
+ *
+ * Plan_75 D5: on 2026-10-03 20:42 wrapped prose in a task file began a line with `continue:`, and
+ * the runner, which looked for grants on any line, refused the order over its own prose. Grants and
+ * advice had two parsers and the task hash a third rule; this module is the single reader, and a
+ * line below the header that still looks like real metadata is refused rather than silently obeyed
+ * or silently ignored.
+ */
+import path from 'node:path';
+import { splitGrantValue } from './order-values.mjs';
+import { ALL_ORDER_LABELS } from './order-schema.mjs';
+
+const BARE_RUN = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/;
+const MISPLACED_GRANT = /^[A-Za-z0-9._-]+(?:$| — | - |:)/;
+
+function validateGrant(value) {
+  const grant = splitGrantValue(value);
+  return grant && BARE_RUN.test(grant.run)
+    ? null
+    : 'grant must name a bare run folder (not . or ..) and a non-placeholder reason';
+}
+
+function descriptor(label, validate, misplaced) {
+  const spellings = [`${label}[ \\t]*[:=]`];
+  for (const wrapper of ['\\*', '_', '`', '\\*\\*', '__']) {
+    spellings.push(`${wrapper}${label}${wrapper}[ \\t]*[:=]`);
+    spellings.push(`${wrapper}${label}[ \\t]*[:=]${wrapper}`);
+  }
+  return Object.freeze({
+    label,
+    validate,
+    misplaced,
+    shape: new RegExp(
+      // Plan_75 D5: try a wrapper before treating its first star as a list marker.
+      `^[ \\t]*(?:[-*][ \\t]*)??(?:${spellings.join('|')})[ \\t]*(.*?)[ \\t]*$`,
+      'i',
+    ),
+    repairHint: `move it into the header at the top of the file, spelled ${label}: <value>; `
+      + 'if it is an example, quote it with > or reword it inside a sentence',
+  });
+}
+
+// Plan_75 D5, 2026-10-03 20:42: one registry prevents wrapped task prose becoming a grant.
+const LABELS = Object.freeze([
+  // Plan_75 D5: empty advice closes the strict header but must still explain the missing value.
+  descriptor('advice', (value) => value.trim() && !/[\r\n]/.test(value)
+    ? null : 'advice value must be non-empty and single line',
+  (value) => !value || /^\S+$/.test(value)
+    || path.posix.isAbsolute(value) || path.win32.isAbsolute(value)),
+  descriptor('continue', validateGrant, (value) => MISPLACED_GRANT.test(value)),
+  descriptor('retry', validateGrant, (value) => MISPLACED_GRANT.test(value)),
+]);
+
+const HEADER_LABELS = Object.freeze([...ALL_ORDER_LABELS, 'advice']);
+const GUARDED_LABELS = Object.freeze(LABELS.map(({ label }) => label));
+const ORDER_ONLY_LABELS = Object.freeze(HEADER_LABELS.filter((label) => !GUARDED_LABELS.includes(label)));
+const HEADER_LINE = new RegExp(`^(${HEADER_LABELS.join('|')}):[ \\t]*(\\S.*?)[ \\t]*$`);
+
+function normalizedHeaderLabel(line) {
+  const colon = line.indexOf(':');
+  if (colon === -1) return null;
+  return line.slice(0, colon).trim().toLowerCase()
+    .replace(/^[-*][ \t]+/, '')
+    .replace(/^[*`_]+|[*`_]+$/g, '')
+    .replace(/[-_]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+export function parseTaskHeader(text) {
+  const lines = text.replace(/^\uFEFF/, '').split(/\r\n|\n|\r/);
+  const fields = {};
+  const entries = [];
+  const problems = [];
+  let headerEnd = 0;
+
+  for (const line of lines) {
+    const match = line.match(HEADER_LINE);
+    if (!match) {
+      // Plan_63 D1/D3: a misspelled or unknown order line must not silently turn into task prose. The
+      // header still closes here (Plan_75 D5), and grant/advice spellings stay with the misplaced guard.
+      const label = normalizedHeaderLabel(line);
+      const rawLabel = line.slice(0, line.indexOf(':')).trim();
+      let reason = null;
+      if (ORDER_ONLY_LABELS.includes(label)) {
+        reason = line.trimEnd() === `${label}:` ? `header label "${label}" has an empty value`
+          : `write the header label exactly as "${label}:"`;
+      } else if (!GUARDED_LABELS.includes(label) && entries.length && /^[a-z][a-z _-]*:[ \t]*\S/.test(line)) {
+        reason = `unknown header label "${rawLabel}"; known labels: ${HEADER_LABELS.join(', ')}`;
+      }
+      if (reason) problems.push({ lineNo: headerEnd + 1, line, reason });
+      break;
+    }
+    const [, label, value] = match;
+    const entry = { label, value, lineNo: headerEnd + 1, line };
+    if (Object.hasOwn(fields, label)) {
+      problems.push({ lineNo: entry.lineNo, line, reason: `duplicate ${label} label` });
+    } else {
+      fields[label] = value;
+    }
+    entries.push(entry);
+    headerEnd++;
+  }
+
+  // Plan_75 D5: conflicting authorization is a label-presence error even if a value is invalid.
+  if (Object.hasOwn(fields, 'continue') && Object.hasOwn(fields, 'retry')) {
+    const conflict = entries.find(({ label }) => label === 'retry');
+    problems.push({
+      lineNo: conflict.lineNo,
+      line: conflict.line,
+      reason: 'continue and retry cannot both be present; keep exactly one grant label',
+    });
+  }
+
+  let grant = null;
+  let advice = null;
+  for (const entry of entries) {
+    const definition = LABELS.find(({ label }) => label === entry.label);
+    if (!definition) continue;
+    const reason = definition.validate(entry.value);
+    if (reason) {
+      problems.push({ lineNo: entry.lineNo, line: entry.line, reason: `${entry.label}: ${reason}` });
+    } else if (entry.value !== fields[entry.label]) {
+      continue;
+    } else if (entry.label === 'advice') {
+      advice ??= entry.value;
+    } else {
+      grant ??= { kind: entry.label, ...splitGrantValue(entry.value) };
+    }
+  }
+
+  // Plan_75 D5, 2026-10-03 20:42: fences are examples, not an escape from the misplaced guard.
+  for (let index = headerEnd; index < lines.length; index++) {
+    for (const definition of LABELS) {
+      const match = lines[index].match(definition.shape);
+      if (!match || !definition.misplaced(match[1])) continue;
+      const reason = match[1] ? `misplaced ${definition.label} metadata`
+        : `${definition.label} value must be non-empty and single line`;
+      problems.push({
+        lineNo: index + 1,
+        line: lines[index],
+        reason: `${reason}; ${definition.repairHint}`,
+      });
+    }
+  }
+
+  problems.sort((a, b) => a.lineNo - b.lineNo);
+  const parsed = { fields, grant, advice, body: lines.slice(headerEnd).join('\n'), problems };
+  // Plan_63 C1: retain source locations for schema diagnostics without changing serialized results.
+  Object.defineProperty(parsed, 'entries', { value: entries });
+  return parsed;
+}
+
+export function taskHeaderRefusal(parsed) {
+  if (!parsed.problems.length) return null;
+  return parsed.problems.map(({ lineNo, line, reason }) => `line ${lineNo}: ${reason}: ${line}`)
+    .concat('The run folder was not created; quota was not spent.').join('\n');
+}

package/src/home/lib/untyped-stop.mjs

@@ -0,0 +1,30 @@
+/** decides whether a subagent stop without agent_type was a Codex dispatcher, from evidence bound to that stop
+ * Plan_67 D9: all 13 missing-type alarms across nine host versions were noise; require evidence
+ * for this stop instead of assuming every untyped subagent is a dispatcher.
+ */
+import { CLI_NAMES } from './cli-names.mjs';
+import { ORDER_AGENTS } from './order-schema.mjs';
+
+export function untypedStopEvidence({ state, toolUses }) {
+  if (state && typeof state === 'object' && !Array.isArray(state) && !state.corrupt
+    && typeof state.agentType === 'string' && ORDER_AGENTS.includes(state.agentType)
+    && Array.isArray(state.seenToolUseIds) && state.seenToolUseIds.length > 0) {
+    return { dispatcher: true, via: 'gate-state', agentType: state.agentType };
+  }
+
+  if (toolUses !== null) {
+    for (const toolUse of toolUses) {
+      if (toolUse?.name !== 'Bash' || typeof toolUse.command !== 'string'
+        || /[;&|`$<>\r\n]/.test(toolUse.command)) continue;
+      const tokens = toolUse.command.trim().split(/\s+/);
+      if (!CLI_NAMES.includes(tokens[0]) || tokens[1] !== 'run') continue;
+      for (let index = 2; index < tokens.length - 1; index += 1) {
+        if (tokens[index] === '--agent' && ORDER_AGENTS.includes(tokens[index + 1])) {
+          return { dispatcher: true, via: 'run-command', runAgent: tokens[index + 1] };
+        }
+      }
+    }
+  }
+
+  return { dispatcher: false, reason: toolUses === null ? 'transcript-unreadable' : 'no-evidence' };
+}