claude-dev-env 8.111.5 → 8.112.1

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.
Files changed (53) hide show
  1. package/.agents/skills/build-eval/evals/review/README.md +2 -2
  2. package/.agents/skills/build-eval/evals/review/review_eval_support/account.py +166 -0
  3. package/.agents/skills/build-eval/evals/review/review_eval_support/config/constants.py +26 -0
  4. package/.agents/skills/build-eval/evals/review/review_eval_support/execution.py +8 -0
  5. package/.agents/skills/build-eval/evals/review/test_run.py +261 -0
  6. package/_shared/advisor/reference/astra-rung.md +13 -5
  7. package/_shared/advisor/scripts/codex_astra_advisor.py +31 -8
  8. package/_shared/advisor/scripts/codex_astra_preflight.py +70 -14
  9. package/_shared/advisor/scripts/config/advisor_scripts_constants/astra_advisor_constants.py +7 -0
  10. package/_shared/advisor/scripts/tests/test_codex_astra_advisor.py +266 -2
  11. package/_shared/advisor/scripts/tests/test_codex_astra_preflight.py +114 -8
  12. package/_shared/pr-loop/scripts/check_convergence.py +5 -1
  13. package/_shared/pr-loop/scripts/codex_review_account.py +180 -0
  14. package/_shared/pr-loop/scripts/codex_review_scripts_constants/account_constants.py +28 -0
  15. package/_shared/pr-loop/scripts/codex_review_scripts_constants/run_constants.py +3 -1
  16. package/_shared/pr-loop/scripts/run_codex_review.py +144 -15
  17. package/_shared/pr-loop/scripts/test_check_convergence_codex.py +3 -3
  18. package/_shared/pr-loop/scripts/test_codex_review_account.py +355 -0
  19. package/_shared/pr-loop/scripts/test_run_codex_review.py +507 -6
  20. package/docs/account-broker.md +5 -3
  21. package/docs/codex-accounts.md +57 -16
  22. package/docs/rule-guides/question-presentation.md +4 -0
  23. package/hooks/blocking/final_reply_gate.py +59 -3
  24. package/hooks/blocking/open_tasks_transcript.py +18 -0
  25. package/hooks/blocking/test_final_reply_gate.py +160 -0
  26. package/hooks/features/conduct-gates.md +1 -4
  27. package/hooks/hooks.json +0 -10
  28. package/hooks/hooks_constants/final_reply_gate_constants.py +16 -0
  29. package/hooks/hooks_constants/open_tasks_stop_gate_constants.py +9 -0
  30. package/package.json +1 -1
  31. package/rules/question-presentation.md +1 -1
  32. package/scripts/Sync-RepoMain.ps1 +86 -3
  33. package/scripts/account_broker.py +50 -25
  34. package/scripts/account_broker_support.py +54 -3
  35. package/scripts/codex_account_choice.py +12 -8
  36. package/scripts/codex_account_chooser.py +110 -0
  37. package/scripts/codex_account_meters.py +43 -4
  38. package/scripts/codex_plan_rules.py +156 -0
  39. package/scripts/dev_env_scripts_constants/account_broker_constants.py +29 -42
  40. package/scripts/dev_env_scripts_constants/codex_account_constants.py +62 -2
  41. package/scripts/dev_env_scripts_constants/test_account_broker_constants.py +359 -2
  42. package/scripts/dev_env_scripts_constants/test_codex_account_constants.py +213 -14
  43. package/scripts/policy_lint/adapter_configuration.py +0 -5
  44. package/scripts/policy_lint/config/constants.py +0 -1
  45. package/scripts/test_account_broker.py +1756 -523
  46. package/scripts/test_account_broker_support.py +77 -0
  47. package/scripts/test_codex_account_meters.py +95 -0
  48. package/scripts/tests/Sync-RepoMain.Tests.ps1 +55 -0
  49. package/scripts/tests/test_adapter_configuration.py +0 -8
  50. package/scripts/tests/test_sync_repo_main_mirror.py +60 -0
  51. package/hooks/blocking/merge_over_review_offer_gate.py +0 -114
  52. package/hooks/blocking/test_merge_over_review_offer_gate.py +0 -138
  53. package/hooks/hooks_constants/merge_over_review_offer_gate_constants.py +0 -34
@@ -0,0 +1,180 @@
1
+ """Choose the Codex account a review runs on from the account broker's answer.
2
+
3
+ ::
4
+
5
+ broker exit 0, tier normal, home "C:/profiles/codex-1" -> Path("C:/profiles/codex-1")
6
+ broker exit 3 (wait), or a tier other than normal -> CodexAccountUnavailable
7
+ broker exit 2, no JSON, no home -> CodexAccountUnavailable
8
+
9
+ The broker answers only with an account on a listed paid plan, never a free,
10
+ unknown, or unlisted plan, so the home it names is the only account a review may
11
+ use. A home already set in ``CODEX_HOME`` goes through the same broker check,
12
+ which refuses it when its plan is free, unknown, or not a listed paid plan, or its
13
+ meters are unread. A paid plan passes whatever its room.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ import sys
20
+ from pathlib import Path
21
+
22
+ from codex_review_scripts_constants.account_constants import (
23
+ ACCOUNT_BROKER_CHOOSE_COMMAND,
24
+ ACCOUNT_BROKER_CODEX_PRODUCT,
25
+ ACCOUNT_BROKER_HOME_FLAG,
26
+ ACCOUNT_BROKER_PRODUCT_FLAG,
27
+ ALL_ACCOUNT_BROKER_RELATIVE_PARTS,
28
+ ALL_ACCOUNT_BROKER_REQUIRE_TIER_ARGUMENTS,
29
+ ALL_BROKER_ACCEPTED_EXIT_CODES,
30
+ ALL_NORMAL_ONLY_TIERS,
31
+ BROKER_DECISION_KEY,
32
+ BROKER_EXIT_REASON_TEMPLATE,
33
+ BROKER_HOME_KEY,
34
+ BROKER_MALFORMED_REASON,
35
+ BROKER_NO_HOME_REASON,
36
+ BROKER_REASON_KEY,
37
+ BROKER_TIER_KEY,
38
+ BROKER_WAIT_EXIT_CODE,
39
+ NO_ACCOUNT_EXIT_CODE,
40
+ NO_ROOM_REASON_TEMPLATE,
41
+ SHARED_ROOT_PARENT_INDEX,
42
+ )
43
+
44
+
45
+ class CodexAccountUnavailable(Exception):
46
+ """No Codex account can run the review, so the review does not start.
47
+
48
+ Attributes:
49
+ exit_code: The broker's own exit code, or the no-account sentinel.
50
+ reason: Plain-words cause for the caller's report.
51
+ """
52
+
53
+ def __init__(self, exit_code: int, reason: str) -> None:
54
+ super().__init__(reason)
55
+ self.exit_code = exit_code
56
+ self.reason = reason
57
+
58
+
59
+ def account_broker_path() -> Path:
60
+ """Return the account broker in the scripts directory beside the shared tree.
61
+
62
+ ::
63
+
64
+ ~/.claude/_shared/pr-loop/scripts -> ~/.claude/scripts/account_broker.py
65
+
66
+ Returns:
67
+ Path to ``account_broker.py``.
68
+ """
69
+ shared_root = Path(__file__).resolve().parents[SHARED_ROOT_PARENT_INDEX]
70
+ return shared_root.joinpath(*ALL_ACCOUNT_BROKER_RELATIVE_PARTS)
71
+
72
+
73
+ def broker_choose_command() -> list[str]:
74
+ """Return the command that asks the broker for a Codex account.
75
+
76
+ Returns:
77
+ Interpreter, broker path, and the ``choose --product codex --require-tier normal`` arguments.
78
+ """
79
+ return [
80
+ sys.executable,
81
+ str(account_broker_path()),
82
+ ACCOUNT_BROKER_CHOOSE_COMMAND,
83
+ ACCOUNT_BROKER_PRODUCT_FLAG,
84
+ ACCOUNT_BROKER_CODEX_PRODUCT,
85
+ *ALL_ACCOUNT_BROKER_REQUIRE_TIER_ARGUMENTS,
86
+ ]
87
+
88
+
89
+ def broker_home_check_command(codex_home: str) -> list[str]:
90
+ """Return the command that asks the broker whether one Codex home may run.
91
+
92
+ Args:
93
+ codex_home: The Codex home path already set for the review.
94
+
95
+ Returns:
96
+ Interpreter, broker path, and the ``choose --product codex --home`` arguments.
97
+ """
98
+ return [
99
+ sys.executable,
100
+ str(account_broker_path()),
101
+ ACCOUNT_BROKER_CHOOSE_COMMAND,
102
+ ACCOUNT_BROKER_PRODUCT_FLAG,
103
+ ACCOUNT_BROKER_CODEX_PRODUCT,
104
+ ACCOUNT_BROKER_HOME_FLAG,
105
+ codex_home,
106
+ ]
107
+
108
+
109
+ def _decision_fields(answer_text: str) -> dict[str, object]:
110
+ try:
111
+ answer = json.loads(answer_text)
112
+ except (TypeError, json.JSONDecodeError) as error:
113
+ raise CodexAccountUnavailable(
114
+ NO_ACCOUNT_EXIT_CODE, BROKER_MALFORMED_REASON
115
+ ) from error
116
+ decision = answer.get(BROKER_DECISION_KEY) if isinstance(answer, dict) else None
117
+ if not isinstance(decision, dict):
118
+ raise CodexAccountUnavailable(NO_ACCOUNT_EXIT_CODE, BROKER_MALFORMED_REASON)
119
+ return decision
120
+
121
+
122
+ def codex_home_from_broker_answer(
123
+ exit_code: int,
124
+ answer_text: str,
125
+ all_accepted_tiers: tuple[str, ...] = ALL_NORMAL_ONLY_TIERS,
126
+ ) -> Path:
127
+ """Read the Codex home a review may run on from the broker's answer.
128
+
129
+ ::
130
+
131
+ exit 0, {"decision": {"tier": "normal", "home": "C:/p/codex-1"}} -> Path("C:/p/codex-1")
132
+ exit 3, {"decision": {"tier": "wait", "reason": "..."}} -> refused
133
+ exit 0, {"decision": {"tier": "luna", "home": "C:/p/codex-1"}} -> refused
134
+
135
+ With no home pinned, a review runs only on the ``normal`` tier, as the
136
+ convergence gate and the Astra advisor do. ``luna`` and ``wait`` mean no
137
+ account has room for one. A home pinned in ``CODEX_HOME`` goes through the
138
+ broker too. The broker refuses it unless its plan is paid and its meters can
139
+ be read, and it answers ``wait`` while a saved spent mark holds the roster
140
+ account that has that home. A home the roster does not list reads as an
141
+ account named for its folder, so a mark saved for the no-roster default
142
+ account, named ``default``, does not hold ``--home <that home>`` unless the
143
+ folder of that home is also named ``default``. A home that passes runs at any
144
+ tier, so the caller passes every tier the broker may run, and launches on the
145
+ home the answer names. The Astra advisor treats a pinned home the same way.
146
+
147
+ Args:
148
+ exit_code: Exit code of ``account_broker.py choose --product codex``.
149
+ answer_text: Standard output of that command.
150
+ all_accepted_tiers: Tiers the answer may name, ``normal`` only by default.
151
+
152
+ Returns:
153
+ The Codex home to set as ``CODEX_HOME`` for the review.
154
+
155
+ Raises:
156
+ CodexAccountUnavailable: The broker exited with a code other than 0 or
157
+ 3, printed text that is not JSON or JSON with no ``decision``
158
+ object, waited, chose a tier outside ``all_accepted_tiers``, or
159
+ named no home.
160
+ """
161
+ if exit_code not in ALL_BROKER_ACCEPTED_EXIT_CODES:
162
+ raise CodexAccountUnavailable(
163
+ exit_code, BROKER_EXIT_REASON_TEMPLATE.format(exit_code=exit_code)
164
+ )
165
+ decision = _decision_fields(answer_text)
166
+ if (
167
+ exit_code == BROKER_WAIT_EXIT_CODE
168
+ or decision.get(BROKER_TIER_KEY) not in all_accepted_tiers
169
+ ):
170
+ reason = decision.get(BROKER_REASON_KEY)
171
+ raise CodexAccountUnavailable(
172
+ NO_ACCOUNT_EXIT_CODE,
173
+ NO_ROOM_REASON_TEMPLATE.format(
174
+ reason=reason if isinstance(reason, str) else ""
175
+ ),
176
+ )
177
+ chosen_home = decision.get(BROKER_HOME_KEY)
178
+ if not isinstance(chosen_home, str) or not chosen_home:
179
+ raise CodexAccountUnavailable(NO_ACCOUNT_EXIT_CODE, BROKER_NO_HOME_REASON)
180
+ return Path(chosen_home)
@@ -0,0 +1,28 @@
1
+ """Named constants for choosing the Codex account a review runs on."""
2
+
3
+ from __future__ import annotations
4
+
5
+ ACCOUNT_BROKER_CHOOSE_COMMAND = "choose"
6
+ ACCOUNT_BROKER_PRODUCT_FLAG = "--product"
7
+ ACCOUNT_BROKER_CODEX_PRODUCT = "codex"
8
+ ALL_ACCOUNT_BROKER_REQUIRE_TIER_ARGUMENTS = ("--require-tier", "normal")
9
+ ALL_ACCOUNT_BROKER_RELATIVE_PARTS = ("scripts", "account_broker.py")
10
+ SHARED_ROOT_PARENT_INDEX = 3
11
+ ACCOUNT_BROKER_TIMEOUT_SECONDS = 150
12
+ BROKER_WAIT_EXIT_CODE = 3
13
+ ALL_BROKER_ACCEPTED_EXIT_CODES = (0, BROKER_WAIT_EXIT_CODE)
14
+ NO_ACCOUNT_EXIT_CODE = 69
15
+ BROKER_DECISION_KEY = "decision"
16
+ BROKER_TIER_KEY = "tier"
17
+ BROKER_HOME_KEY = "home"
18
+ BROKER_REASON_KEY = "reason"
19
+ BROKER_NORMAL_TIER = "normal"
20
+ BROKER_LUNA_TIER = "luna"
21
+ ALL_NORMAL_ONLY_TIERS = (BROKER_NORMAL_TIER,)
22
+ ALL_RUN_TIERS = (BROKER_NORMAL_TIER, BROKER_LUNA_TIER)
23
+ ACCOUNT_BROKER_HOME_FLAG = "--home"
24
+ BROKER_NOT_RUN_REASON_TEMPLATE = "account broker did not answer: exit {exit_code}"
25
+ BROKER_EXIT_REASON_TEMPLATE = "account broker exit {exit_code}"
26
+ BROKER_MALFORMED_REASON = "account broker answer is malformed"
27
+ BROKER_NO_HOME_REASON = "account broker answer names no Codex home"
28
+ NO_ROOM_REASON_TEMPLATE = "no Codex account has room for a review ({reason})"
@@ -26,12 +26,14 @@ VERSION_PROBE_PATTERN = r"codex(?:-cli)?\s+(\d+\.\d+\.\d+)"
26
26
  OUTCOME_CLASS_CODEX_DOWN = "codex_down"
27
27
  OUTCOME_CLASS_COMPLETED = "completed"
28
28
  MISSING_BINARY_EXIT_CODE = 127
29
+ CANNOT_EXECUTE_EXIT_CODE = 126
29
30
  TIMEOUT_EXIT_CODE = 124
30
- SUBPROCESS_DECODE_EXIT_CODE = 70
31
31
  CWD_KEYWORD = "cwd"
32
32
  CAPTURE_STREAMS_KEYWORD = "capture_output"
33
33
  TEXT_MODE_KEYWORD = "text"
34
34
  ENCODING_KEYWORD = "encoding"
35
+ DECODE_ERRORS_KEYWORD = "errors"
36
+ DECODE_ERRORS_REPLACE = "replace"
35
37
  CHECK_KEYWORD = "check"
36
38
  TIMEOUT_KEYWORD = "timeout"
37
39
  ENVIRONMENT_KEYWORD = "env"
@@ -10,6 +10,20 @@
10
10
  review_outcome.outcome_class # "completed" or "codex_down"
11
11
  review_outcome.jsonl_path # path to captured JSONL stream
12
12
  review_outcome.agent_message # final agent_message text
13
+
14
+ The review runs on the Codex account the account broker chooses, with
15
+ ``CODEX_HOME`` set to the home it names. A ``CODEX_HOME`` already set keeps its
16
+ account once the broker confirms that account is on a listed paid plan, whatever
17
+ its room. When the broker does not answer, exits with a code other than 0 or 3,
18
+ prints an answer that holds no ``decision`` object, waits, answers a tier the
19
+ wrapper does not accept, or names no home, no review starts and the outcome is
20
+ ``codex_down``. A broker that does not answer covers a timeout (124), a missing
21
+ interpreter binary (127), and any other ``OSError`` from the spawn, such as
22
+ ``PermissionError`` (126). A missing ``account_broker.py`` makes Python exit 2,
23
+ and that code is the exit code of the outcome. Exit 69 covers a malformed
24
+ answer, a wait, a refused tier, and an answer that names no home. Output that is
25
+ not UTF-8 is decoded with replacement characters and checked like any other
26
+ output.
13
27
  """
14
28
 
15
29
  from __future__ import annotations
@@ -39,22 +53,32 @@ _shared_process_tree_scripts_directory = (
39
53
  if str(_shared_process_tree_scripts_directory) not in sys.path:
40
54
  sys.path.insert(0, str(_shared_process_tree_scripts_directory))
41
55
 
42
- from process_tree_kill import ( # noqa: E402
43
- should_start_new_session,
44
- terminate_process_tree,
56
+ from codex_review_account import (
57
+ CodexAccountUnavailable,
58
+ broker_choose_command,
59
+ broker_home_check_command,
60
+ codex_home_from_broker_answer,
45
61
  )
46
-
47
- from codex_review_scripts_constants.run_constants import ( # noqa: E402
62
+ from codex_review_scripts_constants.account_constants import (
63
+ ACCOUNT_BROKER_TIMEOUT_SECONDS,
64
+ ALL_RUN_TIERS,
65
+ BROKER_NOT_RUN_REASON_TEMPLATE,
66
+ )
67
+ from codex_review_scripts_constants.run_constants import (
48
68
  ALL_SHAPE_PROBE_REQUIRED_FLAGS,
49
69
  ALL_WINDOWS_SCRIPT_SUFFIXES,
50
70
  BASE_TARGET_FLAG,
71
+ CANNOT_EXECUTE_EXIT_CODE,
51
72
  CAPTURE_STREAMS_KEYWORD,
52
73
  CHECK_KEYWORD,
53
74
  CODEX_BINARY_NAME,
75
+ CODEX_HOME_ENV_VAR,
54
76
  CODEX_MODEL_PIN,
55
77
  COMMIT_TARGET_FLAG,
56
78
  CUSTOM_INSTRUCTIONS_PROMPT,
57
79
  CWD_KEYWORD,
80
+ DECODE_ERRORS_KEYWORD,
81
+ DECODE_ERRORS_REPLACE,
58
82
  DEFAULT_TIMEOUT_SECONDS,
59
83
  ENCODING_KEYWORD,
60
84
  ENVIRONMENT_KEYWORD,
@@ -75,7 +99,6 @@ from codex_review_scripts_constants.run_constants import ( # noqa: E402
75
99
  PROCESS_TREE_KILL_TIMEOUT_SECONDS,
76
100
  REVIEW_SUBCOMMAND,
77
101
  SHAPE_FLAG_TOKEN_TAIL_PATTERN,
78
- SUBPROCESS_DECODE_EXIT_CODE,
79
102
  TEXT_MODE_KEYWORD,
80
103
  TIMEOUT_EXIT_CODE,
81
104
  TIMEOUT_KEYWORD,
@@ -87,7 +110,10 @@ from codex_review_scripts_constants.run_constants import ( # noqa: E402
87
110
  WINDOWS_COMMAND_SHELL_RUN_FLAG,
88
111
  WINDOWS_OS_NAME,
89
112
  )
90
-
113
+ from process_tree_kill import (
114
+ should_start_new_session,
115
+ terminate_process_tree,
116
+ )
91
117
  from subprocess_window_access import hidden_window_creation_flags
92
118
 
93
119
 
@@ -100,6 +126,7 @@ def _open_codex_popen(
100
126
  stream_target = subprocess.PIPE if should_capture else None
101
127
  working_directory = all_keyword_arguments.get(CWD_KEYWORD)
102
128
  stream_encoding = all_keyword_arguments.get(ENCODING_KEYWORD)
129
+ decode_errors = all_keyword_arguments.get(DECODE_ERRORS_KEYWORD)
103
130
  process_environment = all_keyword_arguments.get(ENVIRONMENT_KEYWORD)
104
131
  return subprocess.Popen(
105
132
  all_arguments,
@@ -108,6 +135,7 @@ def _open_codex_popen(
108
135
  stderr=stream_target,
109
136
  text=bool(all_keyword_arguments.get(TEXT_MODE_KEYWORD, False)),
110
137
  encoding=stream_encoding if isinstance(stream_encoding, str) else None,
138
+ errors=decode_errors if isinstance(decode_errors, str) else None,
111
139
  env=process_environment if isinstance(process_environment, dict) else None,
112
140
  start_new_session=should_start_new_session(),
113
141
  creationflags=hidden_window_creation_flags(),
@@ -231,8 +259,8 @@ def _run_codex_process(
231
259
  """Run a codex process, killing its whole child tree on a timeout.
232
260
 
233
261
  Mirrors the ``subprocess.run`` keyword arguments the review wrapper passes:
234
- ``cwd``, ``capture_output``, ``text``, ``encoding``, ``check``, ``timeout``,
235
- and ``env``. Avoids ``Popen`` as a context manager so a surviving child after
262
+ ``cwd``, ``capture_output``, ``text``, ``encoding``, ``errors``, ``check``,
263
+ ``timeout``, and ``env``. Avoids ``Popen`` as a context manager so a surviving child after
236
264
  a timed-out drain cannot hang on an unbounded ``wait()``.
237
265
  """
238
266
  timeout_seconds = _optional_timeout_seconds(all_keyword_arguments.get(TIMEOUT_KEYWORD))
@@ -281,7 +309,12 @@ class CodexReviewOutcome:
281
309
  jsonl_path: Captured JSONL path, or None when review did not run.
282
310
  agent_message: Last JSONL ``agent_message`` text when present; on a
283
311
  non-zero review exit, falls back to stderr text when JSONL has no
284
- agent message (config and argument errors land on stderr).
312
+ agent message (config and argument errors land on stderr). When no
313
+ account could run the review, ``no Codex account has room for a
314
+ review (<the broker's reason>)`` for a ``wait`` or a refused tier,
315
+ and the script's own text for any other failure, such as
316
+ ``account broker exit 2``, ``account broker answer is malformed``
317
+ or ``account broker did not answer: exit 124``.
285
318
  """
286
319
 
287
320
  outcome_class: str
@@ -291,13 +324,15 @@ class CodexReviewOutcome:
291
324
  agent_message: str
292
325
 
293
326
 
294
- def _down(*, exit_code: int, binary_version: str) -> CodexReviewOutcome:
327
+ def _down(
328
+ *, exit_code: int, binary_version: str, agent_message: str = ""
329
+ ) -> CodexReviewOutcome:
295
330
  return CodexReviewOutcome(
296
331
  outcome_class=OUTCOME_CLASS_CODEX_DOWN,
297
332
  exit_code=exit_code,
298
333
  binary_version=binary_version,
299
334
  jsonl_path=None,
300
- agent_message="",
335
+ agent_message=agent_message,
301
336
  )
302
337
 
303
338
 
@@ -328,6 +363,7 @@ def _run_command(
328
363
  *,
329
364
  working_directory: Path | None,
330
365
  timeout_seconds: int,
366
+ all_process_environment: dict[str, str] | None = None,
331
367
  ) -> subprocess.CompletedProcess[str]:
332
368
  return codex_subprocess_runner(
333
369
  all_arguments,
@@ -335,9 +371,10 @@ def _run_command(
335
371
  capture_output=True,
336
372
  text=True,
337
373
  encoding=UTF8_ENCODING,
374
+ errors=DECODE_ERRORS_REPLACE,
338
375
  check=False,
339
376
  timeout=timeout_seconds,
340
- env=dict(os.environ),
377
+ env=dict(os.environ) if all_process_environment is None else all_process_environment,
341
378
  )
342
379
 
343
380
 
@@ -346,21 +383,23 @@ def _safe_run(
346
383
  *,
347
384
  working_directory: Path | None,
348
385
  timeout_seconds: int,
386
+ all_process_environment: dict[str, str] | None = None,
349
387
  ) -> subprocess.CompletedProcess[str] | int:
350
388
  try:
351
389
  return _run_command(
352
390
  all_arguments,
353
391
  working_directory=working_directory,
354
392
  timeout_seconds=timeout_seconds,
393
+ all_process_environment=all_process_environment,
355
394
  )
356
395
  except FileNotFoundError:
357
396
  if working_directory is not None and not working_directory.is_dir():
358
397
  raise
359
398
  return MISSING_BINARY_EXIT_CODE
399
+ except OSError:
400
+ return CANNOT_EXECUTE_EXIT_CODE
360
401
  except subprocess.TimeoutExpired:
361
402
  return TIMEOUT_EXIT_CODE
362
- except UnicodeDecodeError:
363
- return SUBPROCESS_DECODE_EXIT_CODE
364
403
 
365
404
 
366
405
  def _parse_binary_version(version_stdout: str) -> str:
@@ -497,6 +536,74 @@ def _probe_or_down(timeout_seconds: int) -> CodexReviewOutcome | str:
497
536
  return binary_version
498
537
 
499
538
 
539
+ def _broker_completion(
540
+ all_broker_arguments: list[str],
541
+ ) -> subprocess.CompletedProcess[str]:
542
+ broker_completion = _safe_run(
543
+ all_broker_arguments,
544
+ working_directory=None,
545
+ timeout_seconds=ACCOUNT_BROKER_TIMEOUT_SECONDS,
546
+ )
547
+ if isinstance(broker_completion, int):
548
+ raise CodexAccountUnavailable(
549
+ broker_completion,
550
+ BROKER_NOT_RUN_REASON_TEMPLATE.format(exit_code=broker_completion),
551
+ )
552
+ return broker_completion
553
+
554
+
555
+ def _review_environment() -> dict[str, str]:
556
+ """Return the environment the review runs in, with its Codex account chosen.
557
+
558
+ ::
559
+
560
+ CODEX_HOME " H " -> CODEX_HOME set to the home the broker answers for "H"
561
+ CODEX_HOME unset -> CODEX_HOME set to the home the account broker names
562
+ broker waits or fails -> CodexAccountUnavailable; the review does not start,
563
+ and ``run_codex_review`` returns ``codex_down``
564
+
565
+ An enclosing broker run, or a caller that exports ``CODEX_HOME``, has
566
+ already chosen the account, so the wrapper keeps that account. The broker
567
+ still checks that home, so a free-plan, unknown-plan, unlisted-plan, or
568
+ unreadable account never runs. The review launches on the home the broker
569
+ answers, the trimmed absolute folder it judged.
570
+
571
+ Returns:
572
+ The process environment for the review run.
573
+
574
+ Raises:
575
+ CodexAccountUnavailable: Raised, with the exit code in parentheses, when
576
+
577
+ - the broker did not answer: it timed out (124), its interpreter
578
+ binary is missing (127), or the spawn raised another ``OSError``
579
+ such as ``PermissionError`` (126);
580
+ - the broker exited with a code other than 0 or 3 (that code), such
581
+ as 2 when Python cannot open a missing ``account_broker.py``;
582
+ - its output is not JSON or holds no ``decision`` object (69);
583
+ - it waited, with exit code 3 (69);
584
+ - it answered a tier outside the accepted tiers, which are
585
+ ``normal`` with no home pinned and ``normal`` or ``luna`` for a
586
+ pinned home (69);
587
+ - it named no home (69).
588
+
589
+ Output that is not UTF-8 is decoded with replacement characters and
590
+ judged like any other output. ``run_codex_review`` catches this
591
+ exception and returns ``codex_down``.
592
+ """
593
+ exported_home = os.environ.get(CODEX_HOME_ENV_VAR, "").strip()
594
+ if exported_home:
595
+ home_check = _broker_completion(broker_home_check_command(exported_home))
596
+ judged_home = codex_home_from_broker_answer(
597
+ home_check.returncode, home_check.stdout or "", ALL_RUN_TIERS
598
+ )
599
+ return {**os.environ, CODEX_HOME_ENV_VAR: str(judged_home)}
600
+ broker_completion = _broker_completion(broker_choose_command())
601
+ chosen_home = codex_home_from_broker_answer(
602
+ broker_completion.returncode, broker_completion.stdout or ""
603
+ )
604
+ return {**os.environ, CODEX_HOME_ENV_VAR: str(chosen_home)}
605
+
606
+
500
607
  def _capture_review_run(
501
608
  *,
502
609
  repository_directory: Path,
@@ -504,11 +611,13 @@ def _capture_review_run(
504
611
  all_review_arguments: list[str],
505
612
  timeout_seconds: int,
506
613
  binary_version: str,
614
+ all_review_environment: dict[str, str],
507
615
  ) -> CodexReviewOutcome:
508
616
  completion_or_exit = _safe_run(
509
617
  all_review_arguments,
510
618
  working_directory=repository_directory,
511
619
  timeout_seconds=timeout_seconds,
620
+ all_process_environment=all_review_environment,
512
621
  )
513
622
  if isinstance(completion_or_exit, int):
514
623
  return _down(exit_code=completion_or_exit, binary_version=binary_version)
@@ -560,6 +669,17 @@ def run_codex_review(
560
669
  ok: outcome_class == "completed" and exit_code == 0
561
670
  flag: outcome_class == "codex_down" even when exit_code == 0
562
671
  (shape probe ran, required flags missing)
672
+ flag: outcome_class == "codex_down", jsonl_path None, exit_code 69
673
+ (no Codex account has room, the tier is refused, the broker
674
+ answer is malformed, or it names no home; the review never
675
+ started)
676
+ flag: outcome_class == "codex_down", jsonl_path None, exit_code 124,
677
+ 126 or 127 (a codex probe, the broker or the review process
678
+ timed out, could not start, or its binary or interpreter is
679
+ missing)
680
+ flag: outcome_class == "codex_down", jsonl_path None, exit_code 2
681
+ (the broker's own exit code, as when Python cannot open a
682
+ missing account_broker.py)
563
683
 
564
684
  Args:
565
685
  repository_directory: Repository root used as the process cwd.
@@ -596,6 +716,14 @@ def run_codex_review(
596
716
  probe_outcome = _probe_or_down(resolved_timeout_seconds)
597
717
  if isinstance(probe_outcome, CodexReviewOutcome):
598
718
  return probe_outcome
719
+ try:
720
+ review_environment = _review_environment()
721
+ except CodexAccountUnavailable as unavailable_account:
722
+ return _down(
723
+ exit_code=unavailable_account.exit_code,
724
+ binary_version=probe_outcome,
725
+ agent_message=unavailable_account.reason,
726
+ )
599
727
  return _capture_review_run(
600
728
  repository_directory=repository_directory,
601
729
  run_state_directory=run_state_directory,
@@ -607,4 +735,5 @@ def run_codex_review(
607
735
  ),
608
736
  timeout_seconds=resolved_timeout_seconds,
609
737
  binary_version=probe_outcome,
738
+ all_review_environment=review_environment,
610
739
  )
@@ -527,7 +527,7 @@ def test_should_read_normal_tier_from_broker_decision(
527
527
  broker_path = tmp_path / "account_broker.py"
528
528
  broker_path.write_text(
529
529
  "import json, sys\n"
530
- "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
530
+ "assert sys.argv[1:] == ['choose', '--product', 'codex', '--require-tier', 'normal']\n"
531
531
  "print(json.dumps({'decision': {'tier': 'normal', 'reason': 'room'}, 'accounts': []}))\n",
532
532
  encoding="utf-8",
533
533
  )
@@ -542,7 +542,7 @@ def test_should_read_wait_tier_from_broker_exit_three(
542
542
  broker_path = tmp_path / "account_broker.py"
543
543
  broker_path.write_text(
544
544
  "import json, sys\n"
545
- "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
545
+ "assert sys.argv[1:] == ['choose', '--product', 'codex', '--require-tier', 'normal']\n"
546
546
  "print(json.dumps({'decision': {'tier': 'wait', 'reason': 'no room'}, 'accounts': []}))\n"
547
547
  "sys.exit(3)\n",
548
548
  encoding="utf-8",
@@ -567,7 +567,7 @@ def test_should_read_the_tier_the_broker_chooses(
567
567
  tmp_path,
568
568
  monkeypatch,
569
569
  "import json, sys\n"
570
- "assert sys.argv[1:] == ['choose', '--product', 'codex']\n"
570
+ "assert sys.argv[1:] == ['choose', '--product', 'codex', '--require-tier', 'normal']\n"
571
571
  "print(json.dumps({'decision': {'tier': 'normal', 'account': 'codex-2'}, 'accounts': []}))\n",
572
572
  )
573
573