@lyupro/codex-bridge 0.6.4 → 0.6.5

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

@@ -4,8 +4,82 @@
  * only the project runs root and existing holders, never the prospective run's directory.
  */
 import path from 'node:path';
-import { activeRunDetails } from '../write-meta.mjs';
+import fs from 'node:fs';
+import { advisorTaskRefusal } from '../meta/advisor-task.mjs';
+import { activeRunDetails, readJson } from '../write-meta.mjs';
 import { codexUnavailableReason } from './codex-cmd.mjs';
+import { agentRole } from '../agents.mjs';
+import { die } from './args.mjs';
+
+/** Plan_59 D5/D6: settle design authority before any probe can spend quota. */
+export function taskPreflight({ agent, taskText }) {
+  const freeRefusal = (reason) => ({
+    refusal: `${reason}\nThe run folder was not created; quota was not spent.`,
+  });
+  if (agent === 'codex-advisor') {
+    const reason = advisorTaskRefusal(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) {
+    if (['mechanical', 'revert', 'docs-only', 'test-only'].includes(advice)) {
+      return { refusal: null, advice };
+    }
+    if (path.isAbsolute(advice)) {
+      try {
+        if (fs.statSync(advice).isDirectory() &&
+            readJson(path.join(advice, 'meta.json'))?.agent === 'codex-advisor') {
+          return { refusal: null, advice };
+        }
+      } catch {
+        // Plan_59 D6: missing or unreadable evidence cannot authorize a construction.
+      }
+    }
+  }
+  return freeRefusal('codex-build requires exactly one advice: line: mechanical | revert | docs-only | test-only ' +
+    'or an absolute path to an existing advisor run directory with meta.json agent codex-advisor. ' +
+    'An order that invents a construction needs a second opinion first; only work with no design choice may skip it.');
+}
+
+/** Plan_59 D14: an advice pass may continue only a completed, successful advisor scope run. */
+export function scopeRunRefusal({ agent, phase, runsRoot, grantRun }) {
+  if (agent !== 'codex-advisor' || phase !== 'advise') return null;
+  let meta;
+  try {
+    meta = readJson(path.join(runsRoot, grantRun, 'meta.json'));
+  } catch {
+    meta = null;
+  }
+  const failed = [
+    meta?.agent === 'codex-advisor' ? null : "agent must be 'codex-advisor'",
+    meta?.phase === 'scope' ? null : "phase must be 'scope'",
+    meta?.status === 'OK' ? null : "status must be 'OK'",
+  ].filter(Boolean);
+  if (!failed.length) return null;
+  return `continued run meta.json failed ${failed.join(', ')}. The run folder was not created; quota was not spent.`;
+}
+
+/** D2: phase mistakes must refuse before even the sandbox probe can spend quota. */
+export function resolveRunPhase({ agent, phase, continue: isContinue }, budgets) {
+  // 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 ' +
+      '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(', ')}. ` +
+    'The run folder was not created; quota was not spent.');
+}
 
 export function preflightRefusal({ agent, projectRunsRoot, repoRoot }) {
   // Two writing runs share one tree: the second snapshot would include the first one's edits.

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

@@ -8,6 +8,45 @@
 import { DEFAULTS } from '../run-config.mjs';
 import { RUN_ENV } from './run-env.mjs';
 const BODIES = {
+  // Plan_59 D3-D5/D7/D10: independent design advice needs explicit lenses and a risk ledger.
+  'codex-advisor': (opts) => {
+    if (opts.phase !== 'scope' && opts.phase !== 'advise') {
+      throw new RangeError('codex-advisor instructions require phase scope or advise.');
+    }
+    return `Judge a DESIGN before code exists.
+
+Rules for both phases:
+- Read ONLY the paths listed under \`## Paths\`, plus \`git log\` / \`git show\` on those paths.
+- Write nothing. Do your own reading and checks; do not spawn or delegate to other agents.
+- Every claim about code must carry a \`path:line\` address inside those paths. Addresses are
+  machine-checked for existence; do not invent addresses or treat an unchecked claim as evidence.
+- Do not guess which option the caller prefers: the task carries no preference on purpose.
+- Two failure modes are forbidden: agreeing without independent checks ("both options are good",
+  "you know better"), and disagreeing to look independent. A disagreement without an address is
+  an opinion, not advice. Agreeing is fine when your own checks support it.
+${opts.phase === 'scope' ? `
+Scope phase:
+- BEFORE reading in depth, name 3-5 predicted_risks with ids r1..r5: where this design most likely
+  breaks. Record those predictions first, then read; do not replace them with hindsight.
+- Answer sufficient, missing_paths (concrete repository paths you still need), and taken_on_trust
+  (facts accepted from the task without checking, never empty), together with predicted_risks.
+` : `
+Advise phase:
+- Settle every predicted risk from the scope run in risk_outcomes: its risk_id, an outcome of
+  confirmed or refuted, and an address supporting that outcome.
+- Give ONE recommendation by task option_id, or none-of-these with a described unlisted_option.
+  Put every rejected task option in rejected with its cost; for none-of-these this means EVERY
+  task option. Set unlisted_option to "none" when recommending a listed option.
+- Each field is a distinct lens: strongest_counterargument comes from a skeptic;
+  pre_mortem comes from the executor who has only this advice and the repository. Give each
+  scenario an early_check of kind test | command | inspect with a target; inspect requires an address.
+- question_defect comes from the requester who needs the problem solved, not an option picked.
+- Rate assumptions VERIFIED (requires an address) | REASONABLE | FRAGILE. Anything the requester
+  could refute with knowledge you lack belongs in open_questions, not why.
+- independent_checks lists what you verified yourself, with addresses. Ground why in those checks
+  and state confidence honestly.
+`}`;
+  },
   'codex-scout': (opts, scope, questions = []) => `Response rules:
 - You are working in read-only mode: do not try to write or edit anything.
 - Answer from your own reading: do not spawn or delegate to other agents.

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

@@ -1,5 +1,6 @@
 /**
  * The shape each agent's answer must have, one JSON schema per agent.
+ * Plan_59 D10 adds alternatives, rated assumptions, risk outcomes, pre-mortems and open questions.
  *
  * Handed to `codex exec --output-schema`, so a run that answers in the wrong shape is
  * rejected by Codex itself rather than discovered later by write-meta.mjs. Keyed by agent
@@ -149,9 +150,144 @@ const REVIEW_SCHEMA = {
   },
 };
 
-/** Same three keys as AGENTS in write-meta.mjs; parseArgs() has already refused anything else. */
+/** Plan_59: execution schemas stay static; schemaFor selects the advisor contract by phase. */
 export const SCHEMAS = {
   'codex-scout': SCOUT_SCHEMA,
   'codex-build': BUILD_SCHEMA,
   'codex-review': REVIEW_SCHEMA,
 };
+
+// Plan_59 D3/D4/D5/D10 keeps the design contract separate from the existing execution roles.
+export const PHASE_SCHEMAS = {
+  advisor: {
+    scope: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      additionalProperties: false,
+      required: ['sufficient', 'missing_paths', 'taken_on_trust', 'predicted_risks'],
+      properties: {
+        sufficient: { type: 'boolean' },
+        missing_paths: { type: 'array', items: { type: 'string' } },
+        taken_on_trust: { type: 'array', minItems: 1, items: { type: 'string' } },
+        predicted_risks: {
+          type: 'array',
+          minItems: 3,
+          maxItems: 5,
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['id', 'risk'],
+            properties: { id: { type: 'string', pattern: '^r[1-9]$' }, risk: { type: 'string' } },
+          },
+        },
+      },
+    },
+    advise: {
+      $schema: 'https://json-schema.org/draft/2020-12/schema',
+      type: 'object',
+      additionalProperties: false,
+      required: [
+        'recommendation', 'why', 'rejected', 'strongest_counterargument', 'question_defect',
+        'unlisted_option', 'assumptions', 'risk_outcomes', 'pre_mortem', 'open_questions',
+        'confidence', 'independent_checks',
+      ],
+      properties: {
+        recommendation: {
+          type: 'object',
+          additionalProperties: false,
+          required: ['option_id', 'text'],
+          properties: {
+            option_id: { type: 'string' },
+            text: { type: 'string', maxLength: 300, pattern: '^[^\\r\\n\\u2028\\u2029]*$' },
+          },
+        },
+        unlisted_option: { type: 'string' },
+        why: { type: 'array', minItems: 3, maxItems: 5, items: { type: 'string' } },
+        rejected: {
+          type: 'array',
+          minItems: 1,
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['option_id', 'cost'],
+            properties: { option_id: { type: 'string' }, cost: { type: 'string' } },
+          },
+        },
+        strongest_counterargument: { type: 'string', minLength: 80 },
+        question_defect: { type: 'string' },
+        assumptions: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['claim', 'rating', 'address'],
+            properties: {
+              claim: { type: 'string' },
+              rating: { type: 'string', enum: ['VERIFIED', 'REASONABLE', 'FRAGILE'] },
+              address: { type: 'string' },
+            },
+          },
+        },
+        risk_outcomes: {
+          type: 'array',
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['risk_id', 'outcome', 'address'],
+            properties: {
+              risk_id: { type: 'string' },
+              outcome: { type: 'string', enum: ['confirmed', 'refuted'] },
+              address: { type: 'string' },
+            },
+          },
+        },
+        pre_mortem: {
+          type: 'array',
+          minItems: 2,
+          maxItems: 3,
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['scenario', 'early_check'],
+            properties: {
+              scenario: { type: 'string', minLength: 30 },
+              early_check: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['kind', 'target'],
+                properties: {
+                  kind: { type: 'string', enum: ['test', 'command', 'inspect'] },
+                  target: { type: 'string', minLength: 3 },
+                },
+              },
+            },
+          },
+        },
+        open_questions: { type: 'array', items: { type: 'string' } },
+        confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+        independent_checks: {
+          type: 'array',
+          minItems: 1,
+          items: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['check', 'address'],
+            properties: { check: { type: 'string' }, address: { type: 'string' } },
+          },
+        },
+      },
+    },
+  },
+};
+
+// Plan_59: an advisor's phase, not its agent name alone, defines the answer contract.
+export function schemaFor(agent, phase) {
+  return agent === 'codex-advisor' ? advisorSchema(phase) : SCHEMAS[agent];
+}
+
+export function advisorSchema(phase) {
+  if (!Object.hasOwn(PHASE_SCHEMAS.advisor, phase)) {
+    throw new RangeError(`Unknown advisor phase ${JSON.stringify(phase)}; use "scope" or "advise".`);
+  }
+  return PHASE_SCHEMAS.advisor[phase];
+}

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

@@ -7,7 +7,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { globToRegExp, normalizePath } from '../meta/paths.mjs';
+import { globToRegExp, normalizePath, SERVICE_RE } from '../meta/paths.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
@@ -43,6 +43,14 @@ function structuralRefusal(repoRoot, pattern) {
       action: 'remove the .. segment and keep the path relative to the repository root',
     };
   }
+  // Plan_59 S1: 2026-09-22_235724_plan59-d1-advisor-docs-surface spent 22 minutes on a
+  // service-directory scope the verdict could never authorise. Refuse it before a run exists.
+  if (SERVICE_RE.test(normalizePath(pattern))) {
+    return {
+      reason: 'lies inside a service directory that no scope can authorise',
+      action: 'name the file outside the service directory, or make that edit yourself',
+    };
+  }
   // Plan_58 D7: 2026-09-19_191402_ports-infra spent a run on a bare scope-new directory,
   // which the verdict could only match as a file. Refuse that intent before spending a run.
   if (!pattern || /[*?]/.test(pattern)) return null;

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

@@ -4,7 +4,7 @@
  * After the launcher/worker split this file is the only connection between the two halves, and the
  * worker never re-reads the CLI or the configuration — a run that consulted config.json twice could
  * end up honouring two different limits. It carries `agent`, `slug`, `order_id`, `repo`,
- * `is_git_repo`, `launcher_pid`, `budget_minutes`, `scope_new`, `profile` and `args`; worker.mjs
+ * `is_git_repo`, `launcher_pid`, `phase`, `budget_minutes`, `scope_new`, `profile` and `args`; worker.mjs
  * reads `repo`, `agent`, `args`, `is_git_repo` and `budget_minutes`. The rest is deliberate: those
  * fields are what a run folder read back months later needs in order to explain itself — which
  * order it belonged to, which new paths it declared included, and which worker was actually
@@ -24,6 +24,7 @@ export function workerOrder({
   repo,
   isGitRepo,
   launcherPid,
+  phase,
   budgetMinutes,
   scopeNew,
   profile,
@@ -36,7 +37,8 @@ export function workerOrder({
     repo,
     is_git_repo: isGitRepo,
     launcher_pid: launcherPid,
-    // The mode's wall-clock budget, resolved by the launcher and never re-read by the worker.
+    phase,
+    // D2: the phase's wall-clock budget is frozen before the worker, never re-read from config.
     budget_minutes: budgetMinutes,
     scope_new: scopeNew,
     // Which worker was ordered, and where each half of that answer came from. Recorded separately

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

@@ -4,8 +4,8 @@
  * It takes its whole order from worker.json, written by launcher.mjs into the run folder —
  * after the split that file is the only connection between the two halves. Read here:
  * `repo`, `agent`, `args`, `is_git_repo`, `budget_minutes`. Written there: those five plus
- * `slug`, `launcher_pid` and `scope_new`, which nothing here needs but a run folder read back
- * months later does. The launcher must write the selected mode's budget into worker.json before
+ * `phase`, `slug`, `launcher_pid` and `scope_new`, which nothing here needs but a run folder read back
+ * months later does. The launcher must write the selected phase's budget into worker.json before
  * spawning this half, so the worker never re-reads config.json and one run cannot acquire two
  * configurations.
  * Neither side may change the shape alone.

package/src/home/lib/write-meta.mjs

@@ -82,6 +82,7 @@ export function collect(runDir, agent, exitCode) {
   const exit = exitCode === undefined || exitCode === null ? null : Number(exitCode);
   const events = readEvents(runDir);
   const worker = readJson(path.join(runDir, 'worker.json'));
+  const launched = readJson(path.join(runDir, 'status.json')) || {};
 
   const args = Array.isArray(worker?.args) ? worker.args : [];
   const argValue = (flag) => {
@@ -99,6 +100,18 @@ export function collect(runDir, agent, exitCode) {
 
   const meta = {
     agent,
+    // D2: old runs have no phase fact; do not invent one from today's registry.
+    phase: worker?.phase ?? launched.phase ?? null,
+    // Plan_59 D4: the scope outcome is a field the orchestrator branches on, not a sentence in
+    // the reply. Null when the result never said, so a missing answer is not read as "sufficient".
+    ...(agent === 'codex-advisor'
+      ? {
+          sufficient: typeof result?.sufficient === 'boolean' ? result.sufficient : null,
+          missing_paths: Array.isArray(result?.missing_paths) ? result.missing_paths : null,
+        }
+      : {}),
+    // Plan_59 D6: which second opinion a build order named, so skipped advice is measurable.
+    ...(agent === 'codex-build' ? { advice: launched.advice ?? null } : {}),
     runner_version: RUNNER_VERSION,
     project: path.basename(path.dirname(runDir)),
     run: path.basename(runDir),