onto-mcp 0.3.0

package/dist/core-runtime/cli/codex-nested-dispatch.js

@@ -0,0 +1,226 @@
+/**
+ * Codex Nested Dispatch Bridge.
+ *
+ * # What this module is
+ *
+ * The bridge between review session artifacts and the nested Codex worker
+ * orchestrator.
+ * It reads the execution plan, constructs the
+ * `NestedLensDispatchInput`, invokes `runCodexNestedTeamlead`, and
+ * classifies per-lens outcomes into the
+ * `ReviewPromptExecutionResult`-compatible shape used downstream by
+ * `completeReviewSession`.
+ *
+ * # Why it exists
+ *
+ * `runCodexNestedTeamlead` is a pure function over lens inputs → outcomes,
+ * intentionally decoupled from onto's session artifacts so it can be
+ * unit-tested without filesystem fixtures. This bridge adds the integration that the
+ * runner (`runReviewInvokeCli`) can branch into when the resolved
+ * profile mode is `nested-workers`.
+ *
+ * Keeping this seat **separate** from `executeReviewPromptExecution`
+ * (which uses the per-lens worker loop) preserves the existing review flow
+ * for main-workers mode.
+ *
+ * # How it relates
+ *
+ * - `ReviewExecutionProfile.mode` selects whether this bridge is used.
+ * - `executeReviewViaCodexNested()` handles the nested worker execution phase.
+ * - `completeReviewSession()` downstream consumes the result to compile
+ *   the final review record.
+ *
+ * # Scope
+ *
+ * - Bridge function `executeReviewViaCodexNested`
+ * - Output-file validation (exists + non-empty) on top of orchestrator
+ *   outcomes — a per-lens `status: "ok"` in the orchestrator is
+ *   necessary but not sufficient; the file must actually be written.
+ * - Tests with injected orchestrator + injected filesystem
+ *
+ * This bridge owns only nested lens dispatch. Synthesize, deliberation
+ * artifact handling, and final record assembly stay in the main review
+ * runner.
+ *
+ * # Design reference
+ *
+ * - Nested Codex validation notes under `development-records/`
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { normalizeLlmModelSwitcher } from "../llm/model-switcher.js";
+import { readYamlDocument } from "../review/review-artifact-utils.js";
+import { runCodexNestedTeamlead, } from "./codex-nested-teamlead-executor.js";
+const defaultInspector = async (p) => {
+    try {
+        const stat = await fs.stat(p);
+        return { exists: stat.isFile(), size: stat.size };
+    }
+    catch {
+        return { exists: false, size: 0 };
+    }
+};
+// ---------------------------------------------------------------------------
+// Artifact archival
+// ---------------------------------------------------------------------------
+/**
+ * Archive for outer codex stdout/stderr when streaming did not
+ * already write the files. Normally `spawnOuterCodex` is invoked with
+ * `stream_stdout_path` / `stream_stderr_path` and the on-disk files
+ * carry the authoritative content via `fs.createWriteStream`; in that
+ * case this helper sees non-empty files and returns without writing
+ * (prevents dual-writer drift — 3rd self-review U4).
+ *
+ * Silently swallows write errors — an artifact write failure must not
+ * mask the actual dispatch outcome. Best-effort.
+ */
+async function archiveOuterStreamsIfMissing(sessionRoot, nestedResult) {
+    const stdoutPath = path.join(sessionRoot, "nested-outer-stdout.log");
+    const stderrPath = path.join(sessionRoot, "nested-outer-stderr.log");
+    await Promise.all([
+        archiveWriteIfMissing(stdoutPath, nestedResult.outer_stdout ?? ""),
+        archiveWriteIfMissing(stderrPath, nestedResult.outer_stderr ?? ""),
+    ]);
+}
+async function archiveWriteIfMissing(targetPath, content) {
+    try {
+        const stat = await fs.stat(targetPath).catch(() => null);
+        if (stat && stat.size > 0) {
+            // Streaming writer produced a non-empty file — respect it as the
+            // single authority. Do not overwrite.
+            return;
+        }
+        await fs.writeFile(targetPath, content).catch(() => { });
+    }
+    catch {
+        // Best-effort; never throw.
+    }
+}
+// ---------------------------------------------------------------------------
+// Worker setting resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve distinct Codex model settings for the outer teamlead and inner lens
+ * workers. Empty objects mean Codex picks its configured defaults for that seat.
+ */
+export function resolveCodexSpawnConfig(config) {
+    const execution = config.review?.execution;
+    const inherited = config.llm;
+    return {
+        teamlead: codexConfigFromRef(execution?.teamlead.llm, inherited) ?? {},
+        lens: codexConfigFromRef(execution?.lens.llm, inherited) ?? {},
+    };
+}
+function codexConfigFromRef(ref, inherited) {
+    const llm = ref === undefined || ref === "inherit" ? inherited : ref;
+    const selection = normalizeLlmModelSwitcher(llm);
+    if (selection?.provider !== "codex")
+        return null;
+    return {
+        ...(selection.model_id ? { model: selection.model_id } : {}),
+        ...(selection.reasoning_effort ? { effort: selection.reasoning_effort } : {}),
+        ...(selection.service_tier ? { service_tier: selection.service_tier } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// Main bridge function
+// ---------------------------------------------------------------------------
+/**
+ * Execute a review via the nested Codex worker path. Reads the execution
+ * plan from `sessionRoot/execution-plan.yaml`, dispatches all lens
+ * packets through one outer Codex teamlead plus one inner Codex worker per lens, and
+ * classifies outcomes into participating / degraded lens sets.
+ *
+ * An orchestrator `status: "ok"` is NOT sufficient for `participating` —
+ * the output file must exist AND be non-empty. This guards against the
+ * outer Codex reporting success when an inner worker failed to write its
+ * `-o` output.
+ *
+ * Injection:
+ *   - `runImpl`: replace the orchestrator (default: `runCodexNestedTeamlead`)
+ *   - `inspector`: replace the file-existence probe (default: `fs.stat`)
+ */
+export async function executeReviewViaCodexNested(args, runImpl = runCodexNestedTeamlead, inspector = defaultInspector) {
+    const executionPlanPath = path.join(args.sessionRoot, "execution-plan.yaml");
+    // `readYamlDocument` throws with a descriptive message when the file
+    // is missing or malformed — let it propagate so the caller sees the
+    // session artifact problem directly rather than a generic null check.
+    const plan = await readYamlDocument(executionPlanPath);
+    const lenses = plan.lens_prompt_packet_seats.map((seat) => ({
+        lens_id: seat.lens_id,
+        packet_path: seat.packet_path,
+        output_path: seat.output_path,
+    }));
+    const spawnConfig = resolveCodexSpawnConfig(args.ontoConfig);
+    // Stream paths live under sessionRoot so the watcher pane can `tail -f`
+    // them from the moment the outer codex starts emitting, instead of
+    // waiting for the post-hoc `archiveOuterStreams` batch write. With
+    // streaming active, these files are the single authority — no post-
+    // dispatch overwrite (3rd self-review U4: prevent dual-writer drift
+    // where two writers could diverge if one was interrupted mid-flush).
+    const streamStdoutPath = path.join(args.sessionRoot, "nested-outer-stdout.log");
+    const streamStderrPath = path.join(args.sessionRoot, "nested-outer-stderr.log");
+    const nestedResult = await runImpl({
+        lenses,
+        ...(spawnConfig.teamlead.model
+            ? { teamlead_model: spawnConfig.teamlead.model }
+            : {}),
+        ...(spawnConfig.teamlead.effort
+            ? { teamlead_reasoning_effort: spawnConfig.teamlead.effort }
+            : {}),
+        ...(spawnConfig.teamlead.service_tier
+            ? { teamlead_service_tier: spawnConfig.teamlead.service_tier }
+            : {}),
+        ...(spawnConfig.lens.model ? { lens_model: spawnConfig.lens.model } : {}),
+        ...(spawnConfig.lens.effort
+            ? { lens_reasoning_effort: spawnConfig.lens.effort }
+            : {}),
+        ...(spawnConfig.lens.service_tier
+            ? { lens_service_tier: spawnConfig.lens.service_tier }
+            : {}),
+        ...(args.projectRoot ? { project_root: args.projectRoot } : {}),
+        ...(typeof args.timeout_ms === "number" ? { timeout_ms: args.timeout_ms } : {}),
+        ...(args.codex_bin ? { codex_bin: args.codex_bin } : {}),
+        stream_stdout_path: streamStdoutPath,
+        stream_stderr_path: streamStderrPath,
+    });
+    // Archive step is a no-op when streaming already produced files.
+    await archiveOuterStreamsIfMissing(args.sessionRoot, nestedResult);
+    const participating = [];
+    const degraded = [];
+    for (let i = 0; i < lenses.length; i += 1) {
+        const lens = lenses[i];
+        const outcome = nestedResult.outcomes[i];
+        const orchestratorOk = outcome?.status === "ok";
+        if (!orchestratorOk) {
+            degraded.push(lens.lens_id);
+            continue;
+        }
+        const probe = await inspector(lens.output_path);
+        if (probe.exists && probe.size > 0) {
+            participating.push(lens.lens_id);
+        }
+        else {
+            degraded.push(lens.lens_id);
+        }
+    }
+    // Determine halt_reason when orchestrator signalled teamlead-level
+    // failure (e.g., timeout, no summary) — surfaces to the caller for
+    // error reporting. Per-lens degradation alone does NOT halt.
+    let halt_reason;
+    if (!nestedResult.summary_parsed && nestedResult.outer_exit_code !== 0) {
+        halt_reason =
+            `codex-nested outer teamlead failed (exit=${nestedResult.outer_exit_code}, summary=${nestedResult.summary_parsed ? "parsed" : "missing"})`;
+    }
+    return {
+        session_root: args.sessionRoot,
+        executed_lens_count: lenses.length,
+        participating_lens_ids: participating,
+        degraded_lens_ids: degraded,
+        synthesis_executed: false,
+        synthesis_output_path: plan.synthesis_output_path,
+        error_log_path: plan.error_log_path ?? null,
+        nested_raw: nestedResult,
+        ...(halt_reason ? { halt_reason } : {}),
+    };
+}

package/dist/core-runtime/cli/codex-nested-dispatch.test.js

@@ -0,0 +1,390 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { writeYamlDocument } from "../review/review-artifact-utils.js";
+import { executeReviewViaCodexNested, } from "./codex-nested-dispatch.js";
+async function mkSession(plan) {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "onto-pr-h-"));
+    const sessionRoot = path.join(root, "session");
+    await fs.mkdir(sessionRoot, { recursive: true });
+    await writeYamlDocument(path.join(sessionRoot, "execution-plan.yaml"), plan);
+    return {
+        sessionRoot,
+        cleanup: async () => {
+            await fs.rm(root, { recursive: true, force: true });
+        },
+    };
+}
+function buildPlan(lenses, sessionRoot) {
+    return {
+        session_id: "pr-h-test",
+        session_root: sessionRoot,
+        execution_realization: "subagent",
+        host_runtime: "codex",
+        review_mode: "core-axis",
+        interpretation_artifact_path: path.join(sessionRoot, "interpretation.yaml"),
+        binding_output_path: path.join(sessionRoot, "binding.yaml"),
+        session_metadata_path: path.join(sessionRoot, "session-metadata.yaml"),
+        execution_preparation_root: path.join(sessionRoot, "prep"),
+        round1_root: path.join(sessionRoot, "round1"),
+        lens_execution_seats: lenses.map((l) => ({
+            lens_id: l.lens_id,
+            output_path: l.output_path,
+        })),
+        prompt_packets_root: path.join(sessionRoot, "prompt-packets"),
+        lens_prompt_packet_seats: lenses,
+        synthesize_prompt_packet_path: path.join(sessionRoot, "synthesize-packet.md"),
+        synthesis_output_path: path.join(sessionRoot, "synthesis.md"),
+        deliberation_output_path: path.join(sessionRoot, "deliberation.md"),
+        execution_result_path: path.join(sessionRoot, "execution-result.yaml"),
+        error_log_path: path.join(sessionRoot, "error-log.md"),
+        final_output_path: path.join(sessionRoot, "final.md"),
+        review_record_path: path.join(sessionRoot, "review-record.yaml"),
+        boundary_policy: {
+            web_research_policy: "allowed",
+            repo_exploration_policy: "allowed",
+            recursive_reference_expansion_policy: "allowed",
+            filesystem_scope: { allowed_roots: [], source_mutation_policy: "denied" },
+        },
+        boundary_presentation: {
+            web_research: { requested_policy: "allowed" },
+            repo_exploration: { requested_policy: "allowed" },
+            recursive_reference_expansion: { requested_policy: "allowed" },
+            source_mutation: { requested_policy: "denied" },
+            filesystem_scope: { requested_allowed_roots: [] },
+        },
+        boundary_enforcement_profile: {
+            web_research: "prompt_declared_only",
+            repo_exploration: "prompt_declared_only",
+            recursive_reference_expansion: "prompt_declared_only",
+            source_mutation: "prompt_declared_only",
+            filesystem_scope: "prompt_declared_only",
+        },
+        effective_boundary_state: {
+            web_research: {
+                requested_policy: "allowed",
+                effective_policy: "allowed",
+                guarantee_level: "prompt_declared_only",
+            },
+            repo_exploration: {
+                requested_policy: "allowed",
+                effective_policy: "allowed",
+                guarantee_level: "prompt_declared_only",
+            },
+            recursive_reference_expansion: {
+                requested_policy: "allowed",
+                effective_policy: "allowed",
+                guarantee_level: "prompt_declared_only",
+            },
+            source_mutation: {
+                requested_policy: "denied",
+                effective_policy: "denied",
+                guarantee_level: "prompt_declared_only",
+            },
+            filesystem_scope: {
+                requested_allowed_roots: [],
+                effective_allowed_roots: [],
+                guarantee_level: "prompt_declared_only",
+            },
+        },
+    };
+}
+function buildOrchestrator(outcomes, opts = {}) {
+    const calls = [];
+    const impl = async (input) => {
+        calls.push(input);
+        return {
+            outcomes,
+            outer_stdout: opts.outer_stdout ?? "",
+            outer_stderr: opts.outer_stderr ?? "",
+            outer_exit_code: opts.outer_exit_code ?? 0,
+            summary_parsed: opts.summary_parsed ?? true,
+        };
+    };
+    return { impl, calls };
+}
+function staticInspector(present, sizes = {}) {
+    return async (p) => ({
+        exists: present.has(p),
+        size: sizes[p] ?? (present.has(p) ? 1 : 0),
+    });
+}
+// ---------------------------------------------------------------------------
+// Forwarding: execution-plan lenses → orchestrator input
+// ---------------------------------------------------------------------------
+describe("executeReviewViaCodexNested — forwarding", () => {
+    let fixture;
+    afterEach(async () => {
+        if (fixture)
+            await fixture.cleanup();
+    });
+    it("forwards lens packet triples in execution-plan order", async () => {
+        const plan = buildPlan([
+            { lens_id: "logic", packet_path: "/pkts/logic.md", output_path: "/out/logic.md" },
+            { lens_id: "pragmatics", packet_path: "/pkts/pr.md", output_path: "/out/pr.md" },
+            { lens_id: "axiology", packet_path: "/pkts/ax.md", output_path: "/out/ax.md" },
+        ], "");
+        fixture = await mkSession(plan);
+        const { impl, calls } = buildOrchestrator([
+            { lens_id: "logic", status: "ok" },
+            { lens_id: "pragmatics", status: "ok" },
+            { lens_id: "axiology", status: "ok" },
+        ]);
+        await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set(["/out/logic.md", "/out/pr.md", "/out/ax.md"])));
+        expect(calls).toHaveLength(1);
+        expect(calls[0].lenses.map((l) => l.lens_id)).toEqual([
+            "logic",
+            "pragmatics",
+            "axiology",
+        ]);
+        expect(calls[0].lenses[0].packet_path).toBe("/pkts/logic.md");
+        expect(calls[0].lenses[0].output_path).toBe("/out/logic.md");
+    });
+    it("passes model from ontoConfig.codex.model and reasoning_effort from codex.effort", async () => {
+        const plan = buildPlan([{ lens_id: "l", packet_path: "/p", output_path: "/o" }], "");
+        fixture = await mkSession(plan);
+        const { impl, calls } = buildOrchestrator([{ lens_id: "l", status: "ok" }]);
+        await executeReviewViaCodexNested({
+            sessionRoot: fixture.sessionRoot,
+            ontoConfig: { codex: { model: "gpt-5.4", effort: "high" } },
+        }, impl, staticInspector(new Set(["/o"])));
+        expect(calls[0].model).toBe("gpt-5.4");
+        expect(calls[0].reasoning_effort).toBe("high");
+    });
+    it("falls back to top-level model / reasoning_effort when codex.* unset", async () => {
+        const plan = buildPlan([{ lens_id: "l", packet_path: "/p", output_path: "/o" }], "");
+        fixture = await mkSession(plan);
+        const { impl, calls } = buildOrchestrator([{ lens_id: "l", status: "ok" }]);
+        await executeReviewViaCodexNested({
+            sessionRoot: fixture.sessionRoot,
+            ontoConfig: { model: "gpt-top", reasoning_effort: "low" },
+        }, impl, staticInspector(new Set(["/o"])));
+        expect(calls[0].model).toBe("gpt-top");
+        expect(calls[0].reasoning_effort).toBe("low");
+    });
+    it("reads model/effort from review.subagent (P2 canonical location)", async () => {
+        const plan = buildPlan([{ lens_id: "l", packet_path: "/p", output_path: "/o" }], "");
+        fixture = await mkSession(plan);
+        const { impl, calls } = buildOrchestrator([{ lens_id: "l", status: "ok" }]);
+        await executeReviewViaCodexNested({
+            sessionRoot: fixture.sessionRoot,
+            ontoConfig: {
+                review: {
+                    subagent: { provider: "codex", model_id: "gpt-sub", effort: "medium" },
+                },
+            },
+        }, impl, staticInspector(new Set(["/o"])));
+        expect(calls[0].model).toBe("gpt-sub");
+        expect(calls[0].reasoning_effort).toBe("medium");
+    });
+    it("reads model/effort from review.teamlead.model when external codex teamlead", async () => {
+        const plan = buildPlan([{ lens_id: "l", packet_path: "/p", output_path: "/o" }], "");
+        fixture = await mkSession(plan);
+        const { impl, calls } = buildOrchestrator([{ lens_id: "l", status: "ok" }]);
+        await executeReviewViaCodexNested({
+            sessionRoot: fixture.sessionRoot,
+            ontoConfig: {
+                review: {
+                    teamlead: { model: { provider: "codex", model_id: "gpt-tl", effort: "high" } },
+                },
+            },
+        }, impl, staticInspector(new Set(["/o"])));
+        expect(calls[0].model).toBe("gpt-tl");
+        expect(calls[0].reasoning_effort).toBe("high");
+    });
+    it("review.subagent wins over top-level codex.* (P2 canonical > legacy)", async () => {
+        const plan = buildPlan([{ lens_id: "l", packet_path: "/p", output_path: "/o" }], "");
+        fixture = await mkSession(plan);
+        const { impl, calls } = buildOrchestrator([{ lens_id: "l", status: "ok" }]);
+        await executeReviewViaCodexNested({
+            sessionRoot: fixture.sessionRoot,
+            ontoConfig: {
+                review: {
+                    subagent: { provider: "codex", model_id: "gpt-sub", effort: "medium" },
+                },
+                codex: { model: "gpt-legacy", effort: "high" },
+            },
+        }, impl, staticInspector(new Set(["/o"])));
+        expect(calls[0].model).toBe("gpt-sub");
+        expect(calls[0].reasoning_effort).toBe("medium");
+    });
+    it("review.subagent with provider=main-native does NOT claim codex slot (falls through)", async () => {
+        // main-native subagent is not a codex provider → resolver should move on
+        // to teamlead → legacy → top-level, not pick up subagent.
+        const plan = buildPlan([{ lens_id: "l", packet_path: "/p", output_path: "/o" }], "");
+        fixture = await mkSession(plan);
+        const { impl, calls } = buildOrchestrator([{ lens_id: "l", status: "ok" }]);
+        await executeReviewViaCodexNested({
+            sessionRoot: fixture.sessionRoot,
+            ontoConfig: {
+                review: {
+                    subagent: { provider: "main-native" },
+                },
+                codex: { model: "gpt-legacy", effort: "high" },
+            },
+        }, impl, staticInspector(new Set(["/o"])));
+        expect(calls[0].model).toBe("gpt-legacy");
+        expect(calls[0].reasoning_effort).toBe("high");
+    });
+    it("passes sessionRoot-based stream_stdout_path/stream_stderr_path to orchestrator (live watcher)", async () => {
+        // The watcher pane's tail -f target is sessionRoot/nested-outer-*.log.
+        // The orchestrator must receive those absolute paths so spawn-watcher
+        // can tee outer codex stdout/stderr there as codex emits chunks. If
+        // the dispatch stopped plumbing these paths, streaming would silently
+        // fall back to memory-only capture.
+        const plan = buildPlan([{ lens_id: "l", packet_path: "/p", output_path: "/o" }], "");
+        fixture = await mkSession(plan);
+        const { impl, calls } = buildOrchestrator([{ lens_id: "l", status: "ok" }]);
+        await executeReviewViaCodexNested({
+            sessionRoot: fixture.sessionRoot,
+            ontoConfig: {},
+        }, impl, staticInspector(new Set(["/o"])));
+        expect(calls[0].stream_stdout_path).toBe(path.join(fixture.sessionRoot, "nested-outer-stdout.log"));
+        expect(calls[0].stream_stderr_path).toBe(path.join(fixture.sessionRoot, "nested-outer-stderr.log"));
+    });
+    it("archives outer stdout/stderr to nested-outer-*.log under sessionRoot", async () => {
+        // Regression guard: outer codex diagnostics (ENV-BEFORE / ENV-AFTER /
+        // LENS_DISPATCH_SUMMARY) and raw stderr are otherwise unreachable
+        // after dispatch completes, because review-invoke's final JSON drops
+        // `nested_raw`. The archive step is what makes post-hoc auditing
+        // possible for the principal.
+        const plan = buildPlan([{ lens_id: "l", packet_path: "/p", output_path: "/o" }], "");
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([{ lens_id: "l", status: "ok" }], {
+            outer_stdout: "ENV-BEFORE lens=l packet=/p output=/o\n" +
+                "ENV-AFTER lens=l exit=0 output_bytes=42\n" +
+                'LENS_DISPATCH_SUMMARY:{"lens_results":[{"lens_id":"l","status":"ok"}]}\n',
+            outer_stderr: "some-warning from outer codex\n",
+        });
+        await executeReviewViaCodexNested({
+            sessionRoot: fixture.sessionRoot,
+            ontoConfig: {},
+        }, impl, staticInspector(new Set(["/o"])));
+        const stdoutArchive = await fs.readFile(path.join(fixture.sessionRoot, "nested-outer-stdout.log"), "utf8");
+        const stderrArchive = await fs.readFile(path.join(fixture.sessionRoot, "nested-outer-stderr.log"), "utf8");
+        expect(stdoutArchive).toContain("ENV-BEFORE lens=l");
+        expect(stdoutArchive).toContain("ENV-AFTER lens=l");
+        expect(stdoutArchive).toContain("LENS_DISPATCH_SUMMARY:");
+        expect(stderrArchive).toContain("some-warning from outer codex");
+    });
+});
+// ---------------------------------------------------------------------------
+// Classification: orchestrator-ok AND file-exists → participating
+// ---------------------------------------------------------------------------
+describe("executeReviewViaCodexNested — per-lens classification", () => {
+    let fixture;
+    afterEach(async () => {
+        if (fixture)
+            await fixture.cleanup();
+    });
+    it("all ok + all files present → all participating", async () => {
+        const plan = buildPlan([
+            { lens_id: "a", packet_path: "/p/a", output_path: "/o/a" },
+            { lens_id: "b", packet_path: "/p/b", output_path: "/o/b" },
+        ], "");
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([
+            { lens_id: "a", status: "ok" },
+            { lens_id: "b", status: "ok" },
+        ]);
+        const result = await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set(["/o/a", "/o/b"])));
+        expect(result.participating_lens_ids).toEqual(["a", "b"]);
+        expect(result.degraded_lens_ids).toEqual([]);
+        expect(result.executed_lens_count).toBe(2);
+    });
+    it("orchestrator fail → degraded (no file probe needed)", async () => {
+        const plan = buildPlan([
+            { lens_id: "a", packet_path: "/p/a", output_path: "/o/a" },
+            { lens_id: "b", packet_path: "/p/b", output_path: "/o/b" },
+        ], "");
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([
+            { lens_id: "a", status: "ok" },
+            { lens_id: "b", status: "fail", error: "inner exit 1" },
+        ]);
+        const result = await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set(["/o/a", "/o/b"])));
+        expect(result.participating_lens_ids).toEqual(["a"]);
+        expect(result.degraded_lens_ids).toEqual(["b"]);
+    });
+    it("orchestrator ok but output file missing → degraded", async () => {
+        const plan = buildPlan([
+            { lens_id: "a", packet_path: "/p/a", output_path: "/o/a" },
+            { lens_id: "b", packet_path: "/p/b", output_path: "/o/b" },
+        ], "");
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([
+            { lens_id: "a", status: "ok" },
+            { lens_id: "b", status: "ok" },
+        ]);
+        const result = await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set(["/o/a"])));
+        expect(result.participating_lens_ids).toEqual(["a"]);
+        expect(result.degraded_lens_ids).toEqual(["b"]);
+    });
+    it("orchestrator ok but output file size=0 → degraded", async () => {
+        const plan = buildPlan([{ lens_id: "a", packet_path: "/p/a", output_path: "/o/a" }], "");
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([{ lens_id: "a", status: "ok" }]);
+        const result = await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set(["/o/a"]), { "/o/a": 0 }));
+        expect(result.participating_lens_ids).toEqual([]);
+        expect(result.degraded_lens_ids).toEqual(["a"]);
+    });
+});
+// ---------------------------------------------------------------------------
+// Result shape
+// ---------------------------------------------------------------------------
+describe("executeReviewViaCodexNested — result shape", () => {
+    let fixture;
+    afterEach(async () => {
+        if (fixture)
+            await fixture.cleanup();
+    });
+    it("synthesis_executed is always false in PR-H (deferred)", async () => {
+        const plan = buildPlan([{ lens_id: "a", packet_path: "/p/a", output_path: "/o/a" }], "");
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([{ lens_id: "a", status: "ok" }]);
+        const result = await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set(["/o/a"])));
+        expect(result.synthesis_executed).toBe(false);
+    });
+    it("synthesis_output_path is sourced from execution-plan for downstream synthesize wire-in", async () => {
+        const plan = buildPlan([{ lens_id: "a", packet_path: "/p/a", output_path: "/o/a" }], "");
+        plan.synthesis_output_path = "/tmp/synth-target.md";
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([{ lens_id: "a", status: "ok" }]);
+        const result = await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set(["/o/a"])));
+        expect(result.synthesis_output_path).toBe("/tmp/synth-target.md");
+    });
+    it("nested_raw exposes orchestrator result verbatim for debugging", async () => {
+        const plan = buildPlan([{ lens_id: "a", packet_path: "/p/a", output_path: "/o/a" }], "");
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([{ lens_id: "a", status: "ok" }], { outer_stdout: "outer stdout content", outer_stderr: "outer stderr content" });
+        const result = await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set(["/o/a"])));
+        expect(result.nested_raw.outer_stdout).toBe("outer stdout content");
+        expect(result.nested_raw.outer_stderr).toBe("outer stderr content");
+    });
+    it("halt_reason populated when outer exit non-zero AND summary not parsed", async () => {
+        const plan = buildPlan([{ lens_id: "a", packet_path: "/p/a", output_path: "/o/a" }], "");
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([{ lens_id: "a", status: "fail", error: "no summary" }], { outer_exit_code: 137, summary_parsed: false });
+        const result = await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set()));
+        expect(result.halt_reason).toBeDefined();
+        expect(result.halt_reason).toContain("137");
+    });
+    it("halt_reason absent when per-lens degraded but teamlead ok", async () => {
+        const plan = buildPlan([{ lens_id: "a", packet_path: "/p/a", output_path: "/o/a" }], "");
+        fixture = await mkSession(plan);
+        const { impl } = buildOrchestrator([{ lens_id: "a", status: "fail", error: "inner 1" }], { outer_exit_code: 0, summary_parsed: true });
+        const result = await executeReviewViaCodexNested({ sessionRoot: fixture.sessionRoot, ontoConfig: {} }, impl, staticInspector(new Set()));
+        expect(result.halt_reason).toBeUndefined();
+        expect(result.degraded_lens_ids).toEqual(["a"]);
+    });
+});
+// ---------------------------------------------------------------------------
+// Execution-plan missing — bridge surfaces the error
+// ---------------------------------------------------------------------------
+describe("executeReviewViaCodexNested — missing execution-plan", () => {
+    it("propagates readYamlDocument error when execution-plan.yaml absent", async () => {
+        const { impl } = buildOrchestrator([]);
+        await expect(executeReviewViaCodexNested({ sessionRoot: "/nonexistent/session/path", ontoConfig: {} }, impl, staticInspector(new Set()))).rejects.toThrow(/Failed to read artifact/);
+    });
+});