@fro.bot/systematic 3.17.0 → 3.18.1

package/dist/cli.js

@@ -33,7 +33,7 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   discoverSkills
-} from "./index-y33enbkc.js";
+} from "./index-v8y6h7y4.js";
 var __defProp = Object.defineProperty;
 var __returnValue = (v) => v;
 function __exportSetter(name, newValue) {
@@ -50,7 +50,7 @@ var __export = (target, all) => {
 };
 
 // src/cli.ts
-import fs6 from "fs";
+import fs7 from "fs";
 import os2 from "os";
 import path5 from "path";
 
@@ -831,7 +831,7 @@ function buildCapabilitySnapshot(options) {
   options.outputSink?.(serialized);
   return snapshot;
 }
-// node_modules/.bun/zod@4.5.4/node_modules/zod/v4/classic/iso.js
+// node_modules/.bun/zod@4.6.0/node_modules/zod/v4/classic/iso.js
 var exports_iso = {};
 __export(exports_iso, {
   ZodISODate: () => ZodISODate,
@@ -2191,14 +2191,33 @@ var REVIEW_ARTIFACT_CUSTOM_MESSAGES = [
   "risk-critical dispatches require a non-empty selection surface",
   "satisfied risk coverage requires a citing input finding ID",
   "unsatisfied risk coverage must not cite an input finding ID",
-  "passed validation must not include a reason; non-passed validation requires a reason"
+  "passed validation must not include a reason; non-passed validation requires a reason",
+  "validation_unavailable dispatches must record zero input findings",
+  "a completed run must not contain validation_unavailable evidence",
+  "a validation_unavailable persona must not have an input finding",
+  "every synthesized input finding ID must resolve to an admitted ledger row",
+  "every provenance submitter must be represented by a cited admitted ledger row",
+  "satisfied risk coverage must cite an admitted ledger row",
+  "duplicate admitted input finding IDs are not allowed",
+  "every cited admitted reviewer must appear in provenance.submitters",
+  "provenance.submitters must not contain duplicate reviewers",
+  "provenance.agreement_credit must not contain duplicate reviewers",
+  "provenance.agreement_credit must not overlap provenance.submitters",
+  "provenance.agreement_credit requires an eligible returned persona with admitted evidence",
+  "satisfied risk coverage must cite a validated finding on the lost persona selection surface",
+  "satisfied risk coverage must cite an admitted ledger row owned by another persona"
 ];
 var boundedText = (maxLength) => string().min(1).max(maxLength).regex(/\S/);
+var LineNumberSchema = number().int().positive();
 var DispatchOutcomeSchema = _enum([
   "findings",
   "empty",
   "malformed",
-  "never_returned"
+  "never_returned",
+  "validation_unavailable"
+]);
+var RejectedSummaryDispatchOutcomeSchema = DispatchOutcomeSchema.exclude([
+  "validation_unavailable"
 ]);
 var DispositionSchema = _enum([
   "surviving",
@@ -2255,7 +2274,7 @@ var AdmittedInputFindingSchema = object({
 var RejectedInputFindingSchema = object({
   record_type: literal("rejected_summary"),
   reviewer: ReviewerSchema,
-  dispatch_outcome: DispatchOutcomeSchema,
+  dispatch_outcome: RejectedSummaryDispatchOutcomeSchema,
   rejected_finding_count: number().int().positive().max(MAX_FINDINGS),
   rejected_severities: array(SeveritySchema).max(MAX_FINDINGS),
   disposition: DispositionSchema.extract(["rejected"]),
@@ -2282,7 +2301,7 @@ var SynthesizedFindingFieldsSchema = object({
   title: FindingTitleSchema,
   severity: FindingSeveritySchema,
   file: RepoRelativePathSchema,
-  line: number().int().positive(),
+  line: LineNumberSchema,
   why_it_matters: boundedText(2048),
   autofix_class: AutofixClassSchema,
   owner: OwnerSchema,
@@ -2412,10 +2431,367 @@ var ReviewArtifactSchema = object({
   advisory_outputs: array(ReasonSchema).max(MAX_FINDINGS),
   coverage: CoverageSchema,
   validation: ValidationSchema.optional()
+}).strict().superRefine((artifact, ctx) => {
+  const unavailablePersonas = new Set(artifact.dispatches.filter((dispatch) => dispatch.dispatch_outcome === "validation_unavailable").map((dispatch) => dispatch.persona));
+  if (unavailablePersonas.size > 0) {
+    if (artifact.run_status === "completed") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["run_status"],
+        message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[7]
+      });
+    }
+    artifact.dispatches.forEach((dispatch, index) => {
+      if (dispatch.dispatch_outcome === "validation_unavailable" && dispatch.input_finding_count !== 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["dispatches", index, "input_finding_count"],
+          message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[6]
+        });
+      }
+    });
+    artifact.input_findings.forEach((finding, index) => {
+      if (unavailablePersonas.has(finding.reviewer)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["input_findings", index, "reviewer"],
+          message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[8]
+        });
+      }
+    });
+  }
+  const admittedById = new Map;
+  artifact.input_findings.forEach((finding, index) => {
+    if (finding.record_type !== "admitted") {
+      return;
+    }
+    if (admittedById.has(finding.input_id)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["input_findings", index, "input_id"],
+        message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[12]
+      });
+      return;
+    }
+    admittedById.set(finding.input_id, finding.reviewer);
+  });
+  const admittedReviewers = new Set(admittedById.values());
+  const eligibleAgreementPersonas = new Set(artifact.dispatches.filter((dispatch) => dispatch.dispatch_outcome === "findings" && admittedReviewers.has(dispatch.persona)).map((dispatch) => dispatch.persona));
+  artifact.findings.forEach((finding, findingIndex) => {
+    const citedAdmittedReviewers = new Set;
+    finding.input_finding_ids.forEach((inputId, idIndex) => {
+      const owner = admittedById.get(inputId);
+      if (owner === undefined) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["findings", findingIndex, "input_finding_ids", idIndex],
+          message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[9]
+        });
+        return;
+      }
+      citedAdmittedReviewers.add(owner);
+    });
+    const seenSubmitters = new Set;
+    finding.provenance.submitters.forEach((submitter, submitterIndex) => {
+      if (seenSubmitters.has(submitter)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [
+            "findings",
+            findingIndex,
+            "provenance",
+            "submitters",
+            submitterIndex
+          ],
+          message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[14]
+        });
+      }
+      seenSubmitters.add(submitter);
+      if (!citedAdmittedReviewers.has(submitter)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [
+            "findings",
+            findingIndex,
+            "provenance",
+            "submitters",
+            submitterIndex
+          ],
+          message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[10]
+        });
+      }
+    });
+    for (const reviewer of citedAdmittedReviewers) {
+      if (!seenSubmitters.has(reviewer)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["findings", findingIndex, "provenance", "submitters"],
+          message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[13]
+        });
+      }
+    }
+    const seenAgreementCredit = new Set;
+    finding.provenance.agreement_credit.forEach((credit, creditIndex) => {
+      if (seenAgreementCredit.has(credit)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [
+            "findings",
+            findingIndex,
+            "provenance",
+            "agreement_credit",
+            creditIndex
+          ],
+          message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[15]
+        });
+      }
+      seenAgreementCredit.add(credit);
+      if (seenSubmitters.has(credit)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [
+            "findings",
+            findingIndex,
+            "provenance",
+            "agreement_credit",
+            creditIndex
+          ],
+          message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[16]
+        });
+      }
+      if (!eligibleAgreementPersonas.has(credit)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [
+            "findings",
+            findingIndex,
+            "provenance",
+            "agreement_credit",
+            creditIndex
+          ],
+          message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[17]
+        });
+      }
+    });
+  });
+  artifact.risk_coverage?.forEach((coverage, coverageIndex) => {
+    if (!coverage.satisfied) {
+      return;
+    }
+    const citedId = coverage.input_finding_id;
+    if (citedId === undefined) {
+      return;
+    }
+    const owner = admittedById.get(citedId);
+    if (owner === undefined || unavailablePersonas.has(owner)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["risk_coverage", coverageIndex, "input_finding_id"],
+        message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[11]
+      });
+      return;
+    }
+    if (owner === coverage.persona) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["risk_coverage", coverageIndex, "input_finding_id"],
+        message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[19]
+      });
+      return;
+    }
+    const lostDispatch = artifact.dispatches.find((dispatch) => dispatch.persona === coverage.persona);
+    const surface = lostDispatch?.selection_surface ?? [];
+    const covered = artifact.findings.some((finding) => finding.input_finding_ids.includes(citedId) && finding.validated !== false && surface.includes(finding.file));
+    if (!covered) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["risk_coverage", coverageIndex, "input_finding_id"],
+        message: REVIEW_ARTIFACT_CUSTOM_MESSAGES[18]
+      });
+    }
+  });
+});
+var MAX_RAW_RISK_LENGTH = 1024;
+var RAW_FINDINGS_LIST_DESCRIPTION = "List of code review findings. Empty array if no issues found.";
+var RawReviewerSchema = ReviewerSchema.describe("Persona name that produced this output (e.g., 'correctness', 'security')");
+var RawHarnessSchema = HarnessSchema.describe("Harness that produced the artifact; populated by the parent orchestrator");
+var RawDispatchOutcomeSchema = DispatchOutcomeSchema.describe("What a persona returned: findings, empty, malformed, or never returned");
+var RawDispositionSchema = DispositionSchema.describe("What happened to an input finding: surviving, merged, suppressed, filtered, or rejected");
+var RawResidualRisksSchema = array(string().max(MAX_RAW_RISK_LENGTH)).max(MAX_PERSONAS).describe("Risks the reviewer noticed but could not confirm as findings");
+var RawTestingGapsSchema = array(string().max(MAX_RAW_RISK_LENGTH)).max(MAX_PERSONAS).describe("Missing test coverage the reviewer identified");
+var RawEvidenceStringSchema = BoundedEvidenceStringSchema.describe("Bounded code-grounded evidence; absolute POSIX, drive-letter, and UNC paths are rejected");
+var RawOverflowExcerptSchema = BoundedEvidenceStringSchema.describe("Bounded excerpt retained when evidence must be shortened");
+var RawOverflowEvidenceSchema = object({
+  overflow: literal(true).describe("Explicit marker that the complete evidence did not fit in one bounded entry"),
+  excerpt: RawOverflowExcerptSchema
+}).strict();
+var RawEvidenceSchema = array(union([RawEvidenceStringSchema, RawOverflowEvidenceSchema])).min(1).max(5).describe("Code-grounded evidence. At least 1 and at most 5 bounded entries; split evidence across entries or use an explicit overflow marker rather than silently truncating it.");
+var RawFindingFieldsSchema = object({
+  title: FindingTitleSchema.describe("Short, specific issue title. 10 words or fewer."),
+  severity: FindingSeveritySchema.describe("Issue severity level"),
+  file: RepoRelativePathSchema.describe("Relative file path from repository root; absolute POSIX, drive-letter, and UNC paths are rejected"),
+  line: LineNumberSchema.describe("Primary line number of the issue"),
+  why_it_matters: boundedText(2048).describe("Non-empty impact and failure mode -- not 'what is wrong' but 'what breaks'"),
+  autofix_class: AutofixClassSchema.describe("Reviewer's conservative recommendation for how this issue should be handled after synthesis"),
+  owner: OwnerSchema.describe("Who should own the next action for this finding after synthesis"),
+  requires_verification: boolean().describe("Whether any fix for this finding must be re-verified with targeted tests or a follow-up review pass"),
+  suggested_fix: string().max(2048).nullable().optional().describe("Concrete minimal fix. Omit or null if no good fix is obvious -- a bad suggestion is worse than none."),
+  confidence: number().min(0).max(1).describe("Reviewer confidence in this finding, calibrated per persona"),
+  evidence: RawEvidenceSchema,
+  pre_existing: boolean().describe("True if this issue exists in unchanged code unrelated to the current diff")
+}).strict();
+var SubAgentFindingSchema = RawFindingFieldsSchema;
+var ParentFindingSchema = RawFindingFieldsSchema.extend({
+  disposition: RawDispositionSchema
+}).strict();
+var SubAgentReturnSchema = object({
+  reviewer: RawReviewerSchema,
+  findings: array(SubAgentFindingSchema).max(MAX_FINDINGS).describe(RAW_FINDINGS_LIST_DESCRIPTION),
+  residual_risks: RawResidualRisksSchema,
+  testing_gaps: RawTestingGapsSchema
+}).strict();
+var ParentRecordSchema = object({
+  reviewer: RawReviewerSchema,
+  harness: RawHarnessSchema,
+  dispatch_outcome: RawDispatchOutcomeSchema,
+  findings: array(ParentFindingSchema).max(MAX_FINDINGS).describe(RAW_FINDINGS_LIST_DESCRIPTION),
+  residual_risks: RawResidualRisksSchema,
+  testing_gaps: RawTestingGapsSchema
 }).strict();
 
-// src/lib/setup.ts
+// src/lib/review-return-validator.ts
 import fs5 from "fs";
+var VALIDATE_REVIEW_RETURN_USAGE = "Usage: systematic validate-review-return";
+var MAX_REVIEW_RETURN_BYTES = 1024 * 1024;
+var MAX_PROJECTED_ISSUE_LINES = 8;
+var REVIEW_RETURN_VALID_MESSAGE = "Review return is valid";
+var REVIEW_RETURN_EMPTY_MESSAGE = "Review return is empty";
+var REVIEW_RETURN_INVALID_UTF8_MESSAGE = "Review return is not valid UTF-8";
+var REVIEW_RETURN_MALFORMED_JSON_MESSAGE = "Review return is not valid JSON";
+var REVIEW_RETURN_OVERSIZED_MESSAGE = "Review return exceeds the 1 MiB input limit";
+var REVIEW_RETURN_READ_FAILED_MESSAGE = "Review return could not be read from stdin";
+var REVIEW_RETURN_TTY_MESSAGE = "validate-review-return reads one JSON document from stdin; interactive input is not supported";
+function validateReviewReturnValue(value) {
+  const result = SubAgentReturnSchema.safeParse(value);
+  if (result.success)
+    return { ok: true };
+  const total = result.error.issues.length;
+  const issues = result.error.issues.slice(0, MAX_PROJECTED_ISSUE_LINES).map((issue) => ({
+    path: formatReviewArtifactIssuePath(issue.path),
+    code: issue.code
+  }));
+  return { issues, ok: false, total };
+}
+function formatReviewReturnValidationFailure(total) {
+  return `Review return validation failed: ${total} issue(s)`;
+}
+var READ_CHUNK_BYTES = 64 * 1024;
+function defaultReadChunk(fd, buffer, offset, length, position) {
+  return fs5.readSync(fd, buffer, offset, length, position);
+}
+var TRANSIENT_READ_RETRY_MS = 1;
+function isTransientReadError(error) {
+  if (typeof error !== "object" || error === null)
+    return false;
+  const code = error.code;
+  return code === "EAGAIN" || code === "EWOULDBLOCK";
+}
+function sleepSync(milliseconds) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+function readChunkWithRetry(fd, buffer, toRead, readChunk) {
+  for (;; ) {
+    try {
+      return {
+        bytesRead: readChunk(fd, buffer, 0, toRead, null),
+        status: "ok"
+      };
+    } catch (error) {
+      if (!isTransientReadError(error))
+        return { status: "read-error" };
+      sleepSync(TRANSIENT_READ_RETRY_MS);
+    }
+  }
+}
+function readBoundedStdin(fd, readChunk) {
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const remaining = MAX_REVIEW_RETURN_BYTES + 1 - total;
+    if (remaining <= 0)
+      return { status: "oversized" };
+    const toRead = Math.min(READ_CHUNK_BYTES, remaining);
+    const buffer = Buffer.allocUnsafe(toRead);
+    const read = readChunkWithRetry(fd, buffer, toRead, readChunk);
+    if (read.status === "read-error")
+      return { status: "read-error" };
+    if (read.bytesRead <= 0)
+      break;
+    total += read.bytesRead;
+    chunks.push(buffer.subarray(0, read.bytesRead));
+    if (total > MAX_REVIEW_RETURN_BYTES)
+      return { status: "oversized" };
+  }
+  return { buffer: Buffer.concat(chunks, total), status: "ok" };
+}
+function isValidInvocation(argv) {
+  const commandIndex = argv[0] === "systematic" ? 1 : 0;
+  return argv[commandIndex] === "validate-review-return" && argv.length === commandIndex + 1;
+}
+function runReviewReturnValidator(options) {
+  const outputSink = options.outputSink ?? ((message) => console.log(message));
+  const errorSink = options.errorSink ?? ((message) => console.error(message));
+  const fd = options.fd ?? 0;
+  const isTTY = options.isTTY ?? (fd === 0 && process.stdin.isTTY === true);
+  if (!isValidInvocation(options.argv)) {
+    errorSink(VALIDATE_REVIEW_RETURN_USAGE);
+    return 2;
+  }
+  if (isTTY) {
+    errorSink(REVIEW_RETURN_TTY_MESSAGE);
+    return 2;
+  }
+  const read = readBoundedStdin(fd, options.readChunk ?? defaultReadChunk);
+  if (read.status === "read-error") {
+    errorSink(REVIEW_RETURN_READ_FAILED_MESSAGE);
+    return 2;
+  }
+  if (read.status === "oversized") {
+    errorSink(REVIEW_RETURN_OVERSIZED_MESSAGE);
+    return 1;
+  }
+  let text;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(read.buffer);
+  } catch {
+    errorSink(REVIEW_RETURN_INVALID_UTF8_MESSAGE);
+    return 1;
+  }
+  if (text.trim() === "") {
+    errorSink(REVIEW_RETURN_EMPTY_MESSAGE);
+    return 1;
+  }
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    errorSink(REVIEW_RETURN_MALFORMED_JSON_MESSAGE);
+    return 1;
+  }
+  const validation = validateReviewReturnValue(value);
+  if (validation.ok) {
+    outputSink(REVIEW_RETURN_VALID_MESSAGE);
+    return 0;
+  }
+  for (const issue of validation.issues) {
+    errorSink(`${issue.path} ${issue.code}`);
+  }
+  errorSink(formatReviewReturnValidationFailure(validation.total));
+  return 1;
+}
+
+// src/lib/setup.ts
+import fs6 from "fs";
 import path4 from "path";
 var SYSTEMATIC_PACKAGE_NAME = "@fro.bot/systematic";
 var PI_PACKAGE_IDENTIFIER = `npm:${SYSTEMATIC_PACKAGE_NAME}`;
@@ -2426,10 +2802,10 @@ function createSetupError(message) {
   return error;
 }
 var DEFAULT_OPS = {
-  writeFileSync: fs5.writeFileSync,
-  renameSync: fs5.renameSync,
-  unlinkSync: fs5.unlinkSync,
-  chmodSync: fs5.chmodSync
+  writeFileSync: fs6.writeFileSync,
+  renameSync: fs6.renameSync,
+  unlinkSync: fs6.unlinkSync,
+  chmodSync: fs6.chmodSync
 };
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -2451,7 +2827,7 @@ function isPiSystematicIdentifier(identifier) {
 }
 function lstatOrNull(targetPath) {
   try {
-    return fs5.lstatSync(targetPath);
+    return fs6.lstatSync(targetPath);
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
       return null;
@@ -2460,8 +2836,8 @@ function lstatOrNull(targetPath) {
   }
 }
 function assertRealpathUnderCwd(dir, cwd) {
-  const realDir = fs5.realpathSync(dir);
-  const realCwd = fs5.realpathSync(cwd);
+  const realDir = fs6.realpathSync(dir);
+  const realCwd = fs6.realpathSync(cwd);
   const relative = path4.relative(realCwd, realDir);
   if (relative.startsWith("..") || path4.isAbsolute(relative)) {
     throw createSetupError(`Refusing to write under ${dir}: resolved directory escapes the project root`);
@@ -2476,7 +2852,7 @@ function assertParentTrusted(parentDir, cwd) {
     assertRealpathUnderCwd(parentDir, cwd);
     return;
   }
-  fs5.mkdirSync(parentDir, { recursive: true });
+  fs6.mkdirSync(parentDir, { recursive: true });
   assertRealpathUnderCwd(parentDir, cwd);
 }
 var OPENCODE_TARGET_CANDIDATES = [
@@ -2498,7 +2874,7 @@ function resolveOpenCodeTargetPath(cwd) {
   return path4.join(cwd, "opencode.jsonc");
 }
 var IS_WINDOWS = process.platform === "win32";
-var OPEN_FLAGS = IS_WINDOWS ? fs5.constants.O_RDONLY : fs5.constants.O_RDONLY | fs5.constants.O_NOFOLLOW | fs5.constants.O_NONBLOCK;
+var OPEN_FLAGS = IS_WINDOWS ? fs6.constants.O_RDONLY : fs6.constants.O_RDONLY | fs6.constants.O_NOFOLLOW | fs6.constants.O_NONBLOCK;
 function assertWindowsPreOpenTrust(targetPath) {
   const preStat = lstatOrNull(targetPath);
   if (preStat && (preStat.isSymbolicLink() || !preStat.isFile())) {
@@ -2510,7 +2886,7 @@ function openTrustedExisting(targetPath) {
     assertWindowsPreOpenTrust(targetPath);
   let fd;
   try {
-    fd = fs5.openSync(targetPath, OPEN_FLAGS);
+    fd = fs6.openSync(targetPath, OPEN_FLAGS);
   } catch (error) {
     if (error instanceof Error && "code" in error) {
       if (error.code === "ENOENT")
@@ -2522,13 +2898,13 @@ function openTrustedExisting(targetPath) {
     throw error;
   }
   try {
-    const stat = fs5.fstatSync(fd);
+    const stat = fs6.fstatSync(fd);
     if (!stat.isFile()) {
       throw createSetupError(`Refusing to read ${targetPath}: not a regular file`);
     }
-    return { bytes: fs5.readFileSync(fd), mode: stat.mode & 511 };
+    return { bytes: fs6.readFileSync(fd), mode: stat.mode & 511 };
   } finally {
-    fs5.closeSync(fd);
+    fs6.closeSync(fd);
   }
 }
 function atomicWrite(targetPath, content, originalBytes, mode, ops) {
@@ -2560,7 +2936,7 @@ function makeTempPath(parentDir, basename) {
   return path4.join(parentDir, `.${basename}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
 }
 function cleanupTemp(tempPath, ops) {
-  if (!fs5.existsSync(tempPath))
+  if (!fs6.existsSync(tempPath))
     return;
   try {
     ops.unlinkSync(tempPath);
@@ -2714,9 +3090,9 @@ function setupHarness(harness, cwd, opsOverride) {
 function readPackageMetadata(packageRoot) {
   try {
     const packageJsonPath = path5.join(packageRoot, "package.json");
-    if (!fs6.existsSync(packageJsonPath))
+    if (!fs7.existsSync(packageJsonPath))
       return {};
-    const content = fs6.readFileSync(packageJsonPath, "utf8");
+    const content = fs7.readFileSync(packageJsonPath, "utf8");
     const parsed = JSON.parse(content);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
       return {};
@@ -2749,6 +3125,12 @@ Commands:
                                CI, issues, or fixtures. Not for the ce:review parent's own run artifact.
                                Exit statuses: 0 valid artifact, 1 validation failure,
                                2 operational failure, 3 legacy artifact with no schema_version
+  validate-review-return       Validate one raw ce:review persona return read from stdin
+                               Reads exactly one JSON document (max 1 MiB) and checks it against the
+                               raw reviewer return schema. No files are read or written; accepts no
+                               arguments or output flags.
+                               Exit statuses: 0 valid return, 1 malformed/empty/oversized/schema-invalid,
+                               2 operational failure (usage, TTY, stdin read)
   config [subcommand]          Configuration management
     show [--json]              Show configuration (--json for a machine-readable resolved view)
     path                       Print config file locations
@@ -2768,6 +3150,7 @@ Examples:
   systematic capabilities
   systematic validate-review-artifact .context/systematic/ce-review/review-summary.json
   systematic validate-review-artifact --allow-outside-artifact-root /path/to/external-artifact.json
+  systematic validate-review-return < reviewer-return.json
   systematic list agents
   systematic config show
   systematic config show --json
@@ -2901,7 +3284,7 @@ function collectConfigMetadata(roots, injected) {
 }
 function resolveCapabilityRootPath(root) {
   try {
-    return fs6.realpathSync(root);
+    return fs7.realpathSync(root);
   } catch {
     return path5.resolve(root);
   }
@@ -2999,6 +3382,19 @@ function runValidateReviewArtifact(options) {
 function runValidateReviewArtifactCli(options) {
   return runValidateReviewArtifact(options);
 }
+function runValidateReviewReturn(options) {
+  return runReviewReturnValidator({
+    argv: options.argv,
+    fd: options.fd ?? 0,
+    isTTY: options.isTTY ?? process.stdin.isTTY === true,
+    readChunk: options.readChunk,
+    outputSink: options.outputSink ?? ((message) => console.log(message)),
+    errorSink: options.errorSink ?? ((message) => console.error(message))
+  });
+}
+function runValidateReviewReturnCli(options) {
+  return runValidateReviewReturn(options);
+}
 function isHarness(value) {
   return value === "opencode" || value === "pi";
 }
@@ -3187,15 +3583,15 @@ function configShow(options) {
 `);
   console.log(`  User config:    ${paths.userConfig}`);
   console.log(`  Project config: ${paths.projectConfig}`);
-  if (fs6.existsSync(paths.projectConfig)) {
+  if (fs7.existsSync(paths.projectConfig)) {
     console.log(`
 Project configuration:`);
-    console.log(fs6.readFileSync(paths.projectConfig, "utf-8"));
+    console.log(fs7.readFileSync(paths.projectConfig, "utf-8"));
   }
-  if (fs6.existsSync(paths.userConfig)) {
+  if (fs7.existsSync(paths.userConfig)) {
     console.log(`
 User configuration:`);
-    console.log(fs6.readFileSync(paths.userConfig, "utf-8"));
+    console.log(fs7.readFileSync(paths.userConfig, "utf-8"));
   }
   printResolvedSection();
 }
@@ -3399,6 +3795,17 @@ function runLegacyCli(args) {
         process.exit(status);
       break;
     }
+    case "validate-review-return": {
+      const status = runValidateReviewReturnCli({
+        argv: ["systematic", ...args],
+        errorSink: console.error,
+        isTTY: process.stdin.isTTY === true,
+        outputSink: console.log
+      });
+      if (status !== 0)
+        process.exit(status);
+      break;
+    }
     case "setup":
       setupCommand(args.slice(1));
       break;
@@ -3442,5 +3849,6 @@ if (import.meta.main) {
 }
 export {
   runCapabilitiesCli,
-  runValidateReviewArtifactCli
+  runValidateReviewArtifactCli,
+  runValidateReviewReturnCli
 };