@xenonbyte/da-vinci-workflow 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## v0.2.8 - 2026-04-05
+
+### Added
+- optional workflow decision tracing via `.da-vinci/logs/workflow-decisions/YYYY-MM-DD.ndjson`, gated by `DA_VINCI_TRACE_WORKFLOW_DECISIONS=1`
+- compact trace coverage for persisted-state trust, canonical task-group seed fallback, task-group focus override, stale planning-signal fallback, verification freshness downgrade, and worktree-isolation downgrade
+- targeted regression coverage in `scripts/test-workflow-decision-tracing.js` for eligible surfaces, silence rules, sink-write failures, and trace-schema validation behavior
+
+### Changed
+- `workflow-status` and `next-step` now emit bounded decision traces only on the explicitly allowed surfaces, while keeping route/state truth unchanged
+- workflow trace records now reject invalid family/key/outcome combinations with visible diagnostic feedback instead of silently disappearing
+- current release notes in `README.md` and `README.zh-CN.md` now point to the `0.2.8` workflow decision tracing release
+
+### Fixed
+- missing review or verification evidence no longer produces fake `evidenceRefs` in workflow decision traces
+- persisted-state fallback traces no longer imply a fingerprint comparison happened for non-fingerprint fallback paths
+- workflow tracing diagnostics remain non-blocking even when trace persistence fails or candidate trace records are invalid
+
+## v0.2.7 - 2026-04-05
+
+### Added
+- `bounded-worker-isolation-contract` OpenSpec change with six contract slices covering advisory bounded-parallel baseline, isolated workspace rules, worker handoff payloads, sequencing, evidence writeback, and downgrade safety
+- `lib/isolated-worker-handoff.js` plus phase 1-4 regression tests for worker handoff payload constraints and contract closeout checks
+
+### Changed
+- `task-execution`, `task-review`, and `workflow-state` now keep isolated-worker evidence aligned with the new contract, including explicit partial-progress handling, review-order enforcement, out-of-scope-write blocking, and bounded-parallel downgrade visibility
+- `quality:ci:contracts` now includes bounded worker isolation contract regressions instead of relying only on docs/asset consistency lanes
+- supervisor-review reviewer execution now invokes `codex exec` with an explicit prompt separator and closed stdin, matching the real bridge behavior used by the integration smoke
+
+### Fixed
+- reviewer bridge diagnostics now keep `stdout` / `stderr` context when Codex exits without writing the expected structured JSON output
+- supervisor-review CLI and integration smoke fixtures now attach valid exported PNG screenshots so real reviewer runs can execute end to end
+- release docs now reflect the current published version and release highlights
+
 ## v0.2.6 - 2026-04-04
 
 ### Added

package/README.md

@@ -34,15 +34,15 @@ Use `da-vinci maintainer-readiness` as the canonical maintainer diagnosis surfac
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.2.6`
+- `@xenonbyte/da-vinci-workflow@0.2.8`
 
-Release highlights for `0.2.6`:
+Release highlights for `0.2.8`:
 
-- quality-gate alignment landed across `lint-spec` + `scope-check` + `lint-tasks`, with shared gate-envelope utilities and explicit clarify/analyze/task-checkpoint routing
-- `scope-check` analyze gate now catches empty `pencil-bindings.md` page-traceability drift and hardens orphan-task detection (with planning-anchor aware advisory fallback)
-- `lint-tasks` now derives upstream clarify/analyze context from current artifacts when persisted signals are stale, including clarify bounded-context carry-forward
-- planning-signal freshness for `lint-tasks` now includes `proposal.md` and page-map dependencies to avoid stale task-checkpoint trust
-- workflow promotion and integrity audit now keep clarify bounded context visible as notes while preserving non-blocking bounded semantics
+- optional workflow decision tracing is now available for `workflow-status` and `next-step` through `DA_VINCI_TRACE_WORKFLOW_DECISIONS=1`, with records written to `.da-vinci/logs/workflow-decisions/YYYY-MM-DD.ndjson`
+- the initial trace-family allowlist now covers persisted-state trust, task-group seed fallback, task-group focus override, stale planning-signal fallback, verification freshness downgrade, and worktree-isolation downgrade
+- workflow decision traces remain bounded and diagnostic-only: they do not change routing truth, do not run on non-eligible commands, and do not block normal command execution when trace persistence fails
+- trace records now reject invalid schema combinations with visible diagnostics instead of silently disappearing
+- trace payloads no longer claim missing evidence exists, and persisted fallback traces no longer imply a fingerprint comparison happened when it did not
 
 ## Discipline And Orchestration Upgrade
 

package/README.zh-CN.md

@@ -37,15 +37,15 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.2.6`
+- `@xenonbyte/da-vinci-workflow@0.2.8`
 
-`0.2.6` 版本重点：
+`0.2.8` 版本重点：
 
-- 完成 `lint-spec`、`scope-check`、`lint-tasks` 质量门对齐，并引入共享 gate-envelope 工具，明确 clarify/analyze/task-checkpoint 路由
-- `scope-check` 的 analyze gate 现在会对空 `pencil-bindings.md` 报告页面可追踪性漂移，并强化 orphan task 检测（支持 planning-anchor 降级为 advisory）
-- `lint-tasks` 在 persisted 信号过期时会从当前工件重新派生 clarify/analyze 上游上下文，并保留 clarify bounded-context
-- `lint-tasks` 的 freshness 依赖新增 `proposal.md` 与 page-map 链路，避免 task-checkpoint 误信陈旧上游信号
-- workflow promotion 与 integrity audit 现在都会稳定展示 clarify bounded context 备注，同时保持 bounded 默认非阻断语义
+- 现在可以通过 `DA_VINCI_TRACE_WORKFLOW_DECISIONS=1` 为 `workflow-status` 与 `next-step` 开启可选的 workflow decision tracing，记录会写入 `.da-vinci/logs/workflow-decisions/YYYY-MM-DD.ndjson`
+- 首批 trace-family allowlist 已覆盖 persisted-state trust、task-group seed fallback、task-group focus override、stale planning-signal fallback、verification freshness downgrade 与 worktree-isolation downgrade
+- workflow decision trace 仍然是 bounded 且 diagnostic-only：不会改变 routing truth，不会在非 eligible command 上发射，也不会因为 trace 持久化失败而阻断正常命令
+- trace record 现在会对非法 schema 组合给出可见诊断，不再静默丢失
+- trace payload 不再为缺失证据伪造 `evidenceRefs`，persisted fallback trace 也不再错误暗示某些未发生的 fingerprint comparison
 
 ## Discipline And Orchestration 升级
 

package/docs/dv-command-reference.md

@@ -97,8 +97,10 @@ These commands do not replace route selection, but they support design execution
   - generates reviewable TODO scaffold templates with framework-aware shape (`next`/`react`/`vue`/`svelte`/`html`)
   - keeps known implementation landing extension/route shape when a concrete landing already exists
   - unknown/ambiguous framework detection falls back to HTML with explicit warning; traversal/output-root safety remains enforced
-- `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--json]`
+- `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv> --confirm-test-evidence-executed] [--pending-test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--out-of-scope-writes <csv>] [--partial] [--json]`
   - persists normalized implementer-status envelopes into execution signals
+  - `--pending-test-evidence` and `--partial` keep the envelope explicitly non-final; `DONE` is invalid when either is present
+  - `--out-of-scope-writes` keeps write-scope drift visible to workflow safety handling
   - use this to keep resume routing machine-readable when implementation is blocked or concerns remain
 - `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> --status <PASS|WARN|BLOCK> --summary <text> [--issues <csv>] [--reviewer <name>] [--write-verification] [--json]`
   - persists ordered two-stage task review evidence (`spec` before `quality`)

package/docs/zh-CN/dv-command-reference.md

@@ -97,8 +97,10 @@ Da Vinci 期望它们遵循工作流状态。
   - 生成 framework-aware 的 TODO 可审查骨架（`next`/`react`/`vue`/`svelte`/`html`）
   - 若已存在明确实现落点，会优先保留该落点的扩展名与路由形状
   - 框架未知或冲突时显式告警并回退 HTML；同时继续严格执行 traversal/output-root 安全约束
-- `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--json]`
+- `da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv> --confirm-test-evidence-executed] [--pending-test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--out-of-scope-writes <csv>] [--partial] [--json]`
   - 持久化结构化 implementer 执行结果包，作为 task 级执行证据
+  - `--pending-test-evidence` 与 `--partial` 会将结果明确标记为非终态；此时不得使用 `DONE`
+  - `--out-of-scope-writes` 会把写范围漂移显式暴露给 workflow safety 处理
 - `da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> --status <PASS|WARN|BLOCK> --summary <text> [--issues <csv>] [--reviewer <name>] [--write-verification] [--json]`
   - 持久化有序两阶段 task review 证据（`spec` 在前，`quality` 在后）
 - `da-vinci worktree-preflight --project <path> [--change <id>] [--json]`

package/lib/cli.js

@@ -125,8 +125,10 @@ const OPTION_FLAGS_WITH_VALUES = new Set([
   "--task-group",
   "--changed-files",
   "--test-evidence",
+  "--pending-test-evidence",
   "--concerns",
   "--blockers",
+  "--out-of-scope-writes",
   "--issues",
   "--reviewer",
   "--source",
@@ -199,8 +201,21 @@ const HELP_OPTION_SPECS = [
     description: "comma-separated changed files for verify-implementation/verify-structure/verify-coverage/task-execution"
   },
   { flag: "--test-evidence <csv>", description: "comma-separated test evidence commands for task-execution" },
+  {
+    flag: "--pending-test-evidence <csv>",
+    description: "comma-separated planned-but-not-executed test commands for task-execution"
+  },
+  {
+    flag: "--confirm-test-evidence-executed",
+    description: "required when providing --test-evidence; confirms listed commands actually ran"
+  },
   { flag: "--concerns <csv>", description: "comma-separated concern text for task-execution" },
   { flag: "--blockers <csv>", description: "comma-separated blocker text for task-execution" },
+  {
+    flag: "--out-of-scope-writes <csv>",
+    description: "comma-separated out-of-scope write paths for task-execution safety visibility"
+  },
+  { flag: "--partial", description: "mark task-execution payload as non-final progress evidence" },
   { flag: "--issues <csv>", description: "comma-separated issue text for task-review" },
   { flag: "--reviewer <name>", description: "reviewer identifier for task-review" },
   { flag: "--write-verification", description: "append task-review evidence into verification.md" },
@@ -560,7 +575,7 @@ function printHelp() {
       "  da-vinci verify-implementation [--project <path>] [--change <id>] [--changed-files <csv>] [--strict] [--json]",
       "  da-vinci verify-structure [--project <path>] [--change <id>] [--changed-files <csv>] [--strict] [--json]",
       "  da-vinci verify-coverage [--project <path>] [--change <id>] [--changed-files <csv>] [--strict] [--json]",
-      "  da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--json]",
+      "  da-vinci task-execution --project <path> --change <id> --task-group <id> --status <DONE|DONE_WITH_CONCERNS|NEEDS_CONTEXT|BLOCKED> --summary <text> [--changed-files <csv>] [--test-evidence <csv> --confirm-test-evidence-executed] [--pending-test-evidence <csv>] [--concerns <csv>] [--blockers <csv>] [--out-of-scope-writes <csv>] [--partial] [--json]",
       "  da-vinci task-review --project <path> --change <id> --task-group <id> --stage <spec|quality> --status <PASS|WARN|BLOCK> --summary <text> [--issues <csv>] [--reviewer <name>] [--write-verification] [--json]",
       "  da-vinci worktree-preflight --project <path> [--change <id>] [--json]",
       "  da-vinci diff-spec [--project <path>] [--change <id>] [--from <sidecars-dir>] [--json]",
@@ -1082,7 +1097,11 @@ async function runCli(argv) {
   if (command === "workflow-status") {
     const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
     const changeId = getOption(argv, "--change");
-    const result = deriveWorkflowStatus(projectPath, { changeId });
+    const result = deriveWorkflowStatus(projectPath, {
+      changeId,
+      traceSurface: "workflow-status",
+      env: process.env
+    });
 
     if (argv.includes("--json")) {
       console.log(JSON.stringify(result, null, 2));
@@ -1096,7 +1115,11 @@ async function runCli(argv) {
   if (command === "next-step") {
     const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
     const changeId = getOption(argv, "--change");
-    const result = deriveWorkflowStatus(projectPath, { changeId });
+    const result = deriveWorkflowStatus(projectPath, {
+      changeId,
+      traceSurface: "next-step",
+      env: process.env
+    });
 
     if (argv.includes("--json")) {
       console.log(
@@ -1109,7 +1132,8 @@ async function runCli(argv) {
             discipline: result.discipline || null,
             executionProfile: result.executionProfile || null,
             worktreePreflight: result.worktreePreflight || null,
-            verificationFreshness: result.verificationFreshness || null
+            verificationFreshness: result.verificationFreshness || null,
+            traceDiagnostics: result.traceDiagnostics || null
           },
           null,
           2
@@ -1189,8 +1213,12 @@ async function runCli(argv) {
       summary: getOption(argv, "--summary"),
       changedFiles: getCommaSeparatedOptionValues(argv, "--changed-files"),
       testEvidence: getCommaSeparatedOptionValues(argv, "--test-evidence"),
+      pendingTestEvidence: getCommaSeparatedOptionValues(argv, "--pending-test-evidence"),
+      confirmTestEvidenceExecuted: argv.includes("--confirm-test-evidence-executed"),
       concerns: getCommaSeparatedOptionValues(argv, "--concerns"),
-      blockers: getCommaSeparatedOptionValues(argv, "--blockers")
+      blockers: getCommaSeparatedOptionValues(argv, "--blockers"),
+      outOfScopeWrites: getCommaSeparatedOptionValues(argv, "--out-of-scope-writes"),
+      partial: argv.includes("--partial")
     });
     const useJson = argv.includes("--json");
     const output = useJson ? JSON.stringify(result, null, 2) : formatTaskExecutionReport(result);

package/lib/isolated-worker-handoff.js

@@ -0,0 +1,181 @@
+const VALID_IMPLEMENTER_RESULT_STATUSES = new Set([
+  "DONE",
+  "DONE_WITH_CONCERNS",
+  "NEEDS_CONTEXT",
+  "BLOCKED"
+]);
+
+const IMPLEMENTER_INPUT_REQUIRED_FIELDS = Object.freeze([
+  "changeId",
+  "taskGroupId",
+  "title",
+  "executionIntent",
+  "targetFiles",
+  "fileReferences",
+  "reviewIntent",
+  "verificationActions",
+  "verificationCommands",
+  "canonicalProjectRoot",
+  "isolatedWorkspaceRoot"
+]);
+
+const IMPLEMENTER_RESULT_REQUIRED_FIELDS = Object.freeze([
+  "changeId",
+  "taskGroupId",
+  "status",
+  "summary",
+  "changedFiles",
+  "testEvidence",
+  "concerns",
+  "blockers",
+  "outOfScopeWrites",
+  "recordedAt"
+]);
+
+const IMPLEMENTER_PROGRESS_REQUIRED_FIELDS = Object.freeze([
+  ...IMPLEMENTER_RESULT_REQUIRED_FIELDS,
+  "partial"
+]);
+
+function normalizeString(value) {
+  return String(value || "").trim();
+}
+
+function normalizeList(value) {
+  const source = Array.isArray(value)
+    ? value
+    : String(value || "")
+        .split(/[,\n;]/)
+        .map((item) => item.trim());
+  return Array.from(
+    new Set(
+      source
+        .map((item) => String(item || "").trim())
+        .filter(Boolean)
+    )
+  );
+}
+
+function assertRequiredFields(payload, requiredFields, label) {
+  const missing = requiredFields.filter((field) => !Object.prototype.hasOwnProperty.call(payload || {}, field));
+  if (missing.length > 0) {
+    throw new Error(`${label} is missing required fields: ${missing.join(", ")}`);
+  }
+}
+
+function assertNoUnknownFields(payload, allowedFields, label) {
+  const allowed = new Set(allowedFields);
+  const unknown = Object.keys(payload || {}).filter((field) => !allowed.has(field));
+  if (unknown.length > 0) {
+    throw new Error(`${label} contains unsupported fields: ${unknown.join(", ")}`);
+  }
+}
+
+function normalizeStatus(status) {
+  const normalized = normalizeString(status).toUpperCase();
+  if (!VALID_IMPLEMENTER_RESULT_STATUSES.has(normalized)) {
+    throw new Error(
+      `isolated implementer result status must be one of ${Array.from(VALID_IMPLEMENTER_RESULT_STATUSES).join(", ")}.`
+    );
+  }
+  return normalized;
+}
+
+function normalizeRecordedAt(value, label) {
+  const normalized = normalizeString(value);
+  if (!normalized) {
+    throw new Error(`${label} requires recordedAt.`);
+  }
+  const parsed = Date.parse(normalized);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`${label} recordedAt must be a valid ISO-8601 timestamp.`);
+  }
+  return new Date(parsed).toISOString();
+}
+
+function normalizeIsolatedImplementerInputPayload(payload = {}) {
+  assertRequiredFields(payload, IMPLEMENTER_INPUT_REQUIRED_FIELDS, "isolated implementer input payload");
+  assertNoUnknownFields(payload, IMPLEMENTER_INPUT_REQUIRED_FIELDS, "isolated implementer input payload");
+
+  const changeId = normalizeString(payload.changeId);
+  const taskGroupId = normalizeString(payload.taskGroupId);
+  const title = normalizeString(payload.title);
+  const canonicalProjectRoot = normalizeString(payload.canonicalProjectRoot);
+  const isolatedWorkspaceRoot = normalizeString(payload.isolatedWorkspaceRoot);
+  if (!changeId || !taskGroupId || !title || !canonicalProjectRoot || !isolatedWorkspaceRoot) {
+    throw new Error(
+      "isolated implementer input payload requires non-empty changeId, taskGroupId, title, canonicalProjectRoot, and isolatedWorkspaceRoot."
+    );
+  }
+
+  return {
+    changeId,
+    taskGroupId,
+    title,
+    executionIntent: normalizeList(payload.executionIntent),
+    targetFiles: normalizeList(payload.targetFiles),
+    fileReferences: normalizeList(payload.fileReferences),
+    reviewIntent: payload.reviewIntent === true,
+    verificationActions: normalizeList(payload.verificationActions),
+    verificationCommands: normalizeList(payload.verificationCommands),
+    canonicalProjectRoot,
+    isolatedWorkspaceRoot
+  };
+}
+
+function normalizeIsolatedImplementerResultPayload(payload = {}) {
+  assertRequiredFields(payload, IMPLEMENTER_RESULT_REQUIRED_FIELDS, "isolated implementer result payload");
+  assertNoUnknownFields(payload, IMPLEMENTER_RESULT_REQUIRED_FIELDS, "isolated implementer result payload");
+
+  const changeId = normalizeString(payload.changeId);
+  const taskGroupId = normalizeString(payload.taskGroupId);
+  const summary = normalizeString(payload.summary);
+  if (!changeId || !taskGroupId || !summary) {
+    throw new Error("isolated implementer result payload requires non-empty changeId, taskGroupId, and summary.");
+  }
+
+  return {
+    changeId,
+    taskGroupId,
+    status: normalizeStatus(payload.status),
+    summary,
+    changedFiles: normalizeList(payload.changedFiles),
+    testEvidence: normalizeList(payload.testEvidence),
+    concerns: normalizeList(payload.concerns),
+    blockers: normalizeList(payload.blockers),
+    outOfScopeWrites: normalizeList(payload.outOfScopeWrites),
+    recordedAt: normalizeRecordedAt(payload.recordedAt, "isolated implementer result payload")
+  };
+}
+
+function normalizeIsolatedImplementerProgressPayload(payload = {}) {
+  assertRequiredFields(payload, IMPLEMENTER_PROGRESS_REQUIRED_FIELDS, "isolated implementer progress payload");
+  assertNoUnknownFields(payload, IMPLEMENTER_PROGRESS_REQUIRED_FIELDS, "isolated implementer progress payload");
+  if (payload.partial !== true) {
+    throw new Error("isolated implementer progress payload requires partial=true.");
+  }
+
+  const {
+    partial: _partial,
+    ...resultShape
+  } = payload;
+  const normalizedResult = normalizeIsolatedImplementerResultPayload(resultShape);
+  if (normalizedResult.status === "DONE") {
+    throw new Error("isolated implementer progress payload cannot use status DONE because partial snapshots are non-final.");
+  }
+
+  return {
+    ...normalizedResult,
+    partial: true
+  };
+}
+
+module.exports = {
+  VALID_IMPLEMENTER_RESULT_STATUSES,
+  IMPLEMENTER_INPUT_REQUIRED_FIELDS,
+  IMPLEMENTER_RESULT_REQUIRED_FIELDS,
+  IMPLEMENTER_PROGRESS_REQUIRED_FIELDS,
+  normalizeIsolatedImplementerInputPayload,
+  normalizeIsolatedImplementerResultPayload,
+  normalizeIsolatedImplementerProgressPayload
+};

package/lib/supervisor-review.js

@@ -1,7 +1,7 @@
 const fs = require("fs");
 const path = require("path");
 const os = require("os");
-const { execFile } = require("child_process");
+const { spawn } = require("child_process");
 const {
   escapeRegExp,
   isPlainObject,
@@ -120,6 +120,19 @@ function truncateForError(value, maxLength = 240) {
   return `${text.slice(0, maxLength)}...`;
 }
 
+function buildReviewerExecutionDiagnostics(stdout, stderr) {
+  const diagnostics = [];
+  const normalizedStderr = truncateForError(stderr, 600);
+  const normalizedStdout = truncateForError(stdout, 600);
+  if (normalizedStderr) {
+    diagnostics.push(`stderr: ${normalizedStderr}`);
+  }
+  if (normalizedStdout) {
+    diagnostics.push(`stdout: ${normalizedStdout}`);
+  }
+  return diagnostics;
+}
+
 function parseReviewerPayload(rawText) {
   const payload = parseJsonText(String(rawText || "").trim(), "reviewer JSON payload");
   if (!isPlainObject(payload)) {
@@ -146,8 +159,97 @@ function parseReviewerPayload(rawText) {
 
 function execFileAsync(command, args, options = {}) {
   return new Promise((resolve, reject) => {
-    execFile(command, args, options, (error, stdout, stderr) => {
-      if (error) {
+    const encoding = options.encoding || "utf8";
+    const maxBuffer = Number.isFinite(options.maxBuffer) && options.maxBuffer > 0 ? options.maxBuffer : Infinity;
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+
+    let finished = false;
+    let timedOut = false;
+    let overflowed = false;
+    let stdoutSize = 0;
+    let stderrSize = 0;
+    const stdoutChunks = [];
+    const stderrChunks = [];
+
+    function finalizeError(error) {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      error.stdout = Buffer.concat(stdoutChunks).toString(encoding);
+      error.stderr = Buffer.concat(stderrChunks).toString(encoding);
+      reject(error);
+    }
+
+    function pushChunk(target, chunk, currentSize) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk || ""), encoding);
+      const nextSize = currentSize + buffer.length;
+      target.push(buffer);
+      return nextSize;
+    }
+
+    const timeoutMs = Number.isFinite(options.timeout) && options.timeout > 0 ? options.timeout : 0;
+    const timeoutId =
+      timeoutMs > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            child.kill();
+          }, timeoutMs)
+        : null;
+
+    child.on("error", (error) => {
+      finalizeError(error);
+    });
+
+    child.stdout.on("data", (chunk) => {
+      stdoutSize = pushChunk(stdoutChunks, chunk, stdoutSize);
+      if (stdoutSize > maxBuffer && !overflowed) {
+        overflowed = true;
+        const error = new Error("stdout maxBuffer length exceeded");
+        error.code = "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+        child.kill();
+        finalizeError(error);
+      }
+    });
+
+    child.stderr.on("data", (chunk) => {
+      stderrSize = pushChunk(stderrChunks, chunk, stderrSize);
+      if (stderrSize > maxBuffer && !overflowed) {
+        overflowed = true;
+        const error = new Error("stderr maxBuffer length exceeded");
+        error.code = "ERR_CHILD_PROCESS_STDIO_MAXBUFFER";
+        child.kill();
+        finalizeError(error);
+      }
+    });
+
+    child.on("close", (code, signal) => {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      const stdout = Buffer.concat(stdoutChunks).toString(encoding);
+      const stderr = Buffer.concat(stderrChunks).toString(encoding);
+      if (timedOut || code !== 0) {
+        const error = new Error(
+          timedOut
+            ? `Process timed out after ${timeoutMs}ms`
+            : `Process exited with code ${code !== null ? code : "unknown"}`
+        );
+        error.code = code;
+        error.signal = signal;
+        error.killed = timedOut;
         error.stdout = stdout;
         error.stderr = stderr;
         reject(error);
@@ -241,11 +343,12 @@ async function runReviewerWithCodexOnce(options = {}) {
     for (const screenshotPath of screenshotPaths || []) {
       args.push("-i", screenshotPath);
     }
-    args.push(prompt);
+    args.push("--", prompt);
 
     const timeoutValue = normalizePositiveInt(timeoutMs, 0, 0, 30 * 60 * 1000);
+    let execResult = null;
     try {
-      await execFileAsync(codexBin, args, {
+      execResult = await execFileAsync(codexBin, args, {
         encoding: "utf8",
         maxBuffer: resolvedMaxBuffer,
         timeout: timeoutValue > 0 ? timeoutValue : undefined
@@ -272,7 +375,15 @@ async function runReviewerWithCodexOnce(options = {}) {
     }
 
     if (!pathExists(outputPath)) {
-      throw new Error(`Reviewer \`${reviewer}\` completed but produced no output JSON.`);
+      const diagnostics = buildReviewerExecutionDiagnostics(
+        execResult && execResult.stdout,
+        execResult && execResult.stderr
+      );
+      throw new Error(
+        `Reviewer \`${reviewer}\` completed but produced no output JSON.${
+          diagnostics.length > 0 ? ` ${diagnostics.join(" | ")}` : ""
+        }`
+      );
     }
 
     return parseReviewerPayload(fs.readFileSync(outputPath, "utf8"));