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
@@ -28,9 +28,9 @@ python $suite live --limit 2 --timeout 90 --model gpt-6.1-sol --effort low --out
28
28
  python $suite live --split heldout --limit 6 --timeout 90 --model gpt-6.1-sol --effort low --output review-heldout
29
29
  ```
30
30
 
31
- On Windows, pass `--codex <absolute-path-to-codex.exe>` when the shell launcher cannot run through `subprocess`. The adapter uses the existing login, `codex exec --json --output-schema`, ignores user config, and preserves account authentication. It never installs a service or creates credentials. Choose the account's supported model explicitly.
31
+ On Windows, pass `--codex <absolute-path-to-codex.exe>` when the shell launcher cannot run through `subprocess`. The adapter asks the account broker (`account_broker.py choose --product codex --require-tier normal`) for a Codex home before each model run and sets `CODEX_HOME` to the home it names. With no `CODEX_HOME` set, or a blank one, it runs only on the `normal` tier. A `wait`, a `luna` answer, a missing broker or a broker failure records `infra_error` with the failure `no_codex_account` and starts no model call. A non-blank `CODEX_HOME` already set in the environment goes to the broker as `choose --product codex --home <path>`, trimmed of surrounding whitespace, and the run accepts `normal` or `luna` for it. The model run launches on the home the broker answers, the trimmed absolute folder it judged, so whitespace around the exported value never reaches Codex. A free or unknown plan, a `wait`, an unreadable home, or a broker failure records `infra_error` the same way. The adapter runs `codex exec --json --output-schema`, ignores user config, and preserves account authentication. It never installs a service or creates credentials. The broker call runs before each model call under its own 150-second ceiling, which neither `--timeout` nor `--max-seconds` shortens. Its time counts against the `--max-seconds` deadline, so a later case gets less time or `batch_timeout`, and a batch can end up to 150 seconds past `--max-seconds`. Each case's `latency_seconds` includes it. Choose the account's supported model explicitly.
32
32
 
33
- Before each model run, record CLI and Python versions, model, effort and estimated usage. The default smoke makes at most two calls with 90-second ceilings and a three-minute batch ceiling. `--max-seconds` bounds the model-call portion of any batch and accepts at most 600 seconds. It stops on the first infrastructure failure and has no retries. The runner cannot enforce a dollar budget because the CLI does not expose a documented dollar cap here. Account billing varies; a larger run requires an agreed estimate first. The bounded CLI timeout stops the child process but cannot guarantee upstream cancellation. A run with a failed, invalid or missing attempt returns status 1.
33
+ Before each model run, record CLI and Python versions, model, effort and estimated usage. The default smoke makes at most two calls with 90-second ceilings and a three-minute batch ceiling. `--max-seconds` bounds the summed model-call time of a batch and accepts at most 600 seconds. Each case's model-call ceiling is fixed before its broker call starts, so a model call can begin after the deadline has passed on the wall clock. The batch stops on the first infrastructure failure and has no retries. The runner cannot enforce a dollar budget because the CLI does not expose a documented dollar cap here. Account billing varies; a larger run requires an agreed estimate first. The bounded CLI timeout stops the child process but cannot guarantee upstream cancellation. A run with a failed, invalid or missing attempt returns status 1.
34
34
 
35
35
  Every output directory is new. It holds prompts, raw JSONL traces, stderr, captured responses, per-case latency, usage where supplied, requested model and effort, input/recipe/dataset hashes, and summary metrics by split. Preserve these artifacts with the source commit and CLI version. Do not commit account traces until checked for sensitive paths and account metadata.
36
36
 
@@ -0,0 +1,166 @@
1
+ """Choose the Codex account a live review evaluation runs on.
2
+
3
+ ::
4
+
5
+ CODEX_HOME already set, broker accepts -> environment with CODEX_HOME the home the broker answers
6
+ CODEX_HOME already set, broker refuses -> CodexAccountUnavailable
7
+ broker exit 0, tier normal, home "H" -> environment with CODEX_HOME "H"
8
+ broker exit 3, other tier, any failure -> CodexAccountUnavailable
9
+
10
+ The broker never answers with a free-plan or unknown-plan account, so the home
11
+ it names is the only account a model run may use. A home already set in
12
+ ``CODEX_HOME`` goes through the same broker check, and the run launches on the
13
+ home the broker answers, the trimmed absolute folder it judged.
14
+ """
15
+
16
+ import json
17
+ import os
18
+ import subprocess
19
+ import sys
20
+ from pathlib import Path
21
+
22
+ from review_eval_support.config.constants import (
23
+ ACCOUNT_BROKER_PACKAGE_PARENT_INDEX,
24
+ ACCOUNT_BROKER_TIMEOUT_SECONDS,
25
+ ALL_ACCOUNT_BROKER_ARGUMENTS,
26
+ ALL_ACCOUNT_BROKER_HOME_CHECK_ARGUMENTS,
27
+ ALL_ACCOUNT_BROKER_RELATIVE_PARTS,
28
+ ALL_BROKER_ACCEPTED_EXIT_CODES,
29
+ ALL_NORMAL_ONLY_TIERS,
30
+ ALL_RUN_TIERS,
31
+ BROKER_DECISION_KEY,
32
+ BROKER_EXIT_REASON_TEMPLATE,
33
+ BROKER_HOME_KEY,
34
+ BROKER_MALFORMED_REASON,
35
+ BROKER_MISSING_REASON,
36
+ BROKER_NO_HOME_REASON,
37
+ BROKER_NOT_RUN_REASON,
38
+ BROKER_REASON_KEY,
39
+ BROKER_TIER_KEY,
40
+ BROKER_WAIT_EXIT_CODE,
41
+ CODEX_HOME_VARIABLE,
42
+ NO_ROOM_REASON_TEMPLATE,
43
+ SUITE_ROOT,
44
+ )
45
+
46
+
47
+ class CodexAccountUnavailable(Exception):
48
+ """No Codex account can run the evaluation, so no model call starts."""
49
+
50
+
51
+ def default_broker_candidates() -> tuple[Path, ...]:
52
+ """Return the broker script paths to try, in order.
53
+
54
+ Returns:
55
+ The scripts directory of the package that holds this suite, then its
56
+ ``.claude`` copy.
57
+ """
58
+ package_root = SUITE_ROOT.parents[ACCOUNT_BROKER_PACKAGE_PARENT_INDEX]
59
+ return tuple(
60
+ package_root.joinpath(*each_parts)
61
+ for each_parts in ALL_ACCOUNT_BROKER_RELATIVE_PARTS
62
+ )
63
+
64
+
65
+ def broker_script(all_candidates: tuple[Path, ...]) -> Path:
66
+ """Return the first account broker script that exists.
67
+
68
+ Args:
69
+ all_candidates: Paths to try in order.
70
+
71
+ Returns:
72
+ Path to ``account_broker.py``.
73
+
74
+ Raises:
75
+ CodexAccountUnavailable: No candidate is a file.
76
+ """
77
+ for each_candidate in all_candidates:
78
+ if each_candidate.is_file():
79
+ return each_candidate
80
+ raise CodexAccountUnavailable(BROKER_MISSING_REASON)
81
+
82
+
83
+ def _broker_answer(all_broker_arguments: tuple[str, ...]) -> tuple[int, str]:
84
+ command = [
85
+ sys.executable,
86
+ str(broker_script(default_broker_candidates())),
87
+ *all_broker_arguments,
88
+ ]
89
+ try:
90
+ completed_call = subprocess.run(
91
+ command,
92
+ capture_output=True,
93
+ text=True,
94
+ encoding="utf-8",
95
+ errors="replace",
96
+ timeout=ACCOUNT_BROKER_TIMEOUT_SECONDS,
97
+ check=False,
98
+ )
99
+ except (subprocess.TimeoutExpired, OSError) as error:
100
+ raise CodexAccountUnavailable(BROKER_NOT_RUN_REASON) from error
101
+ return completed_call.returncode, completed_call.stdout
102
+
103
+
104
+ def _decision(answer_text: str) -> dict:
105
+ try:
106
+ answer = json.loads(answer_text)
107
+ except (TypeError, json.JSONDecodeError) as error:
108
+ raise CodexAccountUnavailable(BROKER_MALFORMED_REASON) from error
109
+ decision = answer.get(BROKER_DECISION_KEY) if isinstance(answer, dict) else None
110
+ if not isinstance(decision, dict):
111
+ raise CodexAccountUnavailable(BROKER_MALFORMED_REASON)
112
+ return decision
113
+
114
+
115
+ def _home_from_answer(
116
+ exit_code: int,
117
+ answer_text: str,
118
+ all_accepted_tiers: tuple[str, ...],
119
+ ) -> Path:
120
+ if exit_code not in ALL_BROKER_ACCEPTED_EXIT_CODES:
121
+ raise CodexAccountUnavailable(
122
+ BROKER_EXIT_REASON_TEMPLATE.format(exit_code=exit_code)
123
+ )
124
+ decision = _decision(answer_text)
125
+ if (
126
+ exit_code == BROKER_WAIT_EXIT_CODE
127
+ or decision.get(BROKER_TIER_KEY) not in all_accepted_tiers
128
+ ):
129
+ reason = decision.get(BROKER_REASON_KEY)
130
+ raise CodexAccountUnavailable(
131
+ NO_ROOM_REASON_TEMPLATE.format(
132
+ reason=reason if isinstance(reason, str) else ""
133
+ )
134
+ )
135
+ chosen_home = decision.get(BROKER_HOME_KEY)
136
+ if not isinstance(chosen_home, str) or not chosen_home:
137
+ raise CodexAccountUnavailable(BROKER_NO_HOME_REASON)
138
+ return Path(chosen_home)
139
+
140
+
141
+ def codex_environment() -> dict[str, str]:
142
+ """Return the environment a model run uses, with the broker's Codex home.
143
+
144
+ ::
145
+
146
+ CODEX_HOME " H " -> copy with CODEX_HOME set to the home the broker answers for "H"
147
+ CODEX_HOME unset or blank -> copy with CODEX_HOME set to the broker's home
148
+
149
+ Returns:
150
+ Environment for the ``codex exec`` child process.
151
+
152
+ Raises:
153
+ CodexAccountUnavailable: The broker did not name a Codex home with room.
154
+ """
155
+ exported_home = os.environ.get(CODEX_HOME_VARIABLE, "").strip()
156
+ if exported_home:
157
+ judged_home = _home_from_answer(
158
+ *_broker_answer((*ALL_ACCOUNT_BROKER_HOME_CHECK_ARGUMENTS, exported_home)),
159
+ all_accepted_tiers=ALL_RUN_TIERS,
160
+ )
161
+ return {**os.environ, CODEX_HOME_VARIABLE: str(judged_home)}
162
+ chosen_home = _home_from_answer(
163
+ *_broker_answer(ALL_ACCOUNT_BROKER_ARGUMENTS),
164
+ all_accepted_tiers=ALL_NORMAL_ONLY_TIERS,
165
+ )
166
+ return {**os.environ, CODEX_HOME_VARIABLE: str(chosen_home)}
@@ -45,6 +45,32 @@ ALL_CODEX_ARGUMENTS = (
45
45
  "--sandbox",
46
46
  "read-only",
47
47
  )
48
+ CODEX_HOME_VARIABLE = "CODEX_HOME"
49
+ NO_CODEX_ACCOUNT_FAILURE = "no_codex_account"
50
+ ACCOUNT_BROKER_TIMEOUT_SECONDS = 150
51
+ ACCOUNT_BROKER_PACKAGE_PARENT_INDEX = 4
52
+ ALL_ACCOUNT_BROKER_RELATIVE_PARTS = (
53
+ ("scripts", "account_broker.py"),
54
+ (".claude", "scripts", "account_broker.py"),
55
+ )
56
+ ALL_ACCOUNT_BROKER_ARGUMENTS = ("choose", "--product", "codex", "--require-tier", "normal")
57
+ ALL_ACCOUNT_BROKER_HOME_CHECK_ARGUMENTS = ("choose", "--product", "codex", "--home")
58
+ BROKER_WAIT_EXIT_CODE = 3
59
+ ALL_BROKER_ACCEPTED_EXIT_CODES = (0, BROKER_WAIT_EXIT_CODE)
60
+ BROKER_DECISION_KEY = "decision"
61
+ BROKER_TIER_KEY = "tier"
62
+ BROKER_HOME_KEY = "home"
63
+ BROKER_REASON_KEY = "reason"
64
+ BROKER_NORMAL_TIER = "normal"
65
+ BROKER_LUNA_TIER = "luna"
66
+ ALL_NORMAL_ONLY_TIERS = (BROKER_NORMAL_TIER,)
67
+ ALL_RUN_TIERS = (BROKER_NORMAL_TIER, BROKER_LUNA_TIER)
68
+ BROKER_MISSING_REASON = "account broker script is not installed"
69
+ BROKER_NOT_RUN_REASON = "account broker did not run"
70
+ BROKER_EXIT_REASON_TEMPLATE = "account broker exit {exit_code}"
71
+ BROKER_MALFORMED_REASON = "account broker answer is malformed"
72
+ BROKER_NO_HOME_REASON = "account broker answer names no Codex home"
73
+ NO_ROOM_REASON_TEMPLATE = "no Codex account has room for a review ({reason})"
48
74
  ALL_REPLY_SCHEMA = {
49
75
  "type": "object",
50
76
  "additionalProperties": False,
@@ -6,11 +6,13 @@ import subprocess
6
6
  import time
7
7
  from pathlib import Path
8
8
 
9
+ from review_eval_support.account import CodexAccountUnavailable, codex_environment
9
10
  from review_eval_support.config.constants import (
10
11
  ALL_CODEX_ARGUMENTS,
11
12
  ALL_REPLY_SCHEMA,
12
13
  ERROR_TAIL_LENGTH,
13
14
  LATENCY_DECIMALS,
15
+ NO_CODEX_ACCOUNT_FAILURE,
14
16
  WORKSPACE_SUFFIX,
15
17
  )
16
18
  from review_eval_support.grading import (
@@ -96,6 +98,7 @@ def _score_capture(
96
98
  def _capture(
97
99
  each_case: dict, settings: argparse.Namespace, record_root: Path, recipe: str
98
100
  ) -> dict:
101
+ review_environment = codex_environment()
99
102
  all_command, reply_path = _prepare_command(each_case, settings, record_root)
100
103
  prompt_text = prompt(each_case, recipe)
101
104
  (record_root / f"{each_case['id']}.prompt.txt").write_text(
@@ -110,6 +113,7 @@ def _capture(
110
113
  capture_output=True,
111
114
  timeout=settings.timeout,
112
115
  check=False,
116
+ env=review_environment,
113
117
  )
114
118
  (record_root / f"{each_case['id']}.trace.jsonl").write_text(
115
119
  completed_call.stdout, encoding="utf-8"
@@ -141,6 +145,10 @@ def execute(
141
145
  started = time.monotonic()
142
146
  try:
143
147
  each_attempt.update(_capture(each_case, settings, record_root, recipe))
148
+ except CodexAccountUnavailable as error:
149
+ each_attempt.update(
150
+ status="infra_error", failure=NO_CODEX_ACCOUNT_FAILURE, detail=str(error)
151
+ )
144
152
  except subprocess.TimeoutExpired:
145
153
  each_attempt.update(status="infra_error", failure="timeout")
146
154
  except (ValueError, OSError) as error:
@@ -1,7 +1,9 @@
1
1
  """Check scoring boundaries that could otherwise inflate evaluation results."""
2
2
 
3
+ import argparse
3
4
  import importlib.util
4
5
  import json
6
+ import subprocess
5
7
  from pathlib import Path
6
8
 
7
9
  import pytest
@@ -12,6 +14,15 @@ SPEC = importlib.util.spec_from_file_location(
12
14
  RUN = importlib.util.module_from_spec(SPEC)
13
15
  SPEC.loader.exec_module(RUN)
14
16
  GRADING = __import__("review_eval_support.grading", fromlist=["grading"])
17
+ EXECUTION = __import__("review_eval_support.execution", fromlist=["execution"])
18
+ ACCOUNT = __import__("review_eval_support.account", fromlist=["account"])
19
+
20
+ CODEX_BINARY = "codex-under-test"
21
+ CODEX_HOME_VARIABLE = "CODEX_HOME"
22
+ BROKER_HOME = str(Path("profiles-root") / "codex-1")
23
+ WAIT_REASON = "no account has room; next reset at 2026-11-10T00:00:00Z"
24
+ FREE_PLAN_REASON = "default is on a free plan; the broker never picks it"
25
+ NO_ACCOUNT_FAILURE = "no_codex_account"
15
26
 
16
27
 
17
28
  def finding(line=2, category="falsy-zero"):
@@ -112,3 +123,253 @@ def test_trace_and_saved_response_must_match() -> None:
112
123
  )
113
124
  def test_unsuccessful_evaluation_exits_nonzero(rows) -> None:
114
125
  assert RUN.evaluation_exit_code(rows) == 1
126
+
127
+
128
+ def broker_answer(tier, home, reason="codex-1 has 62% left"):
129
+ return json.dumps(
130
+ {
131
+ "decision": {
132
+ "action": "wait" if tier == "wait" else "run",
133
+ "account": "codex-1",
134
+ "profile": "codex-1",
135
+ "home": home,
136
+ "reason": reason,
137
+ "tier": tier,
138
+ "resets_at": None,
139
+ },
140
+ "accounts": [],
141
+ "state_path": "state.json",
142
+ }
143
+ )
144
+
145
+
146
+ class CallRecorder:
147
+ def __init__(self, broker_exit_code=0, broker_stdout="", broker_error=None):
148
+ self.broker_exit_code = broker_exit_code
149
+ self.broker_stdout = broker_stdout
150
+ self.broker_error = broker_error
151
+ self.all_broker_commands = []
152
+ self.all_codex_calls = []
153
+
154
+ def __call__(self, command, **keywords):
155
+ if command[0] == CODEX_BINARY:
156
+ self.all_codex_calls.append((command, keywords))
157
+ return self._codex_result(command)
158
+ self.all_broker_commands.append(command)
159
+ if self.broker_error:
160
+ raise self.broker_error
161
+ return subprocess.CompletedProcess(
162
+ command, self.broker_exit_code, self.broker_stdout, ""
163
+ )
164
+
165
+ def _codex_result(self, command):
166
+ reply = {"findings": []}
167
+ reply_path = Path(command[command.index("--output-last-message") + 1])
168
+ reply_path.write_text(json.dumps(reply), encoding="utf-8")
169
+ all_events = [
170
+ {"type": "thread.started"},
171
+ {"type": "turn.completed"},
172
+ {"item": {"type": "agent_message", "text": json.dumps(reply)}},
173
+ ]
174
+ stdout = "\n".join(json.dumps(each_event) for each_event in all_events)
175
+ return subprocess.CompletedProcess(command, 0, stdout, "")
176
+
177
+
178
+ @pytest.fixture(autouse=True)
179
+ def no_exported_codex_home(monkeypatch: pytest.MonkeyPatch) -> None:
180
+ monkeypatch.delenv(CODEX_HOME_VARIABLE, raising=False)
181
+
182
+
183
+ def run_live_attempt(recorder, monkeypatch: pytest.MonkeyPatch, record_root) -> dict:
184
+ monkeypatch.setattr(subprocess, "run", recorder)
185
+ settings = argparse.Namespace(
186
+ model="model-under-test", effort="low", codex=CODEX_BINARY, timeout=5
187
+ )
188
+ return EXECUTION.execute(RUN.cases()[0], settings, record_root, "review recipe")
189
+
190
+
191
+ def test_live_attempt_runs_on_the_home_the_broker_names(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
192
+ monkeypatch.setenv("EVAL_MARKER", "kept")
193
+ recorder = CallRecorder(broker_stdout=broker_answer("normal", BROKER_HOME))
194
+
195
+ attempt = run_live_attempt(recorder, monkeypatch, tmp_path)
196
+
197
+ assert attempt["status"] == "scored"
198
+ assert len(recorder.all_codex_calls) == 1
199
+ _, codex_keywords = recorder.all_codex_calls[0]
200
+ assert codex_keywords["env"][CODEX_HOME_VARIABLE] == BROKER_HOME
201
+ assert codex_keywords["env"]["EVAL_MARKER"] == "kept"
202
+ assert recorder.all_broker_commands[0][2:] == ["choose", "--product", "codex", "--require-tier", "normal"]
203
+
204
+
205
+ def test_exported_codex_home_runs_on_the_home_the_broker_answers(
206
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
207
+ ) -> None:
208
+ monkeypatch.setenv(CODEX_HOME_VARIABLE, "exported-home")
209
+ recorder = CallRecorder(broker_stdout=broker_answer("normal", BROKER_HOME))
210
+
211
+ attempt = run_live_attempt(recorder, monkeypatch, tmp_path)
212
+
213
+ assert attempt["status"] == "scored"
214
+ assert [each[2:] for each in recorder.all_broker_commands] == [
215
+ ["choose", "--product", "codex", "--home", "exported-home"]
216
+ ]
217
+ _, codex_keywords = recorder.all_codex_calls[0]
218
+ assert codex_keywords["env"][CODEX_HOME_VARIABLE] == BROKER_HOME
219
+
220
+
221
+ def test_padded_exported_codex_home_runs_on_the_home_the_broker_answers(
222
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
223
+ ) -> None:
224
+ monkeypatch.setenv(CODEX_HOME_VARIABLE, " exported-home ")
225
+ recorder = CallRecorder(broker_stdout=broker_answer("normal", BROKER_HOME))
226
+
227
+ attempt = run_live_attempt(recorder, monkeypatch, tmp_path)
228
+
229
+ assert attempt["status"] == "scored"
230
+ assert [each[2:] for each in recorder.all_broker_commands] == [
231
+ ["choose", "--product", "codex", "--home", "exported-home"]
232
+ ]
233
+ _, codex_keywords = recorder.all_codex_calls[0]
234
+ assert codex_keywords["env"][CODEX_HOME_VARIABLE] == BROKER_HOME
235
+
236
+
237
+ def test_exported_codex_home_on_a_low_room_paid_account_still_runs(
238
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path
239
+ ) -> None:
240
+ monkeypatch.setenv(CODEX_HOME_VARIABLE, "exported-home")
241
+ recorder = CallRecorder(
242
+ broker_stdout=broker_answer("luna", "exported-home", "default has 4% left")
243
+ )
244
+
245
+ attempt = run_live_attempt(recorder, monkeypatch, tmp_path)
246
+
247
+ assert attempt["status"] == "scored"
248
+
249
+
250
+ @pytest.mark.parametrize(
251
+ ("broker_exit_code", "broker_stdout"),
252
+ [
253
+ (3, broker_answer("wait", None, FREE_PLAN_REASON)),
254
+ (2, "cannot read account list"),
255
+ (0, "not json"),
256
+ ],
257
+ )
258
+ def test_exported_codex_home_the_broker_refuses_stops_before_any_model_call(
259
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, broker_exit_code, broker_stdout
260
+ ) -> None:
261
+ monkeypatch.setenv(CODEX_HOME_VARIABLE, "exported-home")
262
+ recorder = CallRecorder(broker_exit_code, broker_stdout)
263
+
264
+ attempt = run_live_attempt(recorder, monkeypatch, tmp_path)
265
+
266
+ assert attempt["status"] == "infra_error"
267
+ assert attempt["failure"] == NO_ACCOUNT_FAILURE
268
+ assert recorder.all_codex_calls == []
269
+ assert list(tmp_path.iterdir()) == []
270
+
271
+
272
+ def test_blank_codex_home_does_not_count_as_a_choice(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
273
+ monkeypatch.setenv(CODEX_HOME_VARIABLE, " ")
274
+ recorder = CallRecorder(broker_stdout=broker_answer("normal", BROKER_HOME))
275
+
276
+ run_live_attempt(recorder, monkeypatch, tmp_path)
277
+
278
+ _, codex_keywords = recorder.all_codex_calls[0]
279
+ assert codex_keywords["env"][CODEX_HOME_VARIABLE] == BROKER_HOME
280
+
281
+
282
+ @pytest.mark.parametrize(
283
+ ("broker_exit_code", "broker_stdout"),
284
+ [
285
+ (3, broker_answer("wait", None, WAIT_REASON)),
286
+ (0, broker_answer("luna", BROKER_HOME, "codex-1 has 4% left")),
287
+ (2, "cannot read account list"),
288
+ (0, ""),
289
+ (0, "not json"),
290
+ (0, "[]"),
291
+ (0, broker_answer("normal", None)),
292
+ (0, broker_answer("normal", "")),
293
+ ],
294
+ )
295
+ def test_unusable_broker_answer_stops_before_any_model_call(
296
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, broker_exit_code, broker_stdout
297
+ ) -> None:
298
+ recorder = CallRecorder(broker_exit_code, broker_stdout)
299
+
300
+ attempt = run_live_attempt(recorder, monkeypatch, tmp_path)
301
+
302
+ assert attempt["status"] == "infra_error"
303
+ assert attempt["failure"] == NO_ACCOUNT_FAILURE
304
+ assert recorder.all_codex_calls == []
305
+ assert list(tmp_path.iterdir()) == []
306
+
307
+
308
+ def test_wait_answer_reports_the_broker_reason(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
309
+ recorder = CallRecorder(3, broker_answer("wait", None, WAIT_REASON))
310
+
311
+ attempt = run_live_attempt(recorder, monkeypatch, tmp_path)
312
+
313
+ assert WAIT_REASON in attempt["detail"]
314
+
315
+
316
+ @pytest.mark.parametrize(
317
+ "broker_error",
318
+ [subprocess.TimeoutExpired("broker", 150), OSError("interpreter missing")],
319
+ )
320
+ def test_broker_that_cannot_run_stops_before_any_model_call(
321
+ monkeypatch: pytest.MonkeyPatch, tmp_path: Path, broker_error
322
+ ) -> None:
323
+ recorder = CallRecorder(broker_error=broker_error)
324
+
325
+ attempt = run_live_attempt(recorder, monkeypatch, tmp_path)
326
+
327
+ assert attempt["status"] == "infra_error"
328
+ assert attempt["failure"] == NO_ACCOUNT_FAILURE
329
+ assert recorder.all_codex_calls == []
330
+
331
+
332
+ GIT_NOT_IGNORED_EXIT_CODE = 1
333
+ GIT_NOT_A_REPOSITORY_EXIT_CODE = 128
334
+
335
+
336
+ def test_every_support_module_can_be_tracked_by_git() -> None:
337
+ support_directory = Path(__file__).with_name("review_eval_support")
338
+ all_modules = sorted(str(each) for each in support_directory.rglob("*.py"))
339
+
340
+ completed = subprocess.run(
341
+ ["git", "check-ignore", "--no-index", "--", *all_modules],
342
+ cwd=support_directory,
343
+ capture_output=True,
344
+ text=True,
345
+ check=False,
346
+ )
347
+
348
+ if completed.returncode == GIT_NOT_A_REPOSITORY_EXIT_CODE:
349
+ pytest.skip("the suite is not inside a git work tree")
350
+ assert completed.returncode == GIT_NOT_IGNORED_EXIT_CODE
351
+
352
+
353
+ def test_broker_script_is_found_beside_the_package() -> None:
354
+ broker_script = ACCOUNT.broker_script(ACCOUNT.default_broker_candidates())
355
+
356
+ assert broker_script.is_file()
357
+ assert broker_script.name == "account_broker.py"
358
+
359
+
360
+ def test_broker_script_prefers_the_first_candidate_that_exists(tmp_path: Path) -> None:
361
+ missing_script = tmp_path / "missing" / "account_broker.py"
362
+ first_script = tmp_path / "first" / "account_broker.py"
363
+ second_script = tmp_path / "second" / "account_broker.py"
364
+ for each_script in (first_script, second_script):
365
+ each_script.parent.mkdir()
366
+ each_script.write_text("", encoding="utf-8")
367
+
368
+ chosen = ACCOUNT.broker_script((missing_script, first_script, second_script))
369
+
370
+ assert chosen == first_script
371
+
372
+
373
+ def test_missing_broker_script_refuses_the_run(tmp_path: Path) -> None:
374
+ with pytest.raises(ACCOUNT.CodexAccountUnavailable):
375
+ ACCOUNT.broker_script((tmp_path / "account_broker.py",))
@@ -14,26 +14,34 @@ A Windows `setx` write only updates the persisted user environment; only a proce
14
14
 
15
15
  `ADVISOR_EFFORT` selects Codex `model_reasoning_effort` for Astra: `low`, `medium`, `high`, `xhigh`, or `max`. The policy default is `medium`, which sends `model_reasoning_effort="medium"`. Astra Xhigh and Max requests route to Medium. Pass `--effort <level>` on the helper to set effort for that Astra run without changing the environment. An unset value uses the policy default. An unknown value blocks advisor routing.
16
16
 
17
- Every fallback reply carries a `fallback_kind` field. `declined` means policy closed the rung (flag off, or the account broker named no Codex account on the `normal` tier). `broken` means the Astra path itself failed (missing executable, spawn error, timeout, malformed reply). A `broken` fallback is a defect to report.
17
+ Every fallback reply carries a `fallback_kind` field. `declined` means policy closed the rung (flag off, the account broker named no Codex account on the `normal` tier, or the broker refused the home pinned in `CODEX_HOME`). `broken` means the Astra path itself failed (missing executable, spawn error, timeout, malformed reply). A `broken` fallback is a defect to report.
18
18
 
19
19
  ## Preflight
20
20
 
21
21
  Flag on: the helper asks the account broker for a Codex account first.
22
22
 
23
23
  ```
24
- python ~/.claude/scripts/account_broker.py choose --product codex
24
+ python ~/.claude/scripts/account_broker.py choose --product codex --require-tier normal
25
25
  ```
26
26
 
27
- **Broker path.** `codex_astra_advisor.resolve_account_broker_path` builds the broker path from the helper's own location: two directories above `_shared/advisor/scripts`, then `scripts/account_broker.py`. Installed, that is `~/.claude/scripts/account_broker.py`. Repo home: `packages/claude-dev-env/scripts/`. The accounts, their order, and sign-in steps are in [`codex-accounts.md`](../../../docs/codex-accounts.md).
27
+ **Broker path.** `codex_astra_advisor.resolve_account_broker_path` builds the broker path from the helper's own location: the directory that holds `_shared` (`parents[2]` of `_shared/advisor/scripts`), then `scripts/account_broker.py`. Installed, that is `~/.claude/scripts/account_broker.py`. Repo home: `packages/claude-dev-env/scripts/`. The accounts, their order, and sign-in steps are in [`codex-accounts.md`](../../../docs/codex-accounts.md).
28
28
 
29
29
  The shared entry point is `~/.claude/_shared/advisor/scripts/codex_astra_advisor.py`. It runs the broker and owns Astra bind or resume parsing. Bind with `python ~/.claude/_shared/advisor/scripts/codex_astra_advisor.py --bind --enable-astra --cwd <repo-root>` and pipe the charter on stdin. Resume with `--resume <session_id>` and pipe the delta consult on stdin.
30
30
 
31
- The gate passes only when the broker exits 0 and answers `decision.tier: normal` with a `decision.home` and finite session or weekly room in the `accounts` entry whose `name` and `home` match. With no roster configured, `accounts` is empty and the gate passes on `decision.home` alone. The helper then runs Codex with `CODEX_HOME` set to `decision.home`. A `luna` or `wait` answer, including exit 3 with a wait answer, declines the preflight when Opus did not bind.
31
+ With no pinned home, the gate passes only when the broker exits 0 and answers `decision.tier: normal` with a `decision.home` and finite session or weekly room in the `accounts` entry whose `name` and `home` match. With no roster configured, `accounts` holds the default Codex home as the account `default`, and the same room check applies to it. The preflight passes `--require-tier normal`. The helper then runs Codex with `CODEX_HOME` set to `decision.home`. A `luna` or `wait` answer, including exit 3 with a wait answer, declines the preflight when Opus did not bind.
32
+
33
+ **Pinned home.** A non-blank `CODEX_HOME` in the helper's environment pins the account, so the preflight asks the broker about that home alone, with no required tier. A blank `CODEX_HOME` counts as unset.
34
+
35
+ ```
36
+ python ~/.claude/scripts/account_broker.py choose --product codex --home <CODEX_HOME>
37
+ ```
38
+
39
+ The gate passes when the broker exits 0 and answers `normal` or `luna` with a `decision.home` and the same room check, whether or not the roster lists the home. A paid plan answers whatever its room, so a home with no room left still binds. The helper then runs Codex on that home. A free plan, a missing, blank, unknown or unlisted plan, an unreadable home, or a `wait` answer declines the preflight with the broker's reason, and no Codex process starts. A broker failure, timeout, or malformed answer is `broken` and also starts no Codex process.
32
40
 
33
41
  ## Branches
34
42
 
35
43
  **Preflight pass.** Bind one Codex CLI session at `gpt-6-astra` with `model_reasoning_effort` set from the policy-selected `ADVISOR_EFFORT` value, `--sandbox read-only`, and JSON output. The helper receives the standing-reviewer charter on stdin and returns only parsed ENDORSE / CORRECTION / PLAN / STOP guidance with a session ID.
36
44
 
37
- **Preflight fail.** A broker failure other than exit 3 with a wait answer, timeout, malformed answer, or a `luna` or `wait` tier fails closed when Opus did not bind.
45
+ **Preflight fail.** A broker failure other than exit 3 with a wait answer, timeout, malformed answer, or a `luna` or `wait` tier fails closed when Opus did not bind. With a pinned home, only a `wait` answer or a tier other than `normal` or `luna` is refused on tier.
38
46
 
39
47
  The helper owns the Astra attempt and returns an explicit fallback result. The consuming advisor path owns the Opus bind. Apply the same gate to every Astra attempt, including resume.
@@ -1,4 +1,14 @@
1
- """Bind and consult a read-only Codex CLI session through Astra."""
1
+ """Bind and consult a read-only Codex CLI session through Astra.
2
+
3
+ Codex runs under the home the account broker approves, so it never runs on a
4
+ free-plan, unknown-plan, unlisted-plan or unreadable account.
5
+
6
+ ::
7
+
8
+ CODEX_HOME exported and paid -> Codex runs on that home, in the roster or not, on normal or luna
9
+ CODEX_HOME exported, refused -> no Codex process starts; the reply is a declined fallback
10
+ CODEX_HOME not exported -> Codex runs on the home the broker chooses on the normal tier
11
+ """
2
12
 
3
13
  from __future__ import annotations
4
14
 
@@ -41,6 +51,7 @@ from advisor_scripts_constants.astra_advisor_constants import (
41
51
  ASTRA_EXECUTABLE_NOT_FOUND_REASON,
42
52
  ASTRA_FALLBACK_KIND_BROKEN,
43
53
  ASTRA_FALLBACK_KIND_DECLINED,
54
+ ASTRA_NO_HOME_REASON,
44
55
  ASTRA_SESSION_ID_METAVAR,
45
56
  CODEX_CONFIG_FLAG,
46
57
  CODEX_EXEC_SUBCOMMAND,
@@ -235,20 +246,23 @@ def build_codex_arguments(
235
246
  return arguments
236
247
 
237
248
 
249
+ def _exported_codex_home(all_settings: Mapping[str, str] | None) -> str | None:
250
+ return _resolved_settings(all_settings).get(CODEX_HOME_ENV_VAR, "").strip() or None
251
+
252
+
238
253
  def _resolve_preflight(
239
254
  preflight: AstraPreflight | None,
240
255
  broker_path: Path | None,
256
+ all_settings: Mapping[str, str] | None,
241
257
  process_runner: Callable[..., subprocess.CompletedProcess[str]],
242
258
  ) -> AstraPreflight:
243
259
  if preflight is not None:
244
260
  return preflight
245
261
  resolved_path = resolve_account_broker_path() if broker_path is None else broker_path
246
- return run_astra_preflight(resolved_path, process_runner)
262
+ return run_astra_preflight(resolved_path, process_runner, _exported_codex_home(all_settings))
247
263
 
248
264
 
249
- def _codex_environment(codex_home: Path | None) -> dict[str, str] | None:
250
- if codex_home is None:
251
- return None
265
+ def _codex_environment(codex_home: Path) -> dict[str, str]:
252
266
  return {**os.environ, CODEX_HOME_ENV_VAR: str(codex_home)}
253
267
 
254
268
 
@@ -258,7 +272,7 @@ def _run_codex(
258
272
  session_id: str | None,
259
273
  all_settings: Mapping[str, str] | None,
260
274
  executable: str,
261
- codex_home: Path | None,
275
+ codex_home: Path,
262
276
  process_runner: Callable[..., subprocess.CompletedProcess[str]],
263
277
  ) -> subprocess.CompletedProcess[str]:
264
278
  model_id, effort = resolve_advisor_pair(all_settings, None)
@@ -291,6 +305,8 @@ def _run_enabled_advisor(
291
305
  ) -> CodexAstraAdvisorReply:
292
306
  if not resolved_preflight.eligible:
293
307
  return build_fallback_reply(resolved_preflight.reason, True, resolved_preflight.fallback_kind)
308
+ if resolved_preflight.codex_home is None:
309
+ return build_fallback_reply(ASTRA_NO_HOME_REASON, True, ASTRA_FALLBACK_KIND_BROKEN)
294
310
  try:
295
311
  completed = _run_codex(
296
312
  prompt,
@@ -338,12 +354,19 @@ def run_codex_astra_advisor(
338
354
  ) -> CodexAstraAdvisorReply:
339
355
  """Bind or resume a read-only Codex Astra advisor.
340
356
 
357
+ A ``CODEX_HOME`` in the settings pins the account. The broker judges that
358
+ home alone, and Codex runs on it whenever its plan is paid, whatever its room,
359
+ on the ``normal`` or ``luna`` tier. A free, unknown, unlisted or unreadable
360
+ home, or a broker that cannot judge it, returns a fallback and starts no
361
+ Codex process. With no ``CODEX_HOME``, the broker chooses the account.
362
+
341
363
  Args:
342
364
  prompt: Advisor prompt text.
343
365
  working_directory: Working directory for Codex.
344
366
  preflight: Account broker result, or None to run the broker.
345
367
  broker_path: Account broker path, or None for the one beside this shared tree.
346
- setting_by_name: Environment mapping, or None to read os.environ.
368
+ setting_by_name: Environment mapping, or None to read os.environ. A non-blank
369
+ ``CODEX_HOME`` in it is the pinned account.
347
370
  session_id: Session to resume, or None for a new bind.
348
371
  process_runner: Callable that runs the broker and Codex.
349
372
 
@@ -355,7 +378,7 @@ def run_codex_astra_advisor(
355
378
  executable = resolve_codex_executable(setting_by_name)
356
379
  if executable is None:
357
380
  return build_fallback_reply(ASTRA_EXECUTABLE_NOT_FOUND_REASON, True)
358
- resolved_preflight = _resolve_preflight(preflight, broker_path, process_runner)
381
+ resolved_preflight = _resolve_preflight(preflight, broker_path, setting_by_name, process_runner)
359
382
  return _run_enabled_advisor(prompt, working_directory, setting_by_name, session_id, executable, resolved_preflight, process_runner)
360
383
 
361
384