@elvis1513/auto-coding-skill 4.2.1 → 4.2.2

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.
@@ -10,13 +10,18 @@ import contextlib
10
10
  import hashlib
11
11
  import datetime as _dt
12
12
  import fnmatch
13
+ import io
13
14
  import json
14
15
  import os
15
16
  import posixpath
16
17
  import re
18
+ import shutil
19
+ import signal
17
20
  import socket
21
+ import subprocess
18
22
  import sys
19
23
  import time
24
+ import tomllib
20
25
  import urllib.parse
21
26
  import urllib.error
22
27
  import urllib.request
@@ -29,7 +34,7 @@ from install_integrity import verify_managed_install
29
34
  from scaffold_templates import MANAGED_FRAMEWORK_DOCS, scaffold_groups, templates_for
30
35
 
31
36
 
32
- _JENKINS_CRUMB_CACHE: dict[str, dict[str, str]] = {}
37
+ _JENKINS_CRUMB_CACHE: dict[tuple[str, str], dict[str, str]] = {}
33
38
  _INVALID_PLACEHOLDERS = {"N/A", "TODO", "TBD", "CHANGEME", "CHANGE_ME", "FILL_ME", "FILL-ME", "PLACEHOLDER", "XXX", "NULL", "~"}
34
39
  _GENERATED_NOISE_PATTERNS = [
35
40
  ".local/auto-coding-skill/**",
@@ -44,6 +49,16 @@ _AGENT_CONTRACT_VERSION = 1
44
49
  _AGENT_CONTRACT_SCHEMA = "data/contracts/orchestration-v1.schema.json"
45
50
  _FOCUSED_REVIEW_TIMEOUT_SECONDS = 90
46
51
  _DEEP_REVIEW_TIMEOUT_SECONDS = 300
52
+ _REVIEW_RUNTIME_FIELDS = (
53
+ "runtime_state",
54
+ "runtime_started_at",
55
+ "runtime_finished_at",
56
+ "runtime_result_path",
57
+ "runtime_exit_code",
58
+ "runtime_command_sha256",
59
+ "runtime_receipt_path",
60
+ )
61
+ _REVIEW_OUTPUT_MAX_BYTES = 1024 * 1024
47
62
  _DEEP_REVIEW_CATEGORIES = {
48
63
  "api",
49
64
  "auth",
@@ -53,6 +68,15 @@ _DEEP_REVIEW_CATEGORIES = {
53
68
  "payment",
54
69
  "prod_config",
55
70
  }
71
+
72
+
73
+ class _ReviewerRuntimeTimeout(RuntimeError):
74
+ """Raised after the supervised Reviewer process group has been stopped."""
75
+
76
+ def __init__(self, stdout: str = "", stderr: str = "") -> None:
77
+ super().__init__("Reviewer runtime exceeded its assignment deadline.")
78
+ self.stdout = stdout
79
+ self.stderr = stderr
56
80
  _RECOMMENDED_FINAL_COMMAND_SECONDS = 120.0
57
81
  _RECOMMENDED_FINAL_TOTAL_SECONDS = 180.0
58
82
  _FINAL_GATE_CACHE_SCHEMA = 1
@@ -60,7 +84,7 @@ _FINAL_GATE_CACHE_ALGORITHM = "final-gate-v1"
60
84
  _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
61
85
  _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
62
86
  "schema_version": 1,
63
- "managed_versions": {"agents": "4.2.1", "engineering": "4.2.1"},
87
+ "managed_versions": {"agents": "4.2.2", "engineering": "4.2.2"},
64
88
  "known_official_engineering_body_sha256": [
65
89
  "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
66
90
  "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
@@ -261,27 +285,101 @@ def _run_configured_command(
261
285
  return True
262
286
 
263
287
 
264
- def _jenkins_basic_auth_headers(cfg: dict) -> dict:
288
+ def _jenkins_access_cfg(cfg: dict, component: str) -> dict:
289
+ access = cfg.get("access") or {}
290
+ jenkins = access.get("jenkins") or {}
291
+ value = jenkins.get(component) or {}
292
+ return value if isinstance(value, dict) else {}
293
+
294
+
295
+ def _configured_jenkins_components(cfg: dict) -> list[str]:
296
+ return [
297
+ component
298
+ for component in ("frontend", "backend")
299
+ if any(
300
+ _is_explicit_fill(value)
301
+ for value in _jenkins_access_cfg(cfg, component).values()
302
+ )
303
+ ]
304
+
305
+
306
+ def _require_http_url(field: str, value: object) -> str:
307
+ raw = _text(value).rstrip("/")
308
+ parsed = urllib.parse.urlparse(raw)
309
+ if not _is_explicit_fill(raw) or parsed.scheme not in {"http", "https"} or not parsed.netloc:
310
+ raise APError(f"Missing or invalid {field}; fill an http/https URL in docs/ENGINEERING.md.")
311
+ return raw
312
+
313
+
314
+ def _resolve_jenkins_component(
315
+ cfg: dict,
316
+ requested: str = "",
317
+ explicit_job_url: str = "",
318
+ ) -> str:
319
+ component = _text(requested).lower()
320
+ configured = _configured_jenkins_components(cfg)
321
+ if component:
322
+ if component not in {"frontend", "backend"}:
323
+ raise APError("Jenkins component must be frontend or backend.")
324
+ if component not in configured:
325
+ raise APError(f"Missing access.jenkins.{component} configuration.")
326
+ return component
327
+ explicit = _text(explicit_job_url).rstrip("/")
328
+ if explicit:
329
+ matches = [
330
+ candidate
331
+ for candidate in configured
332
+ if _text(_jenkins_access_cfg(cfg, candidate).get("url")).rstrip("/") == explicit
333
+ ]
334
+ if len(matches) == 1:
335
+ return matches[0]
336
+ if len(configured) == 1:
337
+ return configured[0]
338
+ if len(configured) > 1:
339
+ identities: set[tuple[str, str, str]] = set()
340
+ for candidate in configured:
341
+ lane = _jenkins_access_cfg(cfg, candidate)
342
+ try:
343
+ secret = _resolve_secret(f"access.jenkins.{candidate}", lane, "password")
344
+ except APError:
345
+ break
346
+ identities.add(
347
+ (
348
+ _text(lane.get("url")).rstrip("/"),
349
+ _text(lane.get("username")),
350
+ secret,
351
+ )
352
+ )
353
+ if len(identities) == 1:
354
+ return configured[0]
355
+ raise APError(
356
+ "Multiple access.jenkins endpoints are configured; pass --component frontend or backend."
357
+ )
358
+ return ""
359
+
360
+
361
+ def _jenkins_auth_config(cfg: dict, component: str = "") -> tuple[str, dict, str, str]:
362
+ if component:
363
+ lane = _jenkins_access_cfg(cfg, component)
364
+ if not _is_explicit_fill(lane.get("username")):
365
+ raise APError(f"Missing access.jenkins.{component}.username.")
366
+ return f"access.jenkins.{component}", lane, "username", "password"
367
+
265
368
  jenkins_cfg = (cfg.get("jenkins") or {})
266
369
  credential_pairs = [
267
370
  ("api_user", "api_password"),
268
371
  ("ui_username", "ui_password"),
269
372
  ]
270
373
  errors: list[str] = []
271
-
272
374
  for user_field, secret_field in credential_pairs:
273
375
  user = _text(jenkins_cfg.get(user_field))
274
- if not _is_explicit_fill(user):
275
- continue
276
- try:
277
- secret = _resolve_secret("jenkins", jenkins_cfg, secret_field)
278
- except APError as exc:
279
- errors.append(str(exc))
280
- continue
281
- raw = f"{user}:{secret}".encode("utf-8")
282
- auth = base64.b64encode(raw).decode("ascii")
283
- return {"Authorization": f"Basic {auth}"}
284
-
376
+ if _is_explicit_fill(user):
377
+ try:
378
+ _resolve_secret("jenkins", jenkins_cfg, secret_field)
379
+ except APError as exc:
380
+ errors.append(str(exc))
381
+ continue
382
+ return "jenkins", jenkins_cfg, user_field, secret_field
285
383
  detail = "\n- " + "\n- ".join(errors) if errors else ""
286
384
  raise APError(
287
385
  "Missing Jenkins API credentials. Configure jenkins.api_user with "
@@ -291,6 +389,15 @@ def _jenkins_basic_auth_headers(cfg: dict) -> dict:
291
389
  )
292
390
 
293
391
 
392
+ def _jenkins_basic_auth_headers(cfg: dict, component: str = "") -> dict:
393
+ section_name, section_cfg, user_field, secret_field = _jenkins_auth_config(cfg, component)
394
+ user = _text(section_cfg.get(user_field))
395
+ secret = _resolve_secret(section_name, section_cfg, secret_field)
396
+ raw = f"{user}:{secret}".encode("utf-8")
397
+ auth = base64.b64encode(raw).decode("ascii")
398
+ return {"Authorization": f"Basic {auth}"}
399
+
400
+
294
401
  def _http_error_body(exc: urllib.error.HTTPError) -> str:
295
402
  try:
296
403
  return exc.read().decode("utf-8", errors="replace").strip()
@@ -313,13 +420,14 @@ def _basic_auth_header(username: str, password: str) -> dict[str, str]:
313
420
  return {"Authorization": f"Basic {auth}"}
314
421
 
315
422
 
316
- def _jenkins_root_url(cfg: dict, job_url: str = "") -> str:
423
+ def _jenkins_root_url(cfg: dict, job_url: str = "", component: str = "") -> str:
317
424
  jenkins_cfg = (cfg.get("jenkins") or {})
318
- base_url = str(jenkins_cfg.get("base_url") or "").strip().rstrip("/")
425
+ lane_url = _text(_jenkins_access_cfg(cfg, component).get("url")) if component else ""
426
+ base_url = "" if component else str(jenkins_cfg.get("base_url") or "").strip().rstrip("/")
319
427
  if base_url:
320
428
  return base_url
321
429
 
322
- source = str(job_url or jenkins_cfg.get("job_url") or "").strip().rstrip("/")
430
+ source = str(job_url or lane_url or jenkins_cfg.get("job_url") or "").strip().rstrip("/")
323
431
  if not source:
324
432
  return ""
325
433
  if "/job/" in source:
@@ -327,23 +435,30 @@ def _jenkins_root_url(cfg: dict, job_url: str = "") -> str:
327
435
  return source
328
436
 
329
437
 
330
- def _jenkins_crumb_api_url(cfg: dict, job_url: str = "") -> str:
331
- root = _jenkins_root_url(cfg, job_url=job_url)
438
+ def _jenkins_crumb_api_url(cfg: dict, job_url: str = "", component: str = "") -> str:
439
+ root = _jenkins_root_url(cfg, job_url=job_url, component=component)
332
440
  if not root:
333
441
  return ""
334
442
  return root.rstrip("/") + "/crumbIssuer/api/json"
335
443
 
336
444
 
337
- def _jenkins_crumb_headers(cfg: dict, job_url: str = "", timeout_s: int = 15) -> dict:
338
- crumb_url = _jenkins_crumb_api_url(cfg, job_url=job_url)
445
+ def _jenkins_crumb_headers(
446
+ cfg: dict,
447
+ job_url: str = "",
448
+ timeout_s: int = 15,
449
+ component: str = "",
450
+ ) -> dict:
451
+ crumb_url = _jenkins_crumb_api_url(cfg, job_url=job_url, component=component)
339
452
  if not crumb_url:
340
453
  return {}
341
- cached = _JENKINS_CRUMB_CACHE.get(crumb_url)
454
+ _, auth_cfg, user_field, _ = _jenkins_auth_config(cfg, component)
455
+ cache_key = (crumb_url, _text(auth_cfg.get(user_field)))
456
+ cached = _JENKINS_CRUMB_CACHE.get(cache_key)
342
457
  if cached:
343
458
  return dict(cached)
344
459
 
345
460
  headers = {"Accept": "application/json"}
346
- headers.update(_jenkins_basic_auth_headers(cfg))
461
+ headers.update(_jenkins_basic_auth_headers(cfg, component))
347
462
  req = urllib.request.Request(crumb_url, headers=headers, method="GET")
348
463
  try:
349
464
  with urllib.request.urlopen(req, timeout=timeout_s) as resp:
@@ -370,13 +485,19 @@ def _jenkins_crumb_headers(cfg: dict, job_url: str = "", timeout_s: int = 15) ->
370
485
  return {}
371
486
 
372
487
  crumb_headers = {field: crumb}
373
- _JENKINS_CRUMB_CACHE[crumb_url] = crumb_headers
488
+ _JENKINS_CRUMB_CACHE[cache_key] = crumb_headers
374
489
  return dict(crumb_headers)
375
490
 
376
491
 
377
- def _jenkins_api_get_json(url: str, cfg: dict, timeout_s: int = 15, allow_404: bool = False) -> Optional[dict]:
492
+ def _jenkins_api_get_json(
493
+ url: str,
494
+ cfg: dict,
495
+ timeout_s: int = 15,
496
+ allow_404: bool = False,
497
+ component: str = "",
498
+ ) -> Optional[dict]:
378
499
  headers = {"Accept": "application/json"}
379
- headers.update(_jenkins_basic_auth_headers(cfg))
500
+ headers.update(_jenkins_basic_auth_headers(cfg, component))
380
501
  req = urllib.request.Request(url, headers=headers, method="GET")
381
502
  try:
382
503
  with urllib.request.urlopen(req, timeout=timeout_s) as resp:
@@ -386,7 +507,12 @@ def _jenkins_api_get_json(url: str, cfg: dict, timeout_s: int = 15, allow_404: b
386
507
  if exc.code == 404 and allow_404:
387
508
  return None
388
509
  if exc.code == 403:
389
- crumb_headers = _jenkins_crumb_headers(cfg, job_url=url, timeout_s=timeout_s)
510
+ crumb_headers = _jenkins_crumb_headers(
511
+ cfg,
512
+ job_url=url,
513
+ timeout_s=timeout_s,
514
+ component=component,
515
+ )
390
516
  if crumb_headers:
391
517
  retry_headers = dict(headers)
392
518
  retry_headers.update(crumb_headers)
@@ -494,12 +620,21 @@ def _jenkins_branch_job_urls(root_job_url: str, branch_name: str) -> List[str]:
494
620
  return urls
495
621
 
496
622
 
497
- def _resolve_jenkins_job_url(cfg: dict, job_name: str = "", job_url: str = "") -> str:
623
+ def _resolve_jenkins_job_url(
624
+ cfg: dict,
625
+ job_name: str = "",
626
+ job_url: str = "",
627
+ component: str = "",
628
+ ) -> str:
498
629
  jenkins_cfg = (cfg.get("jenkins") or {})
499
630
  explicit_url = str(job_url or "").strip()
500
631
  requested_name = str(job_name or "").strip()
501
- configured_url = str(jenkins_cfg.get("job_url") or "").strip()
502
- base_url = str(jenkins_cfg.get("base_url") or "").strip()
632
+ configured_url = (
633
+ _text(_jenkins_access_cfg(cfg, component).get("url"))
634
+ if component
635
+ else str(jenkins_cfg.get("job_url") or "").strip()
636
+ )
637
+ base_url = _jenkins_root_url(cfg, component=component)
503
638
 
504
639
  if explicit_url:
505
640
  return explicit_url.rstrip("/")
@@ -508,13 +643,13 @@ def _resolve_jenkins_job_url(cfg: dict, job_name: str = "", job_url: str = "") -
508
643
  return _jenkins_job_url_from_name(base_url, requested_name)
509
644
  raise APError(
510
645
  f"Cannot resolve Jenkins job URL for job '{requested_name}'. "
511
- "Pass --job-url, or fill jenkins.base_url in docs/ENGINEERING.md."
646
+ "Pass --job-url, or fill the selected Jenkins endpoint in docs/ENGINEERING.md."
512
647
  )
513
648
  if configured_url:
514
649
  return configured_url.rstrip("/")
515
650
  raise APError(
516
- "Missing Jenkins job location. Fill jenkins.job_url in docs/ENGINEERING.md, "
517
- "or pass --job-url / --job-name explicitly."
651
+ "Missing Jenkins job location. Fill access.jenkins.<component>.url or "
652
+ "legacy jenkins.job_url, or pass --job-url / --job-name explicitly."
518
653
  )
519
654
 
520
655
 
@@ -526,6 +661,7 @@ def _resolve_jenkins_job_candidates(
526
661
  job_url: str = "",
527
662
  multibranch_root_job: str = "",
528
663
  branch_name: str = "",
664
+ component: str = "",
529
665
  ) -> List[str]:
530
666
  jenkins_cfg = (cfg.get("jenkins") or {})
531
667
  effective_branch = str(branch_name or "").strip()
@@ -537,25 +673,36 @@ def _resolve_jenkins_job_candidates(
537
673
 
538
674
  explicit_url = str(job_url or "").strip()
539
675
  explicit_name = str(job_name or "").strip()
540
- configured_url = str(jenkins_cfg.get("job_url") or "").strip()
676
+ configured_url = (
677
+ _text(_jenkins_access_cfg(cfg, component).get("url"))
678
+ if component
679
+ else str(jenkins_cfg.get("job_url") or "").strip()
680
+ )
541
681
 
542
682
  if effective_branch:
543
683
  if explicit_url:
544
684
  return _jenkins_branch_job_urls(explicit_url, effective_branch)
545
685
  if effective_root:
546
- base_url = str(jenkins_cfg.get("base_url") or "").strip()
686
+ base_url = _jenkins_root_url(cfg, component=component)
547
687
  return _jenkins_branch_job_urls(_jenkins_job_url_from_name(base_url, effective_root), effective_branch)
548
688
  if explicit_name:
549
- base_url = str(jenkins_cfg.get("base_url") or "").strip()
689
+ base_url = _jenkins_root_url(cfg, component=component)
550
690
  return _jenkins_branch_job_urls(_jenkins_job_url_from_name(base_url, explicit_name), effective_branch)
551
691
  if configured_url:
552
692
  return _jenkins_branch_job_urls(configured_url, effective_branch)
553
693
  raise APError(
554
694
  "Missing Jenkins multibranch root job location. Pass --job-url / --job-name together with "
555
- "--branch-name, or pass --multibranch-root-job with jenkins.base_url."
695
+ "--branch-name, or pass --multibranch-root-job with a configured Jenkins endpoint."
556
696
  )
557
697
 
558
- return [_resolve_jenkins_job_url(cfg, job_name=job_name, job_url=job_url)]
698
+ return [
699
+ _resolve_jenkins_job_url(
700
+ cfg,
701
+ job_name=job_name,
702
+ job_url=job_url,
703
+ component=component,
704
+ )
705
+ ]
559
706
 
560
707
 
561
708
  def _jenkins_build_api_url(job_url: str, build_number: int) -> str:
@@ -785,7 +932,14 @@ def _converged_engineering_document(repo: Path, template_path: Path) -> str:
785
932
  ("concurrency", "delete_remote_branch"),
786
933
  ("validation", "max_command_seconds"),
787
934
  ("validation", "max_total_seconds"),
935
+ ("structure", "enabled"),
936
+ ("structure", "enforcement"),
788
937
  ("structure", "architecture_standard"),
938
+ ("structure", "layer_rules", "enabled"),
939
+ ("structure", "layer_rules", "block"),
940
+ ("optimization", "completion_policy"),
941
+ ("optimization", "require_baseline_for_global_review"),
942
+ ("optimization", "report_accepted_debt_as_findings"),
789
943
  ("docs", "api_docs_required"),
790
944
  ]
791
945
  for field_path in preserve_scalar_paths:
@@ -823,6 +977,22 @@ def _converged_engineering_document(repo: Path, template_path: Path) -> str:
823
977
  _mapping(current_cfg.get("risk")).get("rules")
824
978
  )
825
979
  current_structure = _mapping(current_cfg.get("structure"))
980
+ for key in ("exclude", "allow_large_files", "reusable_tool_dirs"):
981
+ if isinstance(current_structure.get(key), list):
982
+ converged["structure"][key] = _string_list(current_structure.get(key))
983
+ for key in (
984
+ "max_file_lines_warn",
985
+ "max_file_lines_block",
986
+ "max_function_lines_warn",
987
+ "max_added_lines_to_large_file",
988
+ ):
989
+ value = current_structure.get(key)
990
+ if isinstance(value, int) and not isinstance(value, bool):
991
+ converged["structure"][key] = value
992
+ for key in ("require_reuse_search", "block_new_responsibility_in_large_file"):
993
+ value = current_structure.get(key)
994
+ if isinstance(value, bool):
995
+ converged["structure"][key] = value
826
996
  converged["structure"]["accepted_debt_paths"] = _string_list(
827
997
  current_structure.get("accepted_debt_paths")
828
998
  )
@@ -973,8 +1143,8 @@ def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
973
1143
  if _text(workflow_cfg.get("completion")).lower() != "push":
974
1144
  workflow_cfg["completion"] = "push"
975
1145
  changed.append("workflow.completion")
976
- if _text(workflow_cfg.get("skill_version")) != "4.2.1":
977
- workflow_cfg["skill_version"] = "4.2.1"
1146
+ if _text(workflow_cfg.get("skill_version")) != "4.2.2":
1147
+ workflow_cfg["skill_version"] = "4.2.2"
978
1148
  changed.append("workflow.skill_version")
979
1149
 
980
1150
  commands_cfg = cfg.setdefault("commands", {})
@@ -1287,16 +1457,16 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1287
1457
  if current_agents:
1288
1458
  archive_dir = repo / "docs" / "archive" / "workflow"
1289
1459
  archive_header = (
1290
- "# Archived AGENTS.md before auto-coding-skill 4.2.1\n\n"
1460
+ "# Archived AGENTS.md before auto-coding-skill 4.2.2\n\n"
1291
1461
  "This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
1292
1462
  "Move any still-current project facts into docs/ENGINEERING.md or docs/project/,\n"
1293
1463
  "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
1294
1464
  )
1295
1465
  archive_content = archive_header + current_agents
1296
- archive = archive_dir / "AGENTS.pre-4.2.1.md"
1466
+ archive = archive_dir / "AGENTS.pre-4.2.2.md"
1297
1467
  if archive.exists() and archive.read_text(encoding="utf-8") != archive_content:
1298
1468
  digest = hashlib.sha256(current_agents.encode("utf-8")).hexdigest()[:12]
1299
- archive = archive_dir / f"AGENTS.pre-4.2.1-{digest}.md"
1469
+ archive = archive_dir / f"AGENTS.pre-4.2.2-{digest}.md"
1300
1470
  if not archive.exists():
1301
1471
  add_action("policy", archive, "archive", "historical and non-authoritative")
1302
1472
  if write:
@@ -2342,6 +2512,7 @@ def _validate_task_manifest(repo: Path, manifest: dict, expected_task_id: str =
2342
2512
  "pending",
2343
2513
  "approved",
2344
2514
  "changes-requested",
2515
+ "blocked",
2345
2516
  }:
2346
2517
  raise APError(f"Task {task_id} has an invalid review contract.")
2347
2518
  review_required = manifest.get("review_required", schema < 3)
@@ -2356,6 +2527,13 @@ def _validate_task_manifest(repo: Path, manifest: dict, expected_task_id: str =
2356
2527
  effective_profile = _text(manifest.get("effective_profile"))
2357
2528
  if effective_profile and effective_profile not in (_WORKFLOW_PROFILES - {"auto"}):
2358
2529
  raise APError(f"Task {task_id} has an invalid effective_profile.")
2530
+ review_depth = _text(manifest.get("review_depth"))
2531
+ if review_depth and review_depth not in {"none", "focused", "deep"}:
2532
+ raise APError(f"Task {task_id} has an invalid review_depth.")
2533
+ if "review_timeout_seconds" in manifest:
2534
+ timeout_value = manifest.get("review_timeout_seconds")
2535
+ if isinstance(timeout_value, bool) or not isinstance(timeout_value, int) or timeout_value < 0:
2536
+ raise APError(f"Task {task_id} has an invalid review_timeout_seconds.")
2359
2537
  if "design_required" in manifest and not isinstance(manifest.get("design_required"), bool):
2360
2538
  raise APError(f"Task {task_id} has an invalid design_required flag.")
2361
2539
  if "scope_history" in manifest and not isinstance(manifest.get("scope_history"), list):
@@ -3004,16 +3182,25 @@ def _reconcile_task_risk(repo: Path, cfg: dict, manifest: dict) -> None:
3004
3182
  )
3005
3183
  review_required = bool(manifest.get("review_required") or plan.get("review_required"))
3006
3184
  design_required = bool(manifest.get("design_required") or plan.get("design_required"))
3185
+ review_depth, review_timeout_seconds = _normalized_task_review_policy(
3186
+ review_required,
3187
+ manifest.get("review_depth"),
3188
+ plan.get("review_depth"),
3189
+ )
3007
3190
  escalated = (
3008
3191
  effective_profile != old_profile
3009
3192
  or review_required != bool(manifest.get("review_required"))
3010
3193
  or design_required != bool(manifest.get("design_required"))
3194
+ or review_depth != (_text(manifest.get("review_depth")) or "none")
3195
+ or review_timeout_seconds != int(manifest.get("review_timeout_seconds") or 0)
3011
3196
  )
3012
3197
  if not escalated:
3013
3198
  return
3014
3199
  manifest["effective_profile"] = effective_profile
3015
3200
  manifest["review_required"] = review_required
3016
3201
  manifest["design_required"] = design_required
3202
+ manifest["review_depth"] = review_depth
3203
+ manifest["review_timeout_seconds"] = review_timeout_seconds
3017
3204
  _invalidate_task_review(manifest, "actual changed paths raised task risk; review again")
3018
3205
  _clear_final_gate_receipt(repo)
3019
3206
  _save_task_manifest(repo, manifest)
@@ -3271,6 +3458,8 @@ _DEFAULT_FULL_PATH_PATTERNS = [
3271
3458
  "compose*.yaml",
3272
3459
  "docs/ENGINEERING.md",
3273
3460
  "docs/tools/autopipeline/**",
3461
+ "package.json",
3462
+ "**/package.json",
3274
3463
  "package-lock.json",
3275
3464
  "pnpm-lock.yaml",
3276
3465
  "yarn.lock",
@@ -3689,6 +3878,25 @@ def _select_gate_scope(cfg: dict, requested_scope: str, paths: list[str]) -> tup
3689
3878
  return "changed", [reason], matching_rules
3690
3879
 
3691
3880
 
3881
+ def _select_structure_scope(
3882
+ cfg: dict,
3883
+ repo: Path,
3884
+ requested_scope: str,
3885
+ base_ref: str,
3886
+ ) -> str:
3887
+ """Keep repository-wide structure scans explicit while honoring them."""
3888
+ requested = _text(requested_scope).lower()
3889
+ if requested == "full":
3890
+ return "full"
3891
+ impact = _impact_summary(
3892
+ cfg,
3893
+ repo,
3894
+ requested_scope=requested,
3895
+ base_ref=base_ref,
3896
+ )
3897
+ return str(impact["selected_scope"])
3898
+
3899
+
3692
3900
  def _impact_summary(
3693
3901
  cfg: dict,
3694
3902
  repo: Path,
@@ -4078,10 +4286,17 @@ def _is_structure_candidate(path: str, structure_cfg: dict) -> bool:
4078
4286
 
4079
4287
  def _structure_paths_for_scope(repo: Path, scope: str, base_ref: str, structure_cfg: dict) -> list[str]:
4080
4288
  if scope == "full":
4081
- paths = _tracked_files(repo)
4289
+ paths = _unique_paths(
4290
+ _tracked_files(repo)
4291
+ + _git_lines(repo, ["git", "ls-files", "--others", "--exclude-standard"])
4292
+ )
4082
4293
  else:
4083
4294
  paths = _changed_files(repo, base_ref=base_ref)
4084
- return [path for path in paths if _is_structure_candidate(path, structure_cfg)]
4295
+ return [
4296
+ path
4297
+ for path in paths
4298
+ if (repo / path).is_file() and _is_structure_candidate(path, structure_cfg)
4299
+ ]
4085
4300
 
4086
4301
 
4087
4302
  def _read_text_lines(repo: Path, path: str) -> Optional[list[str]]:
@@ -4797,9 +5012,8 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
4797
5012
  ensure_git_repo(repo)
4798
5013
  cfg = _load_cfg(repo)
4799
5014
  requested_scope = str(getattr(args, "scope", "") or "").strip().lower()
4800
- impact = _impact_summary(cfg, repo, requested_scope=requested_scope, base_ref=str(getattr(args, "base", "") or ""))
4801
- selected_scope = str(impact["selected_scope"])
4802
5015
  base_ref = str(getattr(args, "base", "") or "")
5016
+ selected_scope = _select_structure_scope(cfg, repo, requested_scope, base_ref)
4803
5017
 
4804
5018
  structure_cfg = _structure_cfg(cfg)
4805
5019
  optimization_cfg = _optimization_cfg(cfg)
@@ -4896,11 +5110,25 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
4896
5110
  print(f"[structure-check] OK scope={selected_scope} inspected={inspected} warnings={len(warnings)}")
4897
5111
 
4898
5112
 
4899
- def _run_structure_check_for_gate(repo: Path, cfg: dict, selected_scope: str, base_ref: str) -> list[str]:
5113
+ def _run_structure_check_for_gate(
5114
+ repo: Path,
5115
+ cfg: dict,
5116
+ selected_scope: str,
5117
+ base_ref: str,
5118
+ *,
5119
+ deadline: Optional[float] = None,
5120
+ command_timeout_s: Optional[float] = None,
5121
+ ) -> list[str]:
4900
5122
  if not _structure_gate_enabled(cfg):
4901
5123
  return []
4902
5124
  if _configured_command(cfg, "structure_check"):
4903
- _run_configured_command(repo, cfg, "structure_check")
5125
+ timeout_s = command_timeout_s
5126
+ if deadline is not None:
5127
+ remaining = deadline - time.monotonic()
5128
+ if remaining <= 0:
5129
+ raise APError("Final changed-scope gate budget exhausted before structure check.")
5130
+ timeout_s = min(timeout_s, remaining) if timeout_s is not None else remaining
5131
+ _run_configured_command(repo, cfg, "structure_check", timeout_s=timeout_s)
4904
5132
  return ["structure_check"]
4905
5133
  cmd_structure_check(
4906
5134
  argparse.Namespace(
@@ -5535,6 +5763,11 @@ def _agent_contract_shape() -> tuple[dict, list[str]]:
5535
5763
  "diff_head",
5536
5764
  "diff_fingerprint",
5537
5765
  "owning_fixer",
5766
+ "review_depth",
5767
+ "timeout_seconds",
5768
+ "issued_at",
5769
+ "deadline_at",
5770
+ "scope_revision",
5538
5771
  ],
5539
5772
  },
5540
5773
  [
@@ -5644,6 +5877,12 @@ def _contract_validation_errors(
5644
5877
  if pattern and not re.search(str(pattern), value):
5645
5878
  errors.append(f"{path}: string does not match {pattern!r}")
5646
5879
 
5880
+ if isinstance(value, (int, float)) and not isinstance(value, bool):
5881
+ if "minimum" in fragment and value < fragment["minimum"]:
5882
+ errors.append(f"{path}: number is below minimum {fragment['minimum']}")
5883
+ if "maximum" in fragment and value > fragment["maximum"]:
5884
+ errors.append(f"{path}: number exceeds maximum {fragment['maximum']}")
5885
+
5647
5886
  if isinstance(value, list):
5648
5887
  if "maxItems" in fragment and len(value) > int(fragment["maxItems"]):
5649
5888
  errors.append(f"{path}: too many array items")
@@ -5701,6 +5940,31 @@ def _validate_orchestration_contract(kind: str, payload: dict) -> dict:
5701
5940
  if kind == "assignment" and role == "reviewer":
5702
5941
  if _text(payload.get("node_id")) == _text(payload.get("owning_fixer")):
5703
5942
  errors.append("$.node_id: reviewer must differ from owning_fixer")
5943
+ timing_fields = ("issued_at", "deadline_at", "timeout_seconds")
5944
+ timing_values = [payload.get(field) for field in timing_fields]
5945
+ if any(value is not None for value in timing_values):
5946
+ if not all(value is not None for value in timing_values):
5947
+ errors.append("$: reviewer timing fields must be supplied together")
5948
+ else:
5949
+ try:
5950
+ issued_at = _parse_iso_timestamp(payload.get("issued_at"), "issued_at")
5951
+ deadline_at = _parse_iso_timestamp(payload.get("deadline_at"), "deadline_at")
5952
+ timeout_seconds = int(payload.get("timeout_seconds"))
5953
+ expected_timeout = {
5954
+ "focused": _FOCUSED_REVIEW_TIMEOUT_SECONDS,
5955
+ "deep": _DEEP_REVIEW_TIMEOUT_SECONDS,
5956
+ }.get(_text(payload.get("review_depth")))
5957
+ if expected_timeout is not None and timeout_seconds != expected_timeout:
5958
+ errors.append(
5959
+ "$.timeout_seconds: must match the fixed "
5960
+ f"{_text(payload.get('review_depth'))} review budget {expected_timeout}"
5961
+ )
5962
+ if deadline_at <= issued_at:
5963
+ errors.append("$.deadline_at: must be after issued_at")
5964
+ elif int((deadline_at - issued_at).total_seconds()) != timeout_seconds:
5965
+ errors.append("$.deadline_at: interval must equal timeout_seconds")
5966
+ except (APError, TypeError, ValueError) as exc:
5967
+ errors.append(f"$: invalid reviewer timing contract: {exc}")
5704
5968
  if kind == "result":
5705
5969
  owned_paths = payload.get("owned_paths")
5706
5970
  changed_paths = payload.get("changed_paths")
@@ -5774,6 +6038,165 @@ def _reviewer_result_template(assignment: dict, verdict: str) -> dict:
5774
6038
  return _validate_orchestration_contract("result", result)
5775
6039
 
5776
6040
 
6041
+ def _normalize_reviewer_runtime_result(assignment: dict, payload: dict) -> dict:
6042
+ """Normalize presentation fields while refusing assignment-binding spoofing."""
6043
+ if not isinstance(payload, dict):
6044
+ raise APError("Reviewer runtime output must be one JSON object.")
6045
+ verdict = _text(payload.get("verdict")).lower()
6046
+ if verdict not in {"approved", "changes-requested", "blocked"}:
6047
+ raise APError(
6048
+ "Reviewer runtime output must include verdict=approved, changes-requested, or blocked."
6049
+ )
6050
+ result = _reviewer_result_template(assignment, verdict)
6051
+ binding_fields = {
6052
+ "contract_version": result["contract_version"],
6053
+ "node_id": result["node_id"],
6054
+ "role": result["role"],
6055
+ "task_id": result["task_id"],
6056
+ "base_sha": result["base_sha"],
6057
+ "diff_fingerprint": result["diff_fingerprint"],
6058
+ }
6059
+ mismatched = [
6060
+ field
6061
+ for field, expected in binding_fields.items()
6062
+ if field in payload and payload.get(field) != expected
6063
+ ]
6064
+ if mismatched:
6065
+ raise APError(
6066
+ "Reviewer runtime result does not match its assignment: "
6067
+ + ", ".join(mismatched)
6068
+ )
6069
+ if "summary" in payload:
6070
+ if not isinstance(payload["summary"], str):
6071
+ raise APError("Reviewer runtime result summary must be a string.")
6072
+ result["summary"] = payload["summary"]
6073
+ for field in ("evidence", "findings", "risks"):
6074
+ if field not in payload:
6075
+ continue
6076
+ value = payload[field]
6077
+ if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
6078
+ raise APError(f"Reviewer runtime result {field} must be an array of strings.")
6079
+ result[field] = value
6080
+ return _validate_orchestration_contract("result", result)
6081
+
6082
+
6083
+ def _reviewer_agent_instructions(worktree: Path) -> str:
6084
+ candidates = [
6085
+ worktree / ".agents" / "agents" / "reviewer.toml",
6086
+ _skill_root().parent.parent / "agents" / "reviewer.toml",
6087
+ ]
6088
+ for path in candidates:
6089
+ try:
6090
+ payload = tomllib.loads(path.read_text(encoding="utf-8"))
6091
+ except FileNotFoundError:
6092
+ continue
6093
+ except (OSError, tomllib.TOMLDecodeError) as exc:
6094
+ raise APError(f"Cannot load managed Reviewer Agent config: {path}: {exc}") from exc
6095
+ instructions = _text(payload.get("developer_instructions"))
6096
+ if instructions:
6097
+ return instructions
6098
+ return (
6099
+ "Act as an independent read-only code reviewer. Review only the supplied "
6100
+ "assignment and return one JSON object with an approved, changes-requested, "
6101
+ "or blocked verdict. Do not modify files."
6102
+ )
6103
+
6104
+
6105
+ def _codex_reviewer_command(
6106
+ worktree: Path,
6107
+ assignment_path: Path,
6108
+ result_path: Path,
6109
+ ) -> list[str]:
6110
+ codex = shutil.which("codex")
6111
+ if not codex:
6112
+ raise APError(
6113
+ "The supervised Reviewer runtime requires the Codex CLI on PATH. "
6114
+ "Install Codex or run review-assignment and use another deadline-capable host."
6115
+ )
6116
+ instructions = _reviewer_agent_instructions(worktree)
6117
+ prompt = (
6118
+ f"Review the exact assignment at {assignment_path}. "
6119
+ "Stay inside its diff, identity, and deadline. Use "
6120
+ "`python3 docs/tools/autopipeline/ap.py agent-result-template --file "
6121
+ f"{assignment_path} --verdict <approved|changes-requested|blocked>` when useful. "
6122
+ "Return only one JSON object as the final response; do not modify files."
6123
+ )
6124
+ return [
6125
+ codex,
6126
+ "-a",
6127
+ "never",
6128
+ "exec",
6129
+ "--ephemeral",
6130
+ "--ignore-user-config",
6131
+ "-C",
6132
+ str(worktree),
6133
+ "-s",
6134
+ "read-only",
6135
+ "-c",
6136
+ 'model_reasoning_effort="xhigh"',
6137
+ "-c",
6138
+ "developer_instructions=" + json.dumps(instructions, ensure_ascii=False),
6139
+ "-o",
6140
+ str(result_path),
6141
+ prompt,
6142
+ ]
6143
+
6144
+
6145
+ def _terminate_reviewer_process(process: subprocess.Popen[str]) -> tuple[str, str]:
6146
+ if process.poll() is None:
6147
+ try:
6148
+ if os.name == "posix":
6149
+ os.killpg(process.pid, signal.SIGTERM)
6150
+ else:
6151
+ process.terminate()
6152
+ except ProcessLookupError:
6153
+ pass
6154
+ try:
6155
+ stdout, stderr = process.communicate(timeout=2)
6156
+ except subprocess.TimeoutExpired:
6157
+ try:
6158
+ if os.name == "posix":
6159
+ os.killpg(process.pid, signal.SIGKILL)
6160
+ else:
6161
+ process.kill()
6162
+ except ProcessLookupError:
6163
+ pass
6164
+ stdout, stderr = process.communicate()
6165
+ return stdout or "", stderr or ""
6166
+
6167
+
6168
+ def _run_supervised_reviewer_process(
6169
+ command: list[str],
6170
+ *,
6171
+ cwd: Path,
6172
+ env: dict[str, str],
6173
+ timeout_seconds: float,
6174
+ ) -> subprocess.CompletedProcess[str]:
6175
+ if timeout_seconds <= 0:
6176
+ raise _ReviewerRuntimeTimeout()
6177
+ process = subprocess.Popen(
6178
+ command,
6179
+ cwd=str(cwd),
6180
+ env=env,
6181
+ stdin=subprocess.DEVNULL,
6182
+ stdout=subprocess.PIPE,
6183
+ stderr=subprocess.PIPE,
6184
+ text=True,
6185
+ start_new_session=True,
6186
+ )
6187
+ try:
6188
+ stdout, stderr = process.communicate(timeout=timeout_seconds)
6189
+ except subprocess.TimeoutExpired as exc:
6190
+ stdout, stderr = _terminate_reviewer_process(process)
6191
+ raise _ReviewerRuntimeTimeout(stdout, stderr) from exc
6192
+ return subprocess.CompletedProcess(
6193
+ command,
6194
+ int(process.returncode or 0),
6195
+ stdout or "",
6196
+ stderr or "",
6197
+ )
6198
+
6199
+
5777
6200
  def _validate_agent_plan(plan: dict) -> dict:
5778
6201
  required = {
5779
6202
  "contract_version",
@@ -5822,6 +6245,24 @@ def _review_execution_policy(
5822
6245
  }
5823
6246
 
5824
6247
 
6248
+ def _normalized_task_review_policy(
6249
+ review_required: bool,
6250
+ *depth_candidates: object,
6251
+ ) -> tuple[str, int]:
6252
+ if not review_required:
6253
+ return "none", 0
6254
+ depth_rank = {"none": 0, "focused": 1, "deep": 2}
6255
+ depth = "focused"
6256
+ for candidate in depth_candidates:
6257
+ normalized = _text(candidate).lower()
6258
+ if depth_rank.get(normalized, 0) > depth_rank[depth]:
6259
+ depth = normalized
6260
+ timeout_seconds = (
6261
+ _DEEP_REVIEW_TIMEOUT_SECONDS if depth == "deep" else _FOCUSED_REVIEW_TIMEOUT_SECONDS
6262
+ )
6263
+ return depth, timeout_seconds
6264
+
6265
+
5825
6266
  def _agent_execution_plan(
5826
6267
  profile: str,
5827
6268
  categories: set[str],
@@ -6531,6 +6972,16 @@ def cmd_light_gate(args: argparse.Namespace) -> None:
6531
6972
  deadline=deadline,
6532
6973
  command_timeout_s=budget["command_seconds"],
6533
6974
  )
6975
+ executed.extend(
6976
+ _run_structure_check_for_gate(
6977
+ repo,
6978
+ cfg,
6979
+ selected_scope,
6980
+ _text(getattr(args, "base", "")),
6981
+ deadline=deadline,
6982
+ command_timeout_s=budget["command_seconds"],
6983
+ )
6984
+ )
6534
6985
 
6535
6986
  _run_git_diff_check(repo, cfg)
6536
6987
  if time.monotonic() > deadline:
@@ -6612,25 +7063,30 @@ def cmd_runtime_down(args: argparse.Namespace) -> None:
6612
7063
  print("[runtime-down] OK")
6613
7064
 
6614
7065
 
6615
- def cmd_wait_health(args: argparse.Namespace) -> None:
6616
- repo = Path(args.repo).resolve()
6617
- cfg = _load_cfg(repo)
6618
- scope = args.scope
6619
- if scope == "runtime":
6620
- runtime_cfg = (cfg.get("runtime") or {})
6621
- url = _join_url(str(runtime_cfg.get("health_base_url") or ""), str(runtime_cfg.get("health_path") or ""))
6622
- timeout_s = int(runtime_cfg.get("startup_timeout_sec") or 120)
6623
- else:
6624
- target_cfg = (cfg.get("target_env") or {})
6625
- jenkins_cfg = (cfg.get("jenkins") or {})
6626
- base_url = str(target_cfg.get("health_base_url") or "")
6627
- path = str(target_cfg.get("health_path") or "")
6628
- url = _join_url(
6629
- base_url,
6630
- path,
6631
- )
6632
- timeout_s = int(jenkins_cfg.get("deploy_timeout_sec") or 1800)
7066
+ def _target_endpoint_config(
7067
+ cfg: dict,
7068
+ component: str,
7069
+ ) -> tuple[str, dict, str, str, str]:
7070
+ access = cfg.get("access") or {}
7071
+ project = access.get("project") or {}
7072
+ lane = project.get(component) or {}
7073
+ if isinstance(lane, dict) and any(_is_explicit_fill(value) for value in lane.values()):
7074
+ base_url = _require_http_url(f"access.project.{component}.url", lane.get("url"))
7075
+ return f"access.project.{component}", lane, base_url, "username", "password"
7076
+ legacy = cfg.get("target_env") or {}
7077
+ base_field = f"{component}_base_url"
7078
+ base_url = _require_http_url(f"target_env.{base_field}", legacy.get(base_field))
7079
+ return (
7080
+ "target_env",
7081
+ legacy,
7082
+ base_url,
7083
+ f"{component}_username",
7084
+ f"{component}_password",
7085
+ )
7086
+
6633
7087
 
7088
+ def _wait_for_health_url(scope: str, url: str, timeout_s: int) -> None:
7089
+ _require_http_url(f"{scope} health URL", url)
6634
7090
  deadline = time.time() + timeout_s
6635
7091
  last_error = "(none)"
6636
7092
  while time.time() < deadline:
@@ -6646,50 +7102,94 @@ def cmd_wait_health(args: argparse.Namespace) -> None:
6646
7102
  raise APError(f"Health check timeout for {scope}: {url}\nLast result: {last_error}")
6647
7103
 
6648
7104
 
7105
+ def cmd_wait_health(args: argparse.Namespace) -> None:
7106
+ repo = Path(args.repo).resolve()
7107
+ cfg = _load_cfg(repo)
7108
+ scope = args.scope
7109
+ requested_timeout = int(getattr(args, "timeout_sec", 0) or 0)
7110
+ if scope == "runtime":
7111
+ runtime_cfg = cfg.get("runtime") or {}
7112
+ base_url = _require_http_url("runtime.health_base_url", runtime_cfg.get("health_base_url"))
7113
+ url = _join_url(base_url, runtime_cfg.get("health_path"))
7114
+ timeout_s = requested_timeout or int(runtime_cfg.get("startup_timeout_sec") or 120)
7115
+ else:
7116
+ target_cfg = cfg.get("target_env") or {}
7117
+ explicit_path = _text(getattr(args, "path", ""))
7118
+ legacy_base = _text(target_cfg.get("health_base_url"))
7119
+ legacy_path = _text(target_cfg.get("health_path"))
7120
+ if explicit_path:
7121
+ component = _text(getattr(args, "component", "")) or "backend"
7122
+ _, _, base_url, _, _ = _target_endpoint_config(cfg, component)
7123
+ url = _join_url(base_url, explicit_path)
7124
+ elif legacy_base and legacy_path:
7125
+ base_url = _require_http_url("target_env.health_base_url", legacy_base)
7126
+ url = _join_url(base_url, legacy_path)
7127
+ else:
7128
+ raise APError(
7129
+ "Target health check requires --component and --path for access.project, "
7130
+ "or legacy target_env.health_base_url plus target_env.health_path."
7131
+ )
7132
+ timeout_s = requested_timeout or int((cfg.get("jenkins") or {}).get("deploy_timeout_sec") or 120)
7133
+ _wait_for_health_url(scope, url, timeout_s)
7134
+
7135
+
6649
7136
  def cmd_verify_target(args: argparse.Namespace) -> None:
6650
7137
  repo = Path(args.repo).resolve()
6651
7138
  cfg = _load_cfg(repo)
6652
- target_cfg = (cfg.get("target_env") or {})
7139
+ requested = {
7140
+ "backend": list(args.backend_path or []),
7141
+ "frontend": list(args.frontend_path or []),
7142
+ }
7143
+ target_cfg = cfg.get("target_env") or {}
7144
+ legacy_health_base = _text(target_cfg.get("health_base_url"))
7145
+ legacy_health_path = _text(target_cfg.get("health_path"))
7146
+ if not any(requested.values()) and not (legacy_health_base and legacy_health_path):
7147
+ raise APError(
7148
+ "verify-target requires --backend-path or --frontend-path when no legacy target health check is configured."
7149
+ )
7150
+
7151
+ planned_checks: list[tuple[str, str, dict[str, str]]] = []
7152
+ for component in ("backend", "frontend"):
7153
+ paths = requested[component]
7154
+ if not paths:
7155
+ continue
7156
+ section_name, section_cfg, base_url, user_field, secret_field = _target_endpoint_config(
7157
+ cfg,
7158
+ component,
7159
+ )
7160
+ headers: dict[str, str] = {}
7161
+ if bool(getattr(args, f"{component}_basic_auth")):
7162
+ username = _text(section_cfg.get(user_field))
7163
+ if not _is_explicit_fill(username):
7164
+ raise APError(f"Missing {section_name}.{user_field} for basic auth.")
7165
+ password = _resolve_secret(section_name, section_cfg, secret_field)
7166
+ headers = _basic_auth_header(username, password)
7167
+ for path in paths:
7168
+ url = _join_url(base_url, path)
7169
+ _require_http_url(f"{component} target URL", url)
7170
+ planned_checks.append((component, url, headers))
7171
+
7172
+ health_url = ""
7173
+ if legacy_health_base or legacy_health_path:
7174
+ if not (legacy_health_base and legacy_health_path):
7175
+ raise APError(
7176
+ "Legacy target health config requires both target_env.health_base_url and target_env.health_path."
7177
+ )
7178
+ health_base = _require_http_url("target_env.health_base_url", legacy_health_base)
7179
+ health_url = _join_url(health_base, legacy_health_path)
6653
7180
 
6654
- cmd_wait_health(argparse.Namespace(repo=str(repo), scope="target"))
7181
+ if health_url:
7182
+ timeout_s = int((cfg.get("jenkins") or {}).get("deploy_timeout_sec") or 120)
7183
+ _wait_for_health_url("target", health_url, timeout_s)
6655
7184
 
6656
7185
  checks: List[str] = []
6657
-
6658
- backend_base = str(target_cfg.get("backend_base_url") or "").strip().rstrip("/")
6659
- frontend_base = str(target_cfg.get("frontend_base_url") or "").strip().rstrip("/")
6660
-
6661
- backend_headers: dict[str, str] = {}
6662
- frontend_headers: dict[str, str] = {}
6663
- if args.backend_basic_auth:
6664
- user = str(target_cfg.get("backend_username") or "").strip()
6665
- if not user:
6666
- raise APError("Missing target_env.backend_username for backend basic auth.")
6667
- password = _resolve_secret("target_env", target_cfg, "backend_password")
6668
- backend_headers = _basic_auth_header(user, password)
6669
- if args.frontend_basic_auth:
6670
- user = str(target_cfg.get("frontend_username") or "").strip()
6671
- if not user:
6672
- raise APError("Missing target_env.frontend_username for frontend basic auth.")
6673
- password = _resolve_secret("target_env", target_cfg, "frontend_password")
6674
- frontend_headers = _basic_auth_header(user, password)
6675
-
6676
- for path in args.backend_path or []:
6677
- if not backend_base:
6678
- raise APError("Missing target_env.backend_base_url for backend path verification.")
6679
- url = _join_url(backend_base, path)
6680
- status, body = _http_get(url, headers=backend_headers, timeout_s=10)
6681
- if not (200 <= status < 400):
6682
- raise APError(f"Backend target verification failed: {url} -> {status}\n{body[:400]}")
6683
- checks.append(f"backend:{url}->{status}")
6684
-
6685
- for path in args.frontend_path or []:
6686
- if not frontend_base:
6687
- raise APError("Missing target_env.frontend_base_url for frontend path verification.")
6688
- url = _join_url(frontend_base, path)
6689
- status, body = _http_get(url, headers=frontend_headers, timeout_s=10)
7186
+ for component, url, headers in planned_checks:
7187
+ status, body = _http_get(url, headers=headers, timeout_s=10)
6690
7188
  if not (200 <= status < 400):
6691
- raise APError(f"Frontend target verification failed: {url} -> {status}\n{body[:400]}")
6692
- checks.append(f"frontend:{url}->{status}")
7189
+ raise APError(
7190
+ f"{component.title()} target verification failed: {url} -> {status}\n{body[:400]}"
7191
+ )
7192
+ checks.append(f"{component}:{url}->{status}")
6693
7193
 
6694
7194
  summary = ", ".join(checks) if checks else "health-only"
6695
7195
  _record_evidence(repo, cfg, "verify_target", "pass", {"summary": summary, "checks": checks})
@@ -6707,6 +7207,28 @@ def cmd_verify_jenkins(args: argparse.Namespace) -> None:
6707
7207
  if not jenkinsfile.exists():
6708
7208
  raise APError(f"Jenkinsfile not found: {jenkinsfile}")
6709
7209
 
7210
+ configured_components = _configured_jenkins_components(cfg)
7211
+ if configured_components:
7212
+ requested = _text(getattr(args, "component", "all")).lower() or "all"
7213
+ selected = ("frontend", "backend") if requested == "all" else (requested,)
7214
+ checked: list[str] = []
7215
+ for component in selected:
7216
+ lane = _jenkins_access_cfg(cfg, component)
7217
+ _require_http_url(f"access.jenkins.{component}.url", lane.get("url"))
7218
+ if not _is_explicit_fill(lane.get("username")):
7219
+ raise APError(f"Missing access.jenkins.{component}.username.")
7220
+ _resolve_secret(f"access.jenkins.{component}", lane, "password")
7221
+ checked.append(component)
7222
+ _record_evidence(
7223
+ repo,
7224
+ cfg,
7225
+ "verify_jenkins",
7226
+ "pass",
7227
+ {"jenkinsfile": str(jenkinsfile), "components": checked},
7228
+ )
7229
+ print(f"[verify-jenkins] OK: {jenkinsfile} components={','.join(checked)}")
7230
+ return
7231
+
6710
7232
  required = [
6711
7233
  ("jenkins.base_url", jenkins_cfg.get("base_url")),
6712
7234
  ("jenkins.job_url", jenkins_cfg.get("job_url")),
@@ -6963,6 +7485,16 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
6963
7485
  repo = Path(args.repo).resolve()
6964
7486
  cfg = _load_cfg(repo)
6965
7487
  jenkins_cfg = (cfg.get("jenkins") or {})
7488
+ component = _resolve_jenkins_component(
7489
+ cfg,
7490
+ _text(getattr(args, "component", "")),
7491
+ _text(args.job_url),
7492
+ )
7493
+ if component:
7494
+ lane = _jenkins_access_cfg(cfg, component)
7495
+ _require_http_url(f"access.jenkins.{component}.url", lane.get("url"))
7496
+ _jenkins_auth_config(cfg, component)
7497
+ _resolve_secret(f"access.jenkins.{component}", lane, "password")
6966
7498
  git_ref = str(args.git_ref or "HEAD").strip()
6967
7499
  candidate_job_urls = _resolve_jenkins_job_candidates(
6968
7500
  cfg,
@@ -6972,6 +7504,7 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
6972
7504
  job_url=args.job_url,
6973
7505
  multibranch_root_job=args.multibranch_root_job,
6974
7506
  branch_name=args.branch_name,
7507
+ component=component,
6975
7508
  )
6976
7509
  build_number = args.build_number
6977
7510
  max_builds = int(args.max_builds or 20)
@@ -6985,6 +7518,7 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
6985
7518
  args.multibranch_root_job
6986
7519
  or args.job_name
6987
7520
  or args.job_url
7521
+ or (_jenkins_access_cfg(cfg, component).get("url") if component else "")
6988
7522
  or jenkins_cfg.get("job_url")
6989
7523
  or ""
6990
7524
  ).strip()
@@ -7000,7 +7534,12 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
7000
7534
  payload = None
7001
7535
  for candidate_job_url in candidate_job_urls:
7002
7536
  api_url = _jenkins_build_api_url(candidate_job_url, int(build_number))
7003
- payload = _jenkins_api_get_json(api_url, cfg, allow_404=True)
7537
+ payload = _jenkins_api_get_json(
7538
+ api_url,
7539
+ cfg,
7540
+ allow_404=True,
7541
+ component=component,
7542
+ )
7004
7543
  if payload is not None:
7005
7544
  break
7006
7545
  if payload is not None and not payload.get("building"):
@@ -7046,7 +7585,12 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
7046
7585
  matched = None
7047
7586
  for candidate_job_url in candidate_job_urls:
7048
7587
  api_url = _jenkins_builds_api_url(candidate_job_url, max_builds)
7049
- payload = _jenkins_api_get_json(api_url, cfg, allow_404=True)
7588
+ payload = _jenkins_api_get_json(
7589
+ api_url,
7590
+ cfg,
7591
+ allow_404=True,
7592
+ component=component,
7593
+ )
7050
7594
  if payload is None:
7051
7595
  continue
7052
7596
  builds = payload.get("builds") or []
@@ -8296,6 +8840,11 @@ def cmd_task_start(args: argparse.Namespace) -> None:
8296
8840
  "only when classify requires isolation/review or the user explicitly requests it."
8297
8841
  )
8298
8842
  review_required = bool(getattr(args, "review_required", False) or plan["review_required"])
8843
+ review_depth, review_timeout_seconds = _normalized_task_review_policy(
8844
+ review_required,
8845
+ plan.get("review_depth"),
8846
+ getattr(args, "review_depth", ""),
8847
+ )
8299
8848
  registry_dir = _task_state_root(repo) / "tasks"
8300
8849
  other_active = any(
8301
8850
  _text((payload or {}).get("state"))
@@ -8350,6 +8899,8 @@ def cmd_task_start(args: argparse.Namespace) -> None:
8350
8899
  "scope_revision": 1,
8351
8900
  "effective_profile": plan["profile"],
8352
8901
  "design_required": bool(plan["design_required"]),
8902
+ "review_depth": review_depth,
8903
+ "review_timeout_seconds": review_timeout_seconds,
8353
8904
  "scope_history": [],
8354
8905
  "depends_on": depends_on,
8355
8906
  "prerequisite_shas": prerequisite_shas,
@@ -8435,6 +8986,8 @@ def cmd_task_start(args: argparse.Namespace) -> None:
8435
8986
  "scope_revision": 1,
8436
8987
  "effective_profile": plan["profile"],
8437
8988
  "design_required": bool(plan["design_required"]),
8989
+ "review_depth": review_depth,
8990
+ "review_timeout_seconds": review_timeout_seconds,
8438
8991
  "scope_history": [],
8439
8992
  "depends_on": depends_on,
8440
8993
  "prerequisite_shas": prerequisite_shas,
@@ -8509,18 +9062,49 @@ def _task_status_payload(repo: Path, manifest: dict) -> dict:
8509
9062
  remote = _text(manifest.get("remote")) or "origin"
8510
9063
  target = _text(manifest.get("target_branch"))
8511
9064
  remote_ref = f"refs/remotes/{remote}/{target}"
8512
- merged = bool(
9065
+ base_sha = _text(manifest.get("base_sha"))
9066
+ has_task_commits = bool(
8513
9067
  tip
9068
+ and base_sha
9069
+ and tip != base_sha
9070
+ and run(
9071
+ ["git", "merge-base", "--is-ancestor", base_sha, tip],
9072
+ cwd=repo,
9073
+ check=False,
9074
+ ).returncode
9075
+ == 0
9076
+ )
9077
+ merged = bool(
9078
+ has_task_commits
8514
9079
  and _git_ref_exists(repo, remote_ref)
8515
9080
  and run(["git", "merge-base", "--is-ancestor", tip, remote_ref], cwd=repo, check=False).returncode == 0
8516
9081
  )
9082
+ review = manifest.get("review") or {}
9083
+ deadline_at = _text(review.get("deadline_at"))
9084
+ review_seconds_remaining: Optional[int] = None
9085
+ review_deadline_expired = False
9086
+ if deadline_at:
9087
+ try:
9088
+ remaining = (
9089
+ _parse_iso_timestamp(deadline_at, "deadline_at")
9090
+ - _dt.datetime.now(_dt.timezone.utc)
9091
+ ).total_seconds()
9092
+ seconds = int(remaining)
9093
+ review_seconds_remaining = max(0, seconds)
9094
+ review_deadline_expired = remaining < 0
9095
+ except APError:
9096
+ review_deadline_expired = True
9097
+ review_seconds_remaining = 0
8517
9098
  return {
8518
9099
  **manifest,
8519
9100
  "worktree_exists": worktree.exists(),
8520
9101
  "dirty": bool(_git_status(worktree)) if worktree.exists() else False,
8521
9102
  "local_branch_exists": bool(tip),
8522
9103
  "tip": tip,
9104
+ "has_task_commits": has_task_commits,
8523
9105
  "merged_into_target": merged,
9106
+ "review_deadline_expired": review_deadline_expired,
9107
+ "review_seconds_remaining": review_seconds_remaining,
8524
9108
  "current_diff_fingerprint": _task_review_fingerprint(worktree, manifest)
8525
9109
  if worktree.exists()
8526
9110
  else "",
@@ -8551,7 +9135,9 @@ def cmd_task_status(args: argparse.Namespace) -> None:
8551
9135
  print(
8552
9136
  f"[task-status] task={status['task_id']} state={status.get('state')} "
8553
9137
  f"branch={status.get('task_branch')} worktree={status.get('worktree_path')} "
8554
- f"dirty={str(status['dirty']).lower()} merged={str(status['merged_into_target']).lower()}"
9138
+ f"dirty={str(status['dirty']).lower()} commits="
9139
+ f"{str(status['has_task_commits']).lower()} "
9140
+ f"merged={str(status['merged_into_target']).lower()}"
8555
9141
  )
8556
9142
 
8557
9143
 
@@ -8678,6 +9264,13 @@ def cmd_task_scope_add(args: argparse.Namespace) -> None:
8678
9264
  manifest["design_required"] = bool(
8679
9265
  manifest.get("design_required") or plan.get("design_required")
8680
9266
  )
9267
+ review_depth, review_timeout_seconds = _normalized_task_review_policy(
9268
+ bool(manifest["review_required"]),
9269
+ manifest.get("review_depth"),
9270
+ plan.get("review_depth"),
9271
+ )
9272
+ manifest["review_depth"] = review_depth
9273
+ manifest["review_timeout_seconds"] = review_timeout_seconds
8681
9274
  manifest["claimed_paths"] = []
8682
9275
  history = list(manifest.get("scope_history") or [])
8683
9276
  history.append(
@@ -8730,6 +9323,543 @@ def cmd_task_scope_add(args: argparse.Namespace) -> None:
8730
9323
  )
8731
9324
 
8732
9325
 
9326
+ def _parse_iso_timestamp(value: object, field: str) -> _dt.datetime:
9327
+ raw = _text(value)
9328
+ try:
9329
+ parsed = _dt.datetime.fromisoformat(raw.replace("Z", "+00:00"))
9330
+ except ValueError as exc:
9331
+ raise APError(f"Invalid {field} timestamp in review assignment: {raw!r}.") from exc
9332
+ if parsed.tzinfo is None:
9333
+ raise APError(f"Review assignment {field} must include a timezone.")
9334
+ return parsed.astimezone(_dt.timezone.utc)
9335
+
9336
+
9337
+ def _task_review_policy(cfg: dict, worktree: Path, manifest: dict) -> tuple[str, int]:
9338
+ changed_paths = _task_changed_paths_from_base(worktree, _text(manifest.get("base_sha")))
9339
+ plan = _resolve_execution_plan(
9340
+ cfg,
9341
+ worktree,
9342
+ changed_paths=changed_paths,
9343
+ planned_paths=list(manifest.get("owned_paths") or []),
9344
+ requested_task_kind="change",
9345
+ )
9346
+ return _normalized_task_review_policy(
9347
+ True,
9348
+ manifest.get("review_depth"),
9349
+ plan.get("review_depth"),
9350
+ )
9351
+
9352
+
9353
+ def cmd_review_assignment(args: argparse.Namespace) -> None:
9354
+ repo = Path(args.repo).resolve()
9355
+ ensure_git_repo(repo)
9356
+ cfg = _load_cfg(repo)
9357
+ task_id = _validate_task_id(args.task_id)
9358
+ control_repo, worktree, _ = _task_lifecycle_context(repo, cfg, task_id)
9359
+ timeout_s = float(_concurrency_cfg(cfg).get("lock_timeout_sec") or 30)
9360
+ with _repo_lock(control_repo, f"task-{task_id}", timeout_s=timeout_s):
9361
+ manifest = _load_task_manifest(control_repo, task_id)
9362
+ lifecycle_actor = _text(os.environ.get("CODEX_THREAD_ID"))
9363
+ if not lifecycle_actor or lifecycle_actor != _text(manifest.get("owner")):
9364
+ raise APError("Only the task lifecycle owner may issue a review assignment.")
9365
+ if _text(manifest.get("state")) not in {"active", "pushed", "integration-raced"}:
9366
+ raise APError(f"Task {task_id} is not reviewable in state={manifest.get('state')}.")
9367
+ if not bool(manifest.get("review_required")):
9368
+ raise APError(f"Task {task_id} does not require an independent review assignment.")
9369
+ if not worktree.exists():
9370
+ raise APError(f"Task worktree is missing: {worktree}")
9371
+ worktree_cfg = _load_cfg(worktree)
9372
+ unowned = _task_unowned_paths(worktree, worktree_cfg, manifest)
9373
+ if unowned:
9374
+ raise APError("Changes outside task owned_paths:\n- " + "\n- ".join(unowned))
9375
+ changed_paths = _task_changed_paths_from_base(
9376
+ worktree,
9377
+ _text(manifest.get("base_sha")),
9378
+ )
9379
+ owned_paths = [
9380
+ path
9381
+ for path in changed_paths
9382
+ if _path_is_owned(path, list(manifest.get("owned_paths") or []))
9383
+ ]
9384
+ if not owned_paths:
9385
+ raise APError("Cannot issue a review assignment before the task has an owned diff.")
9386
+ reviewer = _text(args.reviewer)
9387
+ if not reviewer or any(char in reviewer for char in "\0\r\n"):
9388
+ raise APError("Reviewer identity is empty or contains invalid characters.")
9389
+ owner = _text(manifest.get("owner"))
9390
+ owning_fixer = _text((manifest.get("writer_lease") or {}).get("holder")) or owner
9391
+ if reviewer in {owner, owning_fixer}:
9392
+ raise APError("Independent reviewer must differ from lifecycle owner and owning fixer.")
9393
+ fingerprint = _task_review_fingerprint(worktree, manifest, worktree_cfg)
9394
+ depth, review_timeout = _task_review_policy(worktree_cfg, worktree, manifest)
9395
+ issued = _dt.datetime.now(_dt.timezone.utc).replace(microsecond=0)
9396
+ deadline = issued + _dt.timedelta(seconds=review_timeout)
9397
+ assignment = {
9398
+ "contract_version": _AGENT_CONTRACT_VERSION,
9399
+ "node_id": reviewer,
9400
+ "task_id": task_id,
9401
+ "role": "reviewer",
9402
+ "base_sha": _text(manifest.get("base_sha")),
9403
+ "scope": f"Review the task-owned diff for {task_id}",
9404
+ "depends_on": [owning_fixer],
9405
+ "acceptance": [
9406
+ "Review only the assigned stable diff and supplied evidence.",
9407
+ "Return the complete 16-field reviewer result bound to diff_fingerprint.",
9408
+ ],
9409
+ "diff_base": _text(manifest.get("base_sha")),
9410
+ "diff_head": _resolve_commit(worktree, "HEAD"),
9411
+ "diff_fingerprint": fingerprint,
9412
+ "owning_fixer": owning_fixer,
9413
+ "review_depth": depth,
9414
+ "timeout_seconds": review_timeout,
9415
+ "issued_at": issued.isoformat(),
9416
+ "deadline_at": deadline.isoformat(),
9417
+ "scope_revision": int(manifest.get("scope_revision") or 1),
9418
+ }
9419
+ _validate_orchestration_contract("assignment", assignment)
9420
+ assignment_path = (
9421
+ _task_state_root(control_repo)
9422
+ / "reviews"
9423
+ / f"{task_id}-{fingerprint}.assignment.json"
9424
+ )
9425
+ prior_review = manifest.get("review") or {}
9426
+ if (
9427
+ _text(prior_review.get("diff_fingerprint")) == fingerprint
9428
+ and (
9429
+ _text(prior_review.get("verdict"))
9430
+ in {"approved", "changes-requested", "blocked"}
9431
+ or _text(prior_review.get("runtime_state"))
9432
+ or _text(prior_review.get("runtime_receipt_path"))
9433
+ )
9434
+ ):
9435
+ raise APError(
9436
+ "The single review attempt for this diff fingerprint is already complete or consumed."
9437
+ )
9438
+ existing_assignment = _read_json_object(assignment_path)
9439
+ if existing_assignment:
9440
+ _validate_orchestration_contract("assignment", existing_assignment)
9441
+ expected_fields = {
9442
+ "task_id": task_id,
9443
+ "base_sha": assignment["base_sha"],
9444
+ "diff_base": assignment["diff_base"],
9445
+ "diff_head": assignment["diff_head"],
9446
+ "diff_fingerprint": fingerprint,
9447
+ "owning_fixer": owning_fixer,
9448
+ "scope_revision": assignment["scope_revision"],
9449
+ }
9450
+ mismatched = [
9451
+ field
9452
+ for field, expected in expected_fields.items()
9453
+ if existing_assignment.get(field) != expected
9454
+ ]
9455
+ if mismatched:
9456
+ raise APError(
9457
+ "Existing review assignment does not match current task state: "
9458
+ + ", ".join(mismatched)
9459
+ )
9460
+ if _text(existing_assignment.get("node_id")) != reviewer:
9461
+ raise APError(
9462
+ "This diff fingerprint already has a reviewer assignment; "
9463
+ "the single review attempt cannot be reassigned."
9464
+ )
9465
+ existing_deadline = _parse_iso_timestamp(
9466
+ existing_assignment.get("deadline_at"),
9467
+ "deadline_at",
9468
+ )
9469
+ if _dt.datetime.now(_dt.timezone.utc) > existing_deadline:
9470
+ raise APError(
9471
+ "Review attempt timed out and is blocked for this diff fingerprint; "
9472
+ "do not renew it without a semantic diff/scope change or explicit user authorization."
9473
+ )
9474
+ assignment = existing_assignment
9475
+ depth = _text(assignment.get("review_depth"))
9476
+ review_timeout = int(assignment.get("timeout_seconds") or 0)
9477
+ elif (
9478
+ _text(prior_review.get("diff_fingerprint")) == fingerprint
9479
+ and _text(prior_review.get("deadline_at"))
9480
+ ):
9481
+ if _text(prior_review.get("reviewer")) != reviewer:
9482
+ raise APError(
9483
+ "This diff fingerprint already has a reviewer assignment; "
9484
+ "the single review attempt cannot be reassigned."
9485
+ )
9486
+ issued = _parse_iso_timestamp(prior_review.get("issued_at"), "issued_at")
9487
+ deadline = _parse_iso_timestamp(prior_review.get("deadline_at"), "deadline_at")
9488
+ if _dt.datetime.now(_dt.timezone.utc) > deadline:
9489
+ raise APError(
9490
+ "Review attempt timed out and is blocked for this diff fingerprint; "
9491
+ "do not renew it without a semantic diff/scope change or explicit user authorization."
9492
+ )
9493
+ assignment["issued_at"] = issued.isoformat()
9494
+ assignment["deadline_at"] = deadline.isoformat()
9495
+ assignment["timeout_seconds"] = int((deadline - issued).total_seconds())
9496
+ _validate_orchestration_contract("assignment", assignment)
9497
+ _write_json_object(assignment_path, assignment)
9498
+ depth = _text(assignment.get("review_depth"))
9499
+ review_timeout = int(assignment.get("timeout_seconds") or 0)
9500
+ else:
9501
+ _write_json_object(assignment_path, assignment)
9502
+ manifest["review_depth"] = depth
9503
+ manifest["review_timeout_seconds"] = review_timeout
9504
+ review_state = {
9505
+ "verdict": "pending",
9506
+ "diff_base": assignment["diff_base"],
9507
+ "diff_head": assignment["diff_head"],
9508
+ "diff_fingerprint": fingerprint,
9509
+ "reviewer": reviewer,
9510
+ "reviewed_at": "",
9511
+ "reason": "review assignment issued",
9512
+ "assignment_path": str(assignment_path),
9513
+ "issued_at": assignment["issued_at"],
9514
+ "deadline_at": assignment["deadline_at"],
9515
+ }
9516
+ if _text(prior_review.get("diff_fingerprint")) == fingerprint:
9517
+ for field in _REVIEW_RUNTIME_FIELDS:
9518
+ if field in prior_review:
9519
+ review_state[field] = prior_review[field]
9520
+ manifest["review"] = review_state
9521
+ _save_task_manifest(control_repo, manifest)
9522
+ if bool(getattr(args, "json", False)):
9523
+ print(
9524
+ json.dumps(
9525
+ {"assignment_path": str(assignment_path), "assignment": assignment},
9526
+ ensure_ascii=False,
9527
+ indent=2,
9528
+ )
9529
+ )
9530
+ else:
9531
+ print(f"[review-assignment] task={task_id} reviewer={reviewer} depth={depth}")
9532
+ print(f"[review-assignment] timeout_seconds={review_timeout}")
9533
+ print(f"[review-assignment] assignment={assignment_path}")
9534
+
9535
+
9536
+ def _write_private_json(path: Path, payload: dict) -> None:
9537
+ _write_json_object(path, payload)
9538
+ try:
9539
+ path.chmod(0o600)
9540
+ except OSError as exc:
9541
+ raise APError(f"Cannot protect Git-local review state: {path}: {exc}") from exc
9542
+
9543
+
9544
+ def _review_runtime_paths(
9545
+ control_repo: Path,
9546
+ task_id: str,
9547
+ fingerprint: str,
9548
+ ) -> tuple[Path, Path]:
9549
+ root = _task_state_root(control_repo) / "reviews"
9550
+ stem = f"{_validate_task_id(task_id)}-{fingerprint}"
9551
+ return root / f"{stem}.result.json", root / f"{stem}.run.json"
9552
+
9553
+
9554
+ def _review_command_sha256(command: list[str]) -> str:
9555
+ digest = hashlib.sha256()
9556
+ for argument in command:
9557
+ digest.update(argument.encode("utf-8", errors="surrogateescape"))
9558
+ digest.update(b"\0")
9559
+ return digest.hexdigest()
9560
+
9561
+
9562
+ def _bounded_reviewer_output(value: str, label: str) -> str:
9563
+ encoded = value.encode("utf-8", errors="replace")
9564
+ if len(encoded) > _REVIEW_OUTPUT_MAX_BYTES:
9565
+ raise APError(f"Reviewer {label} exceeded {_REVIEW_OUTPUT_MAX_BYTES} bytes; refusing oversized output.")
9566
+ return value
9567
+
9568
+
9569
+ def _read_bounded_reviewer_output(path: Path) -> str:
9570
+ try:
9571
+ with path.open("rb") as handle:
9572
+ payload = handle.read(_REVIEW_OUTPUT_MAX_BYTES + 1)
9573
+ except OSError as exc:
9574
+ raise APError(f"Cannot read Reviewer result: {path}: {exc}") from exc
9575
+ if len(payload) > _REVIEW_OUTPUT_MAX_BYTES:
9576
+ raise APError(f"Reviewer result exceeded {_REVIEW_OUTPUT_MAX_BYTES} bytes; refusing oversized output.")
9577
+ return payload.decode("utf-8", errors="strict")
9578
+
9579
+
9580
+ def _review_result_file_sha256(path: Path) -> str:
9581
+ try:
9582
+ with path.open("rb") as handle:
9583
+ payload = handle.read(_REVIEW_OUTPUT_MAX_BYTES + 1)
9584
+ except OSError as exc:
9585
+ raise APError(f"Cannot hash Reviewer result: {path}: {exc}") from exc
9586
+ if len(payload) > _REVIEW_OUTPUT_MAX_BYTES:
9587
+ raise APError(f"Reviewer result exceeded {_REVIEW_OUTPUT_MAX_BYTES} bytes; refusing oversized output.")
9588
+ return hashlib.sha256(payload).hexdigest()
9589
+
9590
+
9591
+ def _update_review_runtime(
9592
+ control_repo: Path,
9593
+ task_id: str,
9594
+ fingerprint: str,
9595
+ *,
9596
+ updates: dict,
9597
+ receipt_path: Path,
9598
+ receipt_updates: dict,
9599
+ ) -> dict:
9600
+ cfg = _load_cfg(control_repo)
9601
+ timeout_s = float(_concurrency_cfg(cfg).get("lock_timeout_sec") or 30)
9602
+ with _repo_lock(control_repo, f"task-{task_id}", timeout_s=timeout_s):
9603
+ manifest = _load_task_manifest(control_repo, task_id)
9604
+ review = dict(manifest.get("review") or {})
9605
+ if _text(review.get("diff_fingerprint")) != fingerprint:
9606
+ raise APError("Reviewer runtime assignment became stale while the process was running.")
9607
+ review.update(updates)
9608
+ manifest["review"] = review
9609
+ receipt = _read_json_object(receipt_path) or {}
9610
+ receipt.update(receipt_updates)
9611
+ _write_private_json(receipt_path, receipt)
9612
+ _save_task_manifest(control_repo, manifest)
9613
+ return manifest
9614
+
9615
+
9616
+ def _blocked_reviewer_runtime_result(
9617
+ assignment: dict,
9618
+ reason: str,
9619
+ evidence: list[str],
9620
+ ) -> dict:
9621
+ result = _reviewer_result_template(assignment, "blocked")
9622
+ result["summary"] = reason
9623
+ result["evidence"] = evidence
9624
+ return _validate_orchestration_contract("result", result)
9625
+
9626
+
9627
+ def cmd_review_run(args: argparse.Namespace) -> None:
9628
+ repo = Path(args.repo).resolve()
9629
+ ensure_git_repo(repo)
9630
+ cfg = _load_cfg(repo)
9631
+ task_id = _validate_task_id(args.task_id)
9632
+ reviewer = _text(args.reviewer)
9633
+ with contextlib.redirect_stdout(io.StringIO()):
9634
+ cmd_review_assignment(
9635
+ argparse.Namespace(
9636
+ repo=str(repo),
9637
+ task_id=task_id,
9638
+ reviewer=reviewer,
9639
+ json=False,
9640
+ )
9641
+ )
9642
+
9643
+ control_repo, worktree, _ = _task_lifecycle_context(repo, cfg, task_id)
9644
+ manifest = _load_task_manifest(control_repo, task_id)
9645
+ review = manifest.get("review") or {}
9646
+ assignment_path = Path(_text(review.get("assignment_path"))).resolve()
9647
+ assignment = _read_json_object(assignment_path)
9648
+ if not assignment:
9649
+ raise APError("Review assignment file is missing or invalid.")
9650
+ _validate_orchestration_contract("assignment", assignment)
9651
+ fingerprint = _text(assignment.get("diff_fingerprint"))
9652
+ result_path, receipt_path = _review_runtime_paths(control_repo, task_id, fingerprint)
9653
+
9654
+ command_override = _text(getattr(args, "runner_command_json", ""))
9655
+ if command_override:
9656
+ try:
9657
+ command_value = json.loads(command_override)
9658
+ except json.JSONDecodeError as exc:
9659
+ raise APError("--runner-command-json must be a JSON array of argv strings.") from exc
9660
+ if not isinstance(command_value, list) or not command_value or not all(
9661
+ isinstance(item, str) and item for item in command_value
9662
+ ):
9663
+ raise APError("--runner-command-json must be a non-empty JSON array of argv strings.")
9664
+ command = command_value
9665
+ else:
9666
+ command = _codex_reviewer_command(worktree, assignment_path, result_path)
9667
+ command_sha256 = _review_command_sha256(command)
9668
+ started_at = _now_iso()
9669
+ receipt = {
9670
+ "schema": 1,
9671
+ "task_id": task_id,
9672
+ "reviewer": reviewer,
9673
+ "diff_fingerprint": fingerprint,
9674
+ "assignment_path": str(assignment_path),
9675
+ "result_path": str(result_path),
9676
+ "command_sha256": command_sha256,
9677
+ "status": "starting",
9678
+ "started_at": started_at,
9679
+ "finished_at": "",
9680
+ "exit_code": None,
9681
+ }
9682
+ timeout_s = float(_concurrency_cfg(_load_cfg(control_repo)).get("lock_timeout_sec") or 30)
9683
+ with _repo_lock(control_repo, f"task-{task_id}", timeout_s=timeout_s):
9684
+ manifest = _load_task_manifest(control_repo, task_id)
9685
+ current_review = dict(manifest.get("review") or {})
9686
+ if _text(current_review.get("diff_fingerprint")) != fingerprint:
9687
+ raise APError("Review assignment became stale before Reviewer runtime start.")
9688
+ if _text(current_review.get("runtime_state")) or receipt_path.exists():
9689
+ raise APError(
9690
+ "The supervised Reviewer runtime has already started for this diff fingerprint."
9691
+ )
9692
+ deadline = _parse_iso_timestamp(assignment.get("deadline_at"), "deadline_at")
9693
+ if _dt.datetime.now(_dt.timezone.utc) >= deadline:
9694
+ raise APError("Review assignment deadline expired before Reviewer runtime start.")
9695
+ _write_private_json(receipt_path, receipt)
9696
+ current_review.update(
9697
+ {
9698
+ "runtime_state": "starting",
9699
+ "runtime_started_at": started_at,
9700
+ "runtime_finished_at": "",
9701
+ "runtime_result_path": str(result_path),
9702
+ "runtime_exit_code": None,
9703
+ "runtime_command_sha256": command_sha256,
9704
+ "runtime_receipt_path": str(receipt_path),
9705
+ }
9706
+ )
9707
+ manifest["review"] = current_review
9708
+ _save_task_manifest(control_repo, manifest)
9709
+
9710
+ env = os.environ.copy()
9711
+ env.pop("CODEX_THREAD_ID", None)
9712
+ env.update(
9713
+ {
9714
+ "AUTOCODING_REVIEW_ASSIGNMENT": str(assignment_path),
9715
+ "AUTOCODING_REVIEW_RESULT": str(result_path),
9716
+ "AUTOCODING_REVIEW_DEADLINE": _text(assignment.get("deadline_at")),
9717
+ "AUTOCODING_REVIEW_TIMEOUT_SECONDS": str(int(assignment.get("timeout_seconds") or 0)),
9718
+ }
9719
+ )
9720
+ deadline = _parse_iso_timestamp(assignment.get("deadline_at"), "deadline_at")
9721
+ remaining = (deadline - _dt.datetime.now(_dt.timezone.utc)).total_seconds()
9722
+ try:
9723
+ completed = _run_supervised_reviewer_process(
9724
+ command,
9725
+ cwd=worktree,
9726
+ env=env,
9727
+ timeout_seconds=remaining,
9728
+ )
9729
+ except _ReviewerRuntimeTimeout as exc:
9730
+ finished_at = _now_iso()
9731
+ result = _blocked_reviewer_runtime_result(
9732
+ assignment,
9733
+ "Reviewer runtime reached its fixed deadline and was terminated.",
9734
+ ["runtime_timeout=true"],
9735
+ )
9736
+ _write_private_json(result_path, result)
9737
+ _update_review_runtime(
9738
+ control_repo,
9739
+ task_id,
9740
+ fingerprint,
9741
+ updates={
9742
+ "verdict": "blocked",
9743
+ "reason": "reviewer runtime timeout",
9744
+ "runtime_state": "timed-out",
9745
+ "runtime_finished_at": finished_at,
9746
+ "runtime_exit_code": None,
9747
+ },
9748
+ receipt_path=receipt_path,
9749
+ receipt_updates={
9750
+ "status": "timed-out",
9751
+ "finished_at": finished_at,
9752
+ "exit_code": None,
9753
+ },
9754
+ )
9755
+ print(json.dumps(result, ensure_ascii=False, indent=2))
9756
+ raise APError("Reviewer runtime timed out and was terminated; review is blocked.") from exc
9757
+
9758
+ finished_at = _now_iso()
9759
+ if completed.returncode != 0:
9760
+ result = _blocked_reviewer_runtime_result(
9761
+ assignment,
9762
+ "Reviewer runtime exited unsuccessfully.",
9763
+ [f"runner_exit_code={completed.returncode}"],
9764
+ )
9765
+ _write_private_json(result_path, result)
9766
+ _update_review_runtime(
9767
+ control_repo,
9768
+ task_id,
9769
+ fingerprint,
9770
+ updates={
9771
+ "verdict": "blocked",
9772
+ "reason": "reviewer runtime failed",
9773
+ "runtime_state": "failed",
9774
+ "runtime_finished_at": finished_at,
9775
+ "runtime_exit_code": completed.returncode,
9776
+ },
9777
+ receipt_path=receipt_path,
9778
+ receipt_updates={
9779
+ "status": "failed",
9780
+ "finished_at": finished_at,
9781
+ "exit_code": completed.returncode,
9782
+ },
9783
+ )
9784
+ print(json.dumps(result, ensure_ascii=False, indent=2))
9785
+ raise APError(
9786
+ f"Reviewer runtime failed with exit code {completed.returncode}; review is blocked."
9787
+ )
9788
+
9789
+ try:
9790
+ stdout = _bounded_reviewer_output(completed.stdout, "stdout")
9791
+ _bounded_reviewer_output(completed.stderr, "stderr")
9792
+ raw = _read_bounded_reviewer_output(result_path) if result_path.exists() else stdout
9793
+ payload = json.loads(raw)
9794
+ result = _normalize_reviewer_runtime_result(assignment, payload)
9795
+ except (APError, json.JSONDecodeError, UnicodeDecodeError) as exc:
9796
+ result = _blocked_reviewer_runtime_result(
9797
+ assignment,
9798
+ "Reviewer runtime returned an invalid result.",
9799
+ ["result_contract_valid=false"],
9800
+ )
9801
+ _write_private_json(result_path, result)
9802
+ _update_review_runtime(
9803
+ control_repo,
9804
+ task_id,
9805
+ fingerprint,
9806
+ updates={
9807
+ "verdict": "blocked",
9808
+ "reason": "invalid reviewer runtime result",
9809
+ "runtime_state": "failed",
9810
+ "runtime_finished_at": finished_at,
9811
+ "runtime_exit_code": completed.returncode,
9812
+ },
9813
+ receipt_path=receipt_path,
9814
+ receipt_updates={
9815
+ "status": "result-invalid",
9816
+ "finished_at": finished_at,
9817
+ "exit_code": completed.returncode,
9818
+ },
9819
+ )
9820
+ print(json.dumps(result, ensure_ascii=False, indent=2))
9821
+ raise APError(f"Reviewer runtime result is invalid; review is blocked: {exc}") from exc
9822
+
9823
+ _write_private_json(result_path, result)
9824
+ result_sha256 = _review_result_file_sha256(result_path)
9825
+ runtime_state = "blocked" if result["verdict"] == "blocked" else "completed"
9826
+ _update_review_runtime(
9827
+ control_repo,
9828
+ task_id,
9829
+ fingerprint,
9830
+ updates={
9831
+ "verdict": "blocked" if result["verdict"] == "blocked" else "pending",
9832
+ "reason": "reviewer reported blocked" if result["verdict"] == "blocked" else "",
9833
+ "runtime_state": runtime_state,
9834
+ "runtime_finished_at": finished_at,
9835
+ "runtime_exit_code": completed.returncode,
9836
+ },
9837
+ receipt_path=receipt_path,
9838
+ receipt_updates={
9839
+ "status": runtime_state,
9840
+ "finished_at": finished_at,
9841
+ "exit_code": completed.returncode,
9842
+ "verdict": result["verdict"],
9843
+ "result_sha256": result_sha256,
9844
+ },
9845
+ )
9846
+ if result["verdict"] == "blocked":
9847
+ print(json.dumps(result, ensure_ascii=False, indent=2))
9848
+ raise APError("Reviewer returned blocked; task-review was not recorded.")
9849
+
9850
+ with contextlib.redirect_stdout(io.StringIO()):
9851
+ cmd_task_review(
9852
+ argparse.Namespace(
9853
+ repo=str(repo),
9854
+ task_id=task_id,
9855
+ verdict=result["verdict"],
9856
+ diff_fingerprint=fingerprint,
9857
+ reviewer=reviewer,
9858
+ )
9859
+ )
9860
+ print(json.dumps(result, ensure_ascii=False, indent=2))
9861
+
9862
+
8733
9863
  def cmd_task_review(args: argparse.Namespace) -> None:
8734
9864
  repo = Path(args.repo).resolve()
8735
9865
  ensure_git_repo(repo)
@@ -8767,7 +9897,137 @@ def cmd_task_review(args: argparse.Namespace) -> None:
8767
9897
  writer = _text((manifest.get("writer_lease") or {}).get("holder"))
8768
9898
  if reviewer == writer:
8769
9899
  raise APError("Independent reviewer identity must differ from the current writer lease holder.")
8770
- manifest["review"] = {
9900
+ assigned_review = manifest.get("review") or {}
9901
+ if bool(manifest.get("review_required")) and not all(
9902
+ _text(assigned_review.get(field))
9903
+ for field in ("assignment_path", "reviewer", "diff_fingerprint", "deadline_at")
9904
+ ):
9905
+ raise APError(
9906
+ "Review-required tasks must use review-assignment before task-review."
9907
+ )
9908
+ assigned_reviewer = _text(assigned_review.get("reviewer"))
9909
+ if assigned_reviewer and reviewer != assigned_reviewer:
9910
+ raise APError(
9911
+ f"Review verdict reviewer mismatch: assigned={assigned_reviewer}, supplied={reviewer}."
9912
+ )
9913
+ assigned_fingerprint = _text(assigned_review.get("diff_fingerprint"))
9914
+ if assigned_fingerprint and assigned_fingerprint != fingerprint:
9915
+ raise APError("Review assignment is stale; issue a new assignment for the current diff.")
9916
+ assigned_head = _text(assigned_review.get("diff_head"))
9917
+ current_head = _resolve_commit(worktree, "HEAD")
9918
+ if assigned_head and assigned_head != current_head:
9919
+ raise APError("Review assignment HEAD is stale for the current task.")
9920
+ assignment_path = _text(assigned_review.get("assignment_path"))
9921
+ assignment: Optional[dict] = None
9922
+ if assignment_path:
9923
+ expected_assignment_path = (
9924
+ _task_state_root(control_repo)
9925
+ / "reviews"
9926
+ / f"{task_id}-{fingerprint}.assignment.json"
9927
+ ).resolve()
9928
+ if Path(assignment_path).resolve() != expected_assignment_path:
9929
+ raise APError("Review assignment path does not match Git-local task state.")
9930
+ assignment = _read_json_object(expected_assignment_path)
9931
+ if not assignment:
9932
+ raise APError("Review assignment file is missing or invalid.")
9933
+ _validate_orchestration_contract("assignment", assignment)
9934
+ expected_assignment_fields = {
9935
+ "task_id": task_id,
9936
+ "base_sha": _text(manifest.get("base_sha")),
9937
+ "diff_base": _text(manifest.get("base_sha")),
9938
+ "diff_head": current_head,
9939
+ "diff_fingerprint": fingerprint,
9940
+ "node_id": reviewer,
9941
+ "owning_fixer": _text((manifest.get("writer_lease") or {}).get("holder")),
9942
+ "issued_at": _text(assigned_review.get("issued_at")),
9943
+ "deadline_at": _text(assigned_review.get("deadline_at")),
9944
+ }
9945
+ mismatched = [
9946
+ field
9947
+ for field, expected in expected_assignment_fields.items()
9948
+ if assignment.get(field) != expected
9949
+ ]
9950
+ if mismatched:
9951
+ raise APError(
9952
+ "Review assignment does not match the recorded task state: "
9953
+ + ", ".join(mismatched)
9954
+ )
9955
+ if int(assignment.get("scope_revision") or 0) != int(
9956
+ manifest.get("scope_revision") or 1
9957
+ ):
9958
+ raise APError("Review assignment scope revision is stale.")
9959
+ runtime_state = _text(assigned_review.get("runtime_state"))
9960
+ if runtime_state:
9961
+ if runtime_state != "completed":
9962
+ raise APError(
9963
+ f"Reviewer runtime state={runtime_state} cannot be recorded by task-review."
9964
+ )
9965
+ if assignment is None:
9966
+ raise APError("Reviewer runtime result has no validated assignment.")
9967
+ if assigned_review.get("runtime_exit_code") != 0:
9968
+ raise APError("Reviewer runtime did not exit successfully.")
9969
+ expected_result_path, expected_receipt_path = _review_runtime_paths(
9970
+ control_repo,
9971
+ task_id,
9972
+ fingerprint,
9973
+ )
9974
+ result_path = Path(_text(assigned_review.get("runtime_result_path"))).resolve()
9975
+ receipt_path = Path(_text(assigned_review.get("runtime_receipt_path"))).resolve()
9976
+ if result_path != expected_result_path.resolve():
9977
+ raise APError("Reviewer runtime result path does not match Git-local task state.")
9978
+ if receipt_path != expected_receipt_path.resolve():
9979
+ raise APError("Reviewer runtime receipt path does not match Git-local task state.")
9980
+ try:
9981
+ result_payload = json.loads(_read_bounded_reviewer_output(result_path))
9982
+ except (json.JSONDecodeError, UnicodeDecodeError) as exc:
9983
+ raise APError("Reviewer runtime result file is invalid JSON.") from exc
9984
+ if not isinstance(result_payload, dict):
9985
+ raise APError("Reviewer runtime result file must contain one JSON object.")
9986
+ _validate_orchestration_contract("result", result_payload)
9987
+ normalized_result = _normalize_reviewer_runtime_result(assignment, result_payload)
9988
+ if result_payload != normalized_result:
9989
+ raise APError("Reviewer runtime result file is not the canonical bound result.")
9990
+ if _text(result_payload.get("verdict")) != _text(args.verdict):
9991
+ raise APError(
9992
+ "Reviewer runtime verdict does not match the requested task-review verdict."
9993
+ )
9994
+ receipt = _read_json_object(receipt_path)
9995
+ if not receipt:
9996
+ raise APError("Reviewer runtime receipt is missing or invalid.")
9997
+ expected_receipt = {
9998
+ "task_id": task_id,
9999
+ "reviewer": reviewer,
10000
+ "diff_fingerprint": fingerprint,
10001
+ "result_path": str(expected_result_path),
10002
+ "status": "completed",
10003
+ "verdict": _text(args.verdict),
10004
+ "result_sha256": _review_result_file_sha256(result_path),
10005
+ }
10006
+ receipt_mismatches = [
10007
+ field
10008
+ for field, expected in expected_receipt.items()
10009
+ if receipt.get(field) != expected
10010
+ ]
10011
+ if receipt_mismatches:
10012
+ raise APError(
10013
+ "Reviewer runtime receipt does not bind the recorded result: "
10014
+ + ", ".join(receipt_mismatches)
10015
+ )
10016
+ deadline_at = _text(assigned_review.get("deadline_at"))
10017
+ completed_at = _dt.datetime.now(_dt.timezone.utc)
10018
+ if (
10019
+ _text(assigned_review.get("runtime_state")) == "completed"
10020
+ and _text(assigned_review.get("runtime_finished_at"))
10021
+ ):
10022
+ completed_at = _parse_iso_timestamp(
10023
+ assigned_review.get("runtime_finished_at"),
10024
+ "runtime_finished_at",
10025
+ )
10026
+ if deadline_at and completed_at > _parse_iso_timestamp(deadline_at, "deadline_at"):
10027
+ raise APError(
10028
+ "Review assignment deadline expired; the single review attempt is blocked."
10029
+ )
10030
+ review_state = {
8771
10031
  "verdict": args.verdict,
8772
10032
  "diff_base": _text(manifest.get("base_sha")),
8773
10033
  "diff_head": _resolve_commit(worktree, "HEAD"),
@@ -8775,7 +10035,16 @@ def cmd_task_review(args: argparse.Namespace) -> None:
8775
10035
  "reviewer": reviewer,
8776
10036
  "reviewed_at": _now_iso(),
8777
10037
  "reason": "",
10038
+ "assignment_path": assignment_path,
10039
+ "issued_at": _text(assigned_review.get("issued_at")),
10040
+ "deadline_at": deadline_at,
10041
+ "review_depth": _text(manifest.get("review_depth")),
10042
+ "review_timeout_seconds": int(manifest.get("review_timeout_seconds") or 0),
8778
10043
  }
10044
+ for field in _REVIEW_RUNTIME_FIELDS:
10045
+ if field in assigned_review:
10046
+ review_state[field] = assigned_review[field]
10047
+ manifest["review"] = review_state
8779
10048
  _save_task_manifest(control_repo, manifest)
8780
10049
  print(f"[task-review] task={task_id} verdict={args.verdict} fingerprint={fingerprint}")
8781
10050
 
@@ -9862,12 +11131,17 @@ def main(argv: Optional[List[str]] = None) -> int:
9862
11131
 
9863
11132
  s = sp.add_parser("wait-health")
9864
11133
  s.add_argument("--scope", choices=["runtime", "target", "prod"], default="runtime")
11134
+ s.add_argument("--component", choices=["frontend", "backend"], default="backend")
11135
+ s.add_argument("--path")
11136
+ s.add_argument("--timeout-sec", type=int)
9865
11137
  s.set_defaults(func=cmd_wait_health)
9866
11138
 
9867
11139
  s = sp.add_parser("verify-jenkins")
11140
+ s.add_argument("--component", choices=["all", "frontend", "backend"], default="all")
9868
11141
  s.set_defaults(func=cmd_verify_jenkins)
9869
11142
 
9870
11143
  s = sp.add_parser("verify-jenkins-build")
11144
+ s.add_argument("--component", choices=["frontend", "backend"])
9871
11145
  s.add_argument("--git-ref")
9872
11146
  s.add_argument("--job-name")
9873
11147
  s.add_argument("--job-url")
@@ -9917,6 +11191,7 @@ def main(argv: Optional[List[str]] = None) -> int:
9917
11191
  s.add_argument("--writers", type=int, default=1)
9918
11192
  s.add_argument("--isolated", action="store_true")
9919
11193
  s.add_argument("--review-required", action="store_true")
11194
+ s.add_argument("--review-depth", choices=["focused", "deep"])
9920
11195
  s.add_argument("--continue-direct", action="store_true")
9921
11196
  s.add_argument("--direct-claim")
9922
11197
  s.add_argument(
@@ -9944,6 +11219,25 @@ def main(argv: Optional[List[str]] = None) -> int:
9944
11219
  s.add_argument("--json", action="store_true")
9945
11220
  s.set_defaults(func=cmd_task_scope_add)
9946
11221
 
11222
+ s = sp.add_parser(
11223
+ "review-assignment",
11224
+ help="Generate and persist a deadline-bound reviewer assignment for a registered task",
11225
+ )
11226
+ s.add_argument("task_id")
11227
+ s.add_argument("--reviewer", required=True)
11228
+ s.add_argument("--json", action="store_true")
11229
+ s.set_defaults(func=cmd_review_assignment)
11230
+
11231
+ s = sp.add_parser(
11232
+ "review-run",
11233
+ help="Run the independent Codex Reviewer under the assignment's fixed runtime deadline",
11234
+ )
11235
+ s.add_argument("task_id")
11236
+ s.add_argument("--reviewer", required=True)
11237
+ s.add_argument("--json", action="store_true")
11238
+ s.add_argument("--runner-command-json", help=argparse.SUPPRESS)
11239
+ s.set_defaults(func=cmd_review_run)
11240
+
9947
11241
  s = sp.add_parser("task-submodule-sync")
9948
11242
  s.add_argument("task_id")
9949
11243
  s.set_defaults(func=cmd_task_submodule_sync)