@crown-dev-studios/review-council 0.3.0 → 0.4.0

package/README.md

@@ -14,9 +14,9 @@ The orchestrator handles the happy path and common failure modes:
 
 - Stage timeouts with two-phase kill (SIGTERM then SIGKILL) prevent hung runs
 - Automatic retry with exponential backoff handles transient failures
-- Interactive prompts from reviewer CLIs are detected and relayed to the user
+- Every stage emits a JSONL stdout event stream for diagnosis
 - Partial reviewer failure still allows the judge to run on available data
-- Failed stages surface stderr excerpts and validation errors in the HTML report
+- Failed stages surface stderr excerpts, validation errors, warnings, and stream log paths in the HTML report
 
 ## Requirements
 
@@ -66,18 +66,13 @@ Main outputs:
 --retries <n>                     Max retries per stage on failure (default: 2)
 ```
 
-### Overrides (optional)
+### Execution Contract
 
-```
---claude-command <command>        Override default Claude reviewer command
---codex-command <command>         Override default Codex reviewer command
---judge-command <command>         Override default judge command
---allow-missing-sentinel          Treat exit code 0 as success without done.json
-```
+There are no command override or sentinel bypass flags. Review Council uses canonical built-in execution metadata for Claude, Codex, and the judge, and every executable stage still requires exit code `0` plus its expected artifacts plus `done.json`.
 
 ## Operational Rules
 
-- Use non-interactive reviewer commands when possible. Interactive prompts are detected and relayed to the user, but explicit non-interactive mode is more reliable.
+- Built-in reviewer commands are non-interactive and emit JSONL to stdout.
 - Keep reviewer artifacts inside the run directory.
 - Selected skills are passed into reviewer prompts as additional review lenses for the run; the orchestrator does not inline local `SKILL.md` contents.
 - Do not create authoritative files in `todos/` during raw review.
@@ -90,9 +85,9 @@ If a run fails or stalls, inspect:
 - `<run>/claude/status.json`
 - `<run>/codex/status.json`
 - `<run>/judge/status.json`
-- each stage's `stdout.log` and `stderr.log`
+- each stage's `stream.jsonl` and `stderr.log`
 
-The `status.json` for each stage includes `exit_code`, `timed_out`, `attempts`, `retried`, and `validation_errors` fields. The HTML report surfaces stderr excerpts and validation errors for failed stages in a diagnostics section.
+The `status.json` for each stage includes `exit_code`, `timed_out`, `attempts`, `missing_artifacts`, and `validation_errors`. Stages additionally record stream artifact paths, `last_activity_at`, `last_event_type`, `stream_event_count`, `stream_parse_errors`, and optional warnings.
 
 If a stage exits `0` but does not write `done.json`, the stage is incomplete and the run should be treated as failed.
 
@@ -135,4 +130,3 @@ Update [`package.json`](package.json) `repository` / `homepage` / `bugs` if the
 - [references/output-contract.md](references/output-contract.md)
 - [src/orchestrate-review-council.ts](src/orchestrate-review-council.ts)
 - [src/render-review-html.ts](src/render-review-html.ts)
-- [src/interaction-queue.ts](src/interaction-queue.ts)

package/dist/orchestrate-review-council.js

@@ -4,12 +4,9 @@ import { basename, resolve } from "node:path";
 import { finished } from "node:stream/promises";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { close as closeInteractionQueue, enqueue } from "./interaction-queue.js";
 import { buildReviewPaths, createRunId, normalizeReviewTarget, } from "./review-session.js";
 import { renderRunDir, writeFollowUpsMarkdown } from "./render-review-html.js";
-const INTERACTIVE_PROMPT_RE = /(\? |: |> |y\/n|yes\/no)\s*$/i;
-const PROMPT_SILENCE_MS = 3000;
-const PROMPT_CHECK_INTERVAL_MS = 2000;
+import { createStageExecution } from "./stage-runtime.js";
 const DEFAULT_TIMEOUT_MS = 300000;
 const DEFAULT_MAX_RETRIES = 2;
 const REVIEW_PROFILE_TEMPLATES = {
@@ -18,9 +15,6 @@ const REVIEW_PROFILE_TEMPLATES = {
 const JUDGE_PROFILE_TEMPLATES = {
     default: "judge.md",
 };
-const DEFAULT_CLAUDE_COMMAND = 'claude --dangerously-skip-permissions -p "$(cat $CLAUDE_DIR/claude-review-export.md)"';
-const DEFAULT_CODEX_COMMAND = 'codex exec --dangerously-bypass-approvals-and-sandbox "$(cat $CODEX_DIR/codex-review-export.md)"';
-const DEFAULT_JUDGE_COMMAND = 'codex exec --dangerously-bypass-approvals-and-sandbox "$(cat $JUDGE_DIR/judge.md)"';
 function nowIso() {
     return new Date().toISOString();
 }
@@ -122,53 +116,84 @@ function resolvePromptSelection(packageDir, kind, profileId, overridePath) {
         profileId,
     };
 }
-function cleanupStageFiles(stageDir, artifactNames) {
-    for (const fileName of [
-        "stdout.log",
-        "stderr.log",
-        "status.json",
-        "done.json",
-        ...artifactNames,
-    ]) {
-        rmSync(resolve(stageDir, fileName), { force: true, recursive: false });
+function cleanupStageFiles(stage) {
+    const artifactPaths = new Set([
+        stage.execution.artifacts.streamLog,
+        stage.execution.artifacts.stderrLog,
+        resolve(stage.stageDir, "status.json"),
+        resolve(stage.stageDir, "done.json"),
+        ...stage.requiredArtifacts.map((artifactName) => resolve(stage.stageDir, artifactName)),
+    ]);
+    for (const artifactPath of artifactPaths) {
+        rmSync(artifactPath, { force: true, recursive: false });
+    }
+}
+function extractEventType(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
     }
+    const type = value.type;
+    return typeof type === "string" && type.length > 0 ? type : undefined;
 }
-async function runStageOnce(name, command, stageDir, workdir, timeoutMs, commandEnv) {
-    const stdoutPath = resolve(stageDir, "stdout.log");
-    const stderrPath = resolve(stageDir, "stderr.log");
+async function runStageOnce(stage, workdir, timeoutMs, commandEnv) {
+    const { execution } = stage;
+    const streamPath = execution.artifacts.streamLog;
+    const stderrPath = execution.artifacts.stderrLog;
     const startedAt = nowIso();
-    const stdoutFile = createWriteStream(stdoutPath);
+    const streamFile = createWriteStream(streamPath);
     const stderrFile = createWriteStream(stderrPath);
-    const child = spawn("/bin/sh", ["-c", command], {
+    const child = spawn("/bin/sh", ["-c", execution.command], {
         cwd: workdir,
         stdio: ["pipe", "pipe", "pipe"],
         env: { ...process.env, ...commandEnv },
     });
-    child.stdout.pipe(stdoutFile);
-    child.stderr.pipe(stderrFile);
-    const rollingBufferSize = 1024;
-    let recentOutput = "";
-    let lastOutputTime = 0;
+    child.stdin.end();
+    const warnings = [];
+    let lastActivityAt;
+    let lastEventType;
+    let streamBuffer = "";
+    let streamEventCount = 0;
+    let streamParseErrors = 0;
+    const recordActivity = (eventType) => {
+        lastActivityAt = nowIso();
+        if (eventType) {
+            lastEventType = eventType;
+        }
+    };
+    const processStructuredLine = (line) => {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            return;
+        }
+        recordActivity(lastEventType);
+        try {
+            const parsed = JSON.parse(trimmed);
+            streamEventCount += 1;
+            lastEventType = extractEventType(parsed) ?? "stream-event";
+        }
+        catch {
+            streamParseErrors += 1;
+            lastEventType = "stream-parse-error";
+            warnings.push(`Failed to parse ${stage.name} stream output line ${streamParseErrors}.`);
+        }
+    };
     child.stdout.on("data", (chunk) => {
-        recentOutput = (recentOutput + chunk.toString()).slice(-rollingBufferSize);
-        lastOutputTime = Date.now();
-    });
-    const promptInterval = setInterval(() => {
-        if (lastOutputTime > 0 &&
-            Date.now() - lastOutputTime > PROMPT_SILENCE_MS &&
-            INTERACTIVE_PROMPT_RE.test(recentOutput) &&
-            child.stdin.writable) {
-            const promptText = recentOutput;
-            recentOutput = "";
-            lastOutputTime = 0;
-            enqueue({
-                stage: name,
-                prompt: promptText,
-                stdinPipe: child.stdin,
-                resolve: () => { },
-            });
+        streamFile.write(chunk);
+        const text = chunk.toString();
+        streamBuffer += text;
+        while (true) {
+            const newlineIndex = streamBuffer.indexOf("\n");
+            if (newlineIndex === -1) {
+                break;
+            }
+            const line = streamBuffer.slice(0, newlineIndex);
+            streamBuffer = streamBuffer.slice(newlineIndex + 1);
+            processStructuredLine(line);
         }
-    }, PROMPT_CHECK_INTERVAL_MS);
+    });
+    child.stderr.on("data", (chunk) => {
+        stderrFile.write(chunk);
+    });
     let timedOut = false;
     let killTimer = null;
     const timeoutTimer = setTimeout(() => {
@@ -190,17 +215,13 @@ async function runStageOnce(name, command, stageDir, workdir, timeoutMs, command
     clearTimeout(timeoutTimer);
     if (killTimer)
         clearTimeout(killTimer);
-    clearInterval(promptInterval);
-    try {
-        child.stdin.end();
+    if (streamBuffer.trim().length > 0) {
+        processStructuredLine(streamBuffer);
     }
-    catch {
-        // The pipe may already be closed.
-    }
-    stdoutFile.end();
+    streamFile.end();
     stderrFile.end();
     await Promise.all([
-        finished(stdoutFile),
+        finished(streamFile),
         finished(stderrFile),
     ]);
     return {
@@ -208,16 +229,18 @@ async function runStageOnce(name, command, stageDir, workdir, timeoutMs, command
         timedOut,
         startedAt,
         finishedAt: nowIso(),
-        stdoutPath,
+        streamPath,
         stderrPath,
+        lastActivityAt,
+        lastEventType,
+        streamEventCount,
+        streamParseErrors,
+        warnings,
     };
 }
-export function evaluateStageArtifacts(stage, attempt, requireSentinel) {
+export function evaluateStageArtifacts(stage, attempt) {
     const artifactPresence = {};
-    const requiredArtifacts = [...stage.requiredArtifacts];
-    if (requireSentinel) {
-        requiredArtifacts.push("done.json");
-    }
+    const requiredArtifacts = [...stage.requiredArtifacts, "done.json"];
     for (const artifactName of requiredArtifacts) {
         artifactPresence[artifactName] = existsSync(resolve(stage.stageDir, artifactName));
     }
@@ -228,6 +251,7 @@ export function evaluateStageArtifacts(stage, attempt, requireSentinel) {
             failureReason: "timeout",
             artifactPresence,
             missingArtifacts,
+            validationErrors: [],
         };
     }
     if (attempt.exitCode !== 0) {
@@ -236,6 +260,7 @@ export function evaluateStageArtifacts(stage, attempt, requireSentinel) {
             failureReason: "process_failed",
             artifactPresence,
             missingArtifacts,
+            validationErrors: [],
         };
     }
     if (missingArtifacts.length > 0) {
@@ -244,21 +269,24 @@ export function evaluateStageArtifacts(stage, attempt, requireSentinel) {
             failureReason: "missing_artifacts",
             artifactPresence,
             missingArtifacts,
+            validationErrors: [],
         };
     }
-    const structuredArtifactIsValid = validateJsonArtifact(resolve(stage.stageDir, stage.jsonArtifactName), stage.jsonArtifactName);
-    if (!structuredArtifactIsValid) {
+    const validationErrors = validateJsonArtifact(resolve(stage.stageDir, stage.jsonArtifactName), stage.jsonArtifactName);
+    if (validationErrors.length > 0) {
         return {
             success: false,
             failureReason: "invalid_artifacts",
             artifactPresence,
             missingArtifacts,
+            validationErrors,
         };
     }
     return {
         success: true,
         artifactPresence,
         missingArtifacts,
+        validationErrors: [],
     };
 }
 function validateJsonArtifact(artifactPath, artifactName) {
@@ -267,43 +295,57 @@ function validateJsonArtifact(artifactPath, artifactName) {
         parsed = JSON.parse(readFileSync(artifactPath, "utf8"));
     }
     catch {
-        return false;
+        return [{ path: "$", message: "File is not valid JSON." }];
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        return false;
+        return [{ path: "$", message: "Expected a JSON object." }];
     }
     if (artifactName === "findings.json") {
-        return Array.isArray(parsed.findings);
+        return Array.isArray(parsed.findings)
+            ? []
+            : [{ path: "findings", message: "Expected findings to be an array." }];
     }
     const verdict = parsed;
-    return typeof verdict.overall_verdict === "string"
-        && Array.isArray(verdict.confirmed_findings)
-        && Array.isArray(verdict.contested_findings)
-        && Array.isArray(verdict.rejected_findings);
+    const errors = [];
+    if (typeof verdict.overall_verdict !== "string") {
+        errors.push({ path: "overall_verdict", message: "Expected overall_verdict to be a string." });
+    }
+    if (!Array.isArray(verdict.confirmed_findings)) {
+        errors.push({ path: "confirmed_findings", message: "Expected confirmed_findings to be an array." });
+    }
+    if (!Array.isArray(verdict.contested_findings)) {
+        errors.push({ path: "contested_findings", message: "Expected contested_findings to be an array." });
+    }
+    if (!Array.isArray(verdict.rejected_findings)) {
+        errors.push({ path: "rejected_findings", message: "Expected rejected_findings to be an array." });
+    }
+    return errors;
 }
-function writeStageStatus(statusPath, stage, command, attempt, evaluation, requireSentinel, attempts) {
+function writeStageStatus(statusPath, stage, attempt, evaluation, attempts) {
     writeFileSync(statusPath, `${JSON.stringify({
         stage: stage.name,
-        command,
+        command_id: stage.execution.commandId,
+        command: stage.execution.command,
         started_at: attempt.startedAt,
         finished_at: attempt.finishedAt,
         exit_code: attempt.exitCode,
-        require_sentinel: requireSentinel,
-        done_file_present: evaluation.artifactPresence["done.json"] ?? false,
         success: evaluation.success,
         timed_out: attempt.timedOut,
         attempts,
-        retried: attempts > 1,
-        stdout_log: attempt.stdoutPath,
+        stream_log: attempt.streamPath,
         stderr_log: attempt.stderrPath,
+        last_activity_at: attempt.lastActivityAt,
+        last_event_type: attempt.lastEventType,
+        stream_event_count: attempt.streamEventCount,
+        stream_parse_errors: attempt.streamParseErrors,
+        artifact_presence: evaluation.artifactPresence,
+        missing_artifacts: evaluation.missingArtifacts,
+        validation_errors: evaluation.validationErrors,
+        ...(attempt.warnings.length > 0 ? { warnings: attempt.warnings } : {}),
     }, null, 2)}\n`);
 }
-async function runStage(stage, workdir, requireSentinel, timeoutMs, maxRetries, commandEnv) {
-    if (!stage.command) {
-        return null;
-    }
+async function runStage(stage, workdir, timeoutMs, maxRetries, commandEnv) {
     const statusPath = resolve(stage.stageDir, "status.json");
-    const command = stage.command;
     let attempts = 0;
     let lastAttempt = null;
     let lastEvaluation = null;
@@ -314,10 +356,10 @@ async function runStage(stage, workdir, requireSentinel, timeoutMs, maxRetries,
             await new Promise((resolveDelay) => setTimeout(resolveDelay, delayMs));
         }
         attempts = attemptIndex + 1;
-        cleanupStageFiles(stage.stageDir, stage.requiredArtifacts);
-        lastAttempt = await runStageOnce(stage.name, command, stage.stageDir, workdir, timeoutMs, commandEnv);
-        lastEvaluation = evaluateStageArtifacts(stage, lastAttempt, requireSentinel);
-        writeStageStatus(statusPath, stage, command, lastAttempt, lastEvaluation, requireSentinel, attempts);
+        cleanupStageFiles(stage);
+        lastAttempt = await runStageOnce(stage, workdir, timeoutMs, commandEnv);
+        lastEvaluation = evaluateStageArtifacts(stage, lastAttempt);
+        writeStageStatus(statusPath, stage, lastAttempt, lastEvaluation, attempts);
         if (lastEvaluation.success || lastAttempt.timedOut) {
             break;
         }
@@ -334,80 +376,89 @@ async function runStage(stage, workdir, requireSentinel, timeoutMs, maxRetries,
         failure_reason: lastEvaluation.failureReason,
         missing_artifacts: lastEvaluation.missingArtifacts,
         artifact_presence: lastEvaluation.artifactPresence,
+        validation_errors: lastEvaluation.validationErrors,
     };
 }
 export function parseCliOptions(args) {
-    const { values } = parseArgs({
-        args,
-        allowPositionals: false,
-        options: {
-            target: { type: "string" },
-            "run-dir": { type: "string" },
-            "review-profile": { type: "string" },
-            "judge-profile": { type: "string" },
-            "claude-prompt-template": { type: "string" },
-            "codex-prompt-template": { type: "string" },
-            "judge-prompt-template": { type: "string" },
-            "claude-command": { type: "string" },
-            "codex-command": { type: "string" },
-            "judge-command": { type: "string" },
-            "skill-paths": { type: "string" },
-            "no-claude": { type: "boolean" },
-            "no-codex": { type: "boolean" },
-            "allow-missing-sentinel": { type: "boolean" },
-            "skip-judge": { type: "boolean" },
-            "skip-html": { type: "boolean" },
-            "open-html": { type: "boolean" },
-            timeout: { type: "string" },
-            retries: { type: "string" },
-            help: { type: "boolean", short: "h" },
-        },
-    });
+    let values;
+    const getString = (value) => typeof value === "string" ? value : undefined;
+    const getBoolean = (value) => value === true;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            options: {
+                target: { type: "string" },
+                "run-dir": { type: "string" },
+                "review-profile": { type: "string" },
+                "judge-profile": { type: "string" },
+                "claude-prompt-template": { type: "string" },
+                "codex-prompt-template": { type: "string" },
+                "judge-prompt-template": { type: "string" },
+                "skill-paths": { type: "string" },
+                "no-claude": { type: "boolean" },
+                "no-codex": { type: "boolean" },
+                "skip-judge": { type: "boolean" },
+                "skip-html": { type: "boolean" },
+                "open-html": { type: "boolean" },
+                timeout: { type: "string" },
+                retries: { type: "string" },
+                help: { type: "boolean", short: "h" },
+            },
+        }));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return null;
+    }
     if (values.help) {
         printHelp();
         return null;
     }
-    if (!values.target) {
+    const target = getString(values.target);
+    if (!target) {
         console.error("Error: --target is required.");
         printHelp();
         process.exitCode = 1;
         return null;
     }
-    const timeoutMs = values.timeout ? parseInt(values.timeout, 10) : DEFAULT_TIMEOUT_MS;
+    const timeoutValue = getString(values.timeout);
+    const timeoutMs = timeoutValue ? parseInt(timeoutValue, 10) : DEFAULT_TIMEOUT_MS;
     if (Number.isNaN(timeoutMs) || timeoutMs <= 0) {
-        console.error(`Invalid --timeout: "${values.timeout}". Must be a positive integer (ms).`);
+        console.error(`Invalid --timeout: "${timeoutValue}". Must be a positive integer (ms).`);
         process.exitCode = 1;
         return null;
     }
-    const maxRetries = values.retries ? parseInt(values.retries, 10) : DEFAULT_MAX_RETRIES;
+    const retriesValue = getString(values.retries);
+    const maxRetries = retriesValue ? parseInt(retriesValue, 10) : DEFAULT_MAX_RETRIES;
     if (Number.isNaN(maxRetries) || maxRetries < 0) {
-        console.error(`Invalid --retries: "${values.retries}". Must be a non-negative integer.`);
+        console.error(`Invalid --retries: "${retriesValue}". Must be a non-negative integer.`);
         process.exitCode = 1;
         return null;
     }
-    const noClaude = values["no-claude"] ?? false;
-    const noCodex = values["no-codex"] ?? false;
+    const noClaude = getBoolean(values["no-claude"]);
+    const noCodex = getBoolean(values["no-codex"]);
     if (noClaude && noCodex) {
         console.error("Cannot use both --no-claude and --no-codex. At least one model reviewer is required.");
         process.exitCode = 1;
         return null;
     }
+    const skillPathsValue = getString(values["skill-paths"]);
     return {
-        target: values.target,
-        runDir: values["run-dir"],
-        reviewProfileId: values["review-profile"] ?? "default",
-        judgeProfileId: values["judge-profile"] ?? "default",
-        claudePromptTemplate: values["claude-prompt-template"],
-        codexPromptTemplate: values["codex-prompt-template"],
-        judgePromptTemplate: values["judge-prompt-template"],
-        claudeCommand: noClaude ? undefined : (values["claude-command"] ?? DEFAULT_CLAUDE_COMMAND),
-        codexCommand: noCodex ? undefined : (values["codex-command"] ?? DEFAULT_CODEX_COMMAND),
-        judgeCommand: values["judge-command"] ?? DEFAULT_JUDGE_COMMAND,
-        allowMissingSentinel: values["allow-missing-sentinel"] ?? false,
-        skipJudge: values["skip-judge"] ?? false,
-        skipHtml: values["skip-html"] ?? false,
-        openHtml: values["open-html"] ?? false,
-        skillPaths: values["skill-paths"] ? normalizeSkillPaths(values["skill-paths"]) : undefined,
+        target,
+        runDir: getString(values["run-dir"]),
+        enableClaude: !noClaude,
+        enableCodex: !noCodex,
+        reviewProfileId: getString(values["review-profile"]) ?? "default",
+        judgeProfileId: getString(values["judge-profile"]) ?? "default",
+        claudePromptTemplate: getString(values["claude-prompt-template"]),
+        codexPromptTemplate: getString(values["codex-prompt-template"]),
+        judgePromptTemplate: getString(values["judge-prompt-template"]),
+        skipJudge: getBoolean(values["skip-judge"]),
+        skipHtml: getBoolean(values["skip-html"]),
+        openHtml: getBoolean(values["open-html"]),
+        skillPaths: skillPathsValue ? normalizeSkillPaths(skillPathsValue) : undefined,
         timeoutMs,
         maxRetries,
     };
@@ -421,14 +472,14 @@ function resolvePromptSelections(packageDir, options, judgeEnabled) {
             : null,
     };
 }
-function createStageDefinitions(paths, promptSelections, commands, reviewTarget, reviewSchemaPath, judgeSchemaPath, skillReferences) {
-    const reviewerStages = [
-        {
+function createStageDefinitions(paths, promptSelections, enabledStages, reviewTarget, reviewSchemaPath, judgeSchemaPath, skillReferences) {
+    const reviewerStages = [];
+    if (enabledStages.claude) {
+        reviewerStages.push({
             name: "claude",
-            displayName: "Claude",
-            command: commands.claude,
             stageDir: paths.claudeDir,
             promptOutputName: "claude-review-export.md",
+            execution: createStageExecution("claude", paths.claudeDir, "claude-review-export.md"),
             promptTemplatePath: promptSelections.claude.templatePath,
             promptTemplateSource: promptSelections.claude.source,
             requiredArtifacts: ["report.md", "findings.json"],
@@ -443,13 +494,14 @@ function createStageDefinitions(paths, promptSelections, commands, reviewTarget,
                 REVIEWER_NAME_LOWER: "claude",
                 SKILL_REFERENCES: skillReferences,
             },
-        },
-        {
+        });
+    }
+    if (enabledStages.codex) {
+        reviewerStages.push({
             name: "codex",
-            displayName: "Codex",
-            command: commands.codex,
             stageDir: paths.codexDir,
             promptOutputName: "codex-review-export.md",
+            execution: createStageExecution("codex", paths.codexDir, "codex-review-export.md"),
             promptTemplatePath: promptSelections.codex.templatePath,
             promptTemplateSource: promptSelections.codex.source,
             requiredArtifacts: ["report.md", "findings.json"],
@@ -464,19 +516,18 @@ function createStageDefinitions(paths, promptSelections, commands, reviewTarget,
                 REVIEWER_NAME_LOWER: "codex",
                 SKILL_REFERENCES: skillReferences,
             },
-        },
-    ];
-    if (!promptSelections.judge) {
+        });
+    }
+    if (!enabledStages.judge || !promptSelections.judge) {
         return reviewerStages;
     }
     return [
         ...reviewerStages,
         {
             name: "judge",
-            displayName: "Judge",
-            command: commands.judge,
             stageDir: paths.judgeDir,
             promptOutputName: "judge.md",
+            execution: createStageExecution("judge", paths.judgeDir, "judge.md"),
             promptTemplatePath: promptSelections.judge.templatePath,
             promptTemplateSource: promptSelections.judge.source,
             requiredArtifacts: ["summary.md", "verdict.json"],
@@ -491,8 +542,24 @@ function createStageDefinitions(paths, promptSelections, commands, reviewTarget,
         },
     ];
 }
+function serializeExecutionMetadata(stage) {
+    if (!stage) {
+        return null;
+    }
+    return {
+        stage_dir: stage.stageDir,
+        prompt_output_name: stage.promptOutputName,
+        command_id: stage.execution.commandId,
+        command: stage.execution.command,
+        artifacts: {
+            stream_log: stage.execution.artifacts.streamLog,
+            stderr_log: stage.execution.artifacts.stderrLog,
+        },
+    };
+}
 function writeRunMetadata(preparedRun) {
-    const { options, cwd, packageDir, reviewTarget, runId, judgeEnabled, paths, promptSelections, } = preparedRun;
+    const { options, cwd, packageDir, reviewTarget, runId, judgeEnabled, paths, promptSelections, stageDefinitions, } = preparedRun;
+    const stageIndex = new Map(stageDefinitions.map((stage) => [stage.name, stage]));
     writeFileSync(resolve(paths.runDir, "run.json"), `${JSON.stringify({
         run_id: runId,
         review_target: reviewTarget,
@@ -517,10 +584,11 @@ function writeRunMetadata(preparedRun) {
                 source: promptSelections.judge?.source ?? null,
             },
         },
-        command_templates: {
-            claude: options.claudeCommand ?? null,
-            codex: options.codexCommand ?? null,
-            judge: judgeEnabled ? options.judgeCommand ?? null : null,
+        judge_enabled: judgeEnabled,
+        stage_executions: {
+            claude: serializeExecutionMetadata(stageIndex.get("claude")),
+            codex: serializeExecutionMetadata(stageIndex.get("codex")),
+            judge: serializeExecutionMetadata(stageIndex.get("judge")),
         },
     }, null, 2)}\n`);
 }
@@ -531,7 +599,7 @@ function prepareRun(options) {
     const reviewTarget = normalizeReviewTarget(options.target);
     const runId = createRunId();
     const paths = buildReviewPaths(cwd, runId, options.runDir);
-    const judgeEnabled = !options.skipJudge && Boolean(options.judgeCommand);
+    const judgeEnabled = !options.skipJudge;
     let promptSelections;
     try {
         promptSelections = resolvePromptSelections(packageDir, options, judgeEnabled);
@@ -557,33 +625,37 @@ function prepareRun(options) {
         REVIEW_SCHEMA: reviewSchemaPath,
         JUDGE_SCHEMA: judgeSchemaPath,
     };
-    const rawCommands = {
-        claude: options.claudeCommand,
-        codex: options.codexCommand,
-        judge: judgeEnabled ? options.judgeCommand : undefined,
-    };
     const skillReferences = buildSkillReferencesSection(options.skillPaths ?? []);
-    const stageDefinitions = createStageDefinitions(paths, promptSelections, rawCommands, reviewTarget, reviewSchemaPath, judgeSchemaPath, skillReferences);
-    for (const stage of stageDefinitions) {
-        renderTemplate(stage.promptTemplatePath, stage.stageVars, resolve(stage.stageDir, stage.promptOutputName));
-    }
-    writeRunMetadata({
-        options,
-        cwd,
-        packageDir,
-        reviewTarget,
-        runId,
-        judgeEnabled,
-        requireSentinel: !options.allowMissingSentinel,
-        paths,
-        promptSelections,
-        commandEnv,
-        stageDefinitions,
-    });
-    for (const command of Object.values(rawCommands)) {
-        if (command) {
-            assertBinaryExists(command, cwd);
+    let stageDefinitions;
+    try {
+        stageDefinitions = createStageDefinitions(paths, promptSelections, {
+            claude: options.enableClaude,
+            codex: options.enableCodex,
+            judge: judgeEnabled,
+        }, reviewTarget, reviewSchemaPath, judgeSchemaPath, skillReferences);
+        for (const stage of stageDefinitions) {
+            renderTemplate(stage.promptTemplatePath, stage.stageVars, resolve(stage.stageDir, stage.promptOutputName));
         }
+        writeRunMetadata({
+            options,
+            cwd,
+            packageDir,
+            reviewTarget,
+            runId,
+            judgeEnabled,
+            paths,
+            promptSelections,
+            commandEnv,
+            stageDefinitions,
+        });
+        for (const stage of stageDefinitions) {
+            assertBinaryExists(stage.execution.command, cwd);
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+        return null;
     }
     return {
         options,
@@ -592,7 +664,6 @@ function prepareRun(options) {
         reviewTarget,
         runId,
         judgeEnabled,
-        requireSentinel: !options.allowMissingSentinel,
         paths,
         promptSelections,
         commandEnv,
@@ -601,9 +672,8 @@ function prepareRun(options) {
 }
 async function runReviewerStages(preparedRun) {
     const reviewerStages = preparedRun.stageDefinitions.filter((s) => s.name !== "judge");
-    const results = await Promise.all(reviewerStages.map((stage) => runStage(stage, preparedRun.cwd, preparedRun.requireSentinel, preparedRun.options.timeoutMs, preparedRun.options.maxRetries, preparedRun.commandEnv)));
-    closeInteractionQueue();
-    const reviewerResults = results.filter((result) => result !== null);
+    const results = await Promise.all(reviewerStages.map((stage) => runStage(stage, preparedRun.cwd, preparedRun.options.timeoutMs, preparedRun.options.maxRetries, preparedRun.commandEnv)));
+    const reviewerResults = results;
     const successfulReviewerResults = reviewerResults.filter((result) => result.success);
     return {
         reviewerResults,
@@ -628,7 +698,7 @@ async function runJudgeStage(preparedRun, reviewerExecution) {
     if (!judgeStage) {
         return null;
     }
-    return runStage(judgeStage, preparedRun.cwd, preparedRun.requireSentinel, preparedRun.options.timeoutMs, preparedRun.options.maxRetries, preparedRun.commandEnv);
+    return runStage(judgeStage, preparedRun.cwd, preparedRun.options.timeoutMs, preparedRun.options.maxRetries, preparedRun.commandEnv);
 }
 function finalizeRun(preparedRun, reviewerExecution, judgeResult) {
     if (judgeResult?.success === true) {
@@ -678,10 +748,6 @@ options:
   --claude-prompt-template <path>         Override Claude reviewer prompt template
   --codex-prompt-template <path>          Override Codex reviewer prompt template
   --judge-prompt-template <path>          Override judge prompt template
-  --claude-command <command>              Shell command to launch Claude reviewer
-  --codex-command <command>               Shell command to launch Codex reviewer
-  --judge-command <command>               Shell command to launch the judge stage
-  --allow-missing-sentinel                Treat exit code 0 as success without done.json
   --skip-judge                            Skip the judge stage
   --skip-html                             Skip HTML rendering
   --open-html                             Open index.html after rendering (macOS)

package/dist/render-review-html.js

@@ -70,6 +70,12 @@ function stageStatusRow(name, status) {
         if (Array.isArray(status.missing_artifacts) && status.missing_artifacts.length > 0) {
             details.push(`${status.missing_artifacts.length} missing artifact(s)`);
         }
+        if (typeof status.stream_parse_errors === "number" && status.stream_parse_errors > 0) {
+            details.push(`${status.stream_parse_errors} stream parse error(s)`);
+        }
+        if (Array.isArray(status.warnings) && status.warnings.length > 0) {
+            details.push(`${status.warnings.length} warning(s)`);
+        }
     }
     const detailSpan = details.length > 0
         ? `<span class="status-details">${htmlEscape(details.join(" · "))}</span>`
@@ -106,6 +112,15 @@ function buildDiagnostics(runDir, statuses) {
             }
             parts.push("</ul>");
         }
+        if (Array.isArray(status.warnings) && status.warnings.length > 0) {
+            parts.push("<p><strong>Warnings:</strong></p><ul>");
+            for (const warning of status.warnings) {
+                if (typeof warning !== "string")
+                    continue;
+                parts.push(`<li>${htmlEscape(warning)}</li>`);
+            }
+            parts.push("</ul>");
+        }
         if (Array.isArray(status.missing_artifacts) && status.missing_artifacts.length > 0) {
             const missingArtifacts = status.missing_artifacts;
             parts.push("<p><strong>Missing artifacts:</strong></p><ul>");
@@ -114,18 +129,31 @@ function buildDiagnostics(runDir, statuses) {
             }
             parts.push("</ul>");
         }
+        const lastActivityAt = typeof status.last_activity_at === "string" ? status.last_activity_at : "";
+        const lastEventType = typeof status.last_event_type === "string" ? status.last_event_type : "";
+        const streamEventCount = typeof status.stream_event_count === "number" ? status.stream_event_count : null;
+        const streamParseErrors = typeof status.stream_parse_errors === "number" ? status.stream_parse_errors : null;
+        const executionSummary = [
+            streamEventCount !== null ? `stream events: ${streamEventCount}` : "",
+            streamParseErrors !== null ? `stream parse errors: ${streamParseErrors}` : "",
+            lastActivityAt ? `last activity: ${lastActivityAt}` : "",
+            lastEventType ? `last event: ${lastEventType}` : "",
+        ].filter(Boolean);
+        if (executionSummary.length > 0) {
+            parts.push(`<p><strong>Execution:</strong> ${htmlEscape(executionSummary.join(" · "))}</p>`);
+        }
         const stageDir = resolve(runDir, stage);
         const excerpt = stderrExcerpt(stageDir);
         if (excerpt) {
             parts.push("<p><strong>stderr (last 20 lines):</strong></p>");
             parts.push(`<pre class="stderr-excerpt">${htmlEscape(excerpt)}</pre>`);
         }
-        const stdoutLog = typeof status.stdout_log === "string" ? status.stdout_log : "";
+        const streamLog = typeof status.stream_log === "string" ? status.stream_log : "";
         const stderrLog = typeof status.stderr_log === "string" ? status.stderr_log : "";
-        if (stdoutLog || stderrLog) {
+        if (streamLog || stderrLog) {
             parts.push('<div class="log-paths">');
-            if (stdoutLog)
-                parts.push(`<code>${htmlEscape(stdoutLog)}</code>`);
+            if (streamLog)
+                parts.push(`<code>${htmlEscape(streamLog)}</code>`);
             if (stderrLog)
                 parts.push(`<code>${htmlEscape(stderrLog)}</code>`);
             parts.push("</div>");

package/dist/stage-runtime.js

@@ -0,0 +1,40 @@
+import { resolve } from "node:path";
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function buildCodexCommand(promptPath) {
+    return `codex exec --json --dangerously-bypass-approvals-and-sandbox "$(cat ${shellQuote(promptPath)})"`;
+}
+function createClaudeExecution(stageDir, promptOutputName) {
+    const promptPath = resolve(stageDir, promptOutputName);
+    const streamLog = resolve(stageDir, "stream.jsonl");
+    const stderrLog = resolve(stageDir, "stderr.log");
+    return {
+        commandId: "claude-review",
+        command: `claude --dangerously-skip-permissions --verbose --output-format stream-json --include-partial-messages -p "$(cat ${shellQuote(promptPath)})"`,
+        artifacts: {
+            streamLog,
+            stderrLog,
+        },
+    };
+}
+function createCodexExecution(stageDir, promptOutputName, commandId) {
+    const promptPath = resolve(stageDir, promptOutputName);
+    return {
+        commandId,
+        command: buildCodexCommand(promptPath),
+        artifacts: {
+            streamLog: resolve(stageDir, "stream.jsonl"),
+            stderrLog: resolve(stageDir, "stderr.log"),
+        },
+    };
+}
+export function createStageExecution(stageName, stageDir, promptOutputName) {
+    if (stageName === "claude") {
+        return createClaudeExecution(stageDir, promptOutputName);
+    }
+    if (stageName === "judge") {
+        return createCodexExecution(stageDir, promptOutputName, "codex-judge");
+    }
+    return createCodexExecution(stageDir, promptOutputName, "codex-review");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crown-dev-studios/review-council",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Parallel multi-agent code review orchestration with bundled prompts, schemas, and HTML reporting.",
   "repository": {
     "type": "git",

package/references/cli-integration.md

@@ -1,10 +1,8 @@
 # CLI Integration
 
-The orchestrator script accepts literal CLI commands with placeholders.
+The orchestrator uses canonical built-in stage commands and execution metadata. Callers can choose which stages run and which prompt templates render, but command choice and sentinel enforcement are no longer user-overridable API surfaces.
 
-Best practice: point reviewer CLIs at the rendered prompt files created inside the run directory. This keeps the command templates self-contained and avoids depending on any external `/review-export` command.
-
-Available environment variables in commands:
+Available environment variables in built-in commands:
 
 - `$CWD`
 - `$SKILL_DIR`
@@ -24,20 +22,18 @@ The orchestrator renders these prompt files before launching any stage:
 
 When invoking from the project being reviewed, run `npx @crown-dev-studios/review-council` so `process.cwd()` stays anchored to the project and output lands in `docs/reviews/`.
 
-## Default Commands
+## Built-In Commands
 
-The orchestrator provides sensible defaults for Claude, Codex, and the judge. No command flags are needed for the common case:
+The orchestrator provides canonical stage commands for Claude, Codex, and the judge. No command flags are needed for the common case:
 
 ```bash
 npx @crown-dev-studios/review-council --target "staged changes" --open-html
 ```
 
 Built-in defaults:
-- **Claude:** `claude --dangerously-skip-permissions -p "$(cat $CLAUDE_DIR/claude-review-export.md)"`
-- **Codex:** `codex exec --dangerously-bypass-approvals-and-sandbox "$(cat $CODEX_DIR/codex-review-export.md)"`
-- **Judge:** `codex exec --dangerously-bypass-approvals-and-sandbox "$(cat $JUDGE_DIR/judge.md)"`
-
-Use `--claude-command`, `--codex-command`, or `--judge-command` to override any default.
+- **Claude:** `claude --dangerously-skip-permissions --verbose --output-format stream-json --include-partial-messages -p "$(cat "$CLAUDE_DIR/claude-review-export.md")"`
+- **Codex:** `codex exec --json --dangerously-bypass-approvals-and-sandbox "$(cat $CODEX_DIR/codex-review-export.md)"`
+- **Judge:** `codex exec --json --dangerously-bypass-approvals-and-sandbox "$(cat $JUDGE_DIR/judge.md)"`
 
 Use `--no-claude` or `--no-codex` to skip a model reviewer entirely.
 
@@ -91,17 +87,19 @@ Timed-out stages are not retried.
 
 ### Retries
 
-`--retries <n>` (default: 2) retries a stage up to N times on non-zero exit. Delay between retries uses exponential backoff: `2000 * 2^(attempt-1)` ms (2s, 4s, 8s...). The final `status.json` records `attempts` and `retried` fields.
+`--retries <n>` (default: 2) retries a stage up to N times on non-zero exit. Delay between retries uses exponential backoff: `2000 * 2^(attempt-1)` ms (2s, 4s, 8s...). The final `status.json` records the final `attempts` count.
 
 Retries are skipped for timeouts (not transient).
 
-### Interactive Prompt Detection
+### JSONL Streams
 
-The orchestrator monitors each reviewer's stdout for prompt-like output (lines ending with `? `, `: `, `> `, or containing `y/n`, `yes/no`) followed by 3 seconds of silence. When detected, the prompt is relayed to the user's terminal and the response is piped back to the child's stdin.
+All built-in stages emit JSONL events on stdout:
 
-If both reviewers prompt simultaneously, questions are queued and presented one at a time.
+- Claude via `--output-format stream-json`
+- Codex reviewer via `codex exec --json`
+- Codex judge via `codex exec --json`
 
-This is a best-effort safety net. Prefer explicit non-interactive mode (`claude --dangerously-skip-permissions -p`, `codex exec --dangerously-bypass-approvals-and-sandbox`) when possible.
+The orchestrator records that stdout directly to `stream.jsonl` for each stage and derives `last_activity_at`, `last_event_type`, `stream_event_count`, and `stream_parse_errors` from that one stream.
 
 ### Partial Judge Execution
 
@@ -116,4 +114,4 @@ The orchestrator waits for:
 - judge exit code `0`
 - judge `done.json`
 
-If a process exits `0` but omits `done.json`, the stage is treated as incomplete.
+If a process exits `0` but omits `done.json`, the stage is treated as incomplete. There is no sentinel bypass mode.

package/references/output-contract.md

@@ -13,21 +13,21 @@ docs/reviews/<run-id>/
     findings.json
     done.json
     status.json
-    stdout.log
+    stream.jsonl
     stderr.log
   codex/
     report.md
     findings.json
     done.json
     status.json
-    stdout.log
+    stream.jsonl
     stderr.log
   judge/
     summary.md
     verdict.json
     done.json
     status.json
-    stdout.log
+    stream.jsonl
     stderr.log
 ```
 
@@ -40,6 +40,7 @@ Each model reviewer (Claude, Codex) writes:
 - `report.md`: human-readable review
 - `findings.json`: structured findings matching `schemas/review-findings.schema.json`
 - `done.json`: sentinel file confirming the agent finished writing artifacts
+- `stream.jsonl`: raw JSONL stdout event stream for the stage
 
 `done.json` shape:
 
@@ -69,18 +70,27 @@ The orchestrator writes `status.json` per stage with these fields:
 ```json
 {
   "stage": "claude",
-  "command": "claude -p ...",
+  "command_id": "claude-review",
+  "command": "claude --dangerously-skip-permissions --verbose --output-format stream-json --include-partial-messages -p ...",
   "started_at": "2026-03-07T18:25:00Z",
   "finished_at": "2026-03-07T18:30:00Z",
   "exit_code": 0,
-  "require_sentinel": true,
-  "done_file_present": true,
   "success": true,
   "timed_out": false,
   "attempts": 1,
-  "retried": false,
-  "stdout_log": "/path/to/stdout.log",
-  "stderr_log": "/path/to/stderr.log"
+  "stream_log": "/path/to/stream.jsonl",
+  "stderr_log": "/path/to/stderr.log",
+  "last_activity_at": "2026-03-07T18:29:59Z",
+  "last_event_type": "stop",
+  "stream_event_count": 42,
+  "stream_parse_errors": 0,
+  "artifact_presence": {
+    "report.md": true,
+    "findings.json": true,
+    "done.json": true
+  },
+  "missing_artifacts": [],
+  "validation_errors": []
 }
 ```
 
@@ -102,8 +112,45 @@ Key fields:
 | `exit_code` | number | Process exit code. `124` on timeout. |
 | `timed_out` | boolean | Whether the stage was killed due to timeout. |
 | `attempts` | number | Total attempts (1 = no retries). |
-| `retried` | boolean | Whether the stage was retried at least once. |
-| `validation_errors` | array? | Schema validation errors if the output JSON was malformed. |
+| `stream_log` | string | JSONL stdout event stream for the stage. |
+| `last_activity_at` | string? | Last observed stream activity timestamp. |
+| `last_event_type` | string? | Last observed stream event type. |
+| `stream_event_count` | number | Parsed stdout event count for the attempt. |
+| `stream_parse_errors` | number | Number of stdout lines that failed JSON parsing. |
+| `missing_artifacts` | array | Required artifacts absent for the final attempt. |
+| `validation_errors` | array | Lightweight output validation errors for malformed structured artifacts. |
+| `warnings` | array? | Non-authoritative observability warnings, such as stream parse issues. |
+
+## Run Metadata
+
+`run.json` records the rendered prompt sources plus canonical execution metadata for each executable stage:
+
+```json
+{
+  "run_id": "20260330-12345678",
+  "review_target": "staged changes",
+  "stage_executions": {
+    "claude": {
+      "command_id": "claude-review",
+      "artifacts": {
+        "stream_log": "/path/to/stream.jsonl"
+      }
+    },
+    "codex": {
+      "command_id": "codex-review",
+      "artifacts": {
+        "stream_log": "/path/to/stream.jsonl"
+      }
+    },
+    "judge": {
+      "command_id": "codex-judge",
+      "artifacts": {
+        "stream_log": "/path/to/stream.jsonl"
+      }
+    }
+  }
+}
+```
 
 ## Bundle Output
 

package/dist/interaction-queue.js

@@ -1,50 +0,0 @@
-import { createInterface } from "node:readline";
-const queue = [];
-let processing = false;
-let readlineInterface = null;
-function getReadline() {
-    if (!readlineInterface) {
-        readlineInterface = createInterface({ input: process.stdin, output: process.stdout });
-    }
-    return readlineInterface;
-}
-function processNext() {
-    if (queue.length === 0) {
-        processing = false;
-        return;
-    }
-    processing = true;
-    const request = queue.shift();
-    if (!request) {
-        processing = false;
-        return;
-    }
-    const reader = getReadline();
-    process.stderr.write(`\n[${request.stage}] needs your input:\n${request.prompt}\n`);
-    reader.question("", (answer) => {
-        try {
-            request.stdinPipe.write(`${answer}\n`);
-        }
-        catch {
-            // The child process may exit before the response is written.
-        }
-        request.resolve();
-        processNext();
-    });
-}
-export function enqueue(request) {
-    queue.push(request);
-    if (!processing) {
-        processNext();
-    }
-}
-export function close() {
-    if (readlineInterface) {
-        readlineInterface.close();
-        readlineInterface = null;
-    }
-    processing = false;
-    for (const request of queue.splice(0)) {
-        request.resolve();
-    }
-}