@lyupro/codex-bridge 0.6.2 → 0.6.5

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
@@ -24,7 +24,7 @@ function absolutePattern(pattern) {
   );
 }
 
-function structuralRefusal(pattern) {
+function structuralRefusal(repoRoot, pattern) {
   if (absolutePattern(pattern)) {
     return {
       reason: 'is an absolute or drive-qualified path',
@@ -43,6 +43,34 @@ function structuralRefusal(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;
+  const reason = 'names a directory rather than a file';
+  const action = `write ${pattern.replace(/\/$/, '')}/** for everything inside it, or name the file itself`;
+  if (pattern.endsWith('/')) return { reason, action };
+
+  let entry;
+  try {
+    entry = fs.statSync(path.join(repoRoot, pattern));
+  } catch {
+    // An unreadable or vanished path is treated as missing, so only its spelling is checked.
+  }
+  if (entry?.isDirectory()) return { reason, action };
+  if (!entry && !pattern.split('/').at(-1).includes('.')) {
+    return {
+      reason,
+      action: `write ${pattern}/** if it is a directory, or declare the new file by its own name with an extension; a new extensionless file is declared through its directory`,
+    };
+  }
   return null;
 }
 
@@ -133,7 +161,7 @@ export function validateScope(repoRoot, patterns, scopeNewPatterns = []) {
   const allPatterns = [...declared, ...newPaths];
 
   for (const pattern of allPatterns) {
-    const refusal = structuralRefusal(pattern);
+    const refusal = structuralRefusal(repoRoot, pattern);
     if (refusal) return { pattern, ...refusal };
     if (!pattern) return noMatchRefusal(pattern);
   }

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

@@ -29,6 +29,7 @@ import { readEvents } from './meta/events.mjs';
 import { writeStatus } from './meta/run-state.mjs';
 import { resolveStatus } from './meta/verdict.mjs';
 import { AGENTS, failReply, limitReply, withProfileRow } from './meta/reply.mjs';
+import { withLaunchRows } from './meta/launch-rows.mjs';
 
 function readRunnerVersion() {
   try {
@@ -81,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) => {
@@ -98,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),
@@ -149,7 +163,10 @@ export function collect(runDir, agent, exitCode) {
   };
   const reply =
     withProfileRow(
-      status === 'OK' ? cfg.reply(ctx) : status === 'LIMIT' ? limitReply(ctx, meta) : failReply(ctx, meta),
+      withLaunchRows(
+        status === 'OK' ? cfg.reply(ctx) : status === 'LIMIT' ? limitReply(ctx, meta) : failReply(ctx, meta),
+        runDir,
+      ),
       meta,
     );