@lyupro/codex-bridge 0.6.4 → 0.6.5

package/src/home/lib/meta/advice-verdict.mjs

@@ -0,0 +1,226 @@
+/** Judges advisor evidence and independent decisions so Plan_59 D3/D4/D5/D10 failures cannot pass as advice. */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const BACKSTOPS = {
+  English: ['both options are good', 'it depends on preference', 'you know better', 'either works'],
+  Russian: ['оба варианта хороши', 'зависит от предпочтений', 'вам виднее', 'подойдёт любой'],
+};
+const ADDRESS_TOKEN = /(?<![\p{L}\p{N}_./\\:~-])(?:[a-zA-Z]:)?[\p{L}\p{N}_@!$~.%+/\\-]+:\d+(?:-\d+)?(?![\p{L}\p{N}_:\d-])/gu;
+const QUOTED_ADDRESS = /`([^`\r\n]+:\d+(?:-\d+)?)`|"([^"\r\n]+:\d+(?:-\d+)?)"|'([^'\r\n]+:\d+(?:-\d+)?)'/u;
+const ADDRESS = new RegExp(`${QUOTED_ADDRESS.source}|(${ADDRESS_TOKEN.source})`, 'gu');
+
+function* strings(value, field = '') {
+  if (typeof value === 'string') yield { field, value };
+  else if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) yield* strings(item, `${field}[${index}]`);
+  } else if (value && typeof value === 'object') {
+    for (const [key, item] of Object.entries(value)) {
+      yield* strings(item, field ? `${field}.${key}` : key);
+    }
+  }
+}
+
+function backstopPattern(phrase) {
+  // Plan_59 D5 ignores punctuation within words as well as between words, without matching word prefixes.
+  const words = phrase.split(' ').map((word) => [...word].join('[\\p{P}\\p{S}]*'));
+  return new RegExp(`(?<![\\p{L}\\p{N}])${words.join('[\\s\\p{P}\\p{S}]+')}(?![\\p{L}\\p{N}])`, 'iu');
+}
+
+function isInside(root, absolute) {
+  const relative = path.relative(root, absolute);
+  return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function entryInRepo(root, raw) {
+  const normalized = raw.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '');
+  if (path.posix.isAbsolute(normalized) || /^[a-z]:/i.test(normalized)) return null;
+  const absolute = path.resolve(root, normalized);
+  if (!isInside(root, absolute)) return null;
+  try {
+    // Plan_59 D3 requires real containment: a repository symlink cannot authorize outside evidence.
+    if (!isInside(fs.realpathSync(root), fs.realpathSync(absolute))) return null;
+    const stat = fs.statSync(absolute);
+    return {
+      absolute,
+      relative: path.relative(root, absolute).replace(/\\/g, '/'),
+      isFile: stat.isFile(),
+      isDirectory: stat.isDirectory(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function lineCount(absolute) {
+  const text = fs.readFileSync(absolute, 'utf8');
+  if (!text) return 0;
+  const lines = text.split(/\r\n|\n|\r/);
+  return lines.length - (lines.at(-1) === '' ? 1 : 0);
+}
+
+function* addressesIn(value, root) {
+  for (const match of value.matchAll(ADDRESS)) {
+    const address = match.slice(1).find(Boolean);
+    if (!match[4]) {
+      // Plan_59 D3 must distinguish a quoted path with spaces from prose quoting several citations.
+      const embedded = [...address.matchAll(ADDRESS_TOKEN)].map((token) => token[0]);
+      const file = address.match(/^(.+):\d+(?:-\d+)?$/)[1];
+      if (embedded.length && !entryInRepo(root, file)?.isFile &&
+        (embedded.length > 1 || !/^[^\s]*[/\\]/.test(address))) {
+        yield* embedded;
+        continue;
+      }
+    }
+    yield address;
+  }
+}
+
+function citationProblem(raw, root, allowed) {
+  const match = raw.match(/^(.+):(\d+)(?:-(\d+))?$/);
+  if (!match) return 'use a repository-relative path:line or path:line-line address';
+  const entry = entryInRepo(root, match[1]);
+  if (!entry?.isFile) return 'cite an existing file under repoRoot';
+  let count;
+  try {
+    count = lineCount(entry.absolute);
+  } catch {
+    return 'cite a readable file under repoRoot';
+  }
+  const start = Number(match[2]);
+  const end = match[3] === undefined ? start : Number(match[3]);
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 1 || end < start || end > count) {
+    return `use an ascending line range within this file's ${count} lines`;
+  }
+  if (!allowed.some((scope) => entry.relative === scope.relative ||
+    (scope.isDirectory && (!scope.relative || entry.relative.startsWith(`${scope.relative}/`))))) {
+    return 'cite a task path or a scope missing_paths entry';
+  }
+  return null;
+}
+
+function checkCitations({ phase, result, task, repoRoot, scopeResult }, reasons) {
+  const root = path.resolve(repoRoot);
+  const allowed = [...task.paths, ...(phase === 'scope' ? result.missing_paths : scopeResult?.missing_paths ?? [])]
+    .map((raw) => entryInRepo(root, raw)).filter(Boolean);
+  const check = (field, address) => {
+    const problem = citationProblem(address, root, allowed);
+    if (problem) reasons.push(`D3 ${field} ${JSON.stringify(address)}: ${problem}.`);
+  };
+  const checkAddress = (field, raw) => {
+    const trimmed = raw.trim();
+    check(field, /^`.*`$/.test(trimmed) ? trimmed.slice(1, -1) : trimmed);
+  };
+  // D3 covers every address anywhere in the answer. A list of prose fields had to be edited by
+  // hand when `falsifier` became `pre_mortem`, and each new field would have joined it unchecked.
+  // Fields that ARE an address are checked whole below, so they are skipped here.
+  for (const { field, value } of strings(result)) {
+    if (/\.address$|\.early_check\.target$/.test(field)) continue;
+    for (const address of addressesIn(value, root)) check(field, address);
+  }
+  if (result.independent_checks) {
+    for (const [index, item] of result.independent_checks.entries()) {
+      checkAddress(`independent_checks[${index}].address`, item.address);
+    }
+  }
+  if (phase === 'advise') {
+    for (const [index, item] of result.assumptions.entries()) {
+      if (item.rating === 'VERIFIED' || item.address !== '') {
+        checkAddress(`assumptions[${index}].address`, item.address);
+      }
+    }
+    for (const [index, item] of result.pre_mortem.entries()) {
+      if (item.early_check.kind === 'inspect') {
+        checkAddress(`pre_mortem[${index}].early_check.target`, item.early_check.target);
+      }
+    }
+    // An outcome's address is evidence whether or not the phase-1 answer is at hand.
+    for (const [index, item] of result.risk_outcomes.entries()) {
+      checkAddress(`risk_outcomes[${index}].address`, item.address);
+    }
+  }
+}
+
+export function judgeAdvice({ phase, result, task, repoRoot, commandsRun, language, scopeResult }) {
+  if (phase !== 'scope' && phase !== 'advise') throw new RangeError('phase must be "scope" or "advise".');
+  if (!Number.isInteger(commandsRun) || commandsRun < 0) {
+    throw new TypeError('commandsRun must be a non-negative integer.');
+  }
+  if (typeof language !== 'string') throw new TypeError('language must be a string.');
+  if (typeof repoRoot !== 'string' || !repoRoot) throw new TypeError('repoRoot must be a non-empty path.');
+  if (!result || !Array.isArray(task?.options) || !Array.isArray(task?.paths)) {
+    throw new TypeError('result and a parsed advisor task are required.');
+  }
+  const reasons = [];
+  if (commandsRun === 0) reasons.push('D4 commandsRun 0: inspect repository evidence before answering.');
+  if (phase === 'scope') {
+    if (!result.taken_on_trust.length) {
+      reasons.push('D4 taken_on_trust []: name at least one assumption taken on trust.');
+    }
+    if (result.sufficient === false && !result.missing_paths.length) {
+      reasons.push('D4 missing_paths [] with sufficient false: name the paths needed for advice.');
+    }
+    if (result.sufficient === true && result.missing_paths.length) {
+      reasons.push(`D4 missing_paths ${JSON.stringify(result.missing_paths)} with sufficient true: resolve the scope contradiction.`);
+    }
+    const riskIds = new Set();
+    for (const [index, item] of result.predicted_risks.entries()) {
+      if (riskIds.has(item.id)) {
+        reasons.push(`D10 predicted_risks[${index}].id ${JSON.stringify(item.id)}: use a unique predicted risk id.`);
+      }
+      riskIds.add(item.id);
+    }
+  } else {
+    const ids = new Set(task.options.map(({ id }) => id));
+    const chosen = result.recommendation.option_id;
+    if (!ids.has(chosen) && chosen !== 'none-of-these') {
+      reasons.push(`D5 recommendation.option_id ${JSON.stringify(chosen)}: choose a task option id.`);
+    }
+    if (chosen === 'none-of-these') {
+      if (result.unlisted_option === 'none' || [...result.unlisted_option.trim()].length < 40) {
+        reasons.push(`D10 unlisted_option ${JSON.stringify(result.unlisted_option)}: describe an unlisted option in at least 40 characters.`);
+      }
+      const rejected = new Set(result.rejected.map(({ option_id }) => option_id));
+      const missing = [...ids].filter((id) => !rejected.has(id));
+      if (missing.length) {
+        reasons.push(`D10 rejected ${JSON.stringify(missing)}: reject every task option when recommending "none-of-these".`);
+      }
+    } else if (ids.has(chosen) && result.unlisted_option !== 'none') {
+      reasons.push(`D10 unlisted_option ${JSON.stringify(result.unlisted_option)}: use "none" when recommending a task option.`);
+    }
+    for (const [index, item] of result.rejected.entries()) {
+      if (!ids.has(item.option_id)) {
+        reasons.push(`D5 rejected[${index}].option_id ${JSON.stringify(item.option_id)}: use a task option id.`);
+      }
+      if (item.option_id === chosen) {
+        reasons.push(`D5 rejected[${index}].option_id ${JSON.stringify(chosen)}: do not reject the recommended option.`);
+      }
+    }
+    if (scopeResult !== undefined) {
+      const riskIds = new Set(scopeResult.predicted_risks.map(({ id }) => id));
+      for (const [index, item] of result.risk_outcomes.entries()) {
+        if (!riskIds.has(item.risk_id)) {
+          reasons.push(`D10 risk_outcomes[${index}].risk_id ${JSON.stringify(item.risk_id)}: use a scope predicted risk id.`);
+        }
+      }
+      for (const id of riskIds) {
+        const count = result.risk_outcomes.filter(({ risk_id }) => risk_id === id).length;
+        if (count !== 1) {
+          reasons.push(`D10 risk_outcomes ${JSON.stringify(id)} count ${count}: provide exactly one outcome per predicted risk.`);
+        }
+      }
+    }
+  }
+  checkCitations({ phase, result, task, repoRoot, scopeResult }, reasons);
+  const phrases = Object.hasOwn(BACKSTOPS, language) ? BACKSTOPS[language] : Object.values(BACKSTOPS).flat();
+  const patterns = phrases.map((phrase) => [phrase, backstopPattern(phrase)]);
+  for (const { field, value } of strings(result)) {
+    for (const [phrase, pattern] of patterns) {
+      const match = value.normalize('NFKC').match(pattern);
+      if (match) {
+        reasons.push(`D5 ${field} ${JSON.stringify(match[0])}: replace backstop phrase ${JSON.stringify(phrase)} with a decision.`);
+      }
+    }
+  }
+  return { ok: reasons.length === 0, reasons };
+}

package/src/home/lib/meta/advisor-task.mjs

@@ -0,0 +1,69 @@
+/** Parses blind advisor task choices so Plan_59 D5 rejects biased or ambiguous inputs before review. */
+const OPTION = /^\s*-\s+([a-z0-9][a-z0-9-]*):\s*(.*)$/;
+const PREFERENCE = /recommend|prefer|рекоменд|предпочт|\(✓\)|★/iu;
+
+function sections(text) {
+  if (typeof text !== 'string') throw new TypeError('Advisor task text must be a string.');
+  const found = { options: { header: null, lines: [] }, paths: { header: null, lines: [] } };
+  let current = null;
+  for (const [index, value] of text.split(/\r\n|\n|\r/).entries()) {
+    const line = { number: index + 1, value };
+    const heading = value.match(/^\s{0,3}(#{1,2})\s+(.+?)\s*$/);
+    if (heading) {
+      const name = heading[2].replace(/\s+#+$/, '').toLowerCase();
+      current = heading[1] === '##' && Object.hasOwn(found, name) ? found[name] : null;
+      if (current && !current.header) current.header = line;
+    } else if (current) {
+      current.lines.push(line);
+    }
+  }
+  return found;
+}
+
+function optionsFrom(lines) {
+  return lines.flatMap(({ value }) => {
+    const match = value.match(OPTION);
+    return match ? [{ id: match[1], description: match[2].trim() }] : [];
+  });
+}
+
+function pathsFrom(lines) {
+  return lines.flatMap(({ value }) => {
+    const match = value.match(/^\s*-\s+(.+?)\s*$/);
+    return match && match[1].trim() ? [match[1].trim()] : [];
+  });
+}
+
+export function parseAdvisorTask(text) {
+  const { options, paths } = sections(text);
+  return { options: optionsFrom(options.lines), paths: pathsFrom(paths.lines) };
+}
+
+function at(line) {
+  return `line ${line.number} ${JSON.stringify(line.value)}`;
+}
+
+export function advisorTaskRefusal(text) {
+  const { options, paths } = sections(text);
+  if (!options.header) return 'Options: add a "## Options" section with at least two options.';
+  const ids = new Set();
+  for (const line of options.lines) {
+    const preference = line.value.match(PREFERENCE);
+    if (preference) {
+      return `Options ${at(line)}: remove preference marker ${JSON.stringify(preference[0])} (D5).`;
+    }
+    if (!/^\s*[-*+](?:\s|$)/.test(line.value)) continue;
+    const match = line.value.match(OPTION);
+    if (!match) {
+      return `Options ${at(line)}: use "- option-id: description" with id matching [a-z0-9][a-z0-9-]*.`;
+    }
+    if (ids.has(match[1])) return `Options ${at(line)}: replace duplicate option id "${match[1]}".`;
+    ids.add(match[1]);
+  }
+  if (ids.size < 2) return `Options ${at(options.header)}: provide at least two distinct options.`;
+  if (!paths.header) return 'Paths: add a "## Paths" section with repository-relative paths.';
+  if (!pathsFrom(paths.lines).length) {
+    return `Paths ${at(paths.header)}: add at least one repository-relative path as a list item.`;
+  }
+  return null;
+}

package/src/home/lib/meta/reply.mjs

@@ -2,8 +2,7 @@
  * Renders the reply lines a dispatcher is allowed to return, one format per agent.
  *
  * AGENTS adds reply strategies to the shared agent registry: for each one it describes how
- * to tell the result file is filled in and which of the three reply strategies below
- * renders it. FAIL and LIMIT bypass the per-agent strategy — a run that
+ * to tell the result file is filled in and which reply strategy below renders it. FAIL and LIMIT bypass the per-agent strategy — a run that
  * produced nothing has nothing agent-specific left to say.
  *
  * The lines built here ARE the reply. Agents forward this text verbatim instead of
@@ -41,6 +40,12 @@ export const AGENTS = {
     filled: (r) => Boolean(String(r?.verdict || '').trim()),
     reply: reviewReply,
   },
+  // Plan_59 D4: one result file, two contracts. Either phase's decisive field proves it is filled.
+  'codex-advisor': {
+    ...AGENT_DEFINITIONS['codex-advisor'],
+    filled: (r) => typeof r?.sufficient === 'boolean' || Boolean(String(r?.recommendation?.option_id || '').trim()),
+    reply: advisorReply,
+  },
 };
 
 function scoutReply(ctx) {
@@ -113,6 +118,40 @@ function reviewReply(ctx) {
   ];
 }
 
+/**
+ * Plan_59 D4: an insufficient scope is an OK run with a named outcome, not a LIMIT — the first
+ * word stays the status, and the outcome that decides the orchestrator's next step is the first
+ * thing after it, derived from the same fields meta.json records.
+ */
+function advisorReply(ctx) {
+  const r = ctx.result;
+  const log = `Report: ${ctx.file(path.basename(ctx.resultPath))} · Log: ${readCommand(ctx.runDir)}`;
+  // The result's own shape picks the lines, as it does in `filled`: a run folder missing its phase
+  // record must not send a scope answer into the advise branch and crash the verdict.
+  if (typeof r.sufficient === 'boolean') {
+    const missing = r.missing_paths || [];
+    const risks = r.predicted_risks || [];
+    return [
+      r.sufficient
+        ? 'OK — scope: sufficient; continue this run with --phase advise'
+        : `OK — scope: insufficient; ${missing.length} paths named`,
+      ...(missing.length ? [`Missing: ${line(missing.join(', '), 160)}`] : []),
+      `Predicted risks: ${risks.length}${risks[0] ? ` — ${risks[0].id} ${line(risks[0].risk, 120)}` : ''}`,
+      log,
+    ];
+  }
+  const outcomes = r.risk_outcomes || [];
+  const confirmed = outcomes.filter((o) => o.outcome === 'confirmed').length;
+  const rejected = (r.rejected || []).map((o) => `${o.option_id} (${line(o.cost, 60)})`);
+  return [
+    `OK — recommend ${r.recommendation.option_id}: ${line(r.recommendation.text, 200)}`,
+    `Rejected: ${rejected.length ? line(rejected.join('; '), 180) : 'none'}`,
+    `Counter: ${line(r.strongest_counterargument, 180)}`,
+    `Risks: ${confirmed} confirmed · ${outcomes.length - confirmed} refuted · open questions ${(r.open_questions || []).length} · confidence ${r.confidence}`,
+    log,
+  ];
+}
+
 /**
  * Which worker actually ran, printed next to the log link.
  *

package/src/home/lib/meta/run-state.mjs

@@ -197,6 +197,8 @@ export function abandonedBranchDrift(runsRoot, repo, currentBranch) {
 export function writeFailure(runDir, agent, reason, extraLines = [], preStart = false) {
   const meta = {
     agent,
+    phase: readJson(path.join(runDir, 'worker.json'))?.phase
+      ?? readJson(path.join(runDir, 'status.json'))?.phase ?? null,
     project: path.basename(path.dirname(runDir)),
     run: path.basename(runDir),
     finished_at: new Date().toISOString(),

package/src/home/lib/meta/verdict.mjs

@@ -28,6 +28,7 @@ import { deadlineReason } from './deadline.mjs';
 import { startupGap } from './startup.mjs';
 import { transportGap } from './transport.mjs';
 import { reasonFrom } from './reason.mjs';
+import { adviceGap } from './advice-status.mjs';
 
 // How much prose an answer must carry once coordinates and paths are subtracted. Measured
 // on the scout run of 2026-07-30 that replied with a table of `file.ts:60-79` rows: every
@@ -329,6 +330,12 @@ export function resolveStatus({ resultOk, exit, agent, result, runDir, events })
     const gap = scoutCoverageGap(runDir, result);
     if (gap) return { status: 'FAIL', reason: gap };
   }
+  // Plan_59 D3/D4/D5/D10: a schema-valid agreement still needs evidence and decision checks.
+  // Place the advisor judge before the build-only scope check, alongside the other agent contracts.
+  if (agent === 'codex-advisor') {
+    const gap = adviceGap(runDir, result, eventData);
+    if (gap) return { status: 'FAIL', reason: gap };
+  }
   // Files the task never authorised. Checked before the mismatch below, because a run that
   // did the job AND edited three unrelated files passes reportVersusWork() — one matching
   // path is all it needs — and the unrelated files would go unmentioned. No automatic

package/src/home/lib/required-inputs.mjs

@@ -80,6 +80,23 @@ export const REQUIRED_INPUTS = Object.freeze({
     TASK_FILE_INPUT,
     CONTINUATION_INPUT,
   ]),
+  // Plan_59 D7: the caller must name the phase and authorize the continued decision pass.
+  'codex-advisor': freezeEntries([
+    {
+      label: 'order id',
+      source: 'the orchestrator',
+      explanation: 'The label this design order is known by. Keep the same order id for scope and advise so phase 2 can settle the risks predicted in phase 1.',
+      example: 'plan-59-advisor-20260922',
+    },
+    TASK_FILE_INPUT,
+    CONTINUATION_INPUT,
+    {
+      label: 'phase',
+      source: 'the orchestrator',
+      explanation: 'Pass scope first to predict risks and check the reading boundary, then advise with --continue and a continuation grant naming the scope run of the same order.',
+      example: 'scope',
+    },
+  ]),
 });
 
 const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -101,6 +118,10 @@ export function isPlaceholder(value) {
   return PLACEHOLDER_VALUES.has(cleaned.replace(/[.,;:]+$/, '').trim().toLowerCase());
 }
 
+// Plan_59: scope is a real phase value, while it remains a placeholder for existing inputs.
+const isInputPlaceholder = (value, label) =>
+  !(label === 'phase' && cleanValue(value) === 'scope') && isPlaceholder(value);
+
 export function extractValue(promptText, label) {
   const labelPattern = escapeRegExp(label).replaceAll('\\ ', '\\s+');
   const flag = `--${label.replaceAll(/\s+/g, '-')}`;
@@ -141,7 +162,7 @@ export function diagnoseInput(promptText, label) {
   if (candidateLine === undefined) return null;
 
   const value = extractValue(candidateLine, label);
-  if (value !== null && !isPlaceholder(value)) {
+  if (value !== null && !isInputPlaceholder(value, label)) {
     if (label === TASK_FILE_INPUT.label && !isAbsoluteTaskFilePath(value)) {
       return { line: readableDiagnosisLine(candidateLine), reason: `value \`${value}\` is not an absolute path` };
     }
@@ -149,7 +170,7 @@ export function diagnoseInput(promptText, label) {
   }
 
   const line = readableDiagnosisLine(candidateLine);
-  if (value !== null && isPlaceholder(value)) {
+  if (value !== null && isInputPlaceholder(value, label)) {
     const displayedValue = value.trim();
     if (!displayedValue) return { line, reason: 'value is empty; replace it with a concrete value' };
     return {
@@ -195,7 +216,7 @@ export function missingInputs(agentType, promptText) {
   return requiredInputsFor(agentType).filter((entry) => {
     if (entry.conditional) return false;
     const value = extractValue(prompt, entry.label);
-    if (isPlaceholder(value)) return true;
+    if (isInputPlaceholder(value, entry.label)) return true;
     return entry === TASK_FILE_INPUT && !isAbsoluteTaskFilePath(value);
   });
 }
@@ -206,7 +227,7 @@ export function shellUnsafeInputs(agentType, promptText) {
   return requiredInputsFor(agentType).flatMap((entry) => {
     if (entry.conditional) return [];
     const value = extractValue(prompt, entry.label);
-    if (value === null || isPlaceholder(value)) return [];
+    if (value === null || isInputPlaceholder(value, entry.label)) return [];
     const sequence = firstShellUnsafeSequence(value);
     return sequence === null ? [] : [{ entry, sequence }];
   });

package/src/home/lib/run-codex.mjs

@@ -6,6 +6,7 @@
  *
  * Options:
  *   --agent     codex-scout | codex-build | codex-review   (required)
+ *   --phase     declared phase name (optional only for a role with just the default phase)
  *   --repo      repository path (default: current directory)
  *   --slug      short run name used in the run folder (default: agent suffix)
  *   --effort    reasoning effort, passed to Codex as given (default: medium)

package/src/home/lib/run-config.mjs

@@ -79,7 +79,11 @@ const state = (config) => [
     return `${key}: ${model}${profile.effort ? ` at ${profile.effort} effort` : ''}`
       + (profile.speed ? ` on ${profile.speed} tier` : '');
   }).join('; ')}`,
-  `budgets: ${ROLES.map((role) => `${role}: ${config.budgets?.[role] ?? DEFAULTS.budgets[role]} minutes`).join('; ')}`,
+  `budgets: ${ROLES.map((role) => {
+    const phases = Object.entries(config.budgets?.[role] ?? DEFAULTS.budgets[role]);
+    return `${role}: ` + (phases.length === 1 ? `${phases[0][1]} minutes`
+      : phases.map(([phase, minutes]) => `${phase}: ${minutes} minutes`).join(', '));
+  }).join('; ')}`,
   `retention: ${config.retention?.enabled ? `on — transport older than ${config.retention.days} days` : 'off — automatic cleanup disabled'}`,
 ];
 

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

@@ -89,6 +89,7 @@ const SHELL_CHECKED_FLAGS = Object.freeze([
   'scope-new',
   'repo',
   'agent',
+  'phase',
   'effort',
   'changeset',
   'task-file',

package/src/home/lib/runner/codex-args.mjs

@@ -63,7 +63,7 @@ export function runProfile(opts) {
 // Plan_57: the preflight must probe the same permissions that the role will request.
 export function sandboxModeFor(agent) {
   if (agent === 'codex-build') return 'workspace-write';
-  if (agent === 'codex-scout' || agent === 'codex-review') return 'read-only';
+  if (agent === 'codex-scout' || agent === 'codex-review' || agent === 'codex-advisor') return 'read-only';
   throw new Error(`unknown agent for sandbox mode: ${agent}`);
 }
 
@@ -75,7 +75,8 @@ export function codexArgs(opts, runDir, isGitRepo) {
   const modelArgs = profile.model ? ['-m', profile.model] : [];
   // Plan_56 D35: there is no identifier for ordinary speed; an unpinned tier adds no override.
   const speedArgs = profile.speed ? ['-c', `service_tier=${profile.speed}`] : [];
-  if (opts.agent === 'codex-scout') {
+  // Plan_59: advisor uses schema-backed plain exec with the same read-only isolation as scout.
+  if (opts.agent === 'codex-scout' || opts.agent === 'codex-advisor') {
     return [
       'exec',
       '--json',
@@ -89,7 +90,7 @@ export function codexArgs(opts, runDir, isGitRepo) {
       ...modelArgs,
       '--sandbox',
       sandboxMode,
-      '--skip-git-repo-check',
+      ...(opts.agent === 'codex-scout' || !isGitRepo ? ['--skip-git-repo-check'] : []),
       '-C',
       opts.repo,
       '--output-schema',

package/src/home/lib/runner/codex-cmd.mjs

@@ -158,7 +158,7 @@ export function spawnCaptured(command, args, options) {
 export function runCodex(args, taskText, eventsPath, budgetMinutes, graceMs = STDIO_DRAIN_GRACE_MS) {
   const onWindows = process.platform === 'win32';
   const deadlineMs =
-    typeof budgetMinutes === 'number' && Number.isFinite(budgetMinutes) && budgetMinutes > 0
+    Number.isFinite(budgetMinutes) && budgetMinutes > 0
       ? budgetMinutes * 60 * 1000
       : null;
   let exited = false;

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

@@ -27,7 +27,8 @@ import { parseArgs, die } from './args.mjs';
 import { settleTaskInput } from './task-input.mjs';
 import { parseContinuationGrant } from '../required-inputs.mjs';
 import { continuationRefusal } from './continuation.mjs';
-import { SCHEMAS } from './schemas.mjs';
+import { parseAdvisorTask } from '../meta/advisor-task.mjs';
+import { schemaFor } from './schemas.mjs';
 import { INSTRUCTIONS } from './prompts.mjs';
 import { git, headSha, branchName, worktreeSnapshot, reviewScope } from './git-state.mjs';
 import { agentRole } from '../agents.mjs';
@@ -40,7 +41,7 @@ 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 } from './preflight.mjs';
+import { preflightRefusal, resolveRunPhase, scopeRunRefusal, taskPreflight } from './preflight.mjs';
 
 /**
  * The worker is this same program re-invoked as `--worker <runDir>`, so the path spawned
@@ -93,7 +94,11 @@ export const runDirPath = (root, slug, runStamp = stamp()) => {
 export async function launcher(argv = process.argv.slice(2)) {
   loadRunEnv();
   const opts = parseArgs(argv);
+  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 topLevel = git(opts.repo, ['rev-parse', '--show-toplevel']);
   const isGitRepo = topLevel.status === 0;
   const repoRoot = isGitRepo ? topLevel.stdout.trim() : opts.repo;
@@ -155,6 +160,10 @@ export async function launcher(argv = process.argv.slice(2)) {
     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);
 
   // 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
@@ -230,6 +239,8 @@ export async function launcher(argv = process.argv.slice(2)) {
     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,
@@ -263,6 +274,7 @@ export async function launcher(argv = process.argv.slice(2)) {
   if (opts.agent === 'codex-scout') {
     fs.writeFileSync(path.join(runDir, 'questions.json'), `${JSON.stringify(questions, null, 2)}\n`);
   }
+  if (opts.agent === 'codex-advisor') fs.writeFileSync(path.join(runDir, 'advisor-task.json'), `${JSON.stringify(parseAdvisorTask(taskText), null, 2)}\n`);
 
   if (opts.agent === 'codex-build') {
     fs.writeFileSync(path.join(runDir, 'scope.txt'), `${opts.scopePatterns.join('\n')}\n`);
@@ -308,7 +320,7 @@ export async function launcher(argv = process.argv.slice(2)) {
   fs.writeFileSync(path.join(runDir, 'task.md'), `${sections.join('\n\n')}\n`);
   fs.writeFileSync(
     path.join(runDir, 'schema.json'),
-    `${JSON.stringify(SCHEMAS[opts.agent], null, 2)}\n`,
+    `${JSON.stringify(schemaFor(opts.agent, opts.phase), null, 2)}\n`,
   );
 
   if (opts.agent === 'codex-build') {
@@ -341,7 +353,8 @@ export async function launcher(argv = process.argv.slice(2)) {
     repo: repoRoot,
     isGitRepo,
     launcherPid: process.pid,
-    budgetMinutes: RUN_ENV?.budgets?.[agentRole(opts.agent)],
+    phase: opts.phase,
+    budgetMinutes: RUN_ENV.budgets[agentRole(opts.agent)][opts.phase],
     scopeNew: opts.scopeNewPatterns,
     profile: runProfile({ ...opts, repo: repoRoot }),
     args: codexArgv,