@elvis1513/auto-coding-skill 4.2.7 → 4.2.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -15,6 +15,7 @@ import io
15
15
  import json
16
16
  import os
17
17
  import posixpath
18
+ import queue
18
19
  import re
19
20
  import shlex
20
21
  import shutil
@@ -24,6 +25,7 @@ import stat
24
25
  import subprocess
25
26
  import sys
26
27
  import tempfile
28
+ import threading
27
29
  import time
28
30
  import tomllib
29
31
  import urllib.parse
@@ -51,8 +53,10 @@ _GENERATED_NOISE_PATTERNS = [
51
53
  ]
52
54
  _AGENT_CONTRACT_VERSION = 1
53
55
  _AGENT_CONTRACT_SCHEMA = "data/contracts/orchestration-v1.schema.json"
54
- _FOCUSED_REVIEW_TIMEOUT_SECONDS = 90
55
- _DEEP_REVIEW_TIMEOUT_SECONDS = 300
56
+ _FOCUSED_REVIEW_TIMEOUT_SECONDS = 150
57
+ _DEEP_REVIEW_TIMEOUT_SECONDS = 360
58
+ _REVIEW_STARTUP_TIMEOUT_SECONDS = 30.0
59
+ _REVIEW_RUNTIME_ATTEMPT_LIMIT = 2
56
60
  _REVIEW_RUNTIME_FIELDS = (
57
61
  "runtime_state",
58
62
  "runtime_started_at",
@@ -61,6 +65,14 @@ _REVIEW_RUNTIME_FIELDS = (
61
65
  "runtime_exit_code",
62
66
  "runtime_command_sha256",
63
67
  "runtime_receipt_path",
68
+ "runtime_event_log_path",
69
+ "runtime_receipt_sha256",
70
+ "runtime_event_log_sha256",
71
+ "runtime_result_sha256",
72
+ "runtime_attempt_count",
73
+ "runtime_failure_kind",
74
+ "runtime_override_path",
75
+ "runtime_override_sha256",
64
76
  )
65
77
  _REVIEW_OUTPUT_MAX_BYTES = 1024 * 1024
66
78
  _REVIEW_DIFF_ARTIFACT_FORMAT = "git-binary-patch-v1"
@@ -77,13 +89,65 @@ _DEEP_REVIEW_CATEGORIES = {
77
89
  }
78
90
 
79
91
 
80
- class _ReviewerRuntimeTimeout(RuntimeError):
92
+ class _ReviewerRuntimeFailure(RuntimeError):
93
+ """Base class for supervised Reviewer runtime failures with safe diagnostics."""
94
+
95
+ def __init__(self, message: str, diagnostics: Optional[dict] = None) -> None:
96
+ super().__init__(message)
97
+ self.diagnostics = diagnostics or {}
98
+ self.stdout = _text(self.diagnostics.get("stdout"))
99
+ self.stderr = _text(self.diagnostics.get("stderr"))
100
+
101
+
102
+ class _ReviewerRuntimeTimeout(_ReviewerRuntimeFailure):
81
103
  """Raised after the supervised Reviewer process group has been stopped."""
82
104
 
83
- def __init__(self, stdout: str = "", stderr: str = "") -> None:
84
- super().__init__("Reviewer runtime exceeded its assignment deadline.")
85
- self.stdout = stdout
86
- self.stderr = stderr
105
+ def __init__(self, diagnostics: Optional[dict] = None) -> None:
106
+ super().__init__(
107
+ "Reviewer analysis exceeded its assignment deadline.",
108
+ diagnostics,
109
+ )
110
+
111
+
112
+ class _ReviewerRuntimeUnavailable(_ReviewerRuntimeFailure):
113
+ """Raised when no semantic Reviewer event arrives during startup."""
114
+
115
+ def __init__(self, diagnostics: Optional[dict] = None) -> None:
116
+ super().__init__(
117
+ "Reviewer runtime produced no semantic event before its startup deadline.",
118
+ diagnostics,
119
+ )
120
+
121
+
122
+ class _ReviewerRuntimeOutputLimit(_ReviewerRuntimeFailure):
123
+ """Raised after bounded Reviewer output exceeds the private diagnostic limit."""
124
+
125
+ def __init__(self, diagnostics: Optional[dict] = None) -> None:
126
+ super().__init__("Reviewer runtime output exceeded its bounded limit.", diagnostics)
127
+
128
+
129
+ class _ReviewerRuntimeInternalError(_ReviewerRuntimeFailure):
130
+ """Raised after an internal supervision failure has stopped the process group."""
131
+
132
+ def __init__(self, diagnostics: Optional[dict] = None) -> None:
133
+ super().__init__("Reviewer runtime supervision failed safely.", diagnostics)
134
+
135
+
136
+ def _review_startup_timeout_seconds() -> float:
137
+ raw = _text(os.environ.get("AUTOCODING_REVIEW_STARTUP_TIMEOUT_SECONDS"))
138
+ if not raw:
139
+ return _REVIEW_STARTUP_TIMEOUT_SECONDS
140
+ try:
141
+ value = float(raw)
142
+ except ValueError as exc:
143
+ raise APError(
144
+ "AUTOCODING_REVIEW_STARTUP_TIMEOUT_SECONDS must be a positive number."
145
+ ) from exc
146
+ if value <= 0:
147
+ raise APError(
148
+ "AUTOCODING_REVIEW_STARTUP_TIMEOUT_SECONDS must be a positive number."
149
+ )
150
+ return min(value, _REVIEW_STARTUP_TIMEOUT_SECONDS)
87
151
 
88
152
 
89
153
  def _review_diff_artifact_limit() -> int:
@@ -104,7 +168,7 @@ _FINAL_GATE_CACHE_ALGORITHM = "final-gate-v1"
104
168
  _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
105
169
  _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
106
170
  "schema_version": 1,
107
- "managed_versions": {"agents": "4.2.7", "engineering": "4.2.7"},
171
+ "managed_versions": {"agents": "4.2.8", "engineering": "4.2.8"},
108
172
  "known_official_engineering_body_sha256": [
109
173
  "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
110
174
  "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
@@ -1167,8 +1231,8 @@ def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
1167
1231
  if _text(workflow_cfg.get("completion")).lower() != "push":
1168
1232
  workflow_cfg["completion"] = "push"
1169
1233
  changed.append("workflow.completion")
1170
- if _text(workflow_cfg.get("skill_version")) != "4.2.7":
1171
- workflow_cfg["skill_version"] = "4.2.7"
1234
+ if _text(workflow_cfg.get("skill_version")) != "4.2.8":
1235
+ workflow_cfg["skill_version"] = "4.2.8"
1172
1236
  changed.append("workflow.skill_version")
1173
1237
 
1174
1238
  commands_cfg = cfg.setdefault("commands", {})
@@ -1481,16 +1545,16 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1481
1545
  if current_agents:
1482
1546
  archive_dir = repo / "docs" / "archive" / "workflow"
1483
1547
  archive_header = (
1484
- "# Archived AGENTS.md before auto-coding-skill 4.2.7\n\n"
1548
+ "# Archived AGENTS.md before auto-coding-skill 4.2.8\n\n"
1485
1549
  "This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
1486
1550
  "Move any still-current project facts into docs/ENGINEERING.md or docs/project/,\n"
1487
1551
  "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
1488
1552
  )
1489
1553
  archive_content = archive_header + current_agents
1490
- archive = archive_dir / "AGENTS.pre-4.2.7.md"
1554
+ archive = archive_dir / "AGENTS.pre-4.2.8.md"
1491
1555
  if archive.exists() and archive.read_text(encoding="utf-8") != archive_content:
1492
1556
  digest = hashlib.sha256(current_agents.encode("utf-8")).hexdigest()[:12]
1493
- archive = archive_dir / f"AGENTS.pre-4.2.7-{digest}.md"
1557
+ archive = archive_dir / f"AGENTS.pre-4.2.8-{digest}.md"
1494
1558
  if not archive.exists():
1495
1559
  add_action("policy", archive, "archive", "historical and non-authoritative")
1496
1560
  if write:
@@ -2537,6 +2601,7 @@ def _validate_task_manifest(repo: Path, manifest: dict, expected_task_id: str =
2537
2601
  "approved",
2538
2602
  "changes-requested",
2539
2603
  "blocked",
2604
+ "runtime-bypassed",
2540
2605
  }:
2541
2606
  raise APError(f"Task {task_id} has an invalid review contract.")
2542
2607
  review_required = manifest.get("review_required", schema < 3)
@@ -3420,7 +3485,7 @@ def _require_staged_review_matches(repo: Path, cfg: dict, manifest: dict) -> Non
3420
3485
  staged = _staged_task_review_fingerprint(repo, manifest, cfg)
3421
3486
  if staged != approved:
3422
3487
  raise APError(
3423
- "The exact staged tree does not match the immutable Reviewer snapshot; refusing to commit."
3488
+ "The exact staged tree does not match the immutable review clearance snapshot; refusing to commit."
3424
3489
  )
3425
3490
 
3426
3491
 
@@ -3475,6 +3540,78 @@ def _require_dependencies(repo: Path, manifest: dict, ancestor_ref: str) -> None
3475
3540
  )
3476
3541
 
3477
3542
 
3543
+ def _validate_review_runtime_override(repo: Path, manifest: dict, fingerprint: str) -> dict:
3544
+ review = manifest.get("review") or {}
3545
+ override_path = _review_runtime_override_path(
3546
+ repo,
3547
+ _text(manifest.get("task_id")),
3548
+ fingerprint,
3549
+ ).resolve()
3550
+ if Path(_text(review.get("runtime_override_path"))).resolve() != override_path:
3551
+ raise APError("Reviewer runtime override path does not match Git-local task state.")
3552
+ override_sha256 = _text(review.get("runtime_override_sha256"))
3553
+ payload_bytes = _read_private_review_file(override_path, "runtime override")
3554
+ if hashlib.sha256(payload_bytes).hexdigest() != override_sha256:
3555
+ raise APError("Reviewer runtime override SHA-256 binding is invalid.")
3556
+ try:
3557
+ payload = json.loads(payload_bytes.decode("utf-8"))
3558
+ except (json.JSONDecodeError, UnicodeDecodeError) as exc:
3559
+ raise APError("Reviewer runtime override is invalid JSON.") from exc
3560
+ if not isinstance(payload, dict):
3561
+ raise APError("Reviewer runtime override must contain one JSON object.")
3562
+ expected = {
3563
+ "schema": 1,
3564
+ "task_id": _text(manifest.get("task_id")),
3565
+ "diff_fingerprint": fingerprint,
3566
+ "assignment_sha256": _text(review.get("assignment_sha256")),
3567
+ "diff_artifact_sha256": _text(review.get("diff_artifact_sha256")),
3568
+ "runtime_receipt_path": _text(review.get("runtime_receipt_path")),
3569
+ }
3570
+ mismatched = [field for field, value in expected.items() if payload.get(field) != value]
3571
+ if mismatched:
3572
+ raise APError(
3573
+ "Reviewer runtime override does not match task state: " + ", ".join(mismatched)
3574
+ )
3575
+ if payload.get("user_authorized") is not True:
3576
+ raise APError("Reviewer runtime override lacks explicit user authorization.")
3577
+ if not _text(payload.get("authorized_by")) or not _text(payload.get("reason")):
3578
+ raise APError("Reviewer runtime override authorization audit is incomplete.")
3579
+ evidence = payload.get("evidence")
3580
+ if not isinstance(evidence, list) or not evidence or not all(
3581
+ isinstance(item, str) and item for item in evidence
3582
+ ):
3583
+ raise APError("Reviewer runtime override requires non-empty evidence.")
3584
+ receipt_path = Path(_text(payload.get("runtime_receipt_path"))).resolve()
3585
+ expected_result_path, expected_receipt_path = _review_runtime_paths(
3586
+ repo,
3587
+ _text(manifest.get("task_id")),
3588
+ fingerprint,
3589
+ )
3590
+ del expected_result_path
3591
+ if receipt_path != expected_receipt_path.resolve():
3592
+ raise APError("Reviewer runtime override receipt path is not canonical.")
3593
+ receipt_sha256 = _private_review_file_sha256(receipt_path, "runtime receipt")
3594
+ if receipt_sha256 != _text(payload.get("runtime_receipt_sha256")):
3595
+ raise APError("Reviewer runtime override receipt SHA-256 binding is invalid.")
3596
+ failure_state = _text(payload.get("runtime_failure_state"))
3597
+ if failure_state not in {"runtime-unavailable", "analysis-timed-out"}:
3598
+ raise APError("Reviewer runtime override cannot cover this failure state.")
3599
+ assignment_path = Path(_text(review.get("assignment_path"))).resolve()
3600
+ assignment = _load_bound_review_assignment(repo, manifest, assignment_path)
3601
+ receipt = _validate_bound_review_runtime_receipt(
3602
+ repo,
3603
+ manifest,
3604
+ assignment,
3605
+ receipt_path,
3606
+ failure_state,
3607
+ )
3608
+ if _text(receipt.get("status")) != failure_state:
3609
+ raise APError("Reviewer runtime override failure state does not match its receipt.")
3610
+ if failure_state == "runtime-unavailable" and len(receipt.get("attempts") or []) != _REVIEW_RUNTIME_ATTEMPT_LIMIT:
3611
+ raise APError("Reviewer runtime-unavailable override requires exhausted startup attempts.")
3612
+ return payload
3613
+
3614
+
3478
3615
  def _require_approved_review(repo: Path, cfg: dict, manifest: dict) -> str:
3479
3616
  unowned = _task_unowned_paths(repo, cfg, manifest)
3480
3617
  if unowned:
@@ -3483,8 +3620,11 @@ def _require_approved_review(repo: Path, cfg: dict, manifest: dict) -> str:
3483
3620
  if not bool(manifest.get("review_required", int(manifest.get("schema") or 2) < 3)):
3484
3621
  return fingerprint
3485
3622
  review = manifest.get("review") or {}
3486
- if _text(review.get("verdict")) != "approved":
3487
- raise APError("Task review must be approved before commit-push or integration.")
3623
+ verdict = _text(review.get("verdict"))
3624
+ if verdict not in {"approved", "runtime-bypassed"}:
3625
+ raise APError(
3626
+ "Task review must be approved or carry an explicit runtime bypass before commit-push or integration."
3627
+ )
3488
3628
  if _text(review.get("diff_fingerprint")) != fingerprint:
3489
3629
  raise APError("Approved review fingerprint is stale for the current owned diff.")
3490
3630
  if _text(review.get("diff_base")) != _text(manifest.get("base_sha")):
@@ -3508,6 +3648,8 @@ def _require_approved_review(repo: Path, cfg: dict, manifest: dict) -> str:
3508
3648
  if assignment.get(field) != review.get(field):
3509
3649
  raise APError(f"Approved review {field} binding does not match its assignment.")
3510
3650
  _validate_review_diff_artifact(repo, assignment)
3651
+ if verdict == "runtime-bypassed":
3652
+ _validate_review_runtime_override(repo, manifest, fingerprint)
3511
3653
  return fingerprint
3512
3654
 
3513
3655
 
@@ -7231,7 +7373,7 @@ def _normalize_reviewer_runtime_result(assignment: dict, payload: dict) -> dict:
7231
7373
  return _validate_orchestration_contract("result", result)
7232
7374
 
7233
7375
 
7234
- def _reviewer_agent_instructions(worktree: Path) -> str:
7376
+ def _reviewer_agent_config(worktree: Path) -> dict:
7235
7377
  candidates = [
7236
7378
  worktree / ".agents" / "agents" / "reviewer.toml",
7237
7379
  _skill_root().parent.parent / "agents" / "reviewer.toml",
@@ -7245,18 +7387,35 @@ def _reviewer_agent_instructions(worktree: Path) -> str:
7245
7387
  raise APError(f"Cannot load managed Reviewer Agent config: {path}: {exc}") from exc
7246
7388
  instructions = _text(payload.get("developer_instructions"))
7247
7389
  if instructions:
7248
- return instructions
7249
- return (
7250
- "Act as an independent read-only code reviewer. Review only the supplied "
7251
- "assignment and return one JSON object with an approved, changes-requested, "
7252
- "or blocked verdict. Do not modify files."
7253
- )
7390
+ model = _text(payload.get("model"))
7391
+ if model and any(char in model for char in "\0\r\n"):
7392
+ raise APError(f"Managed Reviewer model contains invalid characters: {path}")
7393
+ return {
7394
+ "instructions": instructions,
7395
+ "model": model,
7396
+ "config_path": str(path),
7397
+ }
7398
+ return {
7399
+ "instructions": (
7400
+ "Act as an independent read-only code reviewer. Review only the supplied "
7401
+ "assignment and return one JSON object with an approved, changes-requested, "
7402
+ "or blocked verdict. Do not modify files."
7403
+ ),
7404
+ "model": "",
7405
+ "config_path": "",
7406
+ }
7407
+
7408
+
7409
+ def _reviewer_agent_instructions(worktree: Path) -> str:
7410
+ return _text(_reviewer_agent_config(worktree).get("instructions"))
7254
7411
 
7255
7412
 
7256
7413
  def _codex_reviewer_command(
7257
7414
  worktree: Path,
7258
7415
  assignment_path: Path,
7259
7416
  result_path: Path,
7417
+ *,
7418
+ review_depth: str = "deep",
7260
7419
  ) -> list[str]:
7261
7420
  codex = shutil.which("codex")
7262
7421
  if not codex:
@@ -7264,7 +7423,13 @@ def _codex_reviewer_command(
7264
7423
  "The supervised Reviewer runtime requires the Codex CLI on PATH. "
7265
7424
  "Install Codex or run review-assignment and use another deadline-capable host."
7266
7425
  )
7267
- instructions = _reviewer_agent_instructions(worktree)
7426
+ agent_config = _reviewer_agent_config(worktree)
7427
+ instructions = _text(agent_config.get("instructions"))
7428
+ model = _text(agent_config.get("model"))
7429
+ depth = _text(review_depth).lower()
7430
+ if depth not in {"focused", "deep"}:
7431
+ raise APError(f"Unsupported Reviewer depth: {review_depth!r}")
7432
+ reasoning_effort = "high" if depth == "focused" else "xhigh"
7268
7433
  artifact_command = shlex.join(
7269
7434
  [
7270
7435
  "python3",
@@ -7284,11 +7449,14 @@ def _codex_reviewer_command(
7284
7449
  f"{assignment_path} --verdict <approved|changes-requested|blocked>` when useful. "
7285
7450
  "Return only one JSON object as the final response; do not modify files."
7286
7451
  )
7287
- return [
7452
+ command = [
7288
7453
  codex,
7289
7454
  "-a",
7290
7455
  "never",
7291
7456
  "exec",
7457
+ "--json",
7458
+ "--color",
7459
+ "never",
7292
7460
  "--ephemeral",
7293
7461
  "--ignore-user-config",
7294
7462
  "-C",
@@ -7296,36 +7464,226 @@ def _codex_reviewer_command(
7296
7464
  "-s",
7297
7465
  "read-only",
7298
7466
  "-c",
7299
- 'model_reasoning_effort="xhigh"',
7467
+ f'model_reasoning_effort="{reasoning_effort}"',
7300
7468
  "-c",
7301
7469
  "developer_instructions=" + json.dumps(instructions, ensure_ascii=False),
7302
7470
  "-o",
7303
7471
  str(result_path),
7304
- prompt,
7305
7472
  ]
7473
+ if model:
7474
+ command.extend(["--model", model])
7475
+ command.append(prompt)
7476
+ return command
7306
7477
 
7307
7478
 
7308
- def _terminate_reviewer_process(process: subprocess.Popen[str]) -> tuple[str, str]:
7309
- if process.poll() is None:
7479
+ def _terminate_reviewer_process(process: subprocess.Popen[str]) -> None:
7480
+ if os.name == "posix":
7310
7481
  try:
7311
- if os.name == "posix":
7312
- os.killpg(process.pid, signal.SIGTERM)
7313
- else:
7314
- process.terminate()
7315
- except ProcessLookupError:
7482
+ os.killpg(process.pid, signal.SIGTERM)
7483
+ except (ProcessLookupError, PermissionError):
7316
7484
  pass
7485
+ try:
7486
+ process.wait(timeout=0.1)
7487
+ except subprocess.TimeoutExpired:
7488
+ pass
7489
+ deadline = time.monotonic() + 2
7490
+ while time.monotonic() < deadline:
7491
+ try:
7492
+ os.killpg(process.pid, 0)
7493
+ except ProcessLookupError:
7494
+ break
7495
+ except PermissionError:
7496
+ break
7497
+ time.sleep(0.05)
7498
+ try:
7499
+ os.killpg(process.pid, 0)
7500
+ except (ProcessLookupError, PermissionError):
7501
+ pass
7502
+ else:
7503
+ try:
7504
+ os.killpg(process.pid, signal.SIGKILL)
7505
+ except (ProcessLookupError, PermissionError):
7506
+ pass
7507
+ try:
7508
+ process.wait(timeout=2)
7509
+ except subprocess.TimeoutExpired:
7510
+ pass
7511
+ return
7512
+ if process.poll() is None:
7513
+ process.terminate()
7317
7514
  try:
7318
- stdout, stderr = process.communicate(timeout=2)
7515
+ process.wait(timeout=2)
7319
7516
  except subprocess.TimeoutExpired:
7517
+ if process.poll() is None:
7518
+ process.kill()
7320
7519
  try:
7321
- if os.name == "posix":
7322
- os.killpg(process.pid, signal.SIGKILL)
7323
- else:
7324
- process.kill()
7325
- except ProcessLookupError:
7520
+ process.wait(timeout=2)
7521
+ except subprocess.TimeoutExpired:
7326
7522
  pass
7327
- stdout, stderr = process.communicate()
7328
- return stdout or "", stderr or ""
7523
+
7524
+
7525
+ def _reviewer_diagnostic_categories(value: str) -> list[str]:
7526
+ lowered = value.lower()
7527
+ patterns = {
7528
+ "authentication": ("unauthorized", "forbidden", "login", "401", "403"),
7529
+ "model-discovery": ("available models", "model list", "model unavailable"),
7530
+ "network-disconnect": ("stream disconnected", "connection reset", "connection closed"),
7531
+ "permission": ("operation not permitted", "permission denied", "readonly database"),
7532
+ "rate-limit": ("rate limit", "too many requests", "429"),
7533
+ "state-database": ("state_", "sqlite", "database"),
7534
+ "timeout": ("timed out", "timeout"),
7535
+ "tls": ("tls", "certificate", "handshake eof"),
7536
+ }
7537
+ return sorted(
7538
+ category
7539
+ for category, needles in patterns.items()
7540
+ if any(needle in lowered for needle in needles)
7541
+ )
7542
+
7543
+
7544
+ def _reviewer_event_metadata(stream: str, line: str, timestamp: str) -> tuple[dict, bool]:
7545
+ encoded = line.encode("utf-8", errors="replace")
7546
+ record = {
7547
+ "timestamp": timestamp,
7548
+ "stream": stream,
7549
+ "bytes": len(encoded),
7550
+ "sha256": hashlib.sha256(encoded).hexdigest(),
7551
+ }
7552
+ if stream == "stderr":
7553
+ record["event_type"] = "diagnostic"
7554
+ record["categories"] = _reviewer_diagnostic_categories(line)
7555
+ return record, False
7556
+ try:
7557
+ payload = json.loads(line)
7558
+ except json.JSONDecodeError:
7559
+ record["event_type"] = "stdout-non-json"
7560
+ return record, False
7561
+ if not isinstance(payload, dict):
7562
+ record["event_type"] = "stdout-non-object"
7563
+ return record, False
7564
+ event_type = _text(payload.get("type")) or "unknown-json-event"
7565
+ record["event_type"] = event_type
7566
+ item = payload.get("item")
7567
+ if isinstance(item, dict) and _text(item.get("type")):
7568
+ record["item_type"] = _text(item.get("type"))
7569
+ semantic = event_type != "thread.started"
7570
+ return record, semantic
7571
+
7572
+
7573
+ def _reviewer_phase(event_type: str) -> str:
7574
+ if event_type == "thread.started":
7575
+ return "runtime-started"
7576
+ if event_type == "turn.started":
7577
+ return "analysis-started"
7578
+ if event_type.startswith("item."):
7579
+ return "analyzing"
7580
+ if event_type == "turn.completed":
7581
+ return "finalizing"
7582
+ if event_type in {"error", "turn.failed"}:
7583
+ return "runtime-error"
7584
+ return "runtime-event"
7585
+
7586
+
7587
+ def _append_reviewer_output(parts: list[str], current_bytes: int, value: str) -> int:
7588
+ encoded = value.encode("utf-8", errors="replace")
7589
+ if current_bytes + len(encoded) > _REVIEW_OUTPUT_MAX_BYTES:
7590
+ raise _ReviewerRuntimeOutputLimit()
7591
+ parts.append(value)
7592
+ return current_bytes + len(encoded)
7593
+
7594
+
7595
+ def _reviewer_stream_reader(
7596
+ stream: object,
7597
+ stream_name: str,
7598
+ output_queue: queue.Queue,
7599
+ stop_event: threading.Event,
7600
+ semantic_seen: threading.Event,
7601
+ ) -> None:
7602
+ def emit(raw: bytes) -> None:
7603
+ line = raw.decode("utf-8", errors="replace")
7604
+ timestamp = _now_iso()
7605
+ if stream_name == "stdout" and _reviewer_event_metadata(
7606
+ stream_name,
7607
+ line,
7608
+ timestamp,
7609
+ )[1]:
7610
+ semantic_seen.set()
7611
+ while not stop_event.is_set():
7612
+ try:
7613
+ output_queue.put((stream_name, line, timestamp), timeout=0.05)
7614
+ return
7615
+ except queue.Full:
7616
+ continue
7617
+
7618
+ try:
7619
+ if os.name == "posix":
7620
+ descriptor = stream.fileno() # type: ignore[attr-defined]
7621
+ os.set_blocking(descriptor, False)
7622
+ pending = b""
7623
+ while not stop_event.is_set():
7624
+ try:
7625
+ chunk = os.read(descriptor, 65536)
7626
+ except (BlockingIOError, InterruptedError):
7627
+ stop_event.wait(0.02)
7628
+ continue
7629
+ if not chunk:
7630
+ break
7631
+ pending += chunk
7632
+ while b"\n" in pending:
7633
+ raw, pending = pending.split(b"\n", 1)
7634
+ emit(raw + b"\n")
7635
+ if len(pending) > _REVIEW_OUTPUT_MAX_BYTES:
7636
+ emit(pending)
7637
+ pending = b""
7638
+ if pending and not stop_event.is_set():
7639
+ emit(pending)
7640
+ else:
7641
+ while not stop_event.is_set():
7642
+ raw = stream.readline(_REVIEW_OUTPUT_MAX_BYTES + 1) # type: ignore[attr-defined]
7643
+ if raw == b"":
7644
+ break
7645
+ emit(raw)
7646
+ except (OSError, ValueError):
7647
+ pass
7648
+ finally:
7649
+ while not stop_event.is_set():
7650
+ try:
7651
+ output_queue.put((stream_name, None, _now_iso()), timeout=0.05)
7652
+ break
7653
+ except queue.Full:
7654
+ continue
7655
+
7656
+
7657
+ def _reviewer_attempt_diagnostics(
7658
+ *,
7659
+ started_at: str,
7660
+ finished_at: str,
7661
+ stdout: str,
7662
+ stderr: str,
7663
+ first_event_at: str,
7664
+ last_event_at: str,
7665
+ last_event_type: str,
7666
+ event_count: int,
7667
+ phase: str,
7668
+ exit_code: Optional[int],
7669
+ ) -> dict:
7670
+ return {
7671
+ "started_at": started_at,
7672
+ "finished_at": finished_at,
7673
+ "first_event_at": first_event_at,
7674
+ "last_event_at": last_event_at,
7675
+ "last_event_type": last_event_type,
7676
+ "event_count": event_count,
7677
+ "phase": phase,
7678
+ "exit_code": exit_code,
7679
+ "stdout_bytes": len(stdout.encode("utf-8", errors="replace")),
7680
+ "stderr_bytes": len(stderr.encode("utf-8", errors="replace")),
7681
+ "stdout_sha256": hashlib.sha256(stdout.encode("utf-8", errors="replace")).hexdigest(),
7682
+ "stderr_sha256": hashlib.sha256(stderr.encode("utf-8", errors="replace")).hexdigest(),
7683
+ "diagnostic_categories": _reviewer_diagnostic_categories(stderr),
7684
+ "stdout": stdout,
7685
+ "stderr": stderr,
7686
+ }
7329
7687
 
7330
7688
 
7331
7689
  def _run_supervised_reviewer_process(
@@ -7334,30 +7692,224 @@ def _run_supervised_reviewer_process(
7334
7692
  cwd: Path,
7335
7693
  env: dict[str, str],
7336
7694
  timeout_seconds: float,
7337
- ) -> subprocess.CompletedProcess[str]:
7695
+ startup_timeout_seconds: Optional[float] = None,
7696
+ event_writer: Optional[object] = None,
7697
+ ) -> tuple[subprocess.CompletedProcess[str], dict]:
7338
7698
  if timeout_seconds <= 0:
7339
7699
  raise _ReviewerRuntimeTimeout()
7340
- process = subprocess.Popen(
7341
- command,
7342
- cwd=str(cwd),
7343
- env=env,
7344
- stdin=subprocess.DEVNULL,
7345
- stdout=subprocess.PIPE,
7346
- stderr=subprocess.PIPE,
7347
- text=True,
7348
- start_new_session=True,
7700
+ startup_timeout = min(
7701
+ startup_timeout_seconds or _review_startup_timeout_seconds(),
7702
+ timeout_seconds,
7349
7703
  )
7704
+ started_at = _now_iso()
7705
+ started_monotonic = time.monotonic()
7706
+ try:
7707
+ process = subprocess.Popen(
7708
+ command,
7709
+ cwd=str(cwd),
7710
+ env=env,
7711
+ stdin=subprocess.DEVNULL,
7712
+ stdout=subprocess.PIPE,
7713
+ stderr=subprocess.PIPE,
7714
+ text=False,
7715
+ bufsize=0,
7716
+ start_new_session=True,
7717
+ )
7718
+ except OSError as exc:
7719
+ diagnostics = _reviewer_attempt_diagnostics(
7720
+ started_at=started_at,
7721
+ finished_at=_now_iso(),
7722
+ stdout="",
7723
+ stderr=str(exc),
7724
+ first_event_at="",
7725
+ last_event_at="",
7726
+ last_event_type="",
7727
+ event_count=0,
7728
+ phase="spawn-failed",
7729
+ exit_code=None,
7730
+ )
7731
+ raise _ReviewerRuntimeUnavailable(diagnostics) from exc
7732
+ if process.stdout is None or process.stderr is None:
7733
+ _terminate_reviewer_process(process)
7734
+ raise _ReviewerRuntimeUnavailable()
7735
+
7736
+ output_queue: queue.Queue = queue.Queue(maxsize=256)
7737
+ stop_event = threading.Event()
7738
+ semantic_seen = threading.Event()
7739
+ readers = [
7740
+ threading.Thread(
7741
+ target=_reviewer_stream_reader,
7742
+ args=(process.stdout, "stdout", output_queue, stop_event, semantic_seen),
7743
+ name=f"reviewer-stream-{process.pid}-stdout",
7744
+ daemon=True,
7745
+ ),
7746
+ threading.Thread(
7747
+ target=_reviewer_stream_reader,
7748
+ args=(process.stderr, "stderr", output_queue, stop_event, semantic_seen),
7749
+ name=f"reviewer-stream-{process.pid}-stderr",
7750
+ daemon=True,
7751
+ ),
7752
+ ]
7753
+ for reader in readers:
7754
+ reader.start()
7755
+
7756
+ stdout_parts: list[str] = []
7757
+ stderr_parts: list[str] = []
7758
+ stdout_bytes = 0
7759
+ stderr_bytes = 0
7760
+ closed_streams: set[str] = set()
7761
+ first_event_at = ""
7762
+ last_event_at = ""
7763
+ last_event_type = ""
7764
+ event_count = 0
7765
+ phase = "starting"
7766
+ failure: Optional[type[_ReviewerRuntimeFailure]] = None
7767
+ supervision_error: Optional[Exception] = None
7768
+
7769
+ def consume(item: tuple[str, Optional[str], str], *, write_event: bool = True) -> None:
7770
+ nonlocal stdout_bytes, stderr_bytes, first_event_at, last_event_at
7771
+ nonlocal last_event_type, event_count, phase
7772
+ stream_name, line, timestamp = item
7773
+ if line is None:
7774
+ closed_streams.add(stream_name)
7775
+ return
7776
+ if stream_name == "stdout":
7777
+ stdout_bytes = _append_reviewer_output(stdout_parts, stdout_bytes, line)
7778
+ else:
7779
+ stderr_bytes = _append_reviewer_output(stderr_parts, stderr_bytes, line)
7780
+ record, semantic = _reviewer_event_metadata(stream_name, line, timestamp)
7781
+ if write_event and event_writer is not None:
7782
+ event_writer.write(json.dumps(record, ensure_ascii=False, sort_keys=True) + "\n")
7783
+ event_writer.flush()
7784
+ if stream_name == "stdout" and record["event_type"] not in {
7785
+ "stdout-non-json",
7786
+ "stdout-non-object",
7787
+ }:
7788
+ event_count += 1
7789
+ last_event_at = timestamp
7790
+ last_event_type = _text(record.get("event_type"))
7791
+ phase = _reviewer_phase(last_event_type)
7792
+ if semantic and not first_event_at:
7793
+ first_event_at = timestamp
7794
+
7350
7795
  try:
7351
- stdout, stderr = process.communicate(timeout=timeout_seconds)
7352
- except subprocess.TimeoutExpired as exc:
7353
- stdout, stderr = _terminate_reviewer_process(process)
7354
- raise _ReviewerRuntimeTimeout(stdout, stderr) from exc
7355
- return subprocess.CompletedProcess(
7796
+ while len(closed_streams) < 2 or process.poll() is None:
7797
+ try:
7798
+ item = output_queue.get(timeout=0.05)
7799
+ except queue.Empty:
7800
+ item = None
7801
+ if item is not None:
7802
+ consume(item)
7803
+ elapsed = time.monotonic() - started_monotonic
7804
+ if elapsed >= timeout_seconds:
7805
+ failure = _ReviewerRuntimeTimeout
7806
+ break
7807
+ if (
7808
+ not first_event_at
7809
+ and not semantic_seen.is_set()
7810
+ and elapsed >= startup_timeout
7811
+ ):
7812
+ failure = _ReviewerRuntimeUnavailable
7813
+ break
7814
+ except _ReviewerRuntimeOutputLimit:
7815
+ failure = _ReviewerRuntimeOutputLimit
7816
+ except (OSError, ValueError) as exc:
7817
+ failure = _ReviewerRuntimeInternalError
7818
+ supervision_error = exc
7819
+ phase = "supervision-failed"
7820
+ finally:
7821
+ if failure is not None or process.poll() is None:
7822
+ try:
7823
+ _terminate_reviewer_process(process)
7824
+ except OSError as exc:
7825
+ failure = _ReviewerRuntimeInternalError
7826
+ supervision_error = supervision_error or exc
7827
+ phase = "process-cleanup-failed"
7828
+ tail_deadline = time.monotonic() + 0.5
7829
+ while any(reader.is_alive() for reader in readers) and time.monotonic() < tail_deadline:
7830
+ try:
7831
+ item = output_queue.get(timeout=0.02)
7832
+ except queue.Empty:
7833
+ continue
7834
+ try:
7835
+ consume(item, write_event=supervision_error is None)
7836
+ except _ReviewerRuntimeOutputLimit:
7837
+ failure = _ReviewerRuntimeOutputLimit
7838
+ except (OSError, ValueError) as exc:
7839
+ failure = _ReviewerRuntimeInternalError
7840
+ supervision_error = supervision_error or exc
7841
+ phase = "supervision-failed"
7842
+ stop_event.set()
7843
+ drain_deadline = time.monotonic() + 2
7844
+ while any(reader.is_alive() for reader in readers) and time.monotonic() < drain_deadline:
7845
+ try:
7846
+ item = output_queue.get(timeout=0.05)
7847
+ except queue.Empty:
7848
+ continue
7849
+ try:
7850
+ consume(item, write_event=supervision_error is None)
7851
+ except _ReviewerRuntimeOutputLimit:
7852
+ failure = _ReviewerRuntimeOutputLimit
7853
+ except (OSError, ValueError) as exc:
7854
+ failure = _ReviewerRuntimeInternalError
7855
+ supervision_error = supervision_error or exc
7856
+ phase = "supervision-failed"
7857
+ for reader in readers:
7858
+ reader.join(timeout=0.2)
7859
+ if not any(reader.is_alive() for reader in readers):
7860
+ for stream in (process.stdout, process.stderr):
7861
+ try:
7862
+ stream.close()
7863
+ except (OSError, ValueError):
7864
+ pass
7865
+ while True:
7866
+ try:
7867
+ item = output_queue.get_nowait()
7868
+ except queue.Empty:
7869
+ break
7870
+ try:
7871
+ consume(item, write_event=supervision_error is None)
7872
+ except _ReviewerRuntimeOutputLimit:
7873
+ failure = _ReviewerRuntimeOutputLimit
7874
+ except (OSError, ValueError) as exc:
7875
+ failure = _ReviewerRuntimeInternalError
7876
+ supervision_error = supervision_error or exc
7877
+ phase = "supervision-failed"
7878
+
7879
+ if any(reader.is_alive() for reader in readers):
7880
+ failure = _ReviewerRuntimeInternalError
7881
+ phase = "reader-cleanup-failed"
7882
+ if failure is _ReviewerRuntimeUnavailable and first_event_at:
7883
+ failure = _ReviewerRuntimeTimeout
7884
+
7885
+ stdout = "".join(stdout_parts)
7886
+ stderr = "".join(stderr_parts)
7887
+ diagnostics = _reviewer_attempt_diagnostics(
7888
+ started_at=started_at,
7889
+ finished_at=_now_iso(),
7890
+ stdout=stdout,
7891
+ stderr=stderr,
7892
+ first_event_at=first_event_at,
7893
+ last_event_at=last_event_at,
7894
+ last_event_type=last_event_type,
7895
+ event_count=event_count,
7896
+ phase=phase,
7897
+ exit_code=process.returncode,
7898
+ )
7899
+ if failure is not None:
7900
+ error = failure(diagnostics)
7901
+ if supervision_error is not None:
7902
+ raise error from supervision_error
7903
+ raise error
7904
+ if not first_event_at:
7905
+ raise _ReviewerRuntimeUnavailable(diagnostics)
7906
+ completed = subprocess.CompletedProcess(
7356
7907
  command,
7357
7908
  int(process.returncode or 0),
7358
- stdout or "",
7359
- stderr or "",
7909
+ stdout,
7910
+ stderr,
7360
7911
  )
7912
+ return completed, diagnostics
7361
7913
 
7362
7914
 
7363
7915
  def _validate_agent_plan(plan: dict) -> dict:
@@ -11031,6 +11583,151 @@ def _review_runtime_paths(
11031
11583
  return root / f"{fingerprint}.result.json", root / f"{fingerprint}.run.json"
11032
11584
 
11033
11585
 
11586
+ def _review_runtime_event_log_path(
11587
+ control_repo: Path,
11588
+ task_id: str,
11589
+ fingerprint: str,
11590
+ ) -> Path:
11591
+ if not _REVIEW_SHA256_RE.fullmatch(_text(fingerprint)):
11592
+ raise APError("Review fingerprint must be a lowercase SHA-256 value.")
11593
+ root = _task_review_dir(control_repo, task_id, create=True)
11594
+ return root / f"{fingerprint}.events.jsonl"
11595
+
11596
+
11597
+ def _review_runtime_override_path(
11598
+ control_repo: Path,
11599
+ task_id: str,
11600
+ fingerprint: str,
11601
+ ) -> Path:
11602
+ if not _REVIEW_SHA256_RE.fullmatch(_text(fingerprint)):
11603
+ raise APError("Review fingerprint must be a lowercase SHA-256 value.")
11604
+ root = _task_review_dir(control_repo, task_id, create=True)
11605
+ return root / f"{fingerprint}.override.json"
11606
+
11607
+
11608
+ def _open_private_review_event_log(path: Path):
11609
+ _guard_review_file_parent(path)
11610
+ flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
11611
+ try:
11612
+ descriptor = os.open(path, flags, 0o600)
11613
+ if os.name == "posix":
11614
+ os.fchmod(descriptor, 0o600)
11615
+ return os.fdopen(descriptor, "w", encoding="utf-8", buffering=1)
11616
+ except OSError as exc:
11617
+ raise APError(f"Cannot create private Reviewer event log: {path}: {exc}") from exc
11618
+
11619
+
11620
+ def _private_review_file_sha256(path: Path, label: str) -> str:
11621
+ payload = _read_private_review_file(path, label)
11622
+ return hashlib.sha256(payload).hexdigest()
11623
+
11624
+
11625
+ def _reviewer_cli_version(command: list[str], runner_kind: str) -> str:
11626
+ if runner_kind != "codex" or not command:
11627
+ return "test-override"
11628
+ try:
11629
+ completed = subprocess.run(
11630
+ [command[0], "--version"],
11631
+ check=False,
11632
+ text=True,
11633
+ capture_output=True,
11634
+ timeout=5,
11635
+ )
11636
+ except (OSError, subprocess.TimeoutExpired):
11637
+ return "unavailable"
11638
+ return _text(completed.stdout) or _text(completed.stderr) or "unknown"
11639
+
11640
+
11641
+ def _reviewer_command_metadata(command: list[str], runner_kind: str) -> dict:
11642
+ model = "runtime-default"
11643
+ reasoning_effort = "unknown"
11644
+ for index, argument in enumerate(command):
11645
+ if argument in {"-m", "--model"} and index + 1 < len(command):
11646
+ model = command[index + 1]
11647
+ match = re.fullmatch(r'model_reasoning_effort="?([^"=]+)"?', argument)
11648
+ if match:
11649
+ reasoning_effort = match.group(1)
11650
+ return {
11651
+ "runner_kind": runner_kind,
11652
+ "cli_path": command[0] if command else "",
11653
+ "cli_version": _reviewer_cli_version(command, runner_kind),
11654
+ "model": model,
11655
+ "reasoning_effort": reasoning_effort,
11656
+ }
11657
+
11658
+
11659
+ def _safe_reviewer_attempt(diagnostics: dict, attempt: int, status: str) -> dict:
11660
+ return {
11661
+ "attempt": attempt,
11662
+ "status": status,
11663
+ "started_at": _text(diagnostics.get("started_at")),
11664
+ "finished_at": _text(diagnostics.get("finished_at")),
11665
+ "first_event_at": _text(diagnostics.get("first_event_at")),
11666
+ "last_event_at": _text(diagnostics.get("last_event_at")),
11667
+ "last_event_type": _text(diagnostics.get("last_event_type")),
11668
+ "event_count": int(diagnostics.get("event_count") or 0),
11669
+ "phase": _text(diagnostics.get("phase")) or "unknown",
11670
+ "exit_code": diagnostics.get("exit_code"),
11671
+ "stdout_bytes": int(diagnostics.get("stdout_bytes") or 0),
11672
+ "stderr_bytes": int(diagnostics.get("stderr_bytes") or 0),
11673
+ "stdout_sha256": _text(diagnostics.get("stdout_sha256")),
11674
+ "stderr_sha256": _text(diagnostics.get("stderr_sha256")),
11675
+ "diagnostic_categories": list(diagnostics.get("diagnostic_categories") or []),
11676
+ }
11677
+
11678
+
11679
+ def _validate_review_runtime_receipt(receipt: dict) -> dict:
11680
+ if int(receipt.get("schema") or 0) == 1:
11681
+ return receipt
11682
+ if int(receipt.get("schema") or 0) != 2:
11683
+ raise APError("Reviewer runtime receipt has an unsupported schema.")
11684
+ required_strings = (
11685
+ "task_id",
11686
+ "reviewer",
11687
+ "diff_fingerprint",
11688
+ "assignment_sha256",
11689
+ "diff_artifact_sha256",
11690
+ "command_sha256",
11691
+ "runner_kind",
11692
+ "cli_path",
11693
+ "cli_version",
11694
+ "model",
11695
+ "reasoning_effort",
11696
+ "event_log_path",
11697
+ "status",
11698
+ "started_at",
11699
+ )
11700
+ missing = [field for field in required_strings if not _text(receipt.get(field))]
11701
+ if missing:
11702
+ raise APError("Reviewer runtime receipt is missing: " + ", ".join(missing))
11703
+ attempts = receipt.get("attempts")
11704
+ if not isinstance(attempts, list) or len(attempts) > _REVIEW_RUNTIME_ATTEMPT_LIMIT:
11705
+ raise APError("Reviewer runtime receipt has an invalid attempts list.")
11706
+ allowed_statuses = {
11707
+ "starting",
11708
+ "retrying",
11709
+ "runtime-unavailable",
11710
+ "analysis-timed-out",
11711
+ "output-limit",
11712
+ "failed",
11713
+ "result-invalid",
11714
+ "blocked",
11715
+ "completed",
11716
+ }
11717
+ if _text(receipt.get("status")) not in allowed_statuses:
11718
+ raise APError("Reviewer runtime receipt has an invalid status.")
11719
+ for index, attempt in enumerate(attempts, start=1):
11720
+ if not isinstance(attempt, dict) or int(attempt.get("attempt") or 0) != index:
11721
+ raise APError("Reviewer runtime receipt attempts are not sequential.")
11722
+ if "stderr_tail" in attempt:
11723
+ raise APError("Reviewer runtime receipt cannot persist raw stderr text.")
11724
+ for field in ("stdout_bytes", "stderr_bytes", "event_count"):
11725
+ value = attempt.get(field)
11726
+ if isinstance(value, bool) or not isinstance(value, int) or value < 0:
11727
+ raise APError(f"Reviewer runtime receipt attempt {field} is invalid.")
11728
+ return receipt
11729
+
11730
+
11034
11731
  def _review_command_sha256(command: list[str]) -> str:
11035
11732
  digest = hashlib.sha256()
11036
11733
  for argument in command:
@@ -11046,26 +11743,63 @@ def _bounded_reviewer_output(value: str, label: str) -> str:
11046
11743
  return value
11047
11744
 
11048
11745
 
11049
- def _read_bounded_reviewer_output(path: Path) -> str:
11746
+ def _read_bounded_reviewer_bytes(path: Path) -> bytes:
11050
11747
  try:
11051
- with path.open("rb") as handle:
11748
+ descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
11749
+ metadata = os.fstat(descriptor)
11750
+ if not stat.S_ISREG(metadata.st_mode):
11751
+ os.close(descriptor)
11752
+ raise APError(f"Reviewer result must be a regular file: {path}")
11753
+ with os.fdopen(descriptor, "rb") as handle:
11052
11754
  payload = handle.read(_REVIEW_OUTPUT_MAX_BYTES + 1)
11053
11755
  except OSError as exc:
11054
11756
  raise APError(f"Cannot read Reviewer result: {path}: {exc}") from exc
11055
11757
  if len(payload) > _REVIEW_OUTPUT_MAX_BYTES:
11056
11758
  raise APError(f"Reviewer result exceeded {_REVIEW_OUTPUT_MAX_BYTES} bytes; refusing oversized output.")
11057
- return payload.decode("utf-8", errors="strict")
11759
+ return payload
11760
+
11761
+
11762
+ def _read_bounded_reviewer_output(path: Path) -> str:
11763
+ return _read_bounded_reviewer_bytes(path).decode("utf-8", errors="strict")
11058
11764
 
11059
11765
 
11060
11766
  def _review_result_file_sha256(path: Path) -> str:
11767
+ return hashlib.sha256(_read_bounded_reviewer_bytes(path)).hexdigest()
11768
+
11769
+
11770
+ def _substantive_reviewer_result(path: Path, assignment: dict) -> Optional[dict]:
11771
+ if path.is_symlink():
11772
+ raise APError("Refusing a symlinked Reviewer result.")
11773
+ if not path.exists():
11774
+ return None
11061
11775
  try:
11062
- with path.open("rb") as handle:
11063
- payload = handle.read(_REVIEW_OUTPUT_MAX_BYTES + 1)
11064
- except OSError as exc:
11065
- raise APError(f"Cannot hash Reviewer result: {path}: {exc}") from exc
11066
- if len(payload) > _REVIEW_OUTPUT_MAX_BYTES:
11067
- raise APError(f"Reviewer result exceeded {_REVIEW_OUTPUT_MAX_BYTES} bytes; refusing oversized output.")
11068
- return hashlib.sha256(payload).hexdigest()
11776
+ payload = json.loads(_read_bounded_reviewer_output(path))
11777
+ result = _normalize_reviewer_runtime_result(assignment, payload)
11778
+ except (APError, json.JSONDecodeError, UnicodeDecodeError):
11779
+ return None
11780
+ if _text(result.get("verdict")) in {"blocked", "changes-requested"}:
11781
+ return result
11782
+ return None
11783
+
11784
+
11785
+ def _substantive_reviewer_event_result(stdout: str, assignment: dict) -> Optional[dict]:
11786
+ substantive: Optional[dict] = None
11787
+ for line in stdout.splitlines():
11788
+ try:
11789
+ event = json.loads(line)
11790
+ item = event.get("item") if isinstance(event, dict) else None
11791
+ if not isinstance(item, dict) or _text(item.get("type")) != "agent_message":
11792
+ continue
11793
+ payload = json.loads(_text(item.get("text")))
11794
+ result = _normalize_reviewer_runtime_result(assignment, payload)
11795
+ except (APError, json.JSONDecodeError, TypeError):
11796
+ continue
11797
+ verdict = _text(result.get("verdict"))
11798
+ if verdict == "blocked":
11799
+ substantive = result
11800
+ elif verdict == "changes-requested" and substantive is None:
11801
+ substantive = result
11802
+ return substantive
11069
11803
 
11070
11804
 
11071
11805
  def _update_review_runtime(
@@ -11088,11 +11822,83 @@ def _update_review_runtime(
11088
11822
  manifest["review"] = review
11089
11823
  receipt = _read_json_object(receipt_path) or {}
11090
11824
  receipt.update(receipt_updates)
11825
+ _validate_review_runtime_receipt(receipt)
11091
11826
  _write_private_json(receipt_path, receipt)
11827
+ review["runtime_receipt_sha256"] = _private_review_file_sha256(
11828
+ receipt_path,
11829
+ "runtime receipt",
11830
+ )
11831
+ if _REVIEW_SHA256_RE.fullmatch(_text(receipt.get("event_log_sha256"))):
11832
+ review["runtime_event_log_sha256"] = _text(receipt.get("event_log_sha256"))
11833
+ if _REVIEW_SHA256_RE.fullmatch(_text(receipt.get("result_sha256"))):
11834
+ review["runtime_result_sha256"] = _text(receipt.get("result_sha256"))
11092
11835
  _save_task_manifest(control_repo, manifest)
11093
11836
  return manifest
11094
11837
 
11095
11838
 
11839
+ def _validate_bound_review_runtime_receipt(
11840
+ control_repo: Path,
11841
+ manifest: dict,
11842
+ assignment: dict,
11843
+ receipt_path: Path,
11844
+ expected_status: str,
11845
+ ) -> dict:
11846
+ review = manifest.get("review") or {}
11847
+ task_id = _text(manifest.get("task_id"))
11848
+ fingerprint = _text(review.get("diff_fingerprint"))
11849
+ expected_result_path, expected_receipt_path = _review_runtime_paths(
11850
+ control_repo,
11851
+ task_id,
11852
+ fingerprint,
11853
+ )
11854
+ if receipt_path.resolve() != expected_receipt_path.resolve():
11855
+ raise APError("Reviewer runtime receipt path is not canonical.")
11856
+ payload = _read_private_review_file(receipt_path, "runtime receipt")
11857
+ try:
11858
+ receipt = json.loads(payload.decode("utf-8"))
11859
+ except (json.JSONDecodeError, UnicodeDecodeError) as exc:
11860
+ raise APError("Reviewer runtime receipt is invalid JSON.") from exc
11861
+ if not isinstance(receipt, dict):
11862
+ raise APError("Reviewer runtime receipt must contain one JSON object.")
11863
+ _validate_review_runtime_receipt(receipt)
11864
+ expected = {
11865
+ "task_id": task_id,
11866
+ "reviewer": _text(review.get("reviewer")),
11867
+ "diff_fingerprint": fingerprint,
11868
+ "assignment_path": _text(review.get("assignment_path")),
11869
+ "assignment_sha256": _text(review.get("assignment_sha256")),
11870
+ "diff_artifact_path": _text(assignment.get("diff_artifact_path")),
11871
+ "diff_artifact_sha256": _text(assignment.get("diff_artifact_sha256")),
11872
+ "result_path": str(expected_result_path),
11873
+ "command_sha256": _text(review.get("runtime_command_sha256")),
11874
+ "event_log_path": str(
11875
+ _review_runtime_event_log_path(control_repo, task_id, fingerprint)
11876
+ ),
11877
+ "status": expected_status,
11878
+ }
11879
+ mismatched = [field for field, value in expected.items() if receipt.get(field) != value]
11880
+ if mismatched:
11881
+ raise APError(
11882
+ "Reviewer runtime receipt does not match task state: " + ", ".join(mismatched)
11883
+ )
11884
+ receipt_sha256 = hashlib.sha256(payload).hexdigest()
11885
+ if receipt_sha256 != _text(review.get("runtime_receipt_sha256")):
11886
+ raise APError("Reviewer runtime receipt changed after failure finalization.")
11887
+ event_log_path = Path(_text(receipt.get("event_log_path"))).resolve()
11888
+ event_log_sha256 = _private_review_file_sha256(event_log_path, "event log")
11889
+ if event_log_sha256 != _text(receipt.get("event_log_sha256")) or event_log_sha256 != _text(
11890
+ review.get("runtime_event_log_sha256")
11891
+ ):
11892
+ raise APError("Reviewer runtime event log changed after failure finalization.")
11893
+ result_sha256 = _text(receipt.get("result_sha256"))
11894
+ if result_sha256 and (
11895
+ _review_result_file_sha256(expected_result_path) != result_sha256
11896
+ or result_sha256 != _text(review.get("runtime_result_sha256"))
11897
+ ):
11898
+ raise APError("Reviewer runtime result changed after failure finalization.")
11899
+ return receipt
11900
+
11901
+
11096
11902
  def _blocked_reviewer_runtime_result(
11097
11903
  assignment: dict,
11098
11904
  reason: str,
@@ -11138,6 +11944,11 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11138
11944
 
11139
11945
  command_override = _text(getattr(args, "runner_command_json", ""))
11140
11946
  if command_override:
11947
+ if _text(os.environ.get("AUTOCODING_TEST_RUNNER_OVERRIDE")) != "1":
11948
+ raise APError(
11949
+ "--runner-command-json is test-only; set AUTOCODING_TEST_RUNNER_OVERRIDE=1 "
11950
+ "inside the isolated test harness."
11951
+ )
11141
11952
  try:
11142
11953
  command_value = json.loads(command_override)
11143
11954
  except json.JSONDecodeError as exc:
@@ -11147,12 +11958,21 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11147
11958
  ):
11148
11959
  raise APError("--runner-command-json must be a non-empty JSON array of argv strings.")
11149
11960
  command = command_value
11961
+ runner_kind = "test-override"
11150
11962
  else:
11151
- command = _codex_reviewer_command(worktree, assignment_path, result_path)
11963
+ command = _codex_reviewer_command(
11964
+ worktree,
11965
+ assignment_path,
11966
+ result_path,
11967
+ review_depth=_text(assignment.get("review_depth")) or "focused",
11968
+ )
11969
+ runner_kind = "codex"
11152
11970
  command_sha256 = _review_command_sha256(command)
11971
+ command_metadata = _reviewer_command_metadata(command, runner_kind)
11153
11972
  started_at = _now_iso()
11973
+ event_log_path = _review_runtime_event_log_path(control_repo, task_id, fingerprint)
11154
11974
  receipt = {
11155
- "schema": 1,
11975
+ "schema": 2,
11156
11976
  "task_id": task_id,
11157
11977
  "reviewer": reviewer,
11158
11978
  "diff_fingerprint": fingerprint,
@@ -11162,6 +11982,11 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11162
11982
  "diff_artifact_sha256": _text(assignment.get("diff_artifact_sha256")),
11163
11983
  "result_path": str(result_path),
11164
11984
  "command_sha256": command_sha256,
11985
+ **command_metadata,
11986
+ "event_log_path": str(event_log_path),
11987
+ "event_log_sha256": "",
11988
+ "attempts": [],
11989
+ "failure_kind": "",
11165
11990
  "status": "starting",
11166
11991
  "started_at": started_at,
11167
11992
  "finished_at": "",
@@ -11188,7 +12013,18 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11188
12013
  deadline = _parse_iso_timestamp(assignment.get("deadline_at"), "deadline_at")
11189
12014
  if _dt.datetime.now(_dt.timezone.utc) >= deadline:
11190
12015
  raise APError("Review assignment deadline expired before Reviewer runtime start.")
11191
- _write_private_json(receipt_path, receipt)
12016
+ if result_path.exists() or result_path.is_symlink():
12017
+ raise APError("Reviewer runtime result already exists before the first attempt.")
12018
+ if event_log_path.exists() or event_log_path.is_symlink():
12019
+ raise APError("Reviewer runtime event log already exists for this diff fingerprint.")
12020
+ event_log = _open_private_review_event_log(event_log_path)
12021
+ try:
12022
+ _validate_review_runtime_receipt(receipt)
12023
+ _write_private_json(receipt_path, receipt)
12024
+ except Exception:
12025
+ event_log.close()
12026
+ event_log_path.unlink(missing_ok=True)
12027
+ raise
11192
12028
  current_review.update(
11193
12029
  {
11194
12030
  "runtime_state": "starting",
@@ -11198,6 +12034,9 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11198
12034
  "runtime_exit_code": None,
11199
12035
  "runtime_command_sha256": command_sha256,
11200
12036
  "runtime_receipt_path": str(receipt_path),
12037
+ "runtime_event_log_path": str(event_log_path),
12038
+ "runtime_attempt_count": 0,
12039
+ "runtime_failure_kind": "",
11201
12040
  }
11202
12041
  )
11203
12042
  manifest["review"] = current_review
@@ -11217,43 +12056,212 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11217
12056
  }
11218
12057
  )
11219
12058
  deadline = _parse_iso_timestamp(assignment.get("deadline_at"), "deadline_at")
11220
- remaining = (deadline - _dt.datetime.now(_dt.timezone.utc)).total_seconds()
11221
- try:
11222
- completed = _run_supervised_reviewer_process(
11223
- command,
11224
- cwd=worktree,
11225
- env=env,
11226
- timeout_seconds=remaining,
11227
- )
11228
- except _ReviewerRuntimeTimeout as exc:
12059
+ attempts: list[dict] = []
12060
+ completed: Optional[subprocess.CompletedProcess[str]] = None
12061
+ runtime_failure: Optional[_ReviewerRuntimeFailure] = None
12062
+ failure_kind = ""
12063
+ substantive_result: Optional[dict] = None
12064
+
12065
+ def observed_substantive_result() -> bool:
12066
+ nonlocal substantive_result, runtime_failure, failure_kind
12067
+ try:
12068
+ substantive_result = _substantive_reviewer_result(result_path, assignment)
12069
+ if substantive_result is None and runtime_failure is not None:
12070
+ substantive_result = _substantive_reviewer_event_result(
12071
+ runtime_failure.stdout,
12072
+ assignment,
12073
+ )
12074
+ except APError:
12075
+ runtime_failure = _ReviewerRuntimeInternalError(
12076
+ {"phase": "result-inspection-failed"}
12077
+ )
12078
+ failure_kind = "supervision-error"
12079
+ return True
12080
+ return substantive_result is not None
12081
+
12082
+ for attempt_number in range(1, _REVIEW_RUNTIME_ATTEMPT_LIMIT + 1):
12083
+ remaining = (deadline - _dt.datetime.now(_dt.timezone.utc)).total_seconds()
12084
+ if remaining <= 0:
12085
+ runtime_failure = _ReviewerRuntimeTimeout()
12086
+ failure_kind = "analysis-timeout"
12087
+ break
12088
+ if attempt_number > 1:
12089
+ if result_path.is_symlink():
12090
+ event_log.close()
12091
+ raise APError("Refusing a symlinked Reviewer result before retry.")
12092
+ result_path.unlink(missing_ok=True)
12093
+ try:
12094
+ completed, diagnostics = _run_supervised_reviewer_process(
12095
+ command,
12096
+ cwd=worktree,
12097
+ env=env,
12098
+ timeout_seconds=remaining,
12099
+ startup_timeout_seconds=_review_startup_timeout_seconds(),
12100
+ event_writer=event_log,
12101
+ )
12102
+ attempts.append(
12103
+ _safe_reviewer_attempt(
12104
+ diagnostics,
12105
+ attempt_number,
12106
+ "completed" if completed.returncode == 0 else "failed",
12107
+ )
12108
+ )
12109
+ break
12110
+ except _ReviewerRuntimeUnavailable as exc:
12111
+ runtime_failure = exc
12112
+ failure_kind = "runtime-unavailable"
12113
+ attempts.append(
12114
+ _safe_reviewer_attempt(exc.diagnostics, attempt_number, failure_kind)
12115
+ )
12116
+ if observed_substantive_result():
12117
+ break
12118
+ if attempt_number < _REVIEW_RUNTIME_ATTEMPT_LIMIT:
12119
+ _update_review_runtime(
12120
+ control_repo,
12121
+ task_id,
12122
+ fingerprint,
12123
+ updates={
12124
+ "runtime_state": "retrying",
12125
+ "runtime_attempt_count": attempt_number,
12126
+ "runtime_failure_kind": failure_kind,
12127
+ },
12128
+ receipt_path=receipt_path,
12129
+ receipt_updates={
12130
+ "status": "retrying",
12131
+ "attempts": attempts,
12132
+ "failure_kind": failure_kind,
12133
+ },
12134
+ )
12135
+ continue
12136
+ break
12137
+ except _ReviewerRuntimeTimeout as exc:
12138
+ runtime_failure = exc
12139
+ failure_kind = "analysis-timeout"
12140
+ attempts.append(
12141
+ _safe_reviewer_attempt(exc.diagnostics, attempt_number, failure_kind)
12142
+ )
12143
+ observed_substantive_result()
12144
+ break
12145
+ except _ReviewerRuntimeOutputLimit as exc:
12146
+ runtime_failure = exc
12147
+ failure_kind = "output-limit"
12148
+ attempts.append(
12149
+ _safe_reviewer_attempt(exc.diagnostics, attempt_number, failure_kind)
12150
+ )
12151
+ observed_substantive_result()
12152
+ break
12153
+ except _ReviewerRuntimeInternalError as exc:
12154
+ runtime_failure = exc
12155
+ failure_kind = "supervision-error"
12156
+ attempts.append(
12157
+ _safe_reviewer_attempt(exc.diagnostics, attempt_number, failure_kind)
12158
+ )
12159
+ observed_substantive_result()
12160
+ break
12161
+
12162
+ event_log.close()
12163
+ event_log_sha256 = _private_review_file_sha256(event_log_path, "event log")
12164
+ if runtime_failure is not None:
11229
12165
  finished_at = _now_iso()
12166
+ if substantive_result is not None:
12167
+ _write_private_json(result_path, substantive_result)
12168
+ result_sha256 = _review_result_file_sha256(result_path)
12169
+ _update_review_runtime(
12170
+ control_repo,
12171
+ task_id,
12172
+ fingerprint,
12173
+ updates={
12174
+ "verdict": substantive_result["verdict"],
12175
+ "reason": "substantive Reviewer result observed before runtime failure",
12176
+ "runtime_state": "blocked",
12177
+ "runtime_finished_at": finished_at,
12178
+ "runtime_exit_code": None,
12179
+ "runtime_attempt_count": len(attempts),
12180
+ "runtime_failure_kind": failure_kind,
12181
+ },
12182
+ receipt_path=receipt_path,
12183
+ receipt_updates={
12184
+ "status": "blocked",
12185
+ "finished_at": finished_at,
12186
+ "exit_code": None,
12187
+ "verdict": substantive_result["verdict"],
12188
+ "result_sha256": result_sha256,
12189
+ "attempts": attempts,
12190
+ "failure_kind": failure_kind,
12191
+ "event_log_sha256": event_log_sha256,
12192
+ },
12193
+ )
12194
+ print(json.dumps(substantive_result, ensure_ascii=False, indent=2))
12195
+ raise APError(
12196
+ "Reviewer produced a substantive result before runtime failure; it cannot be bypassed."
12197
+ ) from runtime_failure
12198
+ runtime_state = (
12199
+ "runtime-unavailable"
12200
+ if failure_kind == "runtime-unavailable"
12201
+ else "analysis-timed-out"
12202
+ if failure_kind == "analysis-timeout"
12203
+ else "failed"
12204
+ )
11230
12205
  result = _blocked_reviewer_runtime_result(
11231
12206
  assignment,
11232
- "Reviewer runtime reached its fixed deadline and was terminated.",
11233
- ["runtime_timeout=true"],
12207
+ (
12208
+ "Reviewer runtime was unavailable before analysis started."
12209
+ if failure_kind == "runtime-unavailable"
12210
+ else "Reviewer analysis reached its fixed deadline and was terminated."
12211
+ if failure_kind == "analysis-timeout"
12212
+ else "Reviewer runtime exceeded its bounded output limit."
12213
+ if failure_kind == "output-limit"
12214
+ else "Reviewer runtime supervision failed safely."
12215
+ ),
12216
+ [
12217
+ f"runtime_failure_kind={failure_kind}",
12218
+ f"runtime_attempt_count={len(attempts)}",
12219
+ f"event_log_sha256={event_log_sha256}",
12220
+ ],
11234
12221
  )
11235
12222
  _write_private_json(result_path, result)
12223
+ result_sha256 = _review_result_file_sha256(result_path)
11236
12224
  _update_review_runtime(
11237
12225
  control_repo,
11238
12226
  task_id,
11239
12227
  fingerprint,
11240
12228
  updates={
11241
12229
  "verdict": "blocked",
11242
- "reason": "reviewer runtime timeout",
11243
- "runtime_state": "timed-out",
12230
+ "reason": f"reviewer {failure_kind}",
12231
+ "runtime_state": runtime_state,
11244
12232
  "runtime_finished_at": finished_at,
11245
12233
  "runtime_exit_code": None,
12234
+ "runtime_attempt_count": len(attempts),
12235
+ "runtime_failure_kind": failure_kind,
11246
12236
  },
11247
12237
  receipt_path=receipt_path,
11248
12238
  receipt_updates={
11249
- "status": "timed-out",
12239
+ "status": (
12240
+ "runtime-unavailable"
12241
+ if failure_kind == "runtime-unavailable"
12242
+ else "analysis-timed-out"
12243
+ if failure_kind == "analysis-timeout"
12244
+ else "output-limit"
12245
+ if failure_kind == "output-limit"
12246
+ else "failed"
12247
+ ),
11250
12248
  "finished_at": finished_at,
11251
12249
  "exit_code": None,
12250
+ "attempts": attempts,
12251
+ "failure_kind": failure_kind,
12252
+ "event_log_sha256": event_log_sha256,
12253
+ "result_sha256": result_sha256,
11252
12254
  },
11253
12255
  )
11254
12256
  print(json.dumps(result, ensure_ascii=False, indent=2))
11255
- raise APError("Reviewer runtime timed out and was terminated; review is blocked.") from exc
12257
+ if runtime_state in {"runtime-unavailable", "analysis-timed-out"}:
12258
+ raise APError(
12259
+ f"Reviewer {failure_kind}; review is blocked unless an explicit runtime override is recorded."
12260
+ ) from runtime_failure
12261
+ raise APError(f"Reviewer {failure_kind}; review is blocked.") from runtime_failure
11256
12262
 
12263
+ if completed is None:
12264
+ raise APError("Reviewer runtime ended without a process result.")
11257
12265
  finished_at = _now_iso()
11258
12266
  if completed.returncode != 0:
11259
12267
  result = _blocked_reviewer_runtime_result(
@@ -11262,6 +12270,7 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11262
12270
  [f"runner_exit_code={completed.returncode}"],
11263
12271
  )
11264
12272
  _write_private_json(result_path, result)
12273
+ result_sha256 = _review_result_file_sha256(result_path)
11265
12274
  _update_review_runtime(
11266
12275
  control_repo,
11267
12276
  task_id,
@@ -11272,12 +12281,18 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11272
12281
  "runtime_state": "failed",
11273
12282
  "runtime_finished_at": finished_at,
11274
12283
  "runtime_exit_code": completed.returncode,
12284
+ "runtime_attempt_count": len(attempts),
12285
+ "runtime_failure_kind": "process-exit",
11275
12286
  },
11276
12287
  receipt_path=receipt_path,
11277
12288
  receipt_updates={
11278
12289
  "status": "failed",
11279
12290
  "finished_at": finished_at,
11280
12291
  "exit_code": completed.returncode,
12292
+ "attempts": attempts,
12293
+ "failure_kind": "process-exit",
12294
+ "event_log_sha256": event_log_sha256,
12295
+ "result_sha256": result_sha256,
11281
12296
  },
11282
12297
  )
11283
12298
  print(json.dumps(result, ensure_ascii=False, indent=2))
@@ -11298,6 +12313,7 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11298
12313
  ["result_contract_valid=false"],
11299
12314
  )
11300
12315
  _write_private_json(result_path, result)
12316
+ result_sha256 = _review_result_file_sha256(result_path)
11301
12317
  _update_review_runtime(
11302
12318
  control_repo,
11303
12319
  task_id,
@@ -11308,12 +12324,18 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11308
12324
  "runtime_state": "failed",
11309
12325
  "runtime_finished_at": finished_at,
11310
12326
  "runtime_exit_code": completed.returncode,
12327
+ "runtime_attempt_count": len(attempts),
12328
+ "runtime_failure_kind": "result-invalid",
11311
12329
  },
11312
12330
  receipt_path=receipt_path,
11313
12331
  receipt_updates={
11314
12332
  "status": "result-invalid",
11315
12333
  "finished_at": finished_at,
11316
12334
  "exit_code": completed.returncode,
12335
+ "attempts": attempts,
12336
+ "failure_kind": "result-invalid",
12337
+ "event_log_sha256": event_log_sha256,
12338
+ "result_sha256": result_sha256,
11317
12339
  },
11318
12340
  )
11319
12341
  print(json.dumps(result, ensure_ascii=False, indent=2))
@@ -11332,6 +12354,8 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11332
12354
  "runtime_state": runtime_state,
11333
12355
  "runtime_finished_at": finished_at,
11334
12356
  "runtime_exit_code": completed.returncode,
12357
+ "runtime_attempt_count": len(attempts),
12358
+ "runtime_failure_kind": "",
11335
12359
  },
11336
12360
  receipt_path=receipt_path,
11337
12361
  receipt_updates={
@@ -11340,6 +12364,9 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11340
12364
  "exit_code": completed.returncode,
11341
12365
  "verdict": result["verdict"],
11342
12366
  "result_sha256": result_sha256,
12367
+ "attempts": attempts,
12368
+ "failure_kind": "",
12369
+ "event_log_sha256": event_log_sha256,
11343
12370
  },
11344
12371
  )
11345
12372
  if result["verdict"] == "blocked":
@@ -11359,6 +12386,130 @@ def cmd_review_run(args: argparse.Namespace) -> None:
11359
12386
  print(json.dumps(result, ensure_ascii=False, indent=2))
11360
12387
 
11361
12388
 
12389
+ def cmd_review_runtime_override(args: argparse.Namespace) -> None:
12390
+ repo = Path(args.repo).resolve()
12391
+ ensure_git_repo(repo)
12392
+ cfg = _load_cfg(repo)
12393
+ task_id = _validate_task_id(args.task_id)
12394
+ control_repo, worktree, _ = _task_lifecycle_context(repo, cfg, task_id)
12395
+ if not bool(getattr(args, "confirm_runtime_bypass", False)):
12396
+ raise APError("Runtime bypass requires --confirm-runtime-bypass.")
12397
+ authorized_by = _text(getattr(args, "authorized_by", ""))
12398
+ authorization_ref = _text(getattr(args, "authorization_ref", ""))
12399
+ reason = _text(getattr(args, "reason", ""))
12400
+ evidence = list(getattr(args, "evidence", None) or [])
12401
+ for label, value in (
12402
+ ("authorized-by", authorized_by),
12403
+ ("authorization-ref", authorization_ref),
12404
+ ("reason", reason),
12405
+ ):
12406
+ if not value or any(char in value for char in "\0\r\n"):
12407
+ raise APError(f"--{label} must be non-empty and single-line.")
12408
+ if len(reason) < 12:
12409
+ raise APError("--reason must explain the exceptional delivery decision.")
12410
+ if not evidence or not all(
12411
+ isinstance(item, str) and item and not any(char in item for char in "\0\r\n")
12412
+ for item in evidence
12413
+ ):
12414
+ raise APError("Runtime bypass requires at least one single-line --evidence value.")
12415
+
12416
+ timeout_s = float(_concurrency_cfg(cfg).get("lock_timeout_sec") or 30)
12417
+ with _repo_lock(control_repo, f"task-{task_id}", timeout_s=timeout_s):
12418
+ manifest = _load_task_manifest(control_repo, task_id)
12419
+ lifecycle_actor = _text(os.environ.get("CODEX_THREAD_ID"))
12420
+ if not lifecycle_actor or lifecycle_actor != _text(manifest.get("owner")):
12421
+ raise APError("Only the task lifecycle owner may record a Reviewer runtime bypass.")
12422
+ if _text(manifest.get("state")) not in {"active", "pushed", "integration-raced"}:
12423
+ raise APError(f"Task {task_id} cannot accept a runtime bypass in state={manifest.get('state')}.")
12424
+ review = dict(manifest.get("review") or {})
12425
+ runtime_state = _text(review.get("runtime_state"))
12426
+ if runtime_state not in {"runtime-unavailable", "analysis-timed-out"}:
12427
+ raise APError(
12428
+ "Runtime bypass is allowed only after exhausted runtime-unavailable or analysis-timed-out state."
12429
+ )
12430
+ fingerprint = _task_review_fingerprint(worktree, manifest, _load_cfg(worktree))
12431
+ supplied = _text(args.diff_fingerprint)
12432
+ if supplied != fingerprint or _text(review.get("diff_fingerprint")) != fingerprint:
12433
+ raise APError(
12434
+ f"Runtime bypass fingerprint mismatch: supplied={supplied or '(missing)'}, current={fingerprint}."
12435
+ )
12436
+ assignment_path = Path(_text(review.get("assignment_path"))).resolve()
12437
+ assignment = _load_bound_review_assignment(control_repo, manifest, assignment_path)
12438
+ _validate_review_diff_artifact(control_repo, assignment)
12439
+ receipt_path = Path(_text(review.get("runtime_receipt_path"))).resolve()
12440
+ _, expected_receipt_path = _review_runtime_paths(
12441
+ control_repo,
12442
+ task_id,
12443
+ fingerprint,
12444
+ )
12445
+ if receipt_path != expected_receipt_path.resolve():
12446
+ raise APError("Reviewer runtime receipt path is not canonical.")
12447
+ receipt = _validate_bound_review_runtime_receipt(
12448
+ control_repo,
12449
+ manifest,
12450
+ assignment,
12451
+ receipt_path,
12452
+ runtime_state,
12453
+ )
12454
+ if int(receipt.get("schema") or 0) != 2:
12455
+ raise APError("Runtime bypass requires a schema-2 Reviewer receipt.")
12456
+ if runtime_state == "runtime-unavailable" and len(receipt.get("attempts") or []) != _REVIEW_RUNTIME_ATTEMPT_LIMIT:
12457
+ raise APError("Runtime-unavailable bypass requires exhausted startup attempts.")
12458
+ override_path = _review_runtime_override_path(control_repo, task_id, fingerprint)
12459
+ if override_path.exists() or override_path.is_symlink():
12460
+ raise APError("Reviewer runtime override already exists for this diff fingerprint.")
12461
+ payload = {
12462
+ "schema": 1,
12463
+ "task_id": task_id,
12464
+ "diff_fingerprint": fingerprint,
12465
+ "assignment_sha256": _text(review.get("assignment_sha256")),
12466
+ "diff_artifact_sha256": _text(review.get("diff_artifact_sha256")),
12467
+ "runtime_receipt_path": str(receipt_path),
12468
+ "runtime_receipt_sha256": _private_review_file_sha256(
12469
+ receipt_path,
12470
+ "runtime receipt",
12471
+ ),
12472
+ "runtime_failure_state": runtime_state,
12473
+ "user_authorized": True,
12474
+ "authorized_by": authorized_by,
12475
+ "authorization_ref": authorization_ref,
12476
+ "authorized_at": _now_iso(),
12477
+ "lifecycle_owner": lifecycle_actor,
12478
+ "reason": reason,
12479
+ "evidence": evidence,
12480
+ }
12481
+ _write_private_json(override_path, payload)
12482
+ override_sha256 = _private_review_file_sha256(override_path, "runtime override")
12483
+ review.update(
12484
+ {
12485
+ "verdict": "runtime-bypassed",
12486
+ "reason": reason,
12487
+ "reviewed_at": payload["authorized_at"],
12488
+ "runtime_state": "runtime-bypassed",
12489
+ "runtime_override_path": str(override_path),
12490
+ "runtime_override_sha256": override_sha256,
12491
+ }
12492
+ )
12493
+ manifest["review"] = review
12494
+ _save_task_manifest(control_repo, manifest)
12495
+ result = {
12496
+ "task_id": task_id,
12497
+ "verdict": "runtime-bypassed",
12498
+ "diff_fingerprint": fingerprint,
12499
+ "authorized_by": authorized_by,
12500
+ "authorization_ref": authorization_ref,
12501
+ "override_path": str(override_path),
12502
+ "override_sha256": override_sha256,
12503
+ }
12504
+ if bool(getattr(args, "json", False)):
12505
+ print(json.dumps(result, ensure_ascii=False, indent=2))
12506
+ else:
12507
+ print(
12508
+ f"[review-runtime-override] task={task_id} verdict=runtime-bypassed "
12509
+ f"fingerprint={fingerprint}"
12510
+ )
12511
+
12512
+
11362
12513
  def cmd_task_review(args: argparse.Namespace) -> None:
11363
12514
  repo = Path(args.repo).resolve()
11364
12515
  ensure_git_repo(repo)
@@ -11506,9 +12657,27 @@ def cmd_task_review(args: argparse.Namespace) -> None:
11506
12657
  raise APError(
11507
12658
  "Reviewer runtime verdict does not match the requested task-review verdict."
11508
12659
  )
11509
- receipt = _read_json_object(receipt_path)
11510
- if not receipt:
11511
- raise APError("Reviewer runtime receipt is missing or invalid.")
12660
+ receipt = _validate_bound_review_runtime_receipt(
12661
+ control_repo,
12662
+ manifest,
12663
+ assignment,
12664
+ receipt_path,
12665
+ "completed",
12666
+ )
12667
+ if int(receipt.get("schema") or 0) == 2:
12668
+ expected_event_log_path = _review_runtime_event_log_path(
12669
+ control_repo,
12670
+ task_id,
12671
+ fingerprint,
12672
+ ).resolve()
12673
+ if Path(_text(receipt.get("event_log_path"))).resolve() != expected_event_log_path:
12674
+ raise APError("Reviewer runtime event log path is not canonical.")
12675
+ if Path(_text(assigned_review.get("runtime_event_log_path"))).resolve() != expected_event_log_path:
12676
+ raise APError("Reviewer runtime event log manifest binding is invalid.")
12677
+ if _private_review_file_sha256(expected_event_log_path, "event log") != _text(
12678
+ receipt.get("event_log_sha256")
12679
+ ):
12680
+ raise APError("Reviewer runtime event log SHA-256 binding is invalid.")
11512
12681
  expected_receipt = {
11513
12682
  "task_id": task_id,
11514
12683
  "reviewer": reviewer,
@@ -12271,7 +13440,7 @@ def _push_current_task(repo: Path, manifest: dict, expected_commit: str = "") ->
12271
13440
  manifest["last_commit"] = commit_sha
12272
13441
  manifest["claimed_paths"] = _changed_files(repo, _text(manifest.get("base_sha")))
12273
13442
  review = manifest.get("review") or {}
12274
- if _text(review.get("verdict")) == "approved":
13443
+ if _text(review.get("verdict")) in {"approved", "runtime-bypassed"}:
12275
13444
  review["diff_head"] = commit_sha
12276
13445
  review["diff_fingerprint"] = _task_review_fingerprint(repo, manifest)
12277
13446
  manifest["review"] = review
@@ -12820,6 +13989,20 @@ def main(argv: Optional[List[str]] = None) -> int:
12820
13989
  s.add_argument("--runner-command-json", help=argparse.SUPPRESS)
12821
13990
  s.set_defaults(func=cmd_review_run)
12822
13991
 
13992
+ s = sp.add_parser(
13993
+ "review-runtime-override",
13994
+ help="Record an explicit user-authorized bypass for an exhausted Reviewer runtime failure",
13995
+ )
13996
+ s.add_argument("task_id")
13997
+ s.add_argument("--diff-fingerprint", required=True)
13998
+ s.add_argument("--authorized-by", required=True)
13999
+ s.add_argument("--authorization-ref", required=True)
14000
+ s.add_argument("--reason", required=True)
14001
+ s.add_argument("--evidence", action="append", required=True)
14002
+ s.add_argument("--confirm-runtime-bypass", action="store_true")
14003
+ s.add_argument("--json", action="store_true")
14004
+ s.set_defaults(func=cmd_review_runtime_override)
14005
+
12823
14006
  s = sp.add_parser("task-submodule-sync")
12824
14007
  s.add_argument("task_id")
12825
14008
  s.set_defaults(func=cmd_task_submodule_sync)