onto-mcp 0.3.0

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

@@ -0,0 +1,335 @@
+import { describe, it, expect } from "vitest";
+import { buildNestedTeamleadPrompt, parseNestedTeamleadSummary, runCodexNestedTeamlead, } from "./codex-nested-teamlead-executor.js";
+// ---------------------------------------------------------------------------
+// These tests assert the PR-C orchestrator invariants:
+//
+// (1) The prompt embeds every lens in the same order with packet/output
+//     paths and the sandbox flag the outer codex needs.
+// (2) The summary parser extracts the LENS_DISPATCH_SUMMARY line and
+//     tolerates surrounding noise; malformed lines are ignored; last-one
+//     wins when multiple are present.
+// (3) `runCodexNestedTeamlead` reconciles inputs with reported outcomes:
+//     missing lens_ids become `fail` (teamlead noncompliance), reported
+//     failures carry the reported error, timeouts mark every lens failed.
+// ---------------------------------------------------------------------------
+const LENSES = [
+    {
+        lens_id: "logic",
+        packet_path: "/tmp/session/round1/logic-packet.md",
+        output_path: "/tmp/session/round1/logic.md",
+    },
+    {
+        lens_id: "pragmatics",
+        packet_path: "/tmp/session/round1/pragmatics-packet.md",
+        output_path: "/tmp/session/round1/pragmatics.md",
+    },
+    {
+        lens_id: "axiology",
+        packet_path: "/tmp/session/round1/axiology-packet.md",
+        output_path: "/tmp/session/round1/axiology.md",
+    },
+];
+// ---------------------------------------------------------------------------
+// buildNestedTeamleadPrompt
+// ---------------------------------------------------------------------------
+describe("buildNestedTeamleadPrompt", () => {
+    it("embeds every lens's id, packet path, and output path", () => {
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES });
+        for (const lens of LENSES) {
+            expect(prompt).toContain(lens.lens_id);
+            expect(prompt).toContain(lens.packet_path);
+            expect(prompt).toContain(lens.output_path);
+        }
+    });
+    it("includes sandbox danger-full-access and ephemeral flags for inner codex", () => {
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES });
+        expect(prompt).toContain("--sandbox danger-full-access");
+        expect(prompt).toContain("--ephemeral");
+        expect(prompt).toContain("--skip-git-repo-check");
+    });
+    it("declares the LENS_DISPATCH_SUMMARY sentinel the parser looks for", () => {
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES });
+        expect(prompt).toContain("LENS_DISPATCH_SUMMARY:");
+    });
+    it("passes through model + reasoning_effort when provided", () => {
+        const prompt = buildNestedTeamleadPrompt({
+            lenses: LENSES.slice(0, 1),
+            model: "gpt-5.4",
+            reasoning_effort: "high",
+        });
+        expect(prompt).toContain("-m gpt-5.4");
+        expect(prompt).toContain("model_reasoning_effort=high");
+    });
+    it("omits the model/effort flags when unset (codex uses its defaults)", () => {
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES.slice(0, 1) });
+        expect(prompt).not.toContain(" -m ");
+        expect(prompt).not.toContain("model_reasoning_effort=");
+    });
+    it("states the number of lenses explicitly (sanity check for the outer codex)", () => {
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES });
+        expect(prompt).toContain(`${LENSES.length} lenses`);
+    });
+    it("surfaces nested model/effort in the diagnostic header for outer log readers", () => {
+        const prompt = buildNestedTeamleadPrompt({
+            lenses: LENSES.slice(0, 1),
+            model: "gpt-5.4",
+            reasoning_effort: "medium",
+        });
+        expect(prompt).toContain("model=gpt-5.4");
+        expect(prompt).toContain("effort=medium");
+    });
+    it("falls back to (codex default) in diagnostic header when unset", () => {
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES.slice(0, 1) });
+        expect(prompt).toContain("model=(codex default)");
+        expect(prompt).toContain("effort=(codex default)");
+    });
+    it("embeds ENV-BEFORE and ENV-AFTER diagnostic emissions in the script body", () => {
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES });
+        expect(prompt).toContain("ENV-BEFORE lens=");
+        expect(prompt).toContain("ENV-AFTER lens=");
+    });
+    it("delivers instructions as a literal bash script piped to bash -s", () => {
+        // Regression guard for the descriptive→literal rewrite. Earlier prompts
+        // asked outer to "invoke nested codex for each lens", which outer
+        // interpreted as a self-assignment (using its own file-edit tools) and
+        // never spawned nested subprocesses. The literal-script formulation
+        // removes that interpretation latitude — outer's only action is to
+        // pipe the block below to bash.
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES });
+        expect(prompt).toContain("bash -s");
+        expect(prompt).toContain("```bash");
+        expect(prompt).toContain("#!/usr/bin/env bash");
+        expect(prompt).toContain("LENSES=(");
+    });
+    it("dispatches lenses in parallel via background subshells + wait", () => {
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES });
+        // subshell + background + wait pattern
+        expect(prompt).toMatch(/\)\s*&\s*\ndone\s*\n\s*wait/);
+    });
+    it("persists per-lens running log as nested-stderr.log on failure", () => {
+        // Regression guard: post-hoc audit needs to answer "what failed
+        // inside this lens run?" after dispatch exits. Now that the running
+        // log lives under sessionRoot/round1 for real-time tail -f, the
+        // failure path simply renames it to .<lens>.nested-stderr.log; the
+        // success path removes it. Previous `tail -200` bounded copy is no
+        // longer necessary since the source log is already file-system
+        // resident at the destination directory.
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES });
+        expect(prompt).toContain(".nested-stderr.log");
+        expect(prompt).toContain(".running.log");
+    });
+    it("writes per-lens running log under sessionRoot (not TMPDIR) for live tail -f", () => {
+        // Regression guard for commit 5 streaming: per-lens $LOG must live
+        // under OUTPUT_DIR (sessionRoot/round1) so the watcher pane can
+        // tail it as codex emits. Keeping $LOG in TMPDIR would revert to
+        // post-hoc-only visibility.
+        const prompt = buildNestedTeamleadPrompt({ lenses: LENSES });
+        expect(prompt).toContain('LOG="$OUTPUT_DIR/.$LENS_ID.running.log"');
+        // $STAT remains in TMPDIR (short-lived handoff from lens subshell
+        // to the summary emitter; no value to the watcher).
+        expect(prompt).toContain('STAT="$TMPDIR/$LENS_ID.status"');
+    });
+});
+// ---------------------------------------------------------------------------
+// parseNestedTeamleadSummary
+// ---------------------------------------------------------------------------
+describe("parseNestedTeamleadSummary", () => {
+    it("returns null when no summary line is present", () => {
+        expect(parseNestedTeamleadSummary("just model commentary\nnothing here\n")).toBeNull();
+    });
+    it("extracts a valid summary line with all lens results", () => {
+        const stdout = [
+            "dispatched lens#1...",
+            "dispatched lens#2...",
+            'LENS_DISPATCH_SUMMARY:{"lens_results":[{"lens_id":"logic","status":"ok"},{"lens_id":"pragmatics","status":"fail","error":"exit 1"}]}',
+        ].join("\n");
+        const result = parseNestedTeamleadSummary(stdout);
+        expect(result).not.toBeNull();
+        expect(result.lens_results).toHaveLength(2);
+        expect(result.lens_results[0]).toEqual({ lens_id: "logic", status: "ok" });
+        expect(result.lens_results[1]).toEqual({
+            lens_id: "pragmatics",
+            status: "fail",
+            error: "exit 1",
+        });
+    });
+    it("ignores malformed summary lines", () => {
+        const stdout = "LENS_DISPATCH_SUMMARY:not-json-at-all\nno summary visible\n";
+        expect(parseNestedTeamleadSummary(stdout)).toBeNull();
+    });
+    it("takes the last summary line when multiple appear", () => {
+        const stdout = [
+            'LENS_DISPATCH_SUMMARY:{"lens_results":[{"lens_id":"a","status":"fail"}]}',
+            'LENS_DISPATCH_SUMMARY:{"lens_results":[{"lens_id":"a","status":"ok"}]}',
+        ].join("\n");
+        const result = parseNestedTeamleadSummary(stdout);
+        expect(result.lens_results[0].status).toBe("ok");
+    });
+    it("tolerates leading/trailing whitespace around the summary line", () => {
+        const stdout = '   LENS_DISPATCH_SUMMARY:{"lens_results":[]}   \n';
+        const result = parseNestedTeamleadSummary(stdout);
+        expect(result).not.toBeNull();
+        expect(result.lens_results).toEqual([]);
+    });
+});
+function fakeSpawn(stdout, stderr, exit_code, timed_out = false) {
+    return async () => ({ stdout, stderr, exit_code, timed_out });
+}
+describe("runCodexNestedTeamlead", () => {
+    it("returns outcomes in input order with ok statuses on clean exit", async () => {
+        const input = { lenses: LENSES };
+        const stdout = `LENS_DISPATCH_SUMMARY:${JSON.stringify({
+            lens_results: [
+                { lens_id: "logic", status: "ok" },
+                { lens_id: "pragmatics", status: "ok" },
+                { lens_id: "axiology", status: "ok" },
+            ],
+        })}`;
+        const result = await runCodexNestedTeamlead(input, fakeSpawn(stdout, "", 0));
+        expect(result.summary_parsed).toBe(true);
+        expect(result.outer_exit_code).toBe(0);
+        expect(result.outcomes.map((o) => o.lens_id)).toEqual(["logic", "pragmatics", "axiology"]);
+        expect(result.outcomes.every((o) => o.status === "ok")).toBe(true);
+    });
+    it("propagates per-lens failures from the summary", async () => {
+        const input = { lenses: LENSES };
+        const stdout = `LENS_DISPATCH_SUMMARY:${JSON.stringify({
+            lens_results: [
+                { lens_id: "logic", status: "ok" },
+                { lens_id: "pragmatics", status: "fail", error: "inner codex exit 1" },
+                { lens_id: "axiology", status: "ok" },
+            ],
+        })}`;
+        const result = await runCodexNestedTeamlead(input, fakeSpawn(stdout, "", 0));
+        expect(result.outcomes[0].status).toBe("ok");
+        expect(result.outcomes[1].status).toBe("fail");
+        expect(result.outcomes[1].error).toContain("inner codex exit 1");
+        expect(result.outcomes[2].status).toBe("ok");
+    });
+    it("marks missing lens_ids as fail with teamlead-noncompliance reason", async () => {
+        const input = { lenses: LENSES };
+        // Summary omits axiology entirely.
+        const stdout = `LENS_DISPATCH_SUMMARY:${JSON.stringify({
+            lens_results: [
+                { lens_id: "logic", status: "ok" },
+                { lens_id: "pragmatics", status: "ok" },
+            ],
+        })}`;
+        const result = await runCodexNestedTeamlead(input, fakeSpawn(stdout, "", 0));
+        expect(result.outcomes[2].status).toBe("fail");
+        expect(result.outcomes[2].error).toContain("axiology");
+        expect(result.outcomes[2].error).toContain("summary missing");
+    });
+    it("marks all lenses fail when outer codex never emits a summary", async () => {
+        const input = { lenses: LENSES };
+        const stdout = "just commentary, no summary line\n";
+        const result = await runCodexNestedTeamlead(input, fakeSpawn(stdout, "something went wrong", 1));
+        expect(result.summary_parsed).toBe(false);
+        expect(result.outer_exit_code).toBe(1);
+        expect(result.outcomes.every((o) => o.status === "fail")).toBe(true);
+        for (const outcome of result.outcomes) {
+            expect(outcome.error).toContain("did not emit");
+        }
+    });
+    it("timeout marks all lenses fail with explicit timeout reason", async () => {
+        const input = { lenses: LENSES, timeout_ms: 1234 };
+        const result = await runCodexNestedTeamlead(input, fakeSpawn("", "", 137, true));
+        expect(result.summary_parsed).toBe(false);
+        expect(result.outcomes.every((o) => o.status === "fail")).toBe(true);
+        for (const outcome of result.outcomes) {
+            expect(outcome.error).toContain("1234");
+            expect(outcome.error).toContain("timed out");
+        }
+    });
+    it("trusts per-lens summary even when outer exit code is non-zero", async () => {
+        const input = { lenses: LENSES };
+        const stdout = `LENS_DISPATCH_SUMMARY:${JSON.stringify({
+            lens_results: [
+                { lens_id: "logic", status: "ok" },
+                { lens_id: "pragmatics", status: "ok" },
+                { lens_id: "axiology", status: "fail", error: "model context length exceeded" },
+            ],
+        })}`;
+        // Outer codex exits 1 (e.g., because one nested lens failed), but
+        // summary is still reliable.
+        const result = await runCodexNestedTeamlead(input, fakeSpawn(stdout, "", 1));
+        expect(result.summary_parsed).toBe(true);
+        expect(result.outer_exit_code).toBe(1);
+        expect(result.outcomes[0].status).toBe("ok");
+        expect(result.outcomes[1].status).toBe("ok");
+        expect(result.outcomes[2].status).toBe("fail");
+        expect(result.outcomes[2].error).toContain("context length");
+    });
+    it("captures outer stdout/stderr verbatim for debugging", async () => {
+        const input = { lenses: LENSES.slice(0, 1) };
+        const stdoutRaw = "outer commentary\nmore details\n";
+        const stderrRaw = "some warning\n";
+        const result = await runCodexNestedTeamlead(input, fakeSpawn(stdoutRaw, stderrRaw, 0));
+        expect(result.outer_stdout).toBe(stdoutRaw);
+        expect(result.outer_stderr).toBe(stderrRaw);
+    });
+    it("forwards model and reasoning_effort to outer codex spawn options", async () => {
+        // Regression: outer codex previously inherited ~/.codex/config.toml
+        // defaults (e.g. xhigh effort), ignoring .onto/config.yml overrides and
+        // causing orchestration timeouts. The input fields must reach the
+        // spawn callsite so the CLI can add `-c model_reasoning_effort=…` and
+        // `-m <model>` args.
+        let captured = null;
+        const capturingSpawn = async (_prompt, options) => {
+            captured = options;
+            return { stdout: "", stderr: "", exit_code: 0, timed_out: false };
+        };
+        const input = {
+            lenses: LENSES.slice(0, 1),
+            model: "gpt-5.4",
+            reasoning_effort: "medium",
+        };
+        await runCodexNestedTeamlead(input, capturingSpawn);
+        expect(captured).not.toBeNull();
+        expect(captured.model).toBe("gpt-5.4");
+        expect(captured.reasoning_effort).toBe("medium");
+    });
+    it("omits model and reasoning_effort from spawn options when unset", async () => {
+        let captured = null;
+        const capturingSpawn = async (_prompt, options) => {
+            captured = options;
+            return { stdout: "", stderr: "", exit_code: 0, timed_out: false };
+        };
+        const input = { lenses: LENSES.slice(0, 1) };
+        await runCodexNestedTeamlead(input, capturingSpawn);
+        expect(captured).not.toBeNull();
+        expect(captured.model).toBeUndefined();
+        expect(captured.reasoning_effort).toBeUndefined();
+    });
+    it("forwards stream_stdout_path and stream_stderr_path to spawn options", async () => {
+        // Regression guard for real-time watcher streaming: if these fields
+        // drop, the outer codex stdout/stderr fall back to memory-only
+        // capture and the watcher pane's tail -f hint loses its target.
+        let captured = null;
+        const capturingSpawn = async (_prompt, options) => {
+            captured = options;
+            return { stdout: "", stderr: "", exit_code: 0, timed_out: false };
+        };
+        const input = {
+            lenses: LENSES.slice(0, 1),
+            stream_stdout_path: "/tmp/fake/nested-outer-stdout.log",
+            stream_stderr_path: "/tmp/fake/nested-outer-stderr.log",
+        };
+        await runCodexNestedTeamlead(input, capturingSpawn);
+        expect(captured).not.toBeNull();
+        expect(captured.stream_stdout_path).toBe("/tmp/fake/nested-outer-stdout.log");
+        expect(captured.stream_stderr_path).toBe("/tmp/fake/nested-outer-stderr.log");
+    });
+    it("omits stream_*_path from spawn options when unset (memory-only capture)", async () => {
+        let captured = null;
+        const capturingSpawn = async (_prompt, options) => {
+            captured = options;
+            return { stdout: "", stderr: "", exit_code: 0, timed_out: false };
+        };
+        const input = { lenses: LENSES.slice(0, 1) };
+        await runCodexNestedTeamlead(input, capturingSpawn);
+        expect(captured).not.toBeNull();
+        expect(captured.stream_stdout_path).toBeUndefined();
+        expect(captured.stream_stderr_path).toBeUndefined();
+    });
+});

package/dist/core-runtime/cli/codex-review-unit-executor.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+function requireString(value, optionName) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Missing required option --${optionName}`);
+    }
+    return value;
+}
+function buildBoundedPrompt(packetPath, packetText, outputPath, unitId, unitKind) {
+    return `You are executing a single bounded review unit as a ContextIsolatedReasoningUnit.
+
+Unit id: ${unitId}
+Unit kind: ${unitKind}
+Authoritative prompt packet path: ${packetPath}
+Canonical output path: ${outputPath}
+
+Rules:
+- Treat the prompt packet below as the authoritative contract.
+- Treat the Boundary Policy and Effective Boundary State in the packet as hard constraints.
+- Read the files referenced by the prompt packet when needed.
+- Stay within the smallest sufficient file set implied by the packet.
+- Do not recursively follow reference chains beyond the files explicitly listed in the packet unless the packet requires it.
+- Do not use web research when the packet says web research is denied.
+- Do not read outside the allowed filesystem scope described in the packet.
+- Produce only the final markdown content for the canonical output path.
+- Do not wrap the answer in code fences.
+- Do not add commentary before or after the markdown.
+- Do not modify repository files yourself.
+- Do not change the required output structure from the packet.
+- If the packet asks you to preserve disagreement or uncertainty, preserve it explicitly.
+- If you cannot complete the task within the declared boundary, preserve that limitation explicitly as insufficient access or insufficient evidence within boundary instead of broadening the search.
+
+Authoritative prompt packet follows:
+
+${packetText}
+`;
+}
+async function runCodexWorker(projectRoot, boundedPrompt, outputPath, model, sandboxMode, reasoningEffort, configOverrides, unitId) {
+    const codexArgs = [
+        "exec",
+        "-C",
+        projectRoot,
+        "-s",
+        requireString(sandboxMode, "sandbox-mode"),
+        "-o",
+        outputPath,
+        "--skip-git-repo-check",
+    ];
+    if (typeof reasoningEffort === "string" && reasoningEffort.length > 0) {
+        codexArgs.push("-c", `model_reasoning_effort="${reasoningEffort}"`);
+    }
+    if (typeof model === "string" && model.length > 0) {
+        codexArgs.push("-m", model);
+    }
+    for (const override of configOverrides) {
+        codexArgs.push("-c", override);
+    }
+    codexArgs.push("-");
+    const child = spawn("codex", codexArgs, {
+        cwd: projectRoot,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    // Real-time tee to disk: each codex stdout/stderr chunk is appended to
+    // the running log under the lens output directory so a watcher pane
+    // can `tail -f` it live. The in-memory buffers remain for final error
+    // reporting. Stream path mirrors the nested worker pattern
+    // (hidden filename, sessionRoot/round1/.<lens>.running.log). The
+    // lifecycle — rename on failure / rm on success — happens after the
+    // child exits, below.
+    const outputDir = path.dirname(outputPath);
+    const runningLogPath = path.join(outputDir, `.${unitId}.running.log`);
+    let runningLogStream = null;
+    try {
+        fsSync.mkdirSync(outputDir, { recursive: true });
+        runningLogStream = fsSync.createWriteStream(runningLogPath, { flags: "w" });
+        runningLogStream.write(`ENV-BEFORE unit=${unitId} output=${outputPath}\n`);
+    }
+    catch {
+        // Best-effort; streaming failure must not block the actual codex run.
+        runningLogStream = null;
+    }
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+        stdout += String(chunk);
+        if (runningLogStream)
+            runningLogStream.write(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+        stderr += String(chunk);
+        if (runningLogStream)
+            runningLogStream.write(chunk);
+    });
+    child.stdin.write(boundedPrompt);
+    child.stdin.end();
+    const exitCode = await new Promise((resolve, reject) => {
+        child.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                reject(new Error("codex CLI not found. Install codex or use a different executor."));
+            }
+            else {
+                reject(err);
+            }
+        });
+        child.on("close", (code) => resolve(code ?? 1));
+    });
+    // Flush the stream before deciding cleanup so tail -f readers see final
+    // bytes. ENV-AFTER line is written before close for parse parity with
+    // the codex-nested running log.
+    if (runningLogStream) {
+        try {
+            runningLogStream.write(`ENV-AFTER unit=${unitId} exit=${exitCode}\n`);
+        }
+        catch {
+            // ignore
+        }
+        try {
+            runningLogStream.end();
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (exitCode !== 0) {
+        // Failure path — persist running log for post-hoc inspection at a
+        // stable path (renaming from .running.log to .nested-stderr.log
+        // keeps a single per-lens failure trace filename).
+        try {
+            const nestedErrPath = path.join(outputDir, `.${unitId}.nested-stderr.log`);
+            fsSync.renameSync(runningLogPath, nestedErrPath);
+        }
+        catch {
+            // running log may not exist (stream setup failed) — best effort
+        }
+        const combinedMessage = [stderr.trim(), stdout.trim()]
+            .filter((message) => message.length > 0)
+            .join("\n");
+        throw new Error(combinedMessage.length > 0
+            ? combinedMessage
+            : `Codex worker executor exited with code ${exitCode}`);
+    }
+    // Success — remove the running log to keep round1/ listing principal-
+    // facing lens outputs only. The watcher pane saw it live; the final
+    // result is in <outputPath>.
+    try {
+        fsSync.rmSync(runningLogPath, { force: true });
+    }
+    catch {
+        // ignore
+    }
+    // Codex CLI -o flag may not reliably write the output file.
+    // If the file is missing or empty, fall back to stdout.
+    const outputExists = await fs.access(outputPath).then(() => true, () => false);
+    const outputSize = outputExists ? (await fs.stat(outputPath)).size : 0;
+    if (!outputExists || outputSize === 0) {
+        const normalizedOutput = stdout.trim();
+        if (normalizedOutput.length === 0) {
+            throw new Error("Codex worker executor produced no output (neither -o file nor stdout).");
+        }
+        await fs.writeFile(outputPath, `${normalizedOutput}\n`, "utf8");
+    }
+}
+export async function runCodexReviewUnitExecutorCli(argv) {
+    const { values } = parseArgs({
+        options: {
+            "project-root": { type: "string", default: "." },
+            "session-root": { type: "string" },
+            "unit-id": { type: "string" },
+            "unit-kind": { type: "string" },
+            "packet-path": { type: "string" },
+            "output-path": { type: "string" },
+            model: { type: "string" },
+            "sandbox-mode": { type: "string", default: "read-only" },
+            "reasoning-effort": { type: "string" },
+            "config-override": { type: "string", multiple: true, default: [] },
+        },
+        strict: true,
+        allowPositionals: false,
+        args: argv,
+    });
+    const projectRoot = path.resolve(requireString(values["project-root"], "project-root"));
+    const unitId = requireString(values["unit-id"], "unit-id");
+    const unitKind = requireString(values["unit-kind"], "unit-kind");
+    const packetPath = path.resolve(requireString(values["packet-path"], "packet-path"));
+    const outputPath = path.resolve(requireString(values["output-path"], "output-path"));
+    // Review Recovery PR-1 (R1 observability symmetry). The codex executor does
+    // NOT go through callLlm — it spawns `codex exec` directly — so the PR-1
+    // [model-call] logs in llm-caller.ts cover the background-task path only.
+    // This single startup emit gives parent-process log correlators a breadcrumb
+    // for the lens-execution Codex worker too, so a 5-lens review produces
+    // one [plan:executor] line per lens regardless of provider identity.
+    process.stderr.write(`[plan:executor] kind=codex unit_id=${unitId} model=${typeof values.model === "string" && values.model.length > 0
+        ? values.model
+        : "(codex default)"} sandbox=${values["sandbox-mode"] ?? "read-only"} effort=${typeof values["reasoning-effort"] === "string" && values["reasoning-effort"].length > 0
+        ? values["reasoning-effort"]
+        : "(codex default)"}\n`);
+    const packetText = await fs.readFile(packetPath, "utf8");
+    const boundedPrompt = buildBoundedPrompt(packetPath, packetText, outputPath, unitId, unitKind);
+    await fs.mkdir(path.dirname(outputPath), { recursive: true });
+    await runCodexWorker(projectRoot, boundedPrompt, outputPath, values.model, values["sandbox-mode"], values["reasoning-effort"], values["config-override"], unitId);
+    const outputText = await fs.readFile(outputPath, "utf8");
+    if (outputText.trim().length === 0) {
+        throw new Error(`Codex executor produced empty output: ${outputPath}`);
+    }
+    console.log(JSON.stringify({
+        unit_id: unitId,
+        unit_kind: unitKind,
+        packet_path: packetPath,
+        output_path: outputPath,
+        realization: "worker",
+        host_runtime: "codex",
+    }, null, 2));
+    return 0;
+}
+async function main() {
+    return runCodexReviewUnitExecutorCli(process.argv.slice(2));
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().then((exitCode) => process.exit(exitCode), (error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}

package/dist/core-runtime/cli/complete-review-session.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { runAssembleReviewRecordCli } from "./assemble-review-record.js";
+import { runRenderReviewFinalOutputCli } from "./render-review-final-output.js";
+import { printOntoReleaseChannelNotice } from "../release-channel/release-channel.js";
+function requireString(value, optionName) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Missing required option --${optionName}`);
+    }
+    return value;
+}
+async function main() {
+    await printOntoReleaseChannelNotice();
+    return runCompleteReviewSessionCli(process.argv.slice(2));
+}
+export async function completeReviewSession(argv) {
+    const { values } = parseArgs({
+        options: {
+            "project-root": { type: "string", default: "." },
+            "onto-home": { type: "string" },
+            "session-root": { type: "string" },
+            "request-text": { type: "string" },
+        },
+        strict: true,
+        allowPositionals: false,
+        args: argv,
+    });
+    const projectRoot = requireString(values["project-root"], "project-root");
+    const sessionRoot = requireString(values["session-root"], "session-root");
+    const requestText = requireString(values["request-text"], "request-text");
+    await runRenderReviewFinalOutputCli([
+        "--project-root",
+        projectRoot,
+        "--session-root",
+        sessionRoot,
+    ]);
+    await runAssembleReviewRecordCli([
+        "--project-root",
+        projectRoot,
+        "--session-root",
+        sessionRoot,
+        "--request-text",
+        requestText,
+    ]);
+    return {
+        session_root: sessionRoot,
+        bounded_complete_steps: [
+            "review:render-final-output",
+            "review:finalize-session",
+        ],
+    };
+}
+export async function runCompleteReviewSessionCli(argv) {
+    const result = await completeReviewSession(argv);
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().then((exitCode) => process.exit(exitCode), (error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    });
+}