@elvis1513/auto-coding-skill 4.2.1 → 4.2.3

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.
@@ -5,18 +5,24 @@
5
5
  from __future__ import annotations
6
6
 
7
7
  import argparse
8
+ import ast
8
9
  import base64
9
10
  import contextlib
10
11
  import hashlib
11
12
  import datetime as _dt
12
13
  import fnmatch
14
+ import io
13
15
  import json
14
16
  import os
15
17
  import posixpath
16
18
  import re
19
+ import shutil
20
+ import signal
17
21
  import socket
22
+ import subprocess
18
23
  import sys
19
24
  import time
25
+ import tomllib
20
26
  import urllib.parse
21
27
  import urllib.error
22
28
  import urllib.request
@@ -29,7 +35,7 @@ from install_integrity import verify_managed_install
29
35
  from scaffold_templates import MANAGED_FRAMEWORK_DOCS, scaffold_groups, templates_for
30
36
 
31
37
 
32
- _JENKINS_CRUMB_CACHE: dict[str, dict[str, str]] = {}
38
+ _JENKINS_CRUMB_CACHE: dict[tuple[str, str], dict[str, str]] = {}
33
39
  _INVALID_PLACEHOLDERS = {"N/A", "TODO", "TBD", "CHANGEME", "CHANGE_ME", "FILL_ME", "FILL-ME", "PLACEHOLDER", "XXX", "NULL", "~"}
34
40
  _GENERATED_NOISE_PATTERNS = [
35
41
  ".local/auto-coding-skill/**",
@@ -44,6 +50,16 @@ _AGENT_CONTRACT_VERSION = 1
44
50
  _AGENT_CONTRACT_SCHEMA = "data/contracts/orchestration-v1.schema.json"
45
51
  _FOCUSED_REVIEW_TIMEOUT_SECONDS = 90
46
52
  _DEEP_REVIEW_TIMEOUT_SECONDS = 300
53
+ _REVIEW_RUNTIME_FIELDS = (
54
+ "runtime_state",
55
+ "runtime_started_at",
56
+ "runtime_finished_at",
57
+ "runtime_result_path",
58
+ "runtime_exit_code",
59
+ "runtime_command_sha256",
60
+ "runtime_receipt_path",
61
+ )
62
+ _REVIEW_OUTPUT_MAX_BYTES = 1024 * 1024
47
63
  _DEEP_REVIEW_CATEGORIES = {
48
64
  "api",
49
65
  "auth",
@@ -53,6 +69,15 @@ _DEEP_REVIEW_CATEGORIES = {
53
69
  "payment",
54
70
  "prod_config",
55
71
  }
72
+
73
+
74
+ class _ReviewerRuntimeTimeout(RuntimeError):
75
+ """Raised after the supervised Reviewer process group has been stopped."""
76
+
77
+ def __init__(self, stdout: str = "", stderr: str = "") -> None:
78
+ super().__init__("Reviewer runtime exceeded its assignment deadline.")
79
+ self.stdout = stdout
80
+ self.stderr = stderr
56
81
  _RECOMMENDED_FINAL_COMMAND_SECONDS = 120.0
57
82
  _RECOMMENDED_FINAL_TOTAL_SECONDS = 180.0
58
83
  _FINAL_GATE_CACHE_SCHEMA = 1
@@ -60,7 +85,7 @@ _FINAL_GATE_CACHE_ALGORITHM = "final-gate-v1"
60
85
  _WORKFLOW_MIGRATION_POLICY = Path("data/policies/workflow-migrations-v1.json")
61
86
  _FALLBACK_WORKFLOW_MIGRATION_POLICY = {
62
87
  "schema_version": 1,
63
- "managed_versions": {"agents": "4.2.1", "engineering": "4.2.1"},
88
+ "managed_versions": {"agents": "4.2.3", "engineering": "4.2.3"},
64
89
  "known_official_engineering_body_sha256": [
65
90
  "d1306cc626e8baf8c83c953b760fd771066de2bf125168eca3a7b7d6ff2b87a2",
66
91
  "305931c6edef770033a4f1970b00e5fb1c1728351856a173dbfa497daf563021",
@@ -261,27 +286,101 @@ def _run_configured_command(
261
286
  return True
262
287
 
263
288
 
264
- def _jenkins_basic_auth_headers(cfg: dict) -> dict:
289
+ def _jenkins_access_cfg(cfg: dict, component: str) -> dict:
290
+ access = cfg.get("access") or {}
291
+ jenkins = access.get("jenkins") or {}
292
+ value = jenkins.get(component) or {}
293
+ return value if isinstance(value, dict) else {}
294
+
295
+
296
+ def _configured_jenkins_components(cfg: dict) -> list[str]:
297
+ return [
298
+ component
299
+ for component in ("frontend", "backend")
300
+ if any(
301
+ _is_explicit_fill(value)
302
+ for value in _jenkins_access_cfg(cfg, component).values()
303
+ )
304
+ ]
305
+
306
+
307
+ def _require_http_url(field: str, value: object) -> str:
308
+ raw = _text(value).rstrip("/")
309
+ parsed = urllib.parse.urlparse(raw)
310
+ if not _is_explicit_fill(raw) or parsed.scheme not in {"http", "https"} or not parsed.netloc:
311
+ raise APError(f"Missing or invalid {field}; fill an http/https URL in docs/ENGINEERING.md.")
312
+ return raw
313
+
314
+
315
+ def _resolve_jenkins_component(
316
+ cfg: dict,
317
+ requested: str = "",
318
+ explicit_job_url: str = "",
319
+ ) -> str:
320
+ component = _text(requested).lower()
321
+ configured = _configured_jenkins_components(cfg)
322
+ if component:
323
+ if component not in {"frontend", "backend"}:
324
+ raise APError("Jenkins component must be frontend or backend.")
325
+ if component not in configured:
326
+ raise APError(f"Missing access.jenkins.{component} configuration.")
327
+ return component
328
+ explicit = _text(explicit_job_url).rstrip("/")
329
+ if explicit:
330
+ matches = [
331
+ candidate
332
+ for candidate in configured
333
+ if _text(_jenkins_access_cfg(cfg, candidate).get("url")).rstrip("/") == explicit
334
+ ]
335
+ if len(matches) == 1:
336
+ return matches[0]
337
+ if len(configured) == 1:
338
+ return configured[0]
339
+ if len(configured) > 1:
340
+ identities: set[tuple[str, str, str]] = set()
341
+ for candidate in configured:
342
+ lane = _jenkins_access_cfg(cfg, candidate)
343
+ try:
344
+ secret = _resolve_secret(f"access.jenkins.{candidate}", lane, "password")
345
+ except APError:
346
+ break
347
+ identities.add(
348
+ (
349
+ _text(lane.get("url")).rstrip("/"),
350
+ _text(lane.get("username")),
351
+ secret,
352
+ )
353
+ )
354
+ if len(identities) == 1:
355
+ return configured[0]
356
+ raise APError(
357
+ "Multiple access.jenkins endpoints are configured; pass --component frontend or backend."
358
+ )
359
+ return ""
360
+
361
+
362
+ def _jenkins_auth_config(cfg: dict, component: str = "") -> tuple[str, dict, str, str]:
363
+ if component:
364
+ lane = _jenkins_access_cfg(cfg, component)
365
+ if not _is_explicit_fill(lane.get("username")):
366
+ raise APError(f"Missing access.jenkins.{component}.username.")
367
+ return f"access.jenkins.{component}", lane, "username", "password"
368
+
265
369
  jenkins_cfg = (cfg.get("jenkins") or {})
266
370
  credential_pairs = [
267
371
  ("api_user", "api_password"),
268
372
  ("ui_username", "ui_password"),
269
373
  ]
270
374
  errors: list[str] = []
271
-
272
375
  for user_field, secret_field in credential_pairs:
273
376
  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
-
377
+ if _is_explicit_fill(user):
378
+ try:
379
+ _resolve_secret("jenkins", jenkins_cfg, secret_field)
380
+ except APError as exc:
381
+ errors.append(str(exc))
382
+ continue
383
+ return "jenkins", jenkins_cfg, user_field, secret_field
285
384
  detail = "\n- " + "\n- ".join(errors) if errors else ""
286
385
  raise APError(
287
386
  "Missing Jenkins API credentials. Configure jenkins.api_user with "
@@ -291,6 +390,15 @@ def _jenkins_basic_auth_headers(cfg: dict) -> dict:
291
390
  )
292
391
 
293
392
 
393
+ def _jenkins_basic_auth_headers(cfg: dict, component: str = "") -> dict:
394
+ section_name, section_cfg, user_field, secret_field = _jenkins_auth_config(cfg, component)
395
+ user = _text(section_cfg.get(user_field))
396
+ secret = _resolve_secret(section_name, section_cfg, secret_field)
397
+ raw = f"{user}:{secret}".encode("utf-8")
398
+ auth = base64.b64encode(raw).decode("ascii")
399
+ return {"Authorization": f"Basic {auth}"}
400
+
401
+
294
402
  def _http_error_body(exc: urllib.error.HTTPError) -> str:
295
403
  try:
296
404
  return exc.read().decode("utf-8", errors="replace").strip()
@@ -313,13 +421,14 @@ def _basic_auth_header(username: str, password: str) -> dict[str, str]:
313
421
  return {"Authorization": f"Basic {auth}"}
314
422
 
315
423
 
316
- def _jenkins_root_url(cfg: dict, job_url: str = "") -> str:
424
+ def _jenkins_root_url(cfg: dict, job_url: str = "", component: str = "") -> str:
317
425
  jenkins_cfg = (cfg.get("jenkins") or {})
318
- base_url = str(jenkins_cfg.get("base_url") or "").strip().rstrip("/")
426
+ lane_url = _text(_jenkins_access_cfg(cfg, component).get("url")) if component else ""
427
+ base_url = "" if component else str(jenkins_cfg.get("base_url") or "").strip().rstrip("/")
319
428
  if base_url:
320
429
  return base_url
321
430
 
322
- source = str(job_url or jenkins_cfg.get("job_url") or "").strip().rstrip("/")
431
+ source = str(job_url or lane_url or jenkins_cfg.get("job_url") or "").strip().rstrip("/")
323
432
  if not source:
324
433
  return ""
325
434
  if "/job/" in source:
@@ -327,23 +436,30 @@ def _jenkins_root_url(cfg: dict, job_url: str = "") -> str:
327
436
  return source
328
437
 
329
438
 
330
- def _jenkins_crumb_api_url(cfg: dict, job_url: str = "") -> str:
331
- root = _jenkins_root_url(cfg, job_url=job_url)
439
+ def _jenkins_crumb_api_url(cfg: dict, job_url: str = "", component: str = "") -> str:
440
+ root = _jenkins_root_url(cfg, job_url=job_url, component=component)
332
441
  if not root:
333
442
  return ""
334
443
  return root.rstrip("/") + "/crumbIssuer/api/json"
335
444
 
336
445
 
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)
446
+ def _jenkins_crumb_headers(
447
+ cfg: dict,
448
+ job_url: str = "",
449
+ timeout_s: int = 15,
450
+ component: str = "",
451
+ ) -> dict:
452
+ crumb_url = _jenkins_crumb_api_url(cfg, job_url=job_url, component=component)
339
453
  if not crumb_url:
340
454
  return {}
341
- cached = _JENKINS_CRUMB_CACHE.get(crumb_url)
455
+ _, auth_cfg, user_field, _ = _jenkins_auth_config(cfg, component)
456
+ cache_key = (crumb_url, _text(auth_cfg.get(user_field)))
457
+ cached = _JENKINS_CRUMB_CACHE.get(cache_key)
342
458
  if cached:
343
459
  return dict(cached)
344
460
 
345
461
  headers = {"Accept": "application/json"}
346
- headers.update(_jenkins_basic_auth_headers(cfg))
462
+ headers.update(_jenkins_basic_auth_headers(cfg, component))
347
463
  req = urllib.request.Request(crumb_url, headers=headers, method="GET")
348
464
  try:
349
465
  with urllib.request.urlopen(req, timeout=timeout_s) as resp:
@@ -370,13 +486,19 @@ def _jenkins_crumb_headers(cfg: dict, job_url: str = "", timeout_s: int = 15) ->
370
486
  return {}
371
487
 
372
488
  crumb_headers = {field: crumb}
373
- _JENKINS_CRUMB_CACHE[crumb_url] = crumb_headers
489
+ _JENKINS_CRUMB_CACHE[cache_key] = crumb_headers
374
490
  return dict(crumb_headers)
375
491
 
376
492
 
377
- def _jenkins_api_get_json(url: str, cfg: dict, timeout_s: int = 15, allow_404: bool = False) -> Optional[dict]:
493
+ def _jenkins_api_get_json(
494
+ url: str,
495
+ cfg: dict,
496
+ timeout_s: int = 15,
497
+ allow_404: bool = False,
498
+ component: str = "",
499
+ ) -> Optional[dict]:
378
500
  headers = {"Accept": "application/json"}
379
- headers.update(_jenkins_basic_auth_headers(cfg))
501
+ headers.update(_jenkins_basic_auth_headers(cfg, component))
380
502
  req = urllib.request.Request(url, headers=headers, method="GET")
381
503
  try:
382
504
  with urllib.request.urlopen(req, timeout=timeout_s) as resp:
@@ -386,7 +508,12 @@ def _jenkins_api_get_json(url: str, cfg: dict, timeout_s: int = 15, allow_404: b
386
508
  if exc.code == 404 and allow_404:
387
509
  return None
388
510
  if exc.code == 403:
389
- crumb_headers = _jenkins_crumb_headers(cfg, job_url=url, timeout_s=timeout_s)
511
+ crumb_headers = _jenkins_crumb_headers(
512
+ cfg,
513
+ job_url=url,
514
+ timeout_s=timeout_s,
515
+ component=component,
516
+ )
390
517
  if crumb_headers:
391
518
  retry_headers = dict(headers)
392
519
  retry_headers.update(crumb_headers)
@@ -494,12 +621,21 @@ def _jenkins_branch_job_urls(root_job_url: str, branch_name: str) -> List[str]:
494
621
  return urls
495
622
 
496
623
 
497
- def _resolve_jenkins_job_url(cfg: dict, job_name: str = "", job_url: str = "") -> str:
624
+ def _resolve_jenkins_job_url(
625
+ cfg: dict,
626
+ job_name: str = "",
627
+ job_url: str = "",
628
+ component: str = "",
629
+ ) -> str:
498
630
  jenkins_cfg = (cfg.get("jenkins") or {})
499
631
  explicit_url = str(job_url or "").strip()
500
632
  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()
633
+ configured_url = (
634
+ _text(_jenkins_access_cfg(cfg, component).get("url"))
635
+ if component
636
+ else str(jenkins_cfg.get("job_url") or "").strip()
637
+ )
638
+ base_url = _jenkins_root_url(cfg, component=component)
503
639
 
504
640
  if explicit_url:
505
641
  return explicit_url.rstrip("/")
@@ -508,13 +644,13 @@ def _resolve_jenkins_job_url(cfg: dict, job_name: str = "", job_url: str = "") -
508
644
  return _jenkins_job_url_from_name(base_url, requested_name)
509
645
  raise APError(
510
646
  f"Cannot resolve Jenkins job URL for job '{requested_name}'. "
511
- "Pass --job-url, or fill jenkins.base_url in docs/ENGINEERING.md."
647
+ "Pass --job-url, or fill the selected Jenkins endpoint in docs/ENGINEERING.md."
512
648
  )
513
649
  if configured_url:
514
650
  return configured_url.rstrip("/")
515
651
  raise APError(
516
- "Missing Jenkins job location. Fill jenkins.job_url in docs/ENGINEERING.md, "
517
- "or pass --job-url / --job-name explicitly."
652
+ "Missing Jenkins job location. Fill access.jenkins.<component>.url or "
653
+ "legacy jenkins.job_url, or pass --job-url / --job-name explicitly."
518
654
  )
519
655
 
520
656
 
@@ -526,6 +662,7 @@ def _resolve_jenkins_job_candidates(
526
662
  job_url: str = "",
527
663
  multibranch_root_job: str = "",
528
664
  branch_name: str = "",
665
+ component: str = "",
529
666
  ) -> List[str]:
530
667
  jenkins_cfg = (cfg.get("jenkins") or {})
531
668
  effective_branch = str(branch_name or "").strip()
@@ -537,25 +674,36 @@ def _resolve_jenkins_job_candidates(
537
674
 
538
675
  explicit_url = str(job_url or "").strip()
539
676
  explicit_name = str(job_name or "").strip()
540
- configured_url = str(jenkins_cfg.get("job_url") or "").strip()
677
+ configured_url = (
678
+ _text(_jenkins_access_cfg(cfg, component).get("url"))
679
+ if component
680
+ else str(jenkins_cfg.get("job_url") or "").strip()
681
+ )
541
682
 
542
683
  if effective_branch:
543
684
  if explicit_url:
544
685
  return _jenkins_branch_job_urls(explicit_url, effective_branch)
545
686
  if effective_root:
546
- base_url = str(jenkins_cfg.get("base_url") or "").strip()
687
+ base_url = _jenkins_root_url(cfg, component=component)
547
688
  return _jenkins_branch_job_urls(_jenkins_job_url_from_name(base_url, effective_root), effective_branch)
548
689
  if explicit_name:
549
- base_url = str(jenkins_cfg.get("base_url") or "").strip()
690
+ base_url = _jenkins_root_url(cfg, component=component)
550
691
  return _jenkins_branch_job_urls(_jenkins_job_url_from_name(base_url, explicit_name), effective_branch)
551
692
  if configured_url:
552
693
  return _jenkins_branch_job_urls(configured_url, effective_branch)
553
694
  raise APError(
554
695
  "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."
696
+ "--branch-name, or pass --multibranch-root-job with a configured Jenkins endpoint."
556
697
  )
557
698
 
558
- return [_resolve_jenkins_job_url(cfg, job_name=job_name, job_url=job_url)]
699
+ return [
700
+ _resolve_jenkins_job_url(
701
+ cfg,
702
+ job_name=job_name,
703
+ job_url=job_url,
704
+ component=component,
705
+ )
706
+ ]
559
707
 
560
708
 
561
709
  def _jenkins_build_api_url(job_url: str, build_number: int) -> str:
@@ -785,7 +933,14 @@ def _converged_engineering_document(repo: Path, template_path: Path) -> str:
785
933
  ("concurrency", "delete_remote_branch"),
786
934
  ("validation", "max_command_seconds"),
787
935
  ("validation", "max_total_seconds"),
936
+ ("structure", "enabled"),
937
+ ("structure", "enforcement"),
788
938
  ("structure", "architecture_standard"),
939
+ ("structure", "layer_rules", "enabled"),
940
+ ("structure", "layer_rules", "block"),
941
+ ("optimization", "completion_policy"),
942
+ ("optimization", "require_baseline_for_global_review"),
943
+ ("optimization", "report_accepted_debt_as_findings"),
789
944
  ("docs", "api_docs_required"),
790
945
  ]
791
946
  for field_path in preserve_scalar_paths:
@@ -823,6 +978,26 @@ def _converged_engineering_document(repo: Path, template_path: Path) -> str:
823
978
  _mapping(current_cfg.get("risk")).get("rules")
824
979
  )
825
980
  current_structure = _mapping(current_cfg.get("structure"))
981
+ for key in ("exclude", "allow_large_files", "reusable_tool_dirs"):
982
+ if isinstance(current_structure.get(key), list):
983
+ converged["structure"][key] = _string_list(current_structure.get(key))
984
+ for key in (
985
+ "max_file_lines_warn",
986
+ "max_file_lines_block",
987
+ "max_function_lines_warn",
988
+ "max_added_lines_to_large_file",
989
+ ):
990
+ value = current_structure.get(key)
991
+ if isinstance(value, int) and not isinstance(value, bool):
992
+ converged["structure"][key] = value
993
+ for key in (
994
+ "require_reuse_search",
995
+ "block_new_responsibility_in_large_file",
996
+ "block_warnings",
997
+ ):
998
+ value = current_structure.get(key)
999
+ if isinstance(value, bool):
1000
+ converged["structure"][key] = value
826
1001
  converged["structure"]["accepted_debt_paths"] = _string_list(
827
1002
  current_structure.get("accepted_debt_paths")
828
1003
  )
@@ -973,8 +1148,8 @@ def _migrate_fast_development_defaults(cfg: dict, repo: Path) -> list[str]:
973
1148
  if _text(workflow_cfg.get("completion")).lower() != "push":
974
1149
  workflow_cfg["completion"] = "push"
975
1150
  changed.append("workflow.completion")
976
- if _text(workflow_cfg.get("skill_version")) != "4.2.1":
977
- workflow_cfg["skill_version"] = "4.2.1"
1151
+ if _text(workflow_cfg.get("skill_version")) != "4.2.3":
1152
+ workflow_cfg["skill_version"] = "4.2.3"
978
1153
  changed.append("workflow.skill_version")
979
1154
 
980
1155
  commands_cfg = cfg.setdefault("commands", {})
@@ -1287,16 +1462,16 @@ def cmd_upgrade(args: argparse.Namespace) -> None:
1287
1462
  if current_agents:
1288
1463
  archive_dir = repo / "docs" / "archive" / "workflow"
1289
1464
  archive_header = (
1290
- "# Archived AGENTS.md before auto-coding-skill 4.2.1\n\n"
1465
+ "# Archived AGENTS.md before auto-coding-skill 4.2.3\n\n"
1291
1466
  "This file is historical and non-authoritative. The root AGENTS.md is fully managed.\n"
1292
1467
  "Move any still-current project facts into docs/ENGINEERING.md or docs/project/,\n"
1293
1468
  "without copying workflow rules back into the root AGENTS.md.\n\n---\n\n"
1294
1469
  )
1295
1470
  archive_content = archive_header + current_agents
1296
- archive = archive_dir / "AGENTS.pre-4.2.1.md"
1471
+ archive = archive_dir / "AGENTS.pre-4.2.3.md"
1297
1472
  if archive.exists() and archive.read_text(encoding="utf-8") != archive_content:
1298
1473
  digest = hashlib.sha256(current_agents.encode("utf-8")).hexdigest()[:12]
1299
- archive = archive_dir / f"AGENTS.pre-4.2.1-{digest}.md"
1474
+ archive = archive_dir / f"AGENTS.pre-4.2.3-{digest}.md"
1300
1475
  if not archive.exists():
1301
1476
  add_action("policy", archive, "archive", "historical and non-authoritative")
1302
1477
  if write:
@@ -2342,6 +2517,7 @@ def _validate_task_manifest(repo: Path, manifest: dict, expected_task_id: str =
2342
2517
  "pending",
2343
2518
  "approved",
2344
2519
  "changes-requested",
2520
+ "blocked",
2345
2521
  }:
2346
2522
  raise APError(f"Task {task_id} has an invalid review contract.")
2347
2523
  review_required = manifest.get("review_required", schema < 3)
@@ -2356,6 +2532,13 @@ def _validate_task_manifest(repo: Path, manifest: dict, expected_task_id: str =
2356
2532
  effective_profile = _text(manifest.get("effective_profile"))
2357
2533
  if effective_profile and effective_profile not in (_WORKFLOW_PROFILES - {"auto"}):
2358
2534
  raise APError(f"Task {task_id} has an invalid effective_profile.")
2535
+ review_depth = _text(manifest.get("review_depth"))
2536
+ if review_depth and review_depth not in {"none", "focused", "deep"}:
2537
+ raise APError(f"Task {task_id} has an invalid review_depth.")
2538
+ if "review_timeout_seconds" in manifest:
2539
+ timeout_value = manifest.get("review_timeout_seconds")
2540
+ if isinstance(timeout_value, bool) or not isinstance(timeout_value, int) or timeout_value < 0:
2541
+ raise APError(f"Task {task_id} has an invalid review_timeout_seconds.")
2359
2542
  if "design_required" in manifest and not isinstance(manifest.get("design_required"), bool):
2360
2543
  raise APError(f"Task {task_id} has an invalid design_required flag.")
2361
2544
  if "scope_history" in manifest and not isinstance(manifest.get("scope_history"), list):
@@ -3004,16 +3187,25 @@ def _reconcile_task_risk(repo: Path, cfg: dict, manifest: dict) -> None:
3004
3187
  )
3005
3188
  review_required = bool(manifest.get("review_required") or plan.get("review_required"))
3006
3189
  design_required = bool(manifest.get("design_required") or plan.get("design_required"))
3190
+ review_depth, review_timeout_seconds = _normalized_task_review_policy(
3191
+ review_required,
3192
+ manifest.get("review_depth"),
3193
+ plan.get("review_depth"),
3194
+ )
3007
3195
  escalated = (
3008
3196
  effective_profile != old_profile
3009
3197
  or review_required != bool(manifest.get("review_required"))
3010
3198
  or design_required != bool(manifest.get("design_required"))
3199
+ or review_depth != (_text(manifest.get("review_depth")) or "none")
3200
+ or review_timeout_seconds != int(manifest.get("review_timeout_seconds") or 0)
3011
3201
  )
3012
3202
  if not escalated:
3013
3203
  return
3014
3204
  manifest["effective_profile"] = effective_profile
3015
3205
  manifest["review_required"] = review_required
3016
3206
  manifest["design_required"] = design_required
3207
+ manifest["review_depth"] = review_depth
3208
+ manifest["review_timeout_seconds"] = review_timeout_seconds
3017
3209
  _invalidate_task_review(manifest, "actual changed paths raised task risk; review again")
3018
3210
  _clear_final_gate_receipt(repo)
3019
3211
  _save_task_manifest(repo, manifest)
@@ -3271,6 +3463,8 @@ _DEFAULT_FULL_PATH_PATTERNS = [
3271
3463
  "compose*.yaml",
3272
3464
  "docs/ENGINEERING.md",
3273
3465
  "docs/tools/autopipeline/**",
3466
+ "package.json",
3467
+ "**/package.json",
3274
3468
  "package-lock.json",
3275
3469
  "pnpm-lock.yaml",
3276
3470
  "yarn.lock",
@@ -3689,6 +3883,25 @@ def _select_gate_scope(cfg: dict, requested_scope: str, paths: list[str]) -> tup
3689
3883
  return "changed", [reason], matching_rules
3690
3884
 
3691
3885
 
3886
+ def _select_structure_scope(
3887
+ cfg: dict,
3888
+ repo: Path,
3889
+ requested_scope: str,
3890
+ base_ref: str,
3891
+ ) -> str:
3892
+ """Keep repository-wide structure scans explicit while honoring them."""
3893
+ requested = _text(requested_scope).lower()
3894
+ if requested == "full":
3895
+ return "full"
3896
+ impact = _impact_summary(
3897
+ cfg,
3898
+ repo,
3899
+ requested_scope=requested,
3900
+ base_ref=base_ref,
3901
+ )
3902
+ return str(impact["selected_scope"])
3903
+
3904
+
3692
3905
  def _impact_summary(
3693
3906
  cfg: dict,
3694
3907
  repo: Path,
@@ -3930,16 +4143,27 @@ _TEXT_SOURCE_FILENAMES = {
3930
4143
  "tsconfig.json",
3931
4144
  }
3932
4145
  _FUNCTION_START_RE = re.compile(
3933
- r"^\s*(?:export\s+)?(?:async\s+)?(?:def|function|func)\s+[A-Za-z_][\w]*\b"
4146
+ r"^\s*(?:export\s+)?(?:async\s+)?(?:def|function)\s+[A-Za-z_][\w]*\b"
4147
+ r"|^\s*func\s+(?:\([^)]*\)\s*)?[A-Za-z_][\w]*\b"
3934
4148
  r"|^\s*(?:public|private|protected|static|final|async|\s)+\s*[\w<>\[\], ?]+\s+[A-Za-z_]\w*\s*\([^;]*\)\s*\{"
3935
- r"|^\s*(?:export\s+)?(?:const|let|var)\s+[A-Za-z_]\w*\s*=\s*(?:async\s*)?\([^)]*\)\s*=>"
4149
+ r"|^\s*(?:export\s+)?(?:const|let|var)\s+[A-Za-z_]\w*\s*=\s*(?:async\s+)?"
4150
+ r"(?:\([^)]*\)|[A-Za-z_]\w*)\s*(?::\s*[^=]+)?=>"
3936
4151
  )
4152
+ _ARROW_DECLARATION_RE = re.compile(
4153
+ r"^\s*(?:export\s+)?(?:const|let|var)\s+[A-Za-z_]\w*\s*=\s*(?:async\s+)?"
4154
+ )
4155
+ _ARROW_FUNCTION_BODY_RE = re.compile(r"=>\s*(?::\s*[^=]+)?\{")
3937
4156
  _IMPORT_PATTERNS = [
3938
4157
  re.compile(r"^\s*import\s+(?:.+?\s+from\s+)?[\"']([^\"']+)[\"']"),
3939
4158
  re.compile(r"\brequire\(\s*[\"']([^\"']+)[\"']\s*\)"),
3940
4159
  re.compile(r"\bimport\(\s*[\"']([^\"']+)[\"']\s*\)"),
3941
4160
  re.compile(r"^\s*from\s+([A-Za-z_][\w.]*)\s+import\b"),
3942
- re.compile(r"^\s*import\s+([A-Za-z_][\w.]*)(?:\s+as\s+\w+)?\s*$"),
4161
+ re.compile(
4162
+ r"^\s*import\s+(?:static\s+)?"
4163
+ r"([A-Za-z_]\w*(?:\.[A-Za-z_]\w*)*(?:\.\*)?)"
4164
+ r"(?:\s+as\s+[A-Za-z_]\w*)?\s*;?\s*"
4165
+ r"(?://.*|/\*.*)?$"
4166
+ ),
3943
4167
  re.compile(r"^\s*import\s+[\"']([^\"']+)[\"']\s*$"),
3944
4168
  re.compile(r"^\s*[\"']([^\"']+/[^\"']*)[\"']\s*$"),
3945
4169
  ]
@@ -4078,10 +4302,17 @@ def _is_structure_candidate(path: str, structure_cfg: dict) -> bool:
4078
4302
 
4079
4303
  def _structure_paths_for_scope(repo: Path, scope: str, base_ref: str, structure_cfg: dict) -> list[str]:
4080
4304
  if scope == "full":
4081
- paths = _tracked_files(repo)
4305
+ paths = _unique_paths(
4306
+ _tracked_files(repo)
4307
+ + _git_lines(repo, ["git", "ls-files", "--others", "--exclude-standard"])
4308
+ )
4082
4309
  else:
4083
4310
  paths = _changed_files(repo, base_ref=base_ref)
4084
- return [path for path in paths if _is_structure_candidate(path, structure_cfg)]
4311
+ return [
4312
+ path
4313
+ for path in paths
4314
+ if (repo / path).is_file() and _is_structure_candidate(path, structure_cfg)
4315
+ ]
4085
4316
 
4086
4317
 
4087
4318
  def _read_text_lines(repo: Path, path: str) -> Optional[list[str]]:
@@ -4134,19 +4365,531 @@ def _added_lines_by_path(repo: Path, base_ref: str = "") -> dict[str, int]:
4134
4365
  return added
4135
4366
 
4136
4367
 
4137
- def _function_size_warnings(path: str, lines: list[str], threshold: int) -> list[str]:
4368
+ def _ensure_structure_deadline(deadline: Optional[float]) -> None:
4369
+ if deadline is not None and time.monotonic() >= deadline:
4370
+ raise APError("Final changed-scope gate timed out during structure check.")
4371
+
4372
+
4373
+ def _looks_like_regex_start(line: str, index: int) -> bool:
4374
+ prefix = line[:index].rstrip()
4375
+ if not prefix:
4376
+ return True
4377
+ if prefix.endswith(("=", "(", "[", "{", ",", ":", ";", "!", "?", "=>")):
4378
+ return True
4379
+ return bool(re.search(r"\b(?:return|case|throw|yield)\s*$", prefix))
4380
+
4381
+
4382
+ def _python_function_end(
4383
+ lines: list[str],
4384
+ start: int,
4385
+ threshold: int,
4386
+ deadline: Optional[float],
4387
+ ) -> tuple[int, bool]:
4388
+ """Best-effort range for temporarily invalid Python during an edit."""
4389
+ indent = len(lines[start]) - len(lines[start].lstrip())
4390
+ limit = min(len(lines), start + threshold + 1)
4391
+ body_start: Optional[int] = None
4392
+ for index in range(start, limit):
4393
+ if (index - start) % 32 == 0:
4394
+ _ensure_structure_deadline(deadline)
4395
+ header = re.search(r"\)\s*(?:->\s*.*?)?\s*:", lines[index])
4396
+ if not header:
4397
+ continue
4398
+ tail = lines[index][header.end() :].strip()
4399
+ if tail and not tail.startswith("#"):
4400
+ return index + 1, False
4401
+ body_start = index + 1
4402
+ break
4403
+ if body_start is None:
4404
+ return limit, limit < len(lines)
4405
+
4406
+ end = body_start
4407
+ for index in range(body_start, limit):
4408
+ if (index - body_start) % 32 == 0:
4409
+ _ensure_structure_deadline(deadline)
4410
+ stripped = lines[index].strip()
4411
+ if not stripped or stripped.startswith("#"):
4412
+ continue
4413
+ current_indent = len(lines[index]) - len(lines[index].lstrip())
4414
+ if current_indent <= indent:
4415
+ return end, False
4416
+ end = index + 1
4417
+ return limit if limit < len(lines) else end, limit < len(lines)
4418
+
4419
+
4420
+ def _python_function_ranges(
4421
+ lines: list[str],
4422
+ threshold: int,
4423
+ deadline: Optional[float],
4424
+ ) -> list[tuple[int, int, bool]]:
4425
+ _ensure_structure_deadline(deadline)
4426
+ try:
4427
+ tree = ast.parse("\n".join(lines))
4428
+ except (SyntaxError, ValueError):
4429
+ ranges = []
4430
+ for start, line in enumerate(lines):
4431
+ if not re.match(r"^\s*(?:async\s+)?def\s+[A-Za-z_]\w*\b", line):
4432
+ continue
4433
+ end, truncated = _python_function_end(lines, start, threshold, deadline)
4434
+ ranges.append((start, end, truncated))
4435
+ return ranges
4436
+
4437
+ _ensure_structure_deadline(deadline)
4438
+ ranges = []
4439
+ for node in ast.walk(tree):
4440
+ if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
4441
+ continue
4442
+ start = max(0, int(node.lineno) - 1)
4443
+ end = int(getattr(node, "end_lineno", 0) or node.lineno)
4444
+ ranges.append((start, end, False))
4445
+ return sorted(ranges)
4446
+
4447
+
4448
+ def _find_arrow_line(
4449
+ lines: list[str],
4450
+ start: int,
4451
+ deadline: Optional[float],
4452
+ ) -> Optional[int]:
4453
+ """Find a declaration's top-level arrow, ignoring arrows inside parameters."""
4454
+ state = "code"
4455
+ escaped = False
4456
+ regex_char_class = False
4457
+ paren_depth = 0
4458
+ bracket_depth = 0
4459
+ brace_depth = 0
4460
+ indent = len(lines[start]) - len(lines[start].lstrip())
4461
+ limit = min(len(lines), start + 200)
4462
+ equals = lines[start].find("=")
4463
+ for line_index in range(start, limit):
4464
+ if (line_index - start) % 32 == 0:
4465
+ _ensure_structure_deadline(deadline)
4466
+ line = lines[line_index]
4467
+ if line_index > start:
4468
+ stripped = line.strip()
4469
+ current_indent = len(line) - len(line.lstrip())
4470
+ if stripped and current_indent <= indent and not (paren_depth or bracket_depth or brace_depth):
4471
+ return None
4472
+ char_index = equals + 1 if line_index == start and equals >= 0 else 0
4473
+ while char_index < len(line):
4474
+ char = line[char_index]
4475
+ next_char = line[char_index + 1] if char_index + 1 < len(line) else ""
4476
+ if state == "block_comment":
4477
+ if char == "*" and next_char == "/":
4478
+ state = "code"
4479
+ char_index += 2
4480
+ continue
4481
+ char_index += 1
4482
+ continue
4483
+ if state == "regex":
4484
+ if escaped:
4485
+ escaped = False
4486
+ elif char == "\\":
4487
+ escaped = True
4488
+ elif char == "[":
4489
+ regex_char_class = True
4490
+ elif char == "]":
4491
+ regex_char_class = False
4492
+ elif char == "/" and not regex_char_class:
4493
+ state = "code"
4494
+ char_index += 1
4495
+ continue
4496
+ if state in {"single_quote", "double_quote", "backtick"}:
4497
+ quote = {"single_quote": "'", "double_quote": '"', "backtick": "`"}[state]
4498
+ if escaped:
4499
+ escaped = False
4500
+ elif char == "\\":
4501
+ escaped = True
4502
+ elif char == quote:
4503
+ state = "code"
4504
+ char_index += 1
4505
+ continue
4506
+ if char == "/" and next_char == "/":
4507
+ break
4508
+ if char == "/" and next_char == "*":
4509
+ state = "block_comment"
4510
+ char_index += 2
4511
+ continue
4512
+ if char == "/" and _looks_like_regex_start(line, char_index):
4513
+ state = "regex"
4514
+ regex_char_class = False
4515
+ escaped = False
4516
+ char_index += 1
4517
+ continue
4518
+ if char in {"'", '"', "`"}:
4519
+ state = {"'": "single_quote", '"': "double_quote", "`": "backtick"}[char]
4520
+ escaped = False
4521
+ elif char == "(":
4522
+ paren_depth += 1
4523
+ elif char == ")":
4524
+ paren_depth = max(0, paren_depth - 1)
4525
+ elif char == "[":
4526
+ bracket_depth += 1
4527
+ elif char == "]":
4528
+ bracket_depth = max(0, bracket_depth - 1)
4529
+ elif char == "{":
4530
+ brace_depth += 1
4531
+ elif char == "}":
4532
+ brace_depth = max(0, brace_depth - 1)
4533
+ elif char == "=" and next_char == ">" and not (paren_depth or bracket_depth or brace_depth):
4534
+ return line_index
4535
+ elif char == ";" and not (paren_depth or bracket_depth or brace_depth):
4536
+ return None
4537
+ char_index += 1
4538
+ if line_index > start:
4539
+ stripped = line.strip()
4540
+ current_indent = len(line) - len(line.lstrip())
4541
+ if stripped and current_indent <= indent and not (paren_depth or bracket_depth or brace_depth):
4542
+ return None
4543
+ return None
4544
+
4545
+
4546
+ def _arrow_body_kind(lines: list[str], arrow_line: int) -> str:
4547
+ arrow_column = lines[arrow_line].find("=>")
4548
+ for line_index in range(arrow_line, min(len(lines), arrow_line + 20)):
4549
+ text = lines[line_index][arrow_column + 2 :] if line_index == arrow_line else lines[line_index]
4550
+ stripped = text.strip()
4551
+ if not stripped or stripped.startswith(("//", "/*", "*")):
4552
+ continue
4553
+ return "block" if stripped.startswith("{") else "expression"
4554
+ return "expression"
4555
+
4556
+
4557
+ def _looks_like_return_type_brace(line: str, index: int) -> bool:
4558
+ prefix = line[:index].rstrip()
4559
+ if re.search(r"\b(?:struct|interface)\s*$", prefix):
4560
+ return True
4561
+ close_paren = prefix.rfind(")")
4562
+ return close_paren >= 0 and ":" in prefix[close_paren + 1 :]
4563
+
4564
+
4565
+ def _brace_function_end(
4566
+ lines: list[str],
4567
+ start: int,
4568
+ threshold: int,
4569
+ deadline: Optional[float],
4570
+ arrow_line: Optional[int] = None,
4571
+ ) -> Optional[tuple[int, bool]]:
4572
+ depth = 0
4573
+ opened = False
4574
+ state = "code"
4575
+ escaped = False
4576
+ regex_char_class = False
4577
+ paren_depth = 0
4578
+ bracket_depth = 0
4579
+ type_brace_depth = 0
4580
+ arrow_seen = arrow_line is None
4581
+ limit = min(len(lines), start + threshold + 1)
4582
+
4583
+ for line_index in range(start, limit):
4584
+ if (line_index - start) % 32 == 0:
4585
+ _ensure_structure_deadline(deadline)
4586
+ line = lines[line_index]
4587
+ char_index = 0
4588
+ while char_index < len(line):
4589
+ char = line[char_index]
4590
+ next_char = line[char_index + 1] if char_index + 1 < len(line) else ""
4591
+
4592
+ if state == "block_comment":
4593
+ if char == "*" and next_char == "/":
4594
+ state = "code"
4595
+ char_index += 2
4596
+ continue
4597
+ char_index += 1
4598
+ continue
4599
+ if state == "regex":
4600
+ if escaped:
4601
+ escaped = False
4602
+ elif char == "\\":
4603
+ escaped = True
4604
+ elif char == "[":
4605
+ regex_char_class = True
4606
+ elif char == "]":
4607
+ regex_char_class = False
4608
+ elif char == "/" and not regex_char_class:
4609
+ state = "code"
4610
+ char_index += 1
4611
+ continue
4612
+ if state in {"single_quote", "double_quote"}:
4613
+ if escaped:
4614
+ escaped = False
4615
+ elif char == "\\":
4616
+ escaped = True
4617
+ elif (state == "single_quote" and char == "'") or (
4618
+ state == "double_quote" and char == '"'
4619
+ ):
4620
+ state = "code"
4621
+ char_index += 1
4622
+ continue
4623
+ if state == "backtick":
4624
+ if escaped:
4625
+ escaped = False
4626
+ elif char == "\\":
4627
+ escaped = True
4628
+ elif char == "`":
4629
+ state = "code"
4630
+ char_index += 1
4631
+ continue
4632
+
4633
+ if char == "/" and next_char == "/":
4634
+ break
4635
+ if char == "/" and next_char == "*":
4636
+ state = "block_comment"
4637
+ char_index += 2
4638
+ continue
4639
+ if char == "/" and _looks_like_regex_start(line, char_index):
4640
+ state = "regex"
4641
+ regex_char_class = False
4642
+ escaped = False
4643
+ char_index += 1
4644
+ continue
4645
+ if char == "=" and next_char == ">":
4646
+ if arrow_line is not None and line_index == arrow_line:
4647
+ arrow_seen = True
4648
+ char_index += 2
4649
+ continue
4650
+ if char == "'":
4651
+ state = "single_quote"
4652
+ escaped = False
4653
+ elif char == '"':
4654
+ state = "double_quote"
4655
+ escaped = False
4656
+ elif char == "`":
4657
+ state = "backtick"
4658
+ escaped = False
4659
+ elif not opened and char == "(":
4660
+ paren_depth += 1
4661
+ elif not opened and char == ")":
4662
+ paren_depth = max(0, paren_depth - 1)
4663
+ elif not opened and char == "[":
4664
+ bracket_depth += 1
4665
+ elif not opened and char == "]":
4666
+ bracket_depth = max(0, bracket_depth - 1)
4667
+ elif char == "{":
4668
+ if not opened:
4669
+ if not arrow_seen:
4670
+ char_index += 1
4671
+ continue
4672
+ if arrow_line is None and (paren_depth > 0 or bracket_depth > 0):
4673
+ char_index += 1
4674
+ continue
4675
+ if type_brace_depth > 0:
4676
+ type_brace_depth += 1
4677
+ char_index += 1
4678
+ continue
4679
+ if arrow_line is None and _looks_like_return_type_brace(line, char_index):
4680
+ type_brace_depth = 1
4681
+ char_index += 1
4682
+ continue
4683
+ opened = True
4684
+ depth += 1
4685
+ elif char == "}" and not opened and type_brace_depth > 0:
4686
+ type_brace_depth -= 1
4687
+ elif char == "}" and opened:
4688
+ depth -= 1
4689
+ if depth == 0:
4690
+ return line_index + 1, False
4691
+ char_index += 1
4692
+ if limit < len(lines):
4693
+ return limit, True
4694
+ return None
4695
+
4696
+
4697
+ _EXPRESSION_CONTINUATION_SUFFIXES = (
4698
+ "?", ":", ".", ",", "+", "-", "*", "/", "%", "&&", "||", "??", "=>",
4699
+ )
4700
+ _EXPRESSION_CONTINUATION_PREFIXES = (
4701
+ ".", "?.", "+", "-", "*", "/", "%", "&&", "||", "??", "?", ":", ",",
4702
+ )
4703
+ _JSX_TAG_RE = re.compile(r"</?>|</?[A-Za-z][A-Za-z0-9_.:-]*(?:\s[^<>]*?)?/?>")
4704
+
4705
+
4706
+ def _expression_arrow_end(
4707
+ lines: list[str],
4708
+ start: int,
4709
+ arrow_line: int,
4710
+ threshold: int,
4711
+ deadline: Optional[float],
4712
+ suffix: str,
4713
+ ) -> tuple[int, bool]:
4714
+ indent = len(lines[start]) - len(lines[start].lstrip())
4715
+ limit = min(len(lines), start + threshold + 1)
4716
+ state = "code"
4717
+ escaped = False
4718
+ regex_char_class = False
4719
+ paren_depth = bracket_depth = brace_depth = 0
4720
+ jsx_mode = False
4721
+ jsx_depth = 0
4722
+ saw_jsx_tag = False
4723
+ arrow_column = lines[arrow_line].find("=>")
4724
+
4725
+ for line_index in range(arrow_line, limit):
4726
+ if (line_index - arrow_line) % 32 == 0:
4727
+ _ensure_structure_deadline(deadline)
4728
+ line = lines[line_index]
4729
+ char_index = arrow_column + 2 if line_index == arrow_line else 0
4730
+ visible: list[str] = []
4731
+ top_level_semicolon = False
4732
+ while char_index < len(line):
4733
+ char = line[char_index]
4734
+ next_char = line[char_index + 1] if char_index + 1 < len(line) else ""
4735
+ if state == "block_comment":
4736
+ if char == "*" and next_char == "/":
4737
+ state = "code"
4738
+ char_index += 2
4739
+ continue
4740
+ char_index += 1
4741
+ continue
4742
+ if state == "regex":
4743
+ if escaped:
4744
+ escaped = False
4745
+ elif char == "\\":
4746
+ escaped = True
4747
+ elif char == "[":
4748
+ regex_char_class = True
4749
+ elif char == "]":
4750
+ regex_char_class = False
4751
+ elif char == "/" and not regex_char_class:
4752
+ state = "code"
4753
+ char_index += 1
4754
+ continue
4755
+ if state in {"single_quote", "double_quote", "backtick"}:
4756
+ quote = {"single_quote": "'", "double_quote": '"', "backtick": "`"}[state]
4757
+ if escaped:
4758
+ escaped = False
4759
+ elif char == "\\":
4760
+ escaped = True
4761
+ elif char == quote:
4762
+ state = "code"
4763
+ char_index += 1
4764
+ continue
4765
+ if char == "/" and next_char == "/":
4766
+ break
4767
+ if char == "/" and next_char == "*":
4768
+ state = "block_comment"
4769
+ char_index += 2
4770
+ continue
4771
+ if char == "/" and _looks_like_regex_start(line, char_index):
4772
+ state = "regex"
4773
+ regex_char_class = False
4774
+ escaped = False
4775
+ visible.append(" ")
4776
+ char_index += 1
4777
+ continue
4778
+ if char in {"'", '"', "`"}:
4779
+ state = {"'": "single_quote", '"': "double_quote", "`": "backtick"}[char]
4780
+ escaped = False
4781
+ visible.append(" ")
4782
+ else:
4783
+ visible.append(char)
4784
+ if char == "(":
4785
+ paren_depth += 1
4786
+ elif char == ")":
4787
+ paren_depth = max(0, paren_depth - 1)
4788
+ elif char == "[":
4789
+ bracket_depth += 1
4790
+ elif char == "]":
4791
+ bracket_depth = max(0, bracket_depth - 1)
4792
+ elif char == "{":
4793
+ brace_depth += 1
4794
+ elif char == "}":
4795
+ brace_depth = max(0, brace_depth - 1)
4796
+ elif char == ";" and not (paren_depth or bracket_depth or brace_depth):
4797
+ top_level_semicolon = True
4798
+ char_index += 1
4799
+
4800
+ code = "".join(visible).strip()
4801
+ if suffix in {".jsx", ".tsx"} and not jsx_mode and code.startswith("<") and not code.startswith(("<=", "<<")):
4802
+ jsx_mode = True
4803
+ if jsx_mode:
4804
+ for match in _JSX_TAG_RE.finditer(code):
4805
+ token = match.group(0)
4806
+ saw_jsx_tag = True
4807
+ if token.startswith("</"):
4808
+ jsx_depth = max(0, jsx_depth - 1)
4809
+ elif token not in {"</>"} and not token.endswith("/>"):
4810
+ jsx_depth += 1
4811
+
4812
+ if paren_depth or bracket_depth or brace_depth or jsx_depth > 0:
4813
+ continue
4814
+ if top_level_semicolon:
4815
+ return line_index + 1, False
4816
+ if jsx_mode and saw_jsx_tag:
4817
+ return line_index + 1, False
4818
+
4819
+ next_index = line_index + 1
4820
+ while next_index < len(lines) and not lines[next_index].strip():
4821
+ next_index += 1
4822
+ if next_index >= len(lines):
4823
+ return line_index + 1, False
4824
+ next_text = lines[next_index].strip()
4825
+ next_indent = len(lines[next_index]) - len(lines[next_index].lstrip())
4826
+ if code.endswith(_EXPRESSION_CONTINUATION_SUFFIXES):
4827
+ continue
4828
+ if next_indent > indent:
4829
+ continue
4830
+ if next_text.startswith(_EXPRESSION_CONTINUATION_PREFIXES):
4831
+ continue
4832
+ if jsx_mode and next_text.startswith(("</", ">")):
4833
+ continue
4834
+ return line_index + 1, False
4835
+
4836
+ return limit, limit < len(lines)
4837
+
4838
+
4839
+ def _function_size_warnings(
4840
+ path: str,
4841
+ lines: list[str],
4842
+ threshold: int,
4843
+ deadline: Optional[float] = None,
4844
+ ) -> list[str]:
4138
4845
  if threshold <= 0:
4139
4846
  return []
4140
- starts: list[int] = []
4141
- for index, line in enumerate(lines):
4142
- if _FUNCTION_START_RE.search(line):
4143
- starts.append(index)
4847
+ suffix = Path(path).suffix.lower()
4848
+ if suffix == ".py":
4849
+ ranges = _python_function_ranges(lines, threshold, deadline)
4850
+ else:
4851
+ candidates: dict[int, Optional[int]] = {}
4852
+ for index, line in enumerate(lines):
4853
+ if index % 256 == 0:
4854
+ _ensure_structure_deadline(deadline)
4855
+ if _ARROW_DECLARATION_RE.search(line):
4856
+ arrow_line = _find_arrow_line(lines, index, deadline)
4857
+ if arrow_line is not None:
4858
+ candidates[index] = arrow_line
4859
+ continue
4860
+ if _ARROW_FUNCTION_BODY_RE.search(line):
4861
+ candidates[index] = index
4862
+ elif Path(path).name == "Jenkinsfile":
4863
+ if re.match(r"^\s*def\s+[A-Za-z_]\w*\s*\(", line):
4864
+ candidates[index] = None
4865
+ elif _FUNCTION_START_RE.search(line):
4866
+ candidates[index] = None
4867
+
4868
+ ranges = []
4869
+ for start, arrow_line in sorted(candidates.items()):
4870
+ _ensure_structure_deadline(deadline)
4871
+ if arrow_line is not None and _arrow_body_kind(lines, arrow_line) == "expression":
4872
+ end, truncated = _expression_arrow_end(
4873
+ lines, start, arrow_line, threshold, deadline, suffix
4874
+ )
4875
+ ranges.append((start, end, truncated))
4876
+ continue
4877
+ result = _brace_function_end(
4878
+ lines, start, threshold, deadline, arrow_line=arrow_line
4879
+ )
4880
+ if result is not None:
4881
+ end, truncated = result
4882
+ ranges.append((start, end, truncated))
4883
+
4144
4884
  warnings: list[str] = []
4145
- for pos, start in enumerate(starts):
4146
- end = starts[pos + 1] if pos + 1 < len(starts) else len(lines)
4885
+ for start, end, truncated in ranges:
4147
4886
  size = end - start
4148
- if size > threshold:
4149
- warnings.append(f"{path}:{start + 1} function-like block has {size} lines (warn>{threshold})")
4887
+ if size <= threshold:
4888
+ continue
4889
+ qualifier = "at least " if truncated else ""
4890
+ warnings.append(
4891
+ f"{path}:{start + 1} function-like block has {qualifier}{size} lines (warn>{threshold})"
4892
+ )
4150
4893
  return warnings
4151
4894
 
4152
4895
 
@@ -4797,9 +5540,9 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
4797
5540
  ensure_git_repo(repo)
4798
5541
  cfg = _load_cfg(repo)
4799
5542
  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
5543
  base_ref = str(getattr(args, "base", "") or "")
5544
+ deadline = getattr(args, "deadline", None)
5545
+ selected_scope = _select_structure_scope(cfg, repo, requested_scope, base_ref)
4803
5546
 
4804
5547
  structure_cfg = _structure_cfg(cfg)
4805
5548
  optimization_cfg = _optimization_cfg(cfg)
@@ -4811,6 +5554,9 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
4811
5554
  warn_function_lines = _int_config(structure_cfg.get("max_function_lines_warn"), 120)
4812
5555
  max_added_to_large = _int_config(structure_cfg.get("max_added_lines_to_large_file"), 80)
4813
5556
  block_large_growth = _bool_config(structure_cfg.get("block_new_responsibility_in_large_file"), True)
5557
+ block_warnings = enforcement == "blocking" and _bool_config(
5558
+ structure_cfg.get("block_warnings"), False
5559
+ )
4814
5560
  layer_cfg = _layer_rules_config(structure_cfg)
4815
5561
  block_layer_violations = _bool_config(layer_cfg.get("block"), True)
4816
5562
 
@@ -4822,12 +5568,14 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
4822
5568
  inspected = 0
4823
5569
 
4824
5570
  for path in paths:
5571
+ _ensure_structure_deadline(deadline)
4825
5572
  lines = _read_text_lines(repo, path)
4826
5573
  if lines is None:
4827
5574
  continue
4828
5575
  inspected += 1
4829
5576
  line_count = len(lines)
4830
5577
  accepted_debt = _is_structure_accepted_debt(path, structure_cfg)
5578
+ block_path_size_warnings = block_warnings and not accepted_debt
4831
5579
  if block_file_lines > 0 and line_count > block_file_lines:
4832
5580
  message = f"{path} has {line_count} lines (block>{block_file_lines}); split responsibilities before adding more work"
4833
5581
  if accepted_debt:
@@ -4835,7 +5583,11 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
4835
5583
  else:
4836
5584
  blocking.append(message)
4837
5585
  elif warn_file_lines > 0 and line_count > warn_file_lines:
4838
- warnings.append(f"{path} has {line_count} lines (warn>{warn_file_lines}); prefer extraction before extending it")
5586
+ message = (
5587
+ f"{path} has {line_count} lines (warn>{warn_file_lines}); "
5588
+ "prefer extraction before extending it"
5589
+ )
5590
+ (blocking if block_path_size_warnings else warnings).append(message)
4839
5591
 
4840
5592
  added_lines = added_by_path.get(path, 0)
4841
5593
  if (
@@ -4851,8 +5603,15 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
4851
5603
  "extract a module/helper or document why this is intentionally co-located"
4852
5604
  )
4853
5605
 
4854
- warnings.extend(_function_size_warnings(path, lines, warn_function_lines))
5606
+ function_warnings = _function_size_warnings(
5607
+ path,
5608
+ lines,
5609
+ warn_function_lines,
5610
+ deadline=deadline,
5611
+ )
5612
+ (blocking if block_path_size_warnings else warnings).extend(function_warnings)
4855
5613
  boundary_issues = _structure_boundary_issues(path, lines, structure_cfg)
5614
+ _ensure_structure_deadline(deadline)
4856
5615
  if block_layer_violations:
4857
5616
  blocking.extend(boundary_issues)
4858
5617
  else:
@@ -4877,6 +5636,7 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
4877
5636
  result = {
4878
5637
  "scope": selected_scope,
4879
5638
  "enforcement": enforcement,
5639
+ "block_warnings": block_warnings,
4880
5640
  "inspected_files": inspected,
4881
5641
  "blocking": blocking,
4882
5642
  "warnings": warnings,
@@ -4896,11 +5656,25 @@ def cmd_structure_check(args: argparse.Namespace) -> None:
4896
5656
  print(f"[structure-check] OK scope={selected_scope} inspected={inspected} warnings={len(warnings)}")
4897
5657
 
4898
5658
 
4899
- def _run_structure_check_for_gate(repo: Path, cfg: dict, selected_scope: str, base_ref: str) -> list[str]:
5659
+ def _run_structure_check_for_gate(
5660
+ repo: Path,
5661
+ cfg: dict,
5662
+ selected_scope: str,
5663
+ base_ref: str,
5664
+ *,
5665
+ deadline: Optional[float] = None,
5666
+ command_timeout_s: Optional[float] = None,
5667
+ ) -> list[str]:
4900
5668
  if not _structure_gate_enabled(cfg):
4901
5669
  return []
4902
5670
  if _configured_command(cfg, "structure_check"):
4903
- _run_configured_command(repo, cfg, "structure_check")
5671
+ timeout_s = command_timeout_s
5672
+ if deadline is not None:
5673
+ remaining = deadline - time.monotonic()
5674
+ if remaining <= 0:
5675
+ raise APError("Final changed-scope gate budget exhausted before structure check.")
5676
+ timeout_s = min(timeout_s, remaining) if timeout_s is not None else remaining
5677
+ _run_configured_command(repo, cfg, "structure_check", timeout_s=timeout_s)
4904
5678
  return ["structure_check"]
4905
5679
  cmd_structure_check(
4906
5680
  argparse.Namespace(
@@ -4908,6 +5682,7 @@ def _run_structure_check_for_gate(repo: Path, cfg: dict, selected_scope: str, ba
4908
5682
  scope=selected_scope,
4909
5683
  base=base_ref,
4910
5684
  json=False,
5685
+ deadline=deadline,
4911
5686
  )
4912
5687
  )
4913
5688
  return ["structure_check"]
@@ -5535,6 +6310,11 @@ def _agent_contract_shape() -> tuple[dict, list[str]]:
5535
6310
  "diff_head",
5536
6311
  "diff_fingerprint",
5537
6312
  "owning_fixer",
6313
+ "review_depth",
6314
+ "timeout_seconds",
6315
+ "issued_at",
6316
+ "deadline_at",
6317
+ "scope_revision",
5538
6318
  ],
5539
6319
  },
5540
6320
  [
@@ -5644,6 +6424,12 @@ def _contract_validation_errors(
5644
6424
  if pattern and not re.search(str(pattern), value):
5645
6425
  errors.append(f"{path}: string does not match {pattern!r}")
5646
6426
 
6427
+ if isinstance(value, (int, float)) and not isinstance(value, bool):
6428
+ if "minimum" in fragment and value < fragment["minimum"]:
6429
+ errors.append(f"{path}: number is below minimum {fragment['minimum']}")
6430
+ if "maximum" in fragment and value > fragment["maximum"]:
6431
+ errors.append(f"{path}: number exceeds maximum {fragment['maximum']}")
6432
+
5647
6433
  if isinstance(value, list):
5648
6434
  if "maxItems" in fragment and len(value) > int(fragment["maxItems"]):
5649
6435
  errors.append(f"{path}: too many array items")
@@ -5701,6 +6487,31 @@ def _validate_orchestration_contract(kind: str, payload: dict) -> dict:
5701
6487
  if kind == "assignment" and role == "reviewer":
5702
6488
  if _text(payload.get("node_id")) == _text(payload.get("owning_fixer")):
5703
6489
  errors.append("$.node_id: reviewer must differ from owning_fixer")
6490
+ timing_fields = ("issued_at", "deadline_at", "timeout_seconds")
6491
+ timing_values = [payload.get(field) for field in timing_fields]
6492
+ if any(value is not None for value in timing_values):
6493
+ if not all(value is not None for value in timing_values):
6494
+ errors.append("$: reviewer timing fields must be supplied together")
6495
+ else:
6496
+ try:
6497
+ issued_at = _parse_iso_timestamp(payload.get("issued_at"), "issued_at")
6498
+ deadline_at = _parse_iso_timestamp(payload.get("deadline_at"), "deadline_at")
6499
+ timeout_seconds = int(payload.get("timeout_seconds"))
6500
+ expected_timeout = {
6501
+ "focused": _FOCUSED_REVIEW_TIMEOUT_SECONDS,
6502
+ "deep": _DEEP_REVIEW_TIMEOUT_SECONDS,
6503
+ }.get(_text(payload.get("review_depth")))
6504
+ if expected_timeout is not None and timeout_seconds != expected_timeout:
6505
+ errors.append(
6506
+ "$.timeout_seconds: must match the fixed "
6507
+ f"{_text(payload.get('review_depth'))} review budget {expected_timeout}"
6508
+ )
6509
+ if deadline_at <= issued_at:
6510
+ errors.append("$.deadline_at: must be after issued_at")
6511
+ elif int((deadline_at - issued_at).total_seconds()) != timeout_seconds:
6512
+ errors.append("$.deadline_at: interval must equal timeout_seconds")
6513
+ except (APError, TypeError, ValueError) as exc:
6514
+ errors.append(f"$: invalid reviewer timing contract: {exc}")
5704
6515
  if kind == "result":
5705
6516
  owned_paths = payload.get("owned_paths")
5706
6517
  changed_paths = payload.get("changed_paths")
@@ -5774,6 +6585,165 @@ def _reviewer_result_template(assignment: dict, verdict: str) -> dict:
5774
6585
  return _validate_orchestration_contract("result", result)
5775
6586
 
5776
6587
 
6588
+ def _normalize_reviewer_runtime_result(assignment: dict, payload: dict) -> dict:
6589
+ """Normalize presentation fields while refusing assignment-binding spoofing."""
6590
+ if not isinstance(payload, dict):
6591
+ raise APError("Reviewer runtime output must be one JSON object.")
6592
+ verdict = _text(payload.get("verdict")).lower()
6593
+ if verdict not in {"approved", "changes-requested", "blocked"}:
6594
+ raise APError(
6595
+ "Reviewer runtime output must include verdict=approved, changes-requested, or blocked."
6596
+ )
6597
+ result = _reviewer_result_template(assignment, verdict)
6598
+ binding_fields = {
6599
+ "contract_version": result["contract_version"],
6600
+ "node_id": result["node_id"],
6601
+ "role": result["role"],
6602
+ "task_id": result["task_id"],
6603
+ "base_sha": result["base_sha"],
6604
+ "diff_fingerprint": result["diff_fingerprint"],
6605
+ }
6606
+ mismatched = [
6607
+ field
6608
+ for field, expected in binding_fields.items()
6609
+ if field in payload and payload.get(field) != expected
6610
+ ]
6611
+ if mismatched:
6612
+ raise APError(
6613
+ "Reviewer runtime result does not match its assignment: "
6614
+ + ", ".join(mismatched)
6615
+ )
6616
+ if "summary" in payload:
6617
+ if not isinstance(payload["summary"], str):
6618
+ raise APError("Reviewer runtime result summary must be a string.")
6619
+ result["summary"] = payload["summary"]
6620
+ for field in ("evidence", "findings", "risks"):
6621
+ if field not in payload:
6622
+ continue
6623
+ value = payload[field]
6624
+ if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
6625
+ raise APError(f"Reviewer runtime result {field} must be an array of strings.")
6626
+ result[field] = value
6627
+ return _validate_orchestration_contract("result", result)
6628
+
6629
+
6630
+ def _reviewer_agent_instructions(worktree: Path) -> str:
6631
+ candidates = [
6632
+ worktree / ".agents" / "agents" / "reviewer.toml",
6633
+ _skill_root().parent.parent / "agents" / "reviewer.toml",
6634
+ ]
6635
+ for path in candidates:
6636
+ try:
6637
+ payload = tomllib.loads(path.read_text(encoding="utf-8"))
6638
+ except FileNotFoundError:
6639
+ continue
6640
+ except (OSError, tomllib.TOMLDecodeError) as exc:
6641
+ raise APError(f"Cannot load managed Reviewer Agent config: {path}: {exc}") from exc
6642
+ instructions = _text(payload.get("developer_instructions"))
6643
+ if instructions:
6644
+ return instructions
6645
+ return (
6646
+ "Act as an independent read-only code reviewer. Review only the supplied "
6647
+ "assignment and return one JSON object with an approved, changes-requested, "
6648
+ "or blocked verdict. Do not modify files."
6649
+ )
6650
+
6651
+
6652
+ def _codex_reviewer_command(
6653
+ worktree: Path,
6654
+ assignment_path: Path,
6655
+ result_path: Path,
6656
+ ) -> list[str]:
6657
+ codex = shutil.which("codex")
6658
+ if not codex:
6659
+ raise APError(
6660
+ "The supervised Reviewer runtime requires the Codex CLI on PATH. "
6661
+ "Install Codex or run review-assignment and use another deadline-capable host."
6662
+ )
6663
+ instructions = _reviewer_agent_instructions(worktree)
6664
+ prompt = (
6665
+ f"Review the exact assignment at {assignment_path}. "
6666
+ "Stay inside its diff, identity, and deadline. Use "
6667
+ "`python3 docs/tools/autopipeline/ap.py agent-result-template --file "
6668
+ f"{assignment_path} --verdict <approved|changes-requested|blocked>` when useful. "
6669
+ "Return only one JSON object as the final response; do not modify files."
6670
+ )
6671
+ return [
6672
+ codex,
6673
+ "-a",
6674
+ "never",
6675
+ "exec",
6676
+ "--ephemeral",
6677
+ "--ignore-user-config",
6678
+ "-C",
6679
+ str(worktree),
6680
+ "-s",
6681
+ "read-only",
6682
+ "-c",
6683
+ 'model_reasoning_effort="xhigh"',
6684
+ "-c",
6685
+ "developer_instructions=" + json.dumps(instructions, ensure_ascii=False),
6686
+ "-o",
6687
+ str(result_path),
6688
+ prompt,
6689
+ ]
6690
+
6691
+
6692
+ def _terminate_reviewer_process(process: subprocess.Popen[str]) -> tuple[str, str]:
6693
+ if process.poll() is None:
6694
+ try:
6695
+ if os.name == "posix":
6696
+ os.killpg(process.pid, signal.SIGTERM)
6697
+ else:
6698
+ process.terminate()
6699
+ except ProcessLookupError:
6700
+ pass
6701
+ try:
6702
+ stdout, stderr = process.communicate(timeout=2)
6703
+ except subprocess.TimeoutExpired:
6704
+ try:
6705
+ if os.name == "posix":
6706
+ os.killpg(process.pid, signal.SIGKILL)
6707
+ else:
6708
+ process.kill()
6709
+ except ProcessLookupError:
6710
+ pass
6711
+ stdout, stderr = process.communicate()
6712
+ return stdout or "", stderr or ""
6713
+
6714
+
6715
+ def _run_supervised_reviewer_process(
6716
+ command: list[str],
6717
+ *,
6718
+ cwd: Path,
6719
+ env: dict[str, str],
6720
+ timeout_seconds: float,
6721
+ ) -> subprocess.CompletedProcess[str]:
6722
+ if timeout_seconds <= 0:
6723
+ raise _ReviewerRuntimeTimeout()
6724
+ process = subprocess.Popen(
6725
+ command,
6726
+ cwd=str(cwd),
6727
+ env=env,
6728
+ stdin=subprocess.DEVNULL,
6729
+ stdout=subprocess.PIPE,
6730
+ stderr=subprocess.PIPE,
6731
+ text=True,
6732
+ start_new_session=True,
6733
+ )
6734
+ try:
6735
+ stdout, stderr = process.communicate(timeout=timeout_seconds)
6736
+ except subprocess.TimeoutExpired as exc:
6737
+ stdout, stderr = _terminate_reviewer_process(process)
6738
+ raise _ReviewerRuntimeTimeout(stdout, stderr) from exc
6739
+ return subprocess.CompletedProcess(
6740
+ command,
6741
+ int(process.returncode or 0),
6742
+ stdout or "",
6743
+ stderr or "",
6744
+ )
6745
+
6746
+
5777
6747
  def _validate_agent_plan(plan: dict) -> dict:
5778
6748
  required = {
5779
6749
  "contract_version",
@@ -5822,6 +6792,24 @@ def _review_execution_policy(
5822
6792
  }
5823
6793
 
5824
6794
 
6795
+ def _normalized_task_review_policy(
6796
+ review_required: bool,
6797
+ *depth_candidates: object,
6798
+ ) -> tuple[str, int]:
6799
+ if not review_required:
6800
+ return "none", 0
6801
+ depth_rank = {"none": 0, "focused": 1, "deep": 2}
6802
+ depth = "focused"
6803
+ for candidate in depth_candidates:
6804
+ normalized = _text(candidate).lower()
6805
+ if depth_rank.get(normalized, 0) > depth_rank[depth]:
6806
+ depth = normalized
6807
+ timeout_seconds = (
6808
+ _DEEP_REVIEW_TIMEOUT_SECONDS if depth == "deep" else _FOCUSED_REVIEW_TIMEOUT_SECONDS
6809
+ )
6810
+ return depth, timeout_seconds
6811
+
6812
+
5825
6813
  def _agent_execution_plan(
5826
6814
  profile: str,
5827
6815
  categories: set[str],
@@ -6531,6 +7519,16 @@ def cmd_light_gate(args: argparse.Namespace) -> None:
6531
7519
  deadline=deadline,
6532
7520
  command_timeout_s=budget["command_seconds"],
6533
7521
  )
7522
+ executed.extend(
7523
+ _run_structure_check_for_gate(
7524
+ repo,
7525
+ cfg,
7526
+ selected_scope,
7527
+ _text(getattr(args, "base", "")),
7528
+ deadline=deadline,
7529
+ command_timeout_s=budget["command_seconds"],
7530
+ )
7531
+ )
6534
7532
 
6535
7533
  _run_git_diff_check(repo, cfg)
6536
7534
  if time.monotonic() > deadline:
@@ -6612,25 +7610,30 @@ def cmd_runtime_down(args: argparse.Namespace) -> None:
6612
7610
  print("[runtime-down] OK")
6613
7611
 
6614
7612
 
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)
7613
+ def _target_endpoint_config(
7614
+ cfg: dict,
7615
+ component: str,
7616
+ ) -> tuple[str, dict, str, str, str]:
7617
+ access = cfg.get("access") or {}
7618
+ project = access.get("project") or {}
7619
+ lane = project.get(component) or {}
7620
+ if isinstance(lane, dict) and any(_is_explicit_fill(value) for value in lane.values()):
7621
+ base_url = _require_http_url(f"access.project.{component}.url", lane.get("url"))
7622
+ return f"access.project.{component}", lane, base_url, "username", "password"
7623
+ legacy = cfg.get("target_env") or {}
7624
+ base_field = f"{component}_base_url"
7625
+ base_url = _require_http_url(f"target_env.{base_field}", legacy.get(base_field))
7626
+ return (
7627
+ "target_env",
7628
+ legacy,
7629
+ base_url,
7630
+ f"{component}_username",
7631
+ f"{component}_password",
7632
+ )
7633
+
6633
7634
 
7635
+ def _wait_for_health_url(scope: str, url: str, timeout_s: int) -> None:
7636
+ _require_http_url(f"{scope} health URL", url)
6634
7637
  deadline = time.time() + timeout_s
6635
7638
  last_error = "(none)"
6636
7639
  while time.time() < deadline:
@@ -6646,50 +7649,94 @@ def cmd_wait_health(args: argparse.Namespace) -> None:
6646
7649
  raise APError(f"Health check timeout for {scope}: {url}\nLast result: {last_error}")
6647
7650
 
6648
7651
 
7652
+ def cmd_wait_health(args: argparse.Namespace) -> None:
7653
+ repo = Path(args.repo).resolve()
7654
+ cfg = _load_cfg(repo)
7655
+ scope = args.scope
7656
+ requested_timeout = int(getattr(args, "timeout_sec", 0) or 0)
7657
+ if scope == "runtime":
7658
+ runtime_cfg = cfg.get("runtime") or {}
7659
+ base_url = _require_http_url("runtime.health_base_url", runtime_cfg.get("health_base_url"))
7660
+ url = _join_url(base_url, runtime_cfg.get("health_path"))
7661
+ timeout_s = requested_timeout or int(runtime_cfg.get("startup_timeout_sec") or 120)
7662
+ else:
7663
+ target_cfg = cfg.get("target_env") or {}
7664
+ explicit_path = _text(getattr(args, "path", ""))
7665
+ legacy_base = _text(target_cfg.get("health_base_url"))
7666
+ legacy_path = _text(target_cfg.get("health_path"))
7667
+ if explicit_path:
7668
+ component = _text(getattr(args, "component", "")) or "backend"
7669
+ _, _, base_url, _, _ = _target_endpoint_config(cfg, component)
7670
+ url = _join_url(base_url, explicit_path)
7671
+ elif legacy_base and legacy_path:
7672
+ base_url = _require_http_url("target_env.health_base_url", legacy_base)
7673
+ url = _join_url(base_url, legacy_path)
7674
+ else:
7675
+ raise APError(
7676
+ "Target health check requires --component and --path for access.project, "
7677
+ "or legacy target_env.health_base_url plus target_env.health_path."
7678
+ )
7679
+ timeout_s = requested_timeout or int((cfg.get("jenkins") or {}).get("deploy_timeout_sec") or 120)
7680
+ _wait_for_health_url(scope, url, timeout_s)
7681
+
7682
+
6649
7683
  def cmd_verify_target(args: argparse.Namespace) -> None:
6650
7684
  repo = Path(args.repo).resolve()
6651
7685
  cfg = _load_cfg(repo)
6652
- target_cfg = (cfg.get("target_env") or {})
7686
+ requested = {
7687
+ "backend": list(args.backend_path or []),
7688
+ "frontend": list(args.frontend_path or []),
7689
+ }
7690
+ target_cfg = cfg.get("target_env") or {}
7691
+ legacy_health_base = _text(target_cfg.get("health_base_url"))
7692
+ legacy_health_path = _text(target_cfg.get("health_path"))
7693
+ if not any(requested.values()) and not (legacy_health_base and legacy_health_path):
7694
+ raise APError(
7695
+ "verify-target requires --backend-path or --frontend-path when no legacy target health check is configured."
7696
+ )
7697
+
7698
+ planned_checks: list[tuple[str, str, dict[str, str]]] = []
7699
+ for component in ("backend", "frontend"):
7700
+ paths = requested[component]
7701
+ if not paths:
7702
+ continue
7703
+ section_name, section_cfg, base_url, user_field, secret_field = _target_endpoint_config(
7704
+ cfg,
7705
+ component,
7706
+ )
7707
+ headers: dict[str, str] = {}
7708
+ if bool(getattr(args, f"{component}_basic_auth")):
7709
+ username = _text(section_cfg.get(user_field))
7710
+ if not _is_explicit_fill(username):
7711
+ raise APError(f"Missing {section_name}.{user_field} for basic auth.")
7712
+ password = _resolve_secret(section_name, section_cfg, secret_field)
7713
+ headers = _basic_auth_header(username, password)
7714
+ for path in paths:
7715
+ url = _join_url(base_url, path)
7716
+ _require_http_url(f"{component} target URL", url)
7717
+ planned_checks.append((component, url, headers))
7718
+
7719
+ health_url = ""
7720
+ if legacy_health_base or legacy_health_path:
7721
+ if not (legacy_health_base and legacy_health_path):
7722
+ raise APError(
7723
+ "Legacy target health config requires both target_env.health_base_url and target_env.health_path."
7724
+ )
7725
+ health_base = _require_http_url("target_env.health_base_url", legacy_health_base)
7726
+ health_url = _join_url(health_base, legacy_health_path)
6653
7727
 
6654
- cmd_wait_health(argparse.Namespace(repo=str(repo), scope="target"))
7728
+ if health_url:
7729
+ timeout_s = int((cfg.get("jenkins") or {}).get("deploy_timeout_sec") or 120)
7730
+ _wait_for_health_url("target", health_url, timeout_s)
6655
7731
 
6656
7732
  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)
7733
+ for component, url, headers in planned_checks:
7734
+ status, body = _http_get(url, headers=headers, timeout_s=10)
6690
7735
  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}")
7736
+ raise APError(
7737
+ f"{component.title()} target verification failed: {url} -> {status}\n{body[:400]}"
7738
+ )
7739
+ checks.append(f"{component}:{url}->{status}")
6693
7740
 
6694
7741
  summary = ", ".join(checks) if checks else "health-only"
6695
7742
  _record_evidence(repo, cfg, "verify_target", "pass", {"summary": summary, "checks": checks})
@@ -6707,6 +7754,28 @@ def cmd_verify_jenkins(args: argparse.Namespace) -> None:
6707
7754
  if not jenkinsfile.exists():
6708
7755
  raise APError(f"Jenkinsfile not found: {jenkinsfile}")
6709
7756
 
7757
+ configured_components = _configured_jenkins_components(cfg)
7758
+ if configured_components:
7759
+ requested = _text(getattr(args, "component", "all")).lower() or "all"
7760
+ selected = ("frontend", "backend") if requested == "all" else (requested,)
7761
+ checked: list[str] = []
7762
+ for component in selected:
7763
+ lane = _jenkins_access_cfg(cfg, component)
7764
+ _require_http_url(f"access.jenkins.{component}.url", lane.get("url"))
7765
+ if not _is_explicit_fill(lane.get("username")):
7766
+ raise APError(f"Missing access.jenkins.{component}.username.")
7767
+ _resolve_secret(f"access.jenkins.{component}", lane, "password")
7768
+ checked.append(component)
7769
+ _record_evidence(
7770
+ repo,
7771
+ cfg,
7772
+ "verify_jenkins",
7773
+ "pass",
7774
+ {"jenkinsfile": str(jenkinsfile), "components": checked},
7775
+ )
7776
+ print(f"[verify-jenkins] OK: {jenkinsfile} components={','.join(checked)}")
7777
+ return
7778
+
6710
7779
  required = [
6711
7780
  ("jenkins.base_url", jenkins_cfg.get("base_url")),
6712
7781
  ("jenkins.job_url", jenkins_cfg.get("job_url")),
@@ -6771,6 +7840,13 @@ def cmd_doctor(args: argparse.Namespace) -> None:
6771
7840
  enforcement = _text(structure_cfg.get("enforcement")).lower()
6772
7841
  if enforcement and enforcement not in {"advisory", "blocking"}:
6773
7842
  validation_errors.append("structure.enforcement must be advisory or blocking")
7843
+ raw_block_warnings = structure_cfg.get("block_warnings")
7844
+ if "block_warnings" in structure_cfg and not isinstance(raw_block_warnings, bool):
7845
+ validation_errors.append("structure.block_warnings must be a boolean")
7846
+ elif raw_block_warnings is True and enforcement != "blocking":
7847
+ advisories.append(
7848
+ "structure.block_warnings has no effect unless structure.enforcement=blocking"
7849
+ )
6774
7850
  gate_cfg = _gate_cfg(cfg)
6775
7851
  if "full_on" in gate_cfg:
6776
7852
  validation_errors.append("gate.full_on is legacy automatic full escalation; run ap.py upgrade")
@@ -6963,6 +8039,16 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
6963
8039
  repo = Path(args.repo).resolve()
6964
8040
  cfg = _load_cfg(repo)
6965
8041
  jenkins_cfg = (cfg.get("jenkins") or {})
8042
+ component = _resolve_jenkins_component(
8043
+ cfg,
8044
+ _text(getattr(args, "component", "")),
8045
+ _text(args.job_url),
8046
+ )
8047
+ if component:
8048
+ lane = _jenkins_access_cfg(cfg, component)
8049
+ _require_http_url(f"access.jenkins.{component}.url", lane.get("url"))
8050
+ _jenkins_auth_config(cfg, component)
8051
+ _resolve_secret(f"access.jenkins.{component}", lane, "password")
6966
8052
  git_ref = str(args.git_ref or "HEAD").strip()
6967
8053
  candidate_job_urls = _resolve_jenkins_job_candidates(
6968
8054
  cfg,
@@ -6972,6 +8058,7 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
6972
8058
  job_url=args.job_url,
6973
8059
  multibranch_root_job=args.multibranch_root_job,
6974
8060
  branch_name=args.branch_name,
8061
+ component=component,
6975
8062
  )
6976
8063
  build_number = args.build_number
6977
8064
  max_builds = int(args.max_builds or 20)
@@ -6985,6 +8072,7 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
6985
8072
  args.multibranch_root_job
6986
8073
  or args.job_name
6987
8074
  or args.job_url
8075
+ or (_jenkins_access_cfg(cfg, component).get("url") if component else "")
6988
8076
  or jenkins_cfg.get("job_url")
6989
8077
  or ""
6990
8078
  ).strip()
@@ -7000,7 +8088,12 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
7000
8088
  payload = None
7001
8089
  for candidate_job_url in candidate_job_urls:
7002
8090
  api_url = _jenkins_build_api_url(candidate_job_url, int(build_number))
7003
- payload = _jenkins_api_get_json(api_url, cfg, allow_404=True)
8091
+ payload = _jenkins_api_get_json(
8092
+ api_url,
8093
+ cfg,
8094
+ allow_404=True,
8095
+ component=component,
8096
+ )
7004
8097
  if payload is not None:
7005
8098
  break
7006
8099
  if payload is not None and not payload.get("building"):
@@ -7046,7 +8139,12 @@ def cmd_verify_jenkins_build(args: argparse.Namespace) -> None:
7046
8139
  matched = None
7047
8140
  for candidate_job_url in candidate_job_urls:
7048
8141
  api_url = _jenkins_builds_api_url(candidate_job_url, max_builds)
7049
- payload = _jenkins_api_get_json(api_url, cfg, allow_404=True)
8142
+ payload = _jenkins_api_get_json(
8143
+ api_url,
8144
+ cfg,
8145
+ allow_404=True,
8146
+ component=component,
8147
+ )
7050
8148
  if payload is None:
7051
8149
  continue
7052
8150
  builds = payload.get("builds") or []
@@ -8296,6 +9394,11 @@ def cmd_task_start(args: argparse.Namespace) -> None:
8296
9394
  "only when classify requires isolation/review or the user explicitly requests it."
8297
9395
  )
8298
9396
  review_required = bool(getattr(args, "review_required", False) or plan["review_required"])
9397
+ review_depth, review_timeout_seconds = _normalized_task_review_policy(
9398
+ review_required,
9399
+ plan.get("review_depth"),
9400
+ getattr(args, "review_depth", ""),
9401
+ )
8299
9402
  registry_dir = _task_state_root(repo) / "tasks"
8300
9403
  other_active = any(
8301
9404
  _text((payload or {}).get("state"))
@@ -8350,6 +9453,8 @@ def cmd_task_start(args: argparse.Namespace) -> None:
8350
9453
  "scope_revision": 1,
8351
9454
  "effective_profile": plan["profile"],
8352
9455
  "design_required": bool(plan["design_required"]),
9456
+ "review_depth": review_depth,
9457
+ "review_timeout_seconds": review_timeout_seconds,
8353
9458
  "scope_history": [],
8354
9459
  "depends_on": depends_on,
8355
9460
  "prerequisite_shas": prerequisite_shas,
@@ -8435,6 +9540,8 @@ def cmd_task_start(args: argparse.Namespace) -> None:
8435
9540
  "scope_revision": 1,
8436
9541
  "effective_profile": plan["profile"],
8437
9542
  "design_required": bool(plan["design_required"]),
9543
+ "review_depth": review_depth,
9544
+ "review_timeout_seconds": review_timeout_seconds,
8438
9545
  "scope_history": [],
8439
9546
  "depends_on": depends_on,
8440
9547
  "prerequisite_shas": prerequisite_shas,
@@ -8509,18 +9616,49 @@ def _task_status_payload(repo: Path, manifest: dict) -> dict:
8509
9616
  remote = _text(manifest.get("remote")) or "origin"
8510
9617
  target = _text(manifest.get("target_branch"))
8511
9618
  remote_ref = f"refs/remotes/{remote}/{target}"
8512
- merged = bool(
9619
+ base_sha = _text(manifest.get("base_sha"))
9620
+ has_task_commits = bool(
8513
9621
  tip
9622
+ and base_sha
9623
+ and tip != base_sha
9624
+ and run(
9625
+ ["git", "merge-base", "--is-ancestor", base_sha, tip],
9626
+ cwd=repo,
9627
+ check=False,
9628
+ ).returncode
9629
+ == 0
9630
+ )
9631
+ merged = bool(
9632
+ has_task_commits
8514
9633
  and _git_ref_exists(repo, remote_ref)
8515
9634
  and run(["git", "merge-base", "--is-ancestor", tip, remote_ref], cwd=repo, check=False).returncode == 0
8516
9635
  )
9636
+ review = manifest.get("review") or {}
9637
+ deadline_at = _text(review.get("deadline_at"))
9638
+ review_seconds_remaining: Optional[int] = None
9639
+ review_deadline_expired = False
9640
+ if deadline_at:
9641
+ try:
9642
+ remaining = (
9643
+ _parse_iso_timestamp(deadline_at, "deadline_at")
9644
+ - _dt.datetime.now(_dt.timezone.utc)
9645
+ ).total_seconds()
9646
+ seconds = int(remaining)
9647
+ review_seconds_remaining = max(0, seconds)
9648
+ review_deadline_expired = remaining < 0
9649
+ except APError:
9650
+ review_deadline_expired = True
9651
+ review_seconds_remaining = 0
8517
9652
  return {
8518
9653
  **manifest,
8519
9654
  "worktree_exists": worktree.exists(),
8520
9655
  "dirty": bool(_git_status(worktree)) if worktree.exists() else False,
8521
9656
  "local_branch_exists": bool(tip),
8522
9657
  "tip": tip,
9658
+ "has_task_commits": has_task_commits,
8523
9659
  "merged_into_target": merged,
9660
+ "review_deadline_expired": review_deadline_expired,
9661
+ "review_seconds_remaining": review_seconds_remaining,
8524
9662
  "current_diff_fingerprint": _task_review_fingerprint(worktree, manifest)
8525
9663
  if worktree.exists()
8526
9664
  else "",
@@ -8551,7 +9689,9 @@ def cmd_task_status(args: argparse.Namespace) -> None:
8551
9689
  print(
8552
9690
  f"[task-status] task={status['task_id']} state={status.get('state')} "
8553
9691
  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()}"
9692
+ f"dirty={str(status['dirty']).lower()} commits="
9693
+ f"{str(status['has_task_commits']).lower()} "
9694
+ f"merged={str(status['merged_into_target']).lower()}"
8555
9695
  )
8556
9696
 
8557
9697
 
@@ -8678,6 +9818,13 @@ def cmd_task_scope_add(args: argparse.Namespace) -> None:
8678
9818
  manifest["design_required"] = bool(
8679
9819
  manifest.get("design_required") or plan.get("design_required")
8680
9820
  )
9821
+ review_depth, review_timeout_seconds = _normalized_task_review_policy(
9822
+ bool(manifest["review_required"]),
9823
+ manifest.get("review_depth"),
9824
+ plan.get("review_depth"),
9825
+ )
9826
+ manifest["review_depth"] = review_depth
9827
+ manifest["review_timeout_seconds"] = review_timeout_seconds
8681
9828
  manifest["claimed_paths"] = []
8682
9829
  history = list(manifest.get("scope_history") or [])
8683
9830
  history.append(
@@ -8730,6 +9877,543 @@ def cmd_task_scope_add(args: argparse.Namespace) -> None:
8730
9877
  )
8731
9878
 
8732
9879
 
9880
+ def _parse_iso_timestamp(value: object, field: str) -> _dt.datetime:
9881
+ raw = _text(value)
9882
+ try:
9883
+ parsed = _dt.datetime.fromisoformat(raw.replace("Z", "+00:00"))
9884
+ except ValueError as exc:
9885
+ raise APError(f"Invalid {field} timestamp in review assignment: {raw!r}.") from exc
9886
+ if parsed.tzinfo is None:
9887
+ raise APError(f"Review assignment {field} must include a timezone.")
9888
+ return parsed.astimezone(_dt.timezone.utc)
9889
+
9890
+
9891
+ def _task_review_policy(cfg: dict, worktree: Path, manifest: dict) -> tuple[str, int]:
9892
+ changed_paths = _task_changed_paths_from_base(worktree, _text(manifest.get("base_sha")))
9893
+ plan = _resolve_execution_plan(
9894
+ cfg,
9895
+ worktree,
9896
+ changed_paths=changed_paths,
9897
+ planned_paths=list(manifest.get("owned_paths") or []),
9898
+ requested_task_kind="change",
9899
+ )
9900
+ return _normalized_task_review_policy(
9901
+ True,
9902
+ manifest.get("review_depth"),
9903
+ plan.get("review_depth"),
9904
+ )
9905
+
9906
+
9907
+ def cmd_review_assignment(args: argparse.Namespace) -> None:
9908
+ repo = Path(args.repo).resolve()
9909
+ ensure_git_repo(repo)
9910
+ cfg = _load_cfg(repo)
9911
+ task_id = _validate_task_id(args.task_id)
9912
+ control_repo, worktree, _ = _task_lifecycle_context(repo, cfg, task_id)
9913
+ timeout_s = float(_concurrency_cfg(cfg).get("lock_timeout_sec") or 30)
9914
+ with _repo_lock(control_repo, f"task-{task_id}", timeout_s=timeout_s):
9915
+ manifest = _load_task_manifest(control_repo, task_id)
9916
+ lifecycle_actor = _text(os.environ.get("CODEX_THREAD_ID"))
9917
+ if not lifecycle_actor or lifecycle_actor != _text(manifest.get("owner")):
9918
+ raise APError("Only the task lifecycle owner may issue a review assignment.")
9919
+ if _text(manifest.get("state")) not in {"active", "pushed", "integration-raced"}:
9920
+ raise APError(f"Task {task_id} is not reviewable in state={manifest.get('state')}.")
9921
+ if not bool(manifest.get("review_required")):
9922
+ raise APError(f"Task {task_id} does not require an independent review assignment.")
9923
+ if not worktree.exists():
9924
+ raise APError(f"Task worktree is missing: {worktree}")
9925
+ worktree_cfg = _load_cfg(worktree)
9926
+ unowned = _task_unowned_paths(worktree, worktree_cfg, manifest)
9927
+ if unowned:
9928
+ raise APError("Changes outside task owned_paths:\n- " + "\n- ".join(unowned))
9929
+ changed_paths = _task_changed_paths_from_base(
9930
+ worktree,
9931
+ _text(manifest.get("base_sha")),
9932
+ )
9933
+ owned_paths = [
9934
+ path
9935
+ for path in changed_paths
9936
+ if _path_is_owned(path, list(manifest.get("owned_paths") or []))
9937
+ ]
9938
+ if not owned_paths:
9939
+ raise APError("Cannot issue a review assignment before the task has an owned diff.")
9940
+ reviewer = _text(args.reviewer)
9941
+ if not reviewer or any(char in reviewer for char in "\0\r\n"):
9942
+ raise APError("Reviewer identity is empty or contains invalid characters.")
9943
+ owner = _text(manifest.get("owner"))
9944
+ owning_fixer = _text((manifest.get("writer_lease") or {}).get("holder")) or owner
9945
+ if reviewer in {owner, owning_fixer}:
9946
+ raise APError("Independent reviewer must differ from lifecycle owner and owning fixer.")
9947
+ fingerprint = _task_review_fingerprint(worktree, manifest, worktree_cfg)
9948
+ depth, review_timeout = _task_review_policy(worktree_cfg, worktree, manifest)
9949
+ issued = _dt.datetime.now(_dt.timezone.utc).replace(microsecond=0)
9950
+ deadline = issued + _dt.timedelta(seconds=review_timeout)
9951
+ assignment = {
9952
+ "contract_version": _AGENT_CONTRACT_VERSION,
9953
+ "node_id": reviewer,
9954
+ "task_id": task_id,
9955
+ "role": "reviewer",
9956
+ "base_sha": _text(manifest.get("base_sha")),
9957
+ "scope": f"Review the task-owned diff for {task_id}",
9958
+ "depends_on": [owning_fixer],
9959
+ "acceptance": [
9960
+ "Review only the assigned stable diff and supplied evidence.",
9961
+ "Return the complete 16-field reviewer result bound to diff_fingerprint.",
9962
+ ],
9963
+ "diff_base": _text(manifest.get("base_sha")),
9964
+ "diff_head": _resolve_commit(worktree, "HEAD"),
9965
+ "diff_fingerprint": fingerprint,
9966
+ "owning_fixer": owning_fixer,
9967
+ "review_depth": depth,
9968
+ "timeout_seconds": review_timeout,
9969
+ "issued_at": issued.isoformat(),
9970
+ "deadline_at": deadline.isoformat(),
9971
+ "scope_revision": int(manifest.get("scope_revision") or 1),
9972
+ }
9973
+ _validate_orchestration_contract("assignment", assignment)
9974
+ assignment_path = (
9975
+ _task_state_root(control_repo)
9976
+ / "reviews"
9977
+ / f"{task_id}-{fingerprint}.assignment.json"
9978
+ )
9979
+ prior_review = manifest.get("review") or {}
9980
+ if (
9981
+ _text(prior_review.get("diff_fingerprint")) == fingerprint
9982
+ and (
9983
+ _text(prior_review.get("verdict"))
9984
+ in {"approved", "changes-requested", "blocked"}
9985
+ or _text(prior_review.get("runtime_state"))
9986
+ or _text(prior_review.get("runtime_receipt_path"))
9987
+ )
9988
+ ):
9989
+ raise APError(
9990
+ "The single review attempt for this diff fingerprint is already complete or consumed."
9991
+ )
9992
+ existing_assignment = _read_json_object(assignment_path)
9993
+ if existing_assignment:
9994
+ _validate_orchestration_contract("assignment", existing_assignment)
9995
+ expected_fields = {
9996
+ "task_id": task_id,
9997
+ "base_sha": assignment["base_sha"],
9998
+ "diff_base": assignment["diff_base"],
9999
+ "diff_head": assignment["diff_head"],
10000
+ "diff_fingerprint": fingerprint,
10001
+ "owning_fixer": owning_fixer,
10002
+ "scope_revision": assignment["scope_revision"],
10003
+ }
10004
+ mismatched = [
10005
+ field
10006
+ for field, expected in expected_fields.items()
10007
+ if existing_assignment.get(field) != expected
10008
+ ]
10009
+ if mismatched:
10010
+ raise APError(
10011
+ "Existing review assignment does not match current task state: "
10012
+ + ", ".join(mismatched)
10013
+ )
10014
+ if _text(existing_assignment.get("node_id")) != reviewer:
10015
+ raise APError(
10016
+ "This diff fingerprint already has a reviewer assignment; "
10017
+ "the single review attempt cannot be reassigned."
10018
+ )
10019
+ existing_deadline = _parse_iso_timestamp(
10020
+ existing_assignment.get("deadline_at"),
10021
+ "deadline_at",
10022
+ )
10023
+ if _dt.datetime.now(_dt.timezone.utc) > existing_deadline:
10024
+ raise APError(
10025
+ "Review attempt timed out and is blocked for this diff fingerprint; "
10026
+ "do not renew it without a semantic diff/scope change or explicit user authorization."
10027
+ )
10028
+ assignment = existing_assignment
10029
+ depth = _text(assignment.get("review_depth"))
10030
+ review_timeout = int(assignment.get("timeout_seconds") or 0)
10031
+ elif (
10032
+ _text(prior_review.get("diff_fingerprint")) == fingerprint
10033
+ and _text(prior_review.get("deadline_at"))
10034
+ ):
10035
+ if _text(prior_review.get("reviewer")) != reviewer:
10036
+ raise APError(
10037
+ "This diff fingerprint already has a reviewer assignment; "
10038
+ "the single review attempt cannot be reassigned."
10039
+ )
10040
+ issued = _parse_iso_timestamp(prior_review.get("issued_at"), "issued_at")
10041
+ deadline = _parse_iso_timestamp(prior_review.get("deadline_at"), "deadline_at")
10042
+ if _dt.datetime.now(_dt.timezone.utc) > deadline:
10043
+ raise APError(
10044
+ "Review attempt timed out and is blocked for this diff fingerprint; "
10045
+ "do not renew it without a semantic diff/scope change or explicit user authorization."
10046
+ )
10047
+ assignment["issued_at"] = issued.isoformat()
10048
+ assignment["deadline_at"] = deadline.isoformat()
10049
+ assignment["timeout_seconds"] = int((deadline - issued).total_seconds())
10050
+ _validate_orchestration_contract("assignment", assignment)
10051
+ _write_json_object(assignment_path, assignment)
10052
+ depth = _text(assignment.get("review_depth"))
10053
+ review_timeout = int(assignment.get("timeout_seconds") or 0)
10054
+ else:
10055
+ _write_json_object(assignment_path, assignment)
10056
+ manifest["review_depth"] = depth
10057
+ manifest["review_timeout_seconds"] = review_timeout
10058
+ review_state = {
10059
+ "verdict": "pending",
10060
+ "diff_base": assignment["diff_base"],
10061
+ "diff_head": assignment["diff_head"],
10062
+ "diff_fingerprint": fingerprint,
10063
+ "reviewer": reviewer,
10064
+ "reviewed_at": "",
10065
+ "reason": "review assignment issued",
10066
+ "assignment_path": str(assignment_path),
10067
+ "issued_at": assignment["issued_at"],
10068
+ "deadline_at": assignment["deadline_at"],
10069
+ }
10070
+ if _text(prior_review.get("diff_fingerprint")) == fingerprint:
10071
+ for field in _REVIEW_RUNTIME_FIELDS:
10072
+ if field in prior_review:
10073
+ review_state[field] = prior_review[field]
10074
+ manifest["review"] = review_state
10075
+ _save_task_manifest(control_repo, manifest)
10076
+ if bool(getattr(args, "json", False)):
10077
+ print(
10078
+ json.dumps(
10079
+ {"assignment_path": str(assignment_path), "assignment": assignment},
10080
+ ensure_ascii=False,
10081
+ indent=2,
10082
+ )
10083
+ )
10084
+ else:
10085
+ print(f"[review-assignment] task={task_id} reviewer={reviewer} depth={depth}")
10086
+ print(f"[review-assignment] timeout_seconds={review_timeout}")
10087
+ print(f"[review-assignment] assignment={assignment_path}")
10088
+
10089
+
10090
+ def _write_private_json(path: Path, payload: dict) -> None:
10091
+ _write_json_object(path, payload)
10092
+ try:
10093
+ path.chmod(0o600)
10094
+ except OSError as exc:
10095
+ raise APError(f"Cannot protect Git-local review state: {path}: {exc}") from exc
10096
+
10097
+
10098
+ def _review_runtime_paths(
10099
+ control_repo: Path,
10100
+ task_id: str,
10101
+ fingerprint: str,
10102
+ ) -> tuple[Path, Path]:
10103
+ root = _task_state_root(control_repo) / "reviews"
10104
+ stem = f"{_validate_task_id(task_id)}-{fingerprint}"
10105
+ return root / f"{stem}.result.json", root / f"{stem}.run.json"
10106
+
10107
+
10108
+ def _review_command_sha256(command: list[str]) -> str:
10109
+ digest = hashlib.sha256()
10110
+ for argument in command:
10111
+ digest.update(argument.encode("utf-8", errors="surrogateescape"))
10112
+ digest.update(b"\0")
10113
+ return digest.hexdigest()
10114
+
10115
+
10116
+ def _bounded_reviewer_output(value: str, label: str) -> str:
10117
+ encoded = value.encode("utf-8", errors="replace")
10118
+ if len(encoded) > _REVIEW_OUTPUT_MAX_BYTES:
10119
+ raise APError(f"Reviewer {label} exceeded {_REVIEW_OUTPUT_MAX_BYTES} bytes; refusing oversized output.")
10120
+ return value
10121
+
10122
+
10123
+ def _read_bounded_reviewer_output(path: Path) -> str:
10124
+ try:
10125
+ with path.open("rb") as handle:
10126
+ payload = handle.read(_REVIEW_OUTPUT_MAX_BYTES + 1)
10127
+ except OSError as exc:
10128
+ raise APError(f"Cannot read Reviewer result: {path}: {exc}") from exc
10129
+ if len(payload) > _REVIEW_OUTPUT_MAX_BYTES:
10130
+ raise APError(f"Reviewer result exceeded {_REVIEW_OUTPUT_MAX_BYTES} bytes; refusing oversized output.")
10131
+ return payload.decode("utf-8", errors="strict")
10132
+
10133
+
10134
+ def _review_result_file_sha256(path: Path) -> str:
10135
+ try:
10136
+ with path.open("rb") as handle:
10137
+ payload = handle.read(_REVIEW_OUTPUT_MAX_BYTES + 1)
10138
+ except OSError as exc:
10139
+ raise APError(f"Cannot hash Reviewer result: {path}: {exc}") from exc
10140
+ if len(payload) > _REVIEW_OUTPUT_MAX_BYTES:
10141
+ raise APError(f"Reviewer result exceeded {_REVIEW_OUTPUT_MAX_BYTES} bytes; refusing oversized output.")
10142
+ return hashlib.sha256(payload).hexdigest()
10143
+
10144
+
10145
+ def _update_review_runtime(
10146
+ control_repo: Path,
10147
+ task_id: str,
10148
+ fingerprint: str,
10149
+ *,
10150
+ updates: dict,
10151
+ receipt_path: Path,
10152
+ receipt_updates: dict,
10153
+ ) -> dict:
10154
+ cfg = _load_cfg(control_repo)
10155
+ timeout_s = float(_concurrency_cfg(cfg).get("lock_timeout_sec") or 30)
10156
+ with _repo_lock(control_repo, f"task-{task_id}", timeout_s=timeout_s):
10157
+ manifest = _load_task_manifest(control_repo, task_id)
10158
+ review = dict(manifest.get("review") or {})
10159
+ if _text(review.get("diff_fingerprint")) != fingerprint:
10160
+ raise APError("Reviewer runtime assignment became stale while the process was running.")
10161
+ review.update(updates)
10162
+ manifest["review"] = review
10163
+ receipt = _read_json_object(receipt_path) or {}
10164
+ receipt.update(receipt_updates)
10165
+ _write_private_json(receipt_path, receipt)
10166
+ _save_task_manifest(control_repo, manifest)
10167
+ return manifest
10168
+
10169
+
10170
+ def _blocked_reviewer_runtime_result(
10171
+ assignment: dict,
10172
+ reason: str,
10173
+ evidence: list[str],
10174
+ ) -> dict:
10175
+ result = _reviewer_result_template(assignment, "blocked")
10176
+ result["summary"] = reason
10177
+ result["evidence"] = evidence
10178
+ return _validate_orchestration_contract("result", result)
10179
+
10180
+
10181
+ def cmd_review_run(args: argparse.Namespace) -> None:
10182
+ repo = Path(args.repo).resolve()
10183
+ ensure_git_repo(repo)
10184
+ cfg = _load_cfg(repo)
10185
+ task_id = _validate_task_id(args.task_id)
10186
+ reviewer = _text(args.reviewer)
10187
+ with contextlib.redirect_stdout(io.StringIO()):
10188
+ cmd_review_assignment(
10189
+ argparse.Namespace(
10190
+ repo=str(repo),
10191
+ task_id=task_id,
10192
+ reviewer=reviewer,
10193
+ json=False,
10194
+ )
10195
+ )
10196
+
10197
+ control_repo, worktree, _ = _task_lifecycle_context(repo, cfg, task_id)
10198
+ manifest = _load_task_manifest(control_repo, task_id)
10199
+ review = manifest.get("review") or {}
10200
+ assignment_path = Path(_text(review.get("assignment_path"))).resolve()
10201
+ assignment = _read_json_object(assignment_path)
10202
+ if not assignment:
10203
+ raise APError("Review assignment file is missing or invalid.")
10204
+ _validate_orchestration_contract("assignment", assignment)
10205
+ fingerprint = _text(assignment.get("diff_fingerprint"))
10206
+ result_path, receipt_path = _review_runtime_paths(control_repo, task_id, fingerprint)
10207
+
10208
+ command_override = _text(getattr(args, "runner_command_json", ""))
10209
+ if command_override:
10210
+ try:
10211
+ command_value = json.loads(command_override)
10212
+ except json.JSONDecodeError as exc:
10213
+ raise APError("--runner-command-json must be a JSON array of argv strings.") from exc
10214
+ if not isinstance(command_value, list) or not command_value or not all(
10215
+ isinstance(item, str) and item for item in command_value
10216
+ ):
10217
+ raise APError("--runner-command-json must be a non-empty JSON array of argv strings.")
10218
+ command = command_value
10219
+ else:
10220
+ command = _codex_reviewer_command(worktree, assignment_path, result_path)
10221
+ command_sha256 = _review_command_sha256(command)
10222
+ started_at = _now_iso()
10223
+ receipt = {
10224
+ "schema": 1,
10225
+ "task_id": task_id,
10226
+ "reviewer": reviewer,
10227
+ "diff_fingerprint": fingerprint,
10228
+ "assignment_path": str(assignment_path),
10229
+ "result_path": str(result_path),
10230
+ "command_sha256": command_sha256,
10231
+ "status": "starting",
10232
+ "started_at": started_at,
10233
+ "finished_at": "",
10234
+ "exit_code": None,
10235
+ }
10236
+ timeout_s = float(_concurrency_cfg(_load_cfg(control_repo)).get("lock_timeout_sec") or 30)
10237
+ with _repo_lock(control_repo, f"task-{task_id}", timeout_s=timeout_s):
10238
+ manifest = _load_task_manifest(control_repo, task_id)
10239
+ current_review = dict(manifest.get("review") or {})
10240
+ if _text(current_review.get("diff_fingerprint")) != fingerprint:
10241
+ raise APError("Review assignment became stale before Reviewer runtime start.")
10242
+ if _text(current_review.get("runtime_state")) or receipt_path.exists():
10243
+ raise APError(
10244
+ "The supervised Reviewer runtime has already started for this diff fingerprint."
10245
+ )
10246
+ deadline = _parse_iso_timestamp(assignment.get("deadline_at"), "deadline_at")
10247
+ if _dt.datetime.now(_dt.timezone.utc) >= deadline:
10248
+ raise APError("Review assignment deadline expired before Reviewer runtime start.")
10249
+ _write_private_json(receipt_path, receipt)
10250
+ current_review.update(
10251
+ {
10252
+ "runtime_state": "starting",
10253
+ "runtime_started_at": started_at,
10254
+ "runtime_finished_at": "",
10255
+ "runtime_result_path": str(result_path),
10256
+ "runtime_exit_code": None,
10257
+ "runtime_command_sha256": command_sha256,
10258
+ "runtime_receipt_path": str(receipt_path),
10259
+ }
10260
+ )
10261
+ manifest["review"] = current_review
10262
+ _save_task_manifest(control_repo, manifest)
10263
+
10264
+ env = os.environ.copy()
10265
+ env.pop("CODEX_THREAD_ID", None)
10266
+ env.update(
10267
+ {
10268
+ "AUTOCODING_REVIEW_ASSIGNMENT": str(assignment_path),
10269
+ "AUTOCODING_REVIEW_RESULT": str(result_path),
10270
+ "AUTOCODING_REVIEW_DEADLINE": _text(assignment.get("deadline_at")),
10271
+ "AUTOCODING_REVIEW_TIMEOUT_SECONDS": str(int(assignment.get("timeout_seconds") or 0)),
10272
+ }
10273
+ )
10274
+ deadline = _parse_iso_timestamp(assignment.get("deadline_at"), "deadline_at")
10275
+ remaining = (deadline - _dt.datetime.now(_dt.timezone.utc)).total_seconds()
10276
+ try:
10277
+ completed = _run_supervised_reviewer_process(
10278
+ command,
10279
+ cwd=worktree,
10280
+ env=env,
10281
+ timeout_seconds=remaining,
10282
+ )
10283
+ except _ReviewerRuntimeTimeout as exc:
10284
+ finished_at = _now_iso()
10285
+ result = _blocked_reviewer_runtime_result(
10286
+ assignment,
10287
+ "Reviewer runtime reached its fixed deadline and was terminated.",
10288
+ ["runtime_timeout=true"],
10289
+ )
10290
+ _write_private_json(result_path, result)
10291
+ _update_review_runtime(
10292
+ control_repo,
10293
+ task_id,
10294
+ fingerprint,
10295
+ updates={
10296
+ "verdict": "blocked",
10297
+ "reason": "reviewer runtime timeout",
10298
+ "runtime_state": "timed-out",
10299
+ "runtime_finished_at": finished_at,
10300
+ "runtime_exit_code": None,
10301
+ },
10302
+ receipt_path=receipt_path,
10303
+ receipt_updates={
10304
+ "status": "timed-out",
10305
+ "finished_at": finished_at,
10306
+ "exit_code": None,
10307
+ },
10308
+ )
10309
+ print(json.dumps(result, ensure_ascii=False, indent=2))
10310
+ raise APError("Reviewer runtime timed out and was terminated; review is blocked.") from exc
10311
+
10312
+ finished_at = _now_iso()
10313
+ if completed.returncode != 0:
10314
+ result = _blocked_reviewer_runtime_result(
10315
+ assignment,
10316
+ "Reviewer runtime exited unsuccessfully.",
10317
+ [f"runner_exit_code={completed.returncode}"],
10318
+ )
10319
+ _write_private_json(result_path, result)
10320
+ _update_review_runtime(
10321
+ control_repo,
10322
+ task_id,
10323
+ fingerprint,
10324
+ updates={
10325
+ "verdict": "blocked",
10326
+ "reason": "reviewer runtime failed",
10327
+ "runtime_state": "failed",
10328
+ "runtime_finished_at": finished_at,
10329
+ "runtime_exit_code": completed.returncode,
10330
+ },
10331
+ receipt_path=receipt_path,
10332
+ receipt_updates={
10333
+ "status": "failed",
10334
+ "finished_at": finished_at,
10335
+ "exit_code": completed.returncode,
10336
+ },
10337
+ )
10338
+ print(json.dumps(result, ensure_ascii=False, indent=2))
10339
+ raise APError(
10340
+ f"Reviewer runtime failed with exit code {completed.returncode}; review is blocked."
10341
+ )
10342
+
10343
+ try:
10344
+ stdout = _bounded_reviewer_output(completed.stdout, "stdout")
10345
+ _bounded_reviewer_output(completed.stderr, "stderr")
10346
+ raw = _read_bounded_reviewer_output(result_path) if result_path.exists() else stdout
10347
+ payload = json.loads(raw)
10348
+ result = _normalize_reviewer_runtime_result(assignment, payload)
10349
+ except (APError, json.JSONDecodeError, UnicodeDecodeError) as exc:
10350
+ result = _blocked_reviewer_runtime_result(
10351
+ assignment,
10352
+ "Reviewer runtime returned an invalid result.",
10353
+ ["result_contract_valid=false"],
10354
+ )
10355
+ _write_private_json(result_path, result)
10356
+ _update_review_runtime(
10357
+ control_repo,
10358
+ task_id,
10359
+ fingerprint,
10360
+ updates={
10361
+ "verdict": "blocked",
10362
+ "reason": "invalid reviewer runtime result",
10363
+ "runtime_state": "failed",
10364
+ "runtime_finished_at": finished_at,
10365
+ "runtime_exit_code": completed.returncode,
10366
+ },
10367
+ receipt_path=receipt_path,
10368
+ receipt_updates={
10369
+ "status": "result-invalid",
10370
+ "finished_at": finished_at,
10371
+ "exit_code": completed.returncode,
10372
+ },
10373
+ )
10374
+ print(json.dumps(result, ensure_ascii=False, indent=2))
10375
+ raise APError(f"Reviewer runtime result is invalid; review is blocked: {exc}") from exc
10376
+
10377
+ _write_private_json(result_path, result)
10378
+ result_sha256 = _review_result_file_sha256(result_path)
10379
+ runtime_state = "blocked" if result["verdict"] == "blocked" else "completed"
10380
+ _update_review_runtime(
10381
+ control_repo,
10382
+ task_id,
10383
+ fingerprint,
10384
+ updates={
10385
+ "verdict": "blocked" if result["verdict"] == "blocked" else "pending",
10386
+ "reason": "reviewer reported blocked" if result["verdict"] == "blocked" else "",
10387
+ "runtime_state": runtime_state,
10388
+ "runtime_finished_at": finished_at,
10389
+ "runtime_exit_code": completed.returncode,
10390
+ },
10391
+ receipt_path=receipt_path,
10392
+ receipt_updates={
10393
+ "status": runtime_state,
10394
+ "finished_at": finished_at,
10395
+ "exit_code": completed.returncode,
10396
+ "verdict": result["verdict"],
10397
+ "result_sha256": result_sha256,
10398
+ },
10399
+ )
10400
+ if result["verdict"] == "blocked":
10401
+ print(json.dumps(result, ensure_ascii=False, indent=2))
10402
+ raise APError("Reviewer returned blocked; task-review was not recorded.")
10403
+
10404
+ with contextlib.redirect_stdout(io.StringIO()):
10405
+ cmd_task_review(
10406
+ argparse.Namespace(
10407
+ repo=str(repo),
10408
+ task_id=task_id,
10409
+ verdict=result["verdict"],
10410
+ diff_fingerprint=fingerprint,
10411
+ reviewer=reviewer,
10412
+ )
10413
+ )
10414
+ print(json.dumps(result, ensure_ascii=False, indent=2))
10415
+
10416
+
8733
10417
  def cmd_task_review(args: argparse.Namespace) -> None:
8734
10418
  repo = Path(args.repo).resolve()
8735
10419
  ensure_git_repo(repo)
@@ -8767,7 +10451,137 @@ def cmd_task_review(args: argparse.Namespace) -> None:
8767
10451
  writer = _text((manifest.get("writer_lease") or {}).get("holder"))
8768
10452
  if reviewer == writer:
8769
10453
  raise APError("Independent reviewer identity must differ from the current writer lease holder.")
8770
- manifest["review"] = {
10454
+ assigned_review = manifest.get("review") or {}
10455
+ if bool(manifest.get("review_required")) and not all(
10456
+ _text(assigned_review.get(field))
10457
+ for field in ("assignment_path", "reviewer", "diff_fingerprint", "deadline_at")
10458
+ ):
10459
+ raise APError(
10460
+ "Review-required tasks must use review-assignment before task-review."
10461
+ )
10462
+ assigned_reviewer = _text(assigned_review.get("reviewer"))
10463
+ if assigned_reviewer and reviewer != assigned_reviewer:
10464
+ raise APError(
10465
+ f"Review verdict reviewer mismatch: assigned={assigned_reviewer}, supplied={reviewer}."
10466
+ )
10467
+ assigned_fingerprint = _text(assigned_review.get("diff_fingerprint"))
10468
+ if assigned_fingerprint and assigned_fingerprint != fingerprint:
10469
+ raise APError("Review assignment is stale; issue a new assignment for the current diff.")
10470
+ assigned_head = _text(assigned_review.get("diff_head"))
10471
+ current_head = _resolve_commit(worktree, "HEAD")
10472
+ if assigned_head and assigned_head != current_head:
10473
+ raise APError("Review assignment HEAD is stale for the current task.")
10474
+ assignment_path = _text(assigned_review.get("assignment_path"))
10475
+ assignment: Optional[dict] = None
10476
+ if assignment_path:
10477
+ expected_assignment_path = (
10478
+ _task_state_root(control_repo)
10479
+ / "reviews"
10480
+ / f"{task_id}-{fingerprint}.assignment.json"
10481
+ ).resolve()
10482
+ if Path(assignment_path).resolve() != expected_assignment_path:
10483
+ raise APError("Review assignment path does not match Git-local task state.")
10484
+ assignment = _read_json_object(expected_assignment_path)
10485
+ if not assignment:
10486
+ raise APError("Review assignment file is missing or invalid.")
10487
+ _validate_orchestration_contract("assignment", assignment)
10488
+ expected_assignment_fields = {
10489
+ "task_id": task_id,
10490
+ "base_sha": _text(manifest.get("base_sha")),
10491
+ "diff_base": _text(manifest.get("base_sha")),
10492
+ "diff_head": current_head,
10493
+ "diff_fingerprint": fingerprint,
10494
+ "node_id": reviewer,
10495
+ "owning_fixer": _text((manifest.get("writer_lease") or {}).get("holder")),
10496
+ "issued_at": _text(assigned_review.get("issued_at")),
10497
+ "deadline_at": _text(assigned_review.get("deadline_at")),
10498
+ }
10499
+ mismatched = [
10500
+ field
10501
+ for field, expected in expected_assignment_fields.items()
10502
+ if assignment.get(field) != expected
10503
+ ]
10504
+ if mismatched:
10505
+ raise APError(
10506
+ "Review assignment does not match the recorded task state: "
10507
+ + ", ".join(mismatched)
10508
+ )
10509
+ if int(assignment.get("scope_revision") or 0) != int(
10510
+ manifest.get("scope_revision") or 1
10511
+ ):
10512
+ raise APError("Review assignment scope revision is stale.")
10513
+ runtime_state = _text(assigned_review.get("runtime_state"))
10514
+ if runtime_state:
10515
+ if runtime_state != "completed":
10516
+ raise APError(
10517
+ f"Reviewer runtime state={runtime_state} cannot be recorded by task-review."
10518
+ )
10519
+ if assignment is None:
10520
+ raise APError("Reviewer runtime result has no validated assignment.")
10521
+ if assigned_review.get("runtime_exit_code") != 0:
10522
+ raise APError("Reviewer runtime did not exit successfully.")
10523
+ expected_result_path, expected_receipt_path = _review_runtime_paths(
10524
+ control_repo,
10525
+ task_id,
10526
+ fingerprint,
10527
+ )
10528
+ result_path = Path(_text(assigned_review.get("runtime_result_path"))).resolve()
10529
+ receipt_path = Path(_text(assigned_review.get("runtime_receipt_path"))).resolve()
10530
+ if result_path != expected_result_path.resolve():
10531
+ raise APError("Reviewer runtime result path does not match Git-local task state.")
10532
+ if receipt_path != expected_receipt_path.resolve():
10533
+ raise APError("Reviewer runtime receipt path does not match Git-local task state.")
10534
+ try:
10535
+ result_payload = json.loads(_read_bounded_reviewer_output(result_path))
10536
+ except (json.JSONDecodeError, UnicodeDecodeError) as exc:
10537
+ raise APError("Reviewer runtime result file is invalid JSON.") from exc
10538
+ if not isinstance(result_payload, dict):
10539
+ raise APError("Reviewer runtime result file must contain one JSON object.")
10540
+ _validate_orchestration_contract("result", result_payload)
10541
+ normalized_result = _normalize_reviewer_runtime_result(assignment, result_payload)
10542
+ if result_payload != normalized_result:
10543
+ raise APError("Reviewer runtime result file is not the canonical bound result.")
10544
+ if _text(result_payload.get("verdict")) != _text(args.verdict):
10545
+ raise APError(
10546
+ "Reviewer runtime verdict does not match the requested task-review verdict."
10547
+ )
10548
+ receipt = _read_json_object(receipt_path)
10549
+ if not receipt:
10550
+ raise APError("Reviewer runtime receipt is missing or invalid.")
10551
+ expected_receipt = {
10552
+ "task_id": task_id,
10553
+ "reviewer": reviewer,
10554
+ "diff_fingerprint": fingerprint,
10555
+ "result_path": str(expected_result_path),
10556
+ "status": "completed",
10557
+ "verdict": _text(args.verdict),
10558
+ "result_sha256": _review_result_file_sha256(result_path),
10559
+ }
10560
+ receipt_mismatches = [
10561
+ field
10562
+ for field, expected in expected_receipt.items()
10563
+ if receipt.get(field) != expected
10564
+ ]
10565
+ if receipt_mismatches:
10566
+ raise APError(
10567
+ "Reviewer runtime receipt does not bind the recorded result: "
10568
+ + ", ".join(receipt_mismatches)
10569
+ )
10570
+ deadline_at = _text(assigned_review.get("deadline_at"))
10571
+ completed_at = _dt.datetime.now(_dt.timezone.utc)
10572
+ if (
10573
+ _text(assigned_review.get("runtime_state")) == "completed"
10574
+ and _text(assigned_review.get("runtime_finished_at"))
10575
+ ):
10576
+ completed_at = _parse_iso_timestamp(
10577
+ assigned_review.get("runtime_finished_at"),
10578
+ "runtime_finished_at",
10579
+ )
10580
+ if deadline_at and completed_at > _parse_iso_timestamp(deadline_at, "deadline_at"):
10581
+ raise APError(
10582
+ "Review assignment deadline expired; the single review attempt is blocked."
10583
+ )
10584
+ review_state = {
8771
10585
  "verdict": args.verdict,
8772
10586
  "diff_base": _text(manifest.get("base_sha")),
8773
10587
  "diff_head": _resolve_commit(worktree, "HEAD"),
@@ -8775,7 +10589,16 @@ def cmd_task_review(args: argparse.Namespace) -> None:
8775
10589
  "reviewer": reviewer,
8776
10590
  "reviewed_at": _now_iso(),
8777
10591
  "reason": "",
10592
+ "assignment_path": assignment_path,
10593
+ "issued_at": _text(assigned_review.get("issued_at")),
10594
+ "deadline_at": deadline_at,
10595
+ "review_depth": _text(manifest.get("review_depth")),
10596
+ "review_timeout_seconds": int(manifest.get("review_timeout_seconds") or 0),
8778
10597
  }
10598
+ for field in _REVIEW_RUNTIME_FIELDS:
10599
+ if field in assigned_review:
10600
+ review_state[field] = assigned_review[field]
10601
+ manifest["review"] = review_state
8779
10602
  _save_task_manifest(control_repo, manifest)
8780
10603
  print(f"[task-review] task={task_id} verdict={args.verdict} fingerprint={fingerprint}")
8781
10604
 
@@ -9862,12 +11685,17 @@ def main(argv: Optional[List[str]] = None) -> int:
9862
11685
 
9863
11686
  s = sp.add_parser("wait-health")
9864
11687
  s.add_argument("--scope", choices=["runtime", "target", "prod"], default="runtime")
11688
+ s.add_argument("--component", choices=["frontend", "backend"], default="backend")
11689
+ s.add_argument("--path")
11690
+ s.add_argument("--timeout-sec", type=int)
9865
11691
  s.set_defaults(func=cmd_wait_health)
9866
11692
 
9867
11693
  s = sp.add_parser("verify-jenkins")
11694
+ s.add_argument("--component", choices=["all", "frontend", "backend"], default="all")
9868
11695
  s.set_defaults(func=cmd_verify_jenkins)
9869
11696
 
9870
11697
  s = sp.add_parser("verify-jenkins-build")
11698
+ s.add_argument("--component", choices=["frontend", "backend"])
9871
11699
  s.add_argument("--git-ref")
9872
11700
  s.add_argument("--job-name")
9873
11701
  s.add_argument("--job-url")
@@ -9917,6 +11745,7 @@ def main(argv: Optional[List[str]] = None) -> int:
9917
11745
  s.add_argument("--writers", type=int, default=1)
9918
11746
  s.add_argument("--isolated", action="store_true")
9919
11747
  s.add_argument("--review-required", action="store_true")
11748
+ s.add_argument("--review-depth", choices=["focused", "deep"])
9920
11749
  s.add_argument("--continue-direct", action="store_true")
9921
11750
  s.add_argument("--direct-claim")
9922
11751
  s.add_argument(
@@ -9944,6 +11773,25 @@ def main(argv: Optional[List[str]] = None) -> int:
9944
11773
  s.add_argument("--json", action="store_true")
9945
11774
  s.set_defaults(func=cmd_task_scope_add)
9946
11775
 
11776
+ s = sp.add_parser(
11777
+ "review-assignment",
11778
+ help="Generate and persist a deadline-bound reviewer assignment for a registered task",
11779
+ )
11780
+ s.add_argument("task_id")
11781
+ s.add_argument("--reviewer", required=True)
11782
+ s.add_argument("--json", action="store_true")
11783
+ s.set_defaults(func=cmd_review_assignment)
11784
+
11785
+ s = sp.add_parser(
11786
+ "review-run",
11787
+ help="Run the independent Codex Reviewer under the assignment's fixed runtime deadline",
11788
+ )
11789
+ s.add_argument("task_id")
11790
+ s.add_argument("--reviewer", required=True)
11791
+ s.add_argument("--json", action="store_true")
11792
+ s.add_argument("--runner-command-json", help=argparse.SUPPRESS)
11793
+ s.set_defaults(func=cmd_review_run)
11794
+
9947
11795
  s = sp.add_parser("task-submodule-sync")
9948
11796
  s.add_argument("task_id")
9949
11797
  s.set_defaults(func=cmd_task_submodule_sync)