@lyupro/codex-bridge 0.6.4 → 0.6.5

package/CHANGELOG.md

@@ -4,6 +4,51 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.5] - 2026-09-23
+
+### Added
+
+- A fourth dispatcher, `codex-advisor`, answers "which option is right" before any code is written.
+  The other three answer what is: what the code contains, make the change, what is wrong with a
+  finished diff. An orchestrator asked for advice four times in a row only after the fact, each time
+  convinced its own design was sound — so the advisor is read-only, runs on the Codex subscription,
+  and its answer is judged by the package rather than trusted. It works in two phases of one order:
+  `scope` (5 minutes) says whether the listed files are enough and names the missing ones, and
+  `advise` (15 minutes) continues that run with `--continue` and picks one option. An insufficient
+  scope is an `OK` run with `sufficient: false` and the missing paths in `meta.json`, never `LIMIT`:
+  `LIMIT` means the quota is gone and calls for the opposite reaction.
+- Agreement is made structurally hard to express. The task lists options as `- id: description`
+  with no preference marker — a task that says which option the orchestrator leans towards is refused
+  before the run starts, because an advisor that knows the expected answer agrees with it. The answer
+  names exactly one option id (or `none-of-these` with an unlisted option, and then every listed
+  option is rejected with its cost), a non-empty `rejected` list with costs, the strongest
+  counterargument, assumptions rated `VERIFIED | REASONABLE | FRAGILE`, a pre-mortem whose early
+  checks are a test, a command or an inspectable address, and what the advisor checked on its own.
+- Every `path:line` in the advice is checked: it must exist in the worktree, fall within the file,
+  and lie inside the listed paths or the paths phase 1 declared missing. The sandbox cannot restrict
+  what Codex reads, so the boundary is held on the output — an invented or out-of-scope citation fails
+  the run.
+- A run phase is a runner concept, not an advisor detail. `--phase` is checked against the phases the
+  role declares, travels through `worker.json`, `status.json` and `meta.json`, and the budget resolves
+  by role and phase in one place. `budgets.<role>` in the config accepts a number for single-phase
+  roles and a phase map (`{"scope": 5, "advise": 15}`, partial maps allowed) for roles with phases; a
+  bare number for a role with phases is refused on reading the config instead of silently erasing
+  its phases. Existing configs stay valid without edits.
+- Every `codex-build` task file carries exactly one `advice:` line: the folder of the advisor run
+  behind the order, or one of `mechanical | revert | docs-only | test-only` for work that needs no
+  second opinion. Anything else is refused before the run starts, and the value lands in `meta.json`,
+  so skipped advice is measurable instead of remembered.
+
+### Fixed
+
+- A scope pattern inside a service directory is refused before the run starts. The verdict fails
+  every change under `.git/`, `.claude/`, `.codex/`, `.omx/`, `.omc/` and `node_modules/` whatever the
+  scope says, but the preflight check let such a pattern through: an order scoped to
+  `.claude/context/architecture.md` worked 22 minutes, wrote every file correctly and was failed for
+  one of them. The check now uses the verdict's own definition of a service directory, so the gate and
+  the judge cannot become two measures of one tree. A glob that can also match ordinary files
+  (`**/*.md`) is still accepted.
+
 ## [0.6.4] - 2026-09-21
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # codex-bridge
 
-**Delegate implementation, reconnaissance and review from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
+**Delegate implementation, reconnaissance, review and design advice from Claude Code to Codex — six host guards, zero runtime dependencies, zero build steps.**
 
 [![npm version](https://img.shields.io/npm/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
 [![Node.js](https://img.shields.io/node/v/@lyupro/codex-bridge)](https://www.npmjs.com/package/@lyupro/codex-bridge)
@@ -33,7 +33,7 @@ Use `--scope project` to install the Claude Code-facing files under `<repo>/.cla
 Installation has two roots:
 
 - `~/.lyupro/.codex-bridge/` contains package runtime files, guards, configuration, conventions, and the installation record.
-- The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the three agents, two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
+- The selected Claude Code root (`~/.claude/` or `<repo>/.claude/`) contains the four agents (`codex-scout`, `codex-build`, `codex-review`, `codex-advisor`), two slash commands, merged hook registrations in `settings.json`, and run artifacts under `codex-runs/`.
 
 The repository's `src/home/` directory is the literal image copied into the branded root: its
 `hooks/`, `lib/`, `config.json`, and `conventions.md` paths are the host paths without remapping.
@@ -62,7 +62,7 @@ If a global install and a clone coexist, you have two package copies. `codex-bri
 - **Every run leaves an audit folder.** The verbatim task, scope, before/after git state, events, report, verdict, and reason remain together.
 - **Zero runtime dependencies and zero build steps.** The package is plain `.mjs` on the Node.js standard library.
 
-The current suite contains **1177 automated tests: 1176 passing and 1 skipped**.
+The current suite contains **1491 automated tests: 1490 passing and 1 skipped**.
 
 ## Verify
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lyupro/codex-bridge",
-  "version": "0.6.4",
-  "description": "Claude Code-to-Codex delegation with 6 guards, 1177 tests, zero runtime dependencies, and zero build steps.",
+  "version": "0.6.5",
+  "description": "Claude Code-to-Codex delegation with 6 guards, 1491 tests, zero runtime dependencies, and zero build steps.",
   "keywords": [
     "claude-code",
     "codex",

package/src/agents/codex-advisor.md

@@ -0,0 +1,187 @@
+---
+name: codex-advisor
+description: Независимое второе мнение по DESIGN до появления кода — что правильно, а не что уже есть; работу выполняет Codex CLI по подписке ChatGPT, строго read-only. Два этапа: сначала `scope` — достаточно ли переданного списка файлов и какие риски ожидаются; затем `advise` через `--continue` к запуску scope — одна рекомендация по id варианта, отклонённые варианты с ценой, сильнейший контраргумент и pre-mortem. Вызывай до любого поручения `codex-build`, которое придумывает способ реализации (Plan_59 D6: каждый build task file указывает `advice:` — папку этого запуска или `mechanical | revert | docs-only | test-only`). Полный результат — в ~/.claude/codex-runs/, в чате — не более пяти строк и путь. {{CODEX_REQUIRED_INPUTS_SUMMARY}} {{CODEX_STOP_SUMMARY}}
+model: haiku
+tools: Bash
+---
+
+{{CODEX_NO_SELF_EXECUTION}}
+
+You are the advisor dispatcher. One command starts Codex, and its output is your answer.
+
+**Why you exist.** The orchestrator runs on a Claude Max subscription, while Codex runs on a
+ChatGPT subscription. All design reading and reasoning must happen on the Codex side. Every extra
+line you send to chat costs Claude tokens. Therefore: do not read files, do not retell the report,
+and do not reason about the design yourself.
+
+## Required dispatcher inputs
+
+{{CODEX_REQUIRED_INPUTS}}
+
+## What you receive as input
+
+- The task statement: the design question, candidate options, and completion criteria.
+- The path to a task file containing the question and its context. The orchestrator supplies this
+  path; pass it as `--task-file` and never create, read or rewrite it. Writing that file yourself
+  from the shell — `cat > … << EOF` or any equivalent — puts back the permission prompt the flag
+  exists to remove. Given no path, start the runner without the flag and return its refusal.
+- The path to the repository. If none is given, use the current working directory.
+- `phase` is exactly `scope` or `advise`, supplied by the orchestrator and passed as `--phase`.
+  Run `scope` first. Run `advise` only as the continuation of that same order's successful advisor
+  scope run. Never choose or change the phase yourself.
+- The task file must use these headings and list formats:
+  - `## Question` — free-text design question.
+  - `## Options` — at least two lines of the form `- <option_id>: <description>`. Each id must
+    match `[a-z0-9][a-z0-9-]*`; ids must be unique. Do not include preference markers or wording
+    such as `recommend`, `prefer`, `рекоменд`, `предпочт`, `(✓)`, or `★`. The advisor must not
+    know which option the requester favors (D5). Biased or malformed options are refused before
+    quota is spent.
+  - `## Paths` — at least one repository-relative path per list line. The advisor may cite only
+    these paths and, during `advise`, paths the scope run named in `missing_paths`. Each
+    `path:line` citation is machine-checked; an invented or out-of-list address fails the run (D3).
+- Scope patterns are globs relative to the repository root. A pattern that matches nothing there is
+  refused before the run starts. This dispatcher does not accept scope patterns: its file boundary
+  is the explicit `## Paths` list and, for `advise`, the successful scope run's `missing_paths`.
+- Every input listed under **Required dispatcher inputs** above, passed on exactly as given:
+  `order id` as `--order-id`, `task file` as `--task-file`, and `phase` as `--phase`. Use the same
+  order id for both phases; never invent or edit it. If the orchestrator did not give a required
+  input, do not guess — start the runner without its flag and return its refusal verbatim.
+- `continue` — when the task text contains a line beginning with the `continue:` label, pass the
+  bare `--continue` flag even when its run name or reason looks malformed. Do not inspect, repair,
+  or swallow this grant; pass it through and let the runner issue the refusal. A continuation is
+  assigned by the orchestrator, never chosen by you. After the verdict, return the exact attaching
+  output and stop; do not issue or invent another continuation. If no such grant line is present,
+  the flag must not be present. The advise phase requires this grant to continue the scope run.
+- Optional: `slug: <short-name>` for the run folder; by default, the slug is taken from the order
+  id. Optional: `effort: <none|low|medium|high|xhigh|max>` only when the orchestrator named a
+  depth.
+
+## When the host refuses the command
+
+If the host refuses to run `codex-bridge run` — a permission prompt, a classifier denial, anything
+that stops the command — that refusal is your final answer. Report `FAIL`, name your own order id,
+and state the one correction: the operator runs `codex-bridge install`, which grants the permission
+rule this package needs.
+
+You are forbidden to look for a way around it. Specifically, and without exception:
+
+- never call `run-codex.mjs`, or any file inside the installed package, by path;
+- never start the runner through `node`, `npx`, `sh`, `bash` or any other interpreter;
+- never retry the same call in PowerShell because Bash refused it, or the reverse;
+- never split the call over more than one line, and never add a pipe, a semicolon or a redirect;
+- never advise the operator to grant a permission rule on an internal file — a rule on anything but
+  the package command undoes the very design that makes this call permission-stable.
+
+Every one of those forms was removed on purpose: a host matches a permission rule against the
+beginning of the final command line, so an interpreter, a path or a continuation makes the call
+unmatchable by construction. Reaching for one does not rescue the run; it guarantees the refusal.
+
+## The only thing you do
+
+```bash
+codex-bridge run --agent codex-advisor --repo "<repository-path or .>" --phase "<phase from the orchestrator>" --slug "<slug>" --order-id "<order id from the orchestrator>" --task-file "<task-file path from the orchestrator>"
+```
+
+That is one command line. Add only the bare `--continue` when the task text contains a line
+beginning with `continue:`; it has no value. The runner accepts only `1/true/yes/0/false/no` as a
+grant value in the task text, so a malformed grant is passed through for the runner to refuse. If
+there is no grant line, do not add the flag. Add `--effort "<value>"` only if the orchestrator
+named a depth, and only with one of `none|low|medium|high|xhigh|max`. Never add free text or any
+flags beyond those two conditional flags.
+
+The first `scope` call starts the run and returns at once with `RUN=<path> order-id=<id>` and a
+`STARTED` line. To get its verdict, run the identical command a second time — same order id, slug,
+phase and flags. That second call attaches to the existing run and prints `ATTACH=<path>` before
+blocking for the verdict. Do not start another scope run to attach.
+
+After an `OK` scope verdict, the orchestrator may run `advise` with `--continue`, the same order id,
+and the continuation grant it supplied. That call continues the scope run; it is not a new order.
+Attach to that advise run by repeating its identical command if it returns `STARTED`.
+
+If the runner refuses with an order id collision — the id already belongs to a run whose task
+differs — that refusal is the whole answer: return `FAIL` with the runner's text. Never retry under
+a different id of your own choosing; the order id is the orchestrator's.
+
+Background execution (`run_in_background`, `&`, `nohup`) is prohibited, and so is inventing a
+report from memory. If an attaching call is killed by a time ceiling, repeat the identical command
+once with `--no-wait`. This only checks state; it is never a final answer. If stdout contains the
+ready reply, return it normally. If the call exits 4, return to the ordinary waiting call with the
+same order id and without `--no-wait`. A real run takes 20-25 minutes, which is normal, not a hang.
+Give the ordinary attaching call `timeout: 1800000` (30 minutes).
+
+**Never change `--order-id` or `--slug` to get a fresh run.** The order id is issued by the
+orchestrator and is what makes a repeat harmless; changing it turns a repeat into another paid run.
+
+The runner does the rest: validates the task file and phase, creates the run folder and artifacts,
+starts Codex in a read-only sandbox, records status, and prints ready-made response lines. Invalid
+or biased `Options`/`Paths`, `advise` without `--continue`, `advise` without an `OK` advisor scope
+run, and an undeclared phase are free refusals; no ChatGPT quota is spent.
+
+**Your response = the exact stdout of the attaching call**: the `ATTACH=<path>` line and the status
+block below it. Do not add or remove anything: no preamble, explanations, apologies, or retelling
+of findings. The report is in the file; the orchestrator will read it if needed. A `STARTED` result
+is not final.
+
+The only allowed final response is this exact stdout. Wording such as "the run has started,
+waiting for completion," "I will wait for a notification," or "Monitor started in the background"
+is prohibited: the subagent ceases to exist immediately after responding, nobody can wait, and the
+orchestrator gets a promise instead of a result. Inventing any outcome the runner did not print is
+equally prohibited.
+
+## What you return
+
+Return the attaching output exactly as printed by the runner, including its ready-made short
+result and report path. Do not compose, summarize, or improve the result yourself. The full report
+lives under `~/.claude/codex-runs/`; the orchestrator receives no more than five lines plus that
+path.
+
+## The script determines status, not you
+
+- `OK` — the phase result is valid and the runner returned zero. An insufficient scope is still an
+  `OK` scope result, not a quota limit.
+- `FAIL` — the result is empty, invalid, the return code is nonzero, or the run was abandoned.
+- `LIMIT` — the result is empty and the log signals a ChatGPT quota limit. The quota is spent and
+  the task was not completed; do not restart it.
+
+The script return code mirrors the status: `0` / `1` / `3`. A nonzero code is not a reason to
+retry, change the command, or investigate on your own.
+
+For `scope`, `OK — scope: sufficient; …` means the listed paths cover the question; continue with
+`--phase advise` only when the orchestrator supplies that continuation. `OK — scope: insufficient;
+N paths named` followed by a `Missing:` line is also an `OK` run, not a `LIMIT`: the orchestrator
+may add context or continue with `advise`. `LIMIT` alone means the ChatGPT quota is spent.
+
+For `advise`, expect `OK — recommend <option_id>: …`, followed by `Rejected:`, `Counter:`, and
+`Risks:` lines. The recommendation names one option id, rejected options include their cost,
+`Counter:` gives the strongest counterargument, and `Risks:` is the pre-mortem. Forward those lines
+verbatim; compose nothing.
+
+The run folder contains its status and artifacts. An abandoned run is not a reason to start over
+yourself: the orchestrator decides whether to continue, and without the `--continue` it issued,
+the runner will reject that continuation itself.
+
+## Codex is unavailable
+
+The runner checks `codex --version` before starting. If the binary is missing or authentication
+failed, it prints a ready-made `FAIL` with a verification command for the operator. Return that
+output. Performing the task manually instead of Codex is prohibited for any reason it fails.
+
+## What a violation looks like
+
+Correct (runner output copied exactly):
+
+```
+ATTACH=<artifact root>\myproject\2026-09-22_1412_advisor started=2026-09-22T14:12:03.000Z
+OK — recommend service-boundary: the interface keeps ownership local
+Rejected: shared-kernel — every consumer now pays for cross-domain coupling
+Counter: a shared contract could reduce duplicated validation
+Risks: the boundary may be wrong if a second consumer needs synchronous access
+Report: ...\report.md · Log: ...\2026-09-22_1412_advisor
+```
+
+Incorrect — "Codex started in the background. Waiting for the advice to finish — I will notify
+you." There will be no notification: as a dispatcher, you terminate with the response, so nobody
+can wait and send one. Background execution is prohibited above.
+
+Incorrect — "I reviewed the design manually because Codex could not read one of the paths," followed
+by recommendations. This defeats the boundary: all reading and reasoning belong to the Codex run.

package/src/agents/codex-build.md

@@ -51,6 +51,10 @@ job is to report the run status honestly, including failure.
   heading, one line. You never read that file and never put the command on the command line: an
   operator's real check command contained `&&`, and a compound operator in an argument makes the
   host stop applying its permission rule, which is how a delegation dies on a refusal.
+- Every build task file must contain exactly one `advice:` line from the orchestrator: an absolute
+  path to an existing run folder whose `meta.json` identifies `codex-advisor`, or exactly
+  `mechanical`, `revert`, `docs-only`, or `test-only`. Anything else is refused before the run
+  starts. Pass the task file as supplied; the orchestrator owns this line.
 
 ## When the host refuses the command
 

package/src/commands/env.md

@@ -9,10 +9,11 @@ argument-hint: "[hooks|plugins on|off] | [reset]"
      symlinks nor pointer files (verified 2026-08-02). Edit it here; it travels as a copy when the
      package is installed. -->
 
-Environment switches for `codex-scout` / `codex-build` / `codex-review` runs. By default the hooks
-and plugins from `~/.codex` do not reach a delegated run: they are written for interactive work and
-do harm in an automated one — the failing `Stop` hook of `oh-my-codex` would not let Codex leave the
-session, and instead of doing the task it quarantined `.omx/state/session.json`. The operator's
+Environment switches for `codex-scout` / `codex-build` / `codex-review` / `codex-advisor` runs.
+By default the hooks and plugins from `~/.codex` do not reach a delegated run: they are written for
+interactive work and do harm in an automated one — the failing `Stop` hook of `oh-my-codex` would
+not let Codex leave the session, and instead of doing the task it quarantined
+`.omx/state/session.json`. The operator's
 interactive Codex is untouched: the flags are set on one specific runner invocation,
 `~/.codex/hooks.json` is not modified.
 

package/src/home/lib/agents.mjs

@@ -1,5 +1,6 @@
 /**
  * Defines each delegated agent's role, wall-clock budget, write access and result file.
+ * D2: a budget declares positive minutes or named phases; budgets.mjs alone normalizes it.
  *
  * The three agents were listed four times: twice in run-config.mjs for budgets and models,
  * once in codex-args.mjs for role lookup, and once in order-gate.mjs for guarded names.
@@ -10,6 +11,8 @@ export const AGENTS = {
   'codex-scout': { role: 'scout', budget: 15, writes: false, result: 'result.json' },
   'codex-build': { role: 'build', budget: 25, writes: true, result: 'result.json' },
   'codex-review': { role: 'review', budget: 20, writes: false, result: 'review.json' },
+  // Plan_59: design advice needs a bounded scope pass before the continued decision pass.
+  'codex-advisor': { role: 'advisor', budget: { scope: 5, advise: 15 }, writes: false, result: 'result.json' },
 };
 
 export const agentRole = (agent) => AGENTS[agent]?.role;

package/src/home/lib/budgets.mjs

@@ -0,0 +1,64 @@
+/**
+ * Resolves every role's wall-clock budget into a map of phase names to minutes.
+ *
+ * A run gets a hard wall-clock budget, because the caller's timeout is not a run contract:
+ * on 2026-08-03 one order restarted six times and spent 170,293 accounted tokens while four
+ * killed callers left their Codex processes and token spend unrecorded. Plan_59 D2 made the
+ * phase a runner concept: a number is shorthand for one `default` phase, and it is expanded
+ * here and nowhere else, so no consumer ever has to ask which of the two shapes it holds.
+ */
+import { AGENTS } from './agents.mjs';
+
+export function resolveBudgets(file, overrides = {}, registry = AGENTS) {
+  const roles = Object.values(registry).map(({ role }) => role);
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    throw new Error(`${file}: key “budgets” must be an object keyed by ${roles.join(', ')}, ` +
+      `each holding a positive number of minutes or a phase map, not ${JSON.stringify(overrides)}`);
+  }
+  const normalize = (budget, key, defaults) => {
+    if (typeof budget === 'string' && !budget.trim()) {
+      throw new Error(`${file}: key “${key}” is empty; remove the field to use the default, ` +
+        'or give it a positive number of minutes or a phase map');
+    }
+    const scalar = typeof budget === 'number';
+    // A number for a role with named phases would replace its whole map with `default`: the
+    // config would read cleanly and every run of that role would then be refused.
+    if (scalar && defaults && Object.keys(defaults).some((phase) => phase !== 'default')) {
+      throw new Error(`${file}: key “${key}” must be a phase map for this role, ` +
+        `e.g. {${Object.keys(defaults).map((phase) => `"${phase}": ${defaults[phase]}`).join(', ')}}, ` +
+        `not ${JSON.stringify(budget)}`);
+    }
+    if (scalar) budget = { default: budget };
+    if (!budget || typeof budget !== 'object' || Array.isArray(budget)) {
+      throw new Error(`${file}: key “${key}” must be a positive number of minutes or a phase map, ` +
+        `not ${JSON.stringify(budget)}`);
+    }
+    for (const [phase, minutes] of Object.entries(budget)) {
+      if (!phase.trim()) throw new Error(`${file}: key “${key}” has an empty phase name`);
+      if (defaults && !scalar && !Object.hasOwn(defaults, phase)) {
+        throw new Error(`${file}: key “${key}” has unknown phase “${phase}”. ` +
+          `Only ${Object.keys(defaults).join(', ')} are allowed`);
+      }
+      if (!Number.isFinite(minutes) || minutes <= 0) {
+        throw new Error(`${file}: key “${key}.${phase}” must be a positive number of minutes, ` +
+          `not ${JSON.stringify(minutes)}`);
+      }
+    }
+    // D2: a scalar is a default-only budget; only an object requests a partial phase override.
+    return { ...(scalar ? {} : defaults), ...budget };
+  };
+  const budgets = Object.fromEntries(Object.values(registry).map(({ role, budget }) => {
+    const phases = normalize(budget, `budgets.${role}`);
+    if (!Object.keys(phases).length) {
+      throw new Error(`${file}: key “budgets.${role}” must declare at least one phase`);
+    }
+    return [role, phases];
+  }));
+  for (const [role, budget] of Object.entries(overrides)) {
+    if (!roles.includes(role)) {
+      throw new Error(`${file}: key “budgets” has unknown role “${role}”. Only ${roles.join(', ')} are allowed`);
+    }
+    budgets[role] = normalize(budget, `budgets.${role}`, budgets[role]);
+  }
+  return budgets;
+}

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

@@ -1,5 +1,6 @@
 /** Shared by reading and editing so Plan_56 D27 cannot persist an unreadable config. */
 import { AGENTS } from './agents.mjs';
+import { resolveBudgets } from './budgets.mjs';
 
 const BUDGET_KEY = 'budgets';
 export const ROLES = Object.values(AGENTS).map(({ role }) => role);
@@ -31,7 +32,7 @@ export const DEFAULTS = {
   hooks: false,
   plugins: false,
   models: {},
-  budgets: Object.fromEntries(Object.values(AGENTS).map(({ role, budget }) => [role, budget])),
+  budgets: resolveBudgets('agent registry'),
   retention: DEFAULT_RETENTION,
   environmentPaths: DEFAULT_ENVIRONMENT_PATHS,
   answerLanguage: 'English',
@@ -88,43 +89,6 @@ function readRetention(file, value) {
   return { enabled: true, days: value.days };
 }
 
-/**
- * A run gets a hard wall-clock budget, because the caller's timeout is not a run contract:
- * on 2026-08-03 one order restarted six times and spent 170,293 accounted tokens while four
- * killed callers left their Codex processes and token spend unrecorded.
- */
-function readBudgets(file, value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(
-      `${file}: key “${BUDGET_KEY}” must be an object keyed by ${ROLES.join(', ')}, ` +
-        `each holding a positive number of minutes, not ${JSON.stringify(value)}`,
-    );
-  }
-  const budgets = { ...DEFAULTS.budgets };
-  for (const [role, minutes] of Object.entries(value)) {
-    if (!ROLES.includes(role)) {
-      throw new Error(
-        `${file}: key “${BUDGET_KEY}” has unknown role “${role}”. ` +
-          `Only ${ROLES.join(', ')} are allowed`,
-      );
-    }
-    if (typeof minutes === 'string' && !minutes.trim()) {
-      throw new Error(
-        `${file}: key “${BUDGET_KEY}.${role}” is empty; remove the field to use the default ` +
-          `(${DEFAULTS.budgets[role]} minutes), or give it a positive number of minutes`,
-      );
-    }
-    if (typeof minutes !== 'number' || !Number.isFinite(minutes) || minutes <= 0) {
-      throw new Error(
-        `${file}: key “${BUDGET_KEY}.${role}” must be a positive number of minutes, ` +
-          `not ${JSON.stringify(minutes)}`,
-      );
-    }
-    budgets[role] = minutes;
-  }
-  return budgets;
-}
-
 export function validateRunConfig(file, parsed) {
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
     throw new Error(`${file} must contain an object like {"hooks": false, "plugins": false}`);
@@ -145,7 +109,7 @@ export function validateRunConfig(file, parsed) {
       continue;
     }
     if (key === BUDGET_KEY) {
-      config[key] = readBudgets(file, value);
+      config[key] = resolveBudgets(file, value);
       continue;
     }
     if (key === RETENTION_KEY) {

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

@@ -0,0 +1,61 @@
+/** Converts a finished advisor run into judge inputs because schemas accept well-formed agreement; Plan_59 D3/D4/D5/D10 require the judge to reject it. */
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULTS } from '../run-config.mjs';
+import { judgeAdvice } from './advice-verdict.mjs';
+import { readJson } from './paths.mjs';
+
+function contractReason(reasons) {
+  const message = `advice contract broken (${reasons.length}): ${reasons.slice(0, 2).join('; ')}`;
+  return message.length <= 200 ? message : `${message.slice(0, 197)}...`;
+}
+
+export function adviceGap(runDir, result, eventData) {
+  const worker = readJson(path.join(runDir, 'worker.json')) || {};
+  const status = readJson(path.join(runDir, 'status.json')) || {};
+  const env = readJson(path.join(runDir, 'env.json')) || {};
+  const phase = worker.phase ?? status.phase;
+  const taskFile = path.join(runDir, 'advisor-task.json');
+  const task = readJson(taskFile);
+  const reasons = [];
+
+  if (!fs.existsSync(taskFile)) reasons.push('advisor-task.json is missing');
+  else if (!Array.isArray(task?.options) || !Array.isArray(task?.paths)) {
+    reasons.push('advisor-task.json is missing parsed options or paths');
+  }
+  if (phase !== 'scope' && phase !== 'advise') reasons.push('worker.json/status.json is missing a valid advisor phase');
+  if (typeof status.repo !== 'string' || !status.repo) reasons.push('status.json#repo is missing');
+  if (!Number.isInteger(eventData?.commands_executed) || eventData.commands_executed < 0) {
+    reasons.push('eventData.commands_executed is missing or invalid');
+  }
+  if (!result || typeof result !== 'object' || Array.isArray(result)) reasons.push('result.json is missing or is not an object');
+
+  let scopeResult;
+  if (phase === 'advise') {
+    if (typeof status.continued_from !== 'string' || !status.continued_from) {
+      reasons.push('status.json#continued_from for the phase-1 result is missing');
+    } else {
+      const scopeFile = path.join(path.dirname(runDir), status.continued_from, 'result.json');
+      scopeResult = readJson(scopeFile);
+      if (!scopeResult || typeof scopeResult !== 'object' || !Array.isArray(scopeResult.predicted_risks)) {
+        reasons.push('phase-1 result.json or its predicted_risks is missing');
+      }
+    }
+  }
+  if (reasons.length) return contractReason(reasons);
+
+  try {
+    const verdict = judgeAdvice({
+      phase,
+      result,
+      task,
+      repoRoot: status.repo,
+      commandsRun: eventData.commands_executed,
+      language: env.answerLanguage ?? DEFAULTS.answerLanguage,
+      scopeResult,
+    });
+    return verdict.ok ? null : contractReason(verdict.reasons);
+  } catch (error) {
+    return contractReason([`result.json is missing required fields or has an unexpected shape (${error.message})`]);
+  }
+}