claude-dev-env 2.3.0 → 2.4.0

package/scripts/resolve_worker_spawn.py

@@ -50,6 +50,9 @@ from claude_chain_runner import (  # noqa: E402
     ChainInvocationOutcome,
     run_claude,
 )
+from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
+    collect_forwarded_text_codec,
+)
 from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     AGENT_FLAG,
     ALL_AGENT_FILENAMES_BY_ROLE,
@@ -177,7 +180,9 @@ def _run_claude_with_headless_overrides(
 ) -> ChainInvocationOutcome:
     working_directory_path = str(working_directory)
     with _HEADLESS_CHAIN_RUNNER_LOCK:
-        previous_runner = chain_runner.chain_subprocess_runner
+        previous_runner: TextCapturingSubprocessRunner = (
+            chain_runner.chain_subprocess_runner
+        )
 
         def _runner_with_headless_overrides(
             all_invocation_tokens: Sequence[str],
@@ -186,6 +191,7 @@ def _run_claude_with_headless_overrides(
         ) -> subprocess.CompletedProcess[str]:
             del all_positionals
             prompt_stdin.seek(0)
+            forwarded_text_codec = collect_forwarded_text_codec(all_keywords)
             completed_process: subprocess.CompletedProcess[str] = previous_runner(
                 all_invocation_tokens,
                 capture_output=True,
@@ -194,6 +200,7 @@ def _run_claude_with_headless_overrides(
                 check=False,
                 stdin=prompt_stdin,
                 cwd=working_directory_path,
+                **forwarded_text_codec,
             )
             return completed_process
 

package/scripts/test_invoke_code_review.py

@@ -1,4 +1,4 @@
-"""Behavioral tests for the host-aware ``/code-review`` invoker."""
+"""Behavioral tests for the host-aware ``/code-review`` invoker and stamps."""
 
 from __future__ import annotations
 
@@ -28,7 +28,7 @@ from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
 from dev_env_scripts_constants.code_review_constants import (  # noqa: E402
     CLI_SESSION_MODEL_FLAG,
     CODE_REVIEW_MODEL_ALIAS,
-    CODE_REVIEW_PROMPT,
+    DEFAULT_CODE_REVIEW_EFFORT,
     GIT_BINARY,
     GIT_PORCELAIN_FLAG,
     GIT_STATUS_SUBCOMMAND,
@@ -296,7 +296,7 @@ def test_chain_argv_assembly(
 
     assert call_log.claude_arguments == [
         SINGLE_TURN_FLAG,
-        CODE_REVIEW_PROMPT,
+        invoker.build_code_review_prompt(DEFAULT_CODE_REVIEW_EFFORT),
         MODEL_FLAG,
         CODE_REVIEW_MODEL_ALIAS,
         OUTPUT_FORMAT_FLAG,
@@ -412,7 +412,7 @@ def test_build_code_review_arguments_matches_contract() -> None:
     all_arguments = invoker.build_code_review_arguments()
     assert all_arguments == [
         SINGLE_TURN_FLAG,
-        CODE_REVIEW_PROMPT,
+        invoker.build_code_review_prompt(DEFAULT_CODE_REVIEW_EFFORT),
         MODEL_FLAG,
         CODE_REVIEW_MODEL_ALIAS,
         OUTPUT_FORMAT_FLAG,
@@ -670,3 +670,297 @@ def test_encode_code_review_outcome_shape() -> None:
         RESULT_KEY_RETURNCODE: FIXTURE_CHAIN_RETURNCODE,
         RESULT_KEY_DIRTY_TREE: True,
     }
+
+
+EFFORT_LOW = "low"
+REJECTED_ULTRA_EFFORT = "ultra"
+RECORD_STAMP_MINT_CAP = 3
+SINGLE_PASS_CAP = 1
+INVALID_EFFORT_EXIT_CODE = 2
+DID_NOT_CONVERGE_EXIT_CODE = 1
+RECORD_STAMP_CLI_FLAG = "--record-stamp"
+RESULT_STAMP_MINTED_KEY = "stamp_minted"
+RESULT_PASS_COUNT_KEY = "pass_count"
+RESULT_BOUND_HASH_KEY = "bound_hash"
+MISSING_STORE_FILE_NAME = "code_review_stamp_store_absent.py"
+SURFACE_SOURCE = "def add(left: int, right: int) -> int:\n    return left + right\n"
+SURFACE_CHANGE_SOURCE = "def add(left: int, right: int) -> int:\n    return left - right\n"
+
+
+def _run_git(repository_directory: Path, *git_arguments: str) -> None:
+    subprocess.run(
+        [GIT_BINARY, "-C", str(repository_directory), *git_arguments],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=GIT_INIT_TIMEOUT_SECONDS,
+    )
+
+
+def _make_repo_with_change_surface(tmp_path: Path) -> Path:
+    origin_directory = tmp_path / "origin.git"
+    work_directory = tmp_path / "work"
+    work_directory.mkdir()
+    subprocess.run(
+        [GIT_BINARY, "init", "--bare", "--initial-branch=main", str(origin_directory)],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=GIT_INIT_TIMEOUT_SECONDS,
+    )
+    _run_git(work_directory, "init", "--initial-branch=main")
+    _run_git(work_directory, "config", "user.email", "tests@example.com")
+    _run_git(work_directory, "config", "user.name", "Reviewer")
+    (work_directory / "app.py").write_text(SURFACE_SOURCE, encoding="utf-8")
+    _run_git(work_directory, "add", "-A")
+    _run_git(work_directory, "commit", "-m", "base")
+    _run_git(work_directory, "remote", "add", "origin", str(origin_directory))
+    _run_git(work_directory, "push", "-u", "origin", "main")
+    (work_directory / "app.py").write_text(SURFACE_CHANGE_SOURCE, encoding="utf-8")
+    return work_directory
+
+
+def _isolate_home(monkeypatch: pytest.MonkeyPatch, fake_home: Path) -> None:
+    home_text = str(fake_home)
+    monkeypatch.setenv("HOME", home_text)
+    monkeypatch.setenv("USERPROFILE", home_text)
+    monkeypatch.delenv("HOMEDRIVE", raising=False)
+    monkeypatch.delenv("HOMEPATH", raising=False)
+
+
+def _prepared_surface_repo(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    return _make_repo_with_change_surface(tmp_path)
+
+
+def _chain_clean_outcome() -> invoker.CodeReviewOutcome:
+    return invoker.CodeReviewOutcome(
+        mode=MODE_CHAIN,
+        served_command=FIXTURE_SERVED_COMMAND,
+        returncode=FIXTURE_CHAIN_RETURNCODE,
+        is_dirty_tree=True,
+    )
+
+
+def _stable_clean_review(**_review_keywords: object) -> invoker.CodeReviewOutcome:
+    return _chain_clean_outcome()
+
+
+def _surface_changing_review(
+    *, working_directory: Path, **_review_keywords: object
+) -> invoker.CodeReviewOutcome:
+    applied_fix_path = working_directory / DIRTY_FILE_NAME
+    applied_fix_path.write_text(DIRTY_FILE_CONTENTS, encoding="utf-8")
+    return _chain_clean_outcome()
+
+
+class _DriftingReview:
+    def __init__(self) -> None:
+        self.pass_count = 0
+
+    def __call__(
+        self, *, working_directory: Path, **_review_keywords: object
+    ) -> invoker.CodeReviewOutcome:
+        self.pass_count += 1
+        drift_path = working_directory / f"fix_{self.pass_count}.txt"
+        drift_path.write_text(str(self.pass_count), encoding="utf-8")
+        return _chain_clean_outcome()
+
+
+@pytest.mark.parametrize("valid_effort", ["low", "medium", "high", "xhigh", "max"])
+def test_validate_effort_token_accepts_known_tokens(valid_effort: str) -> None:
+    assert invoker.validate_effort_token(valid_effort) is None
+
+
+def test_validate_effort_token_rejects_ultra_loudly() -> None:
+    error_message = invoker.validate_effort_token(REJECTED_ULTRA_EFFORT)
+    assert error_message is not None
+    assert REJECTED_ULTRA_EFFORT in error_message
+
+
+def test_validate_effort_token_rejects_unknown_token() -> None:
+    error_message = invoker.validate_effort_token("bogus")
+    assert error_message is not None
+    assert "bogus" in error_message
+
+
+def test_build_code_review_prompt_reads_as_slash_command() -> None:
+    assert invoker.build_code_review_prompt(EFFORT_LOW) == "/code-review low --fix"
+    assert invoker.build_code_review_prompt("xhigh") == "/code-review xhigh --fix"
+
+
+def test_cli_rejects_ultra_effort_with_nonzero_exit(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    working_directory = _init_git_repository(tmp_path / "repo")
+    _install_seams(
+        monkeypatch,
+        host_profile=HOST_PROFILE_CLAUDE,
+        claude_outcome=None,
+        working_directory=working_directory,
+    )
+    exit_code = invoker.main(
+        [
+            CWD_FLAG,
+            str(working_directory),
+            CLI_SESSION_MODEL_FLAG,
+            FIXTURE_SESSION_OPUS,
+            REJECTED_ULTRA_EFFORT,
+        ]
+    )
+    assert exit_code == INVALID_EFFORT_EXIT_CODE
+    assert REJECTED_ULTRA_EFFORT in capsys.readouterr().err
+
+
+def test_record_stamp_mints_on_surface_stable_clean_pass(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = _prepared_surface_repo(monkeypatch, tmp_path)
+    monkeypatch.setattr(invoker, "invoke_code_review", _stable_clean_review)
+    mint_outcome = invoker.invoke_code_review_and_record_stamp(
+        working_directory=working_directory,
+        session_model=CODE_REVIEW_MODEL_ALIAS,
+        timeout_seconds=DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
+        effort=EFFORT_LOW,
+    )
+    assert mint_outcome.is_stamp_minted is True
+    assert mint_outcome.bound_hash is not None
+    store_module = invoker.load_code_review_stamp_store()
+    assert store_module.stamp_covers_surface(
+        str(working_directory), mint_outcome.bound_hash, EFFORT_LOW
+    )
+
+
+def test_record_stamp_does_not_mint_when_review_changes_surface(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = _prepared_surface_repo(monkeypatch, tmp_path)
+    monkeypatch.setattr(invoker, "invoke_code_review", _surface_changing_review)
+    mint_outcome = invoker.invoke_code_review_and_record_stamp(
+        working_directory=working_directory,
+        session_model=CODE_REVIEW_MODEL_ALIAS,
+        timeout_seconds=DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
+        effort=EFFORT_LOW,
+        maximum_passes=SINGLE_PASS_CAP,
+    )
+    assert mint_outcome.is_stamp_minted is False
+    assert mint_outcome.pass_count == SINGLE_PASS_CAP
+    assert mint_outcome.bound_hash is None
+
+
+def test_record_stamp_hits_cap_without_minting(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = _prepared_surface_repo(monkeypatch, tmp_path)
+    monkeypatch.setattr(invoker, "invoke_code_review", _DriftingReview())
+    mint_outcome = invoker.invoke_code_review_and_record_stamp(
+        working_directory=working_directory,
+        session_model=CODE_REVIEW_MODEL_ALIAS,
+        timeout_seconds=DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
+        effort=EFFORT_LOW,
+        maximum_passes=RECORD_STAMP_MINT_CAP,
+    )
+    assert mint_outcome.is_stamp_minted is False
+    assert mint_outcome.pass_count == RECORD_STAMP_MINT_CAP
+
+
+def test_cli_record_stamp_returns_non_convergence_code_on_cap(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    working_directory = _prepared_surface_repo(monkeypatch, tmp_path)
+    monkeypatch.setattr(invoker, "invoke_code_review", _DriftingReview())
+    exit_code = invoker.main(
+        [
+            CWD_FLAG,
+            str(working_directory),
+            CLI_SESSION_MODEL_FLAG,
+            CODE_REVIEW_MODEL_ALIAS,
+            RECORD_STAMP_CLI_FLAG,
+            EFFORT_LOW,
+        ]
+    )
+    assert exit_code == DID_NOT_CONVERGE_EXIT_CODE
+    parsed_payload = json.loads(capsys.readouterr().out)
+    assert parsed_payload[RESULT_STAMP_MINTED_KEY] is False
+    assert parsed_payload[RESULT_PASS_COUNT_KEY] == RECORD_STAMP_MINT_CAP
+    assert parsed_payload[RESULT_BOUND_HASH_KEY] is None
+
+
+def test_load_code_review_stamp_store_records_and_covers_surface(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    working_directory = _prepared_surface_repo(monkeypatch, tmp_path)
+    store_module = invoker.load_code_review_stamp_store()
+    surface_hash = store_module.live_surface_hash(str(working_directory))
+    assert surface_hash is not None
+    stamp_path = store_module.record_clean_stamp(
+        str(working_directory), surface_hash, EFFORT_LOW
+    )
+    assert stamp_path.exists()
+    assert store_module.stamp_covers_surface(
+        str(working_directory), surface_hash, EFFORT_LOW
+    )
+
+
+def test_load_code_review_stamp_store_raises_when_file_absent(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        invoker, "STAMP_STORE_MODULE_FILE_NAME", MISSING_STORE_FILE_NAME
+    )
+    with pytest.raises(ModuleNotFoundError):
+        invoker.load_code_review_stamp_store()
+
+
+def test_cli_record_stamp_reports_missing_store_dependency(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    working_directory = _init_git_repository(tmp_path / "repo")
+
+    def raise_missing_store(*all_args: object, **all_keywords: object) -> object:
+        del all_args, all_keywords
+        raise ModuleNotFoundError("store missing", name="code_review_stamp_store")
+
+    monkeypatch.setattr(invoker, "load_code_review_stamp_store", raise_missing_store)
+    exit_code = invoker.main(
+        [
+            CWD_FLAG,
+            str(working_directory),
+            CLI_SESSION_MODEL_FLAG,
+            CODE_REVIEW_MODEL_ALIAS,
+            RECORD_STAMP_CLI_FLAG,
+            EFFORT_LOW,
+        ]
+    )
+    assert exit_code == INVALID_EFFORT_EXIT_CODE
+    captured = capsys.readouterr()
+    assert "stamp store" in captured.err
+    parsed_payload = json.loads(captured.out)
+    assert parsed_payload[RESULT_STAMP_MINTED_KEY] is False
+
+
+def test_encode_stamp_mint_outcome_includes_mint_metadata() -> None:
+    review_outcome = invoker.CodeReviewOutcome(
+        mode=MODE_CHAIN,
+        served_command=FIXTURE_SERVED_COMMAND,
+        returncode=FIXTURE_CHAIN_RETURNCODE,
+        is_dirty_tree=False,
+    )
+    mint_outcome = invoker.StampMintOutcome(
+        review_outcome=review_outcome,
+        is_stamp_minted=True,
+        pass_count=SINGLE_PASS_CAP,
+        bound_hash="abc123",
+    )
+    encoded_payload = invoker.encode_stamp_mint_outcome(mint_outcome)
+    assert encoded_payload[RESULT_STAMP_MINTED_KEY] is True
+    assert encoded_payload[RESULT_PASS_COUNT_KEY] == SINGLE_PASS_CAP
+    assert encoded_payload[RESULT_BOUND_HASH_KEY] == "abc123"

package/scripts/test_invoke_code_review_codec.py

@@ -0,0 +1,77 @@
+"""Behavioral tests for text codec keyword forwarding in the ``/code-review`` invoker."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import invoke_code_review as invoker
+import pytest
+from codec_forwarding_test_support import (
+    FIXTURE_CHAIN_ENCODING,
+    FIXTURE_CHAIN_ERRORS,
+    FIXTURE_ENCODING_KEYWORD_NAME,
+    FIXTURE_ERRORS_KEYWORD_NAME,
+    install_codec_seams,
+)
+from dev_env_scripts_constants.timing import DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS
+
+FIXTURE_CHAIN_STDOUT = '{"result":"review done"}'
+
+
+def _install_invoker_codec_seams(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    all_chain_codec_keywords: dict[str, str],
+) -> dict[str, object]:
+    return install_codec_seams(
+        monkeypatch,
+        all_chain_codec_keywords=all_chain_codec_keywords,
+        chain_stdout=FIXTURE_CHAIN_STDOUT,
+        runner_host=invoker,
+        runner_attribute_name="review_claude_runner",
+    )
+
+
+def test_forwards_text_codec_keywords_to_subprocess_runner(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    all_observed_runner_keywords = _install_invoker_codec_seams(
+        monkeypatch,
+        all_chain_codec_keywords={
+            FIXTURE_ENCODING_KEYWORD_NAME: FIXTURE_CHAIN_ENCODING,
+            FIXTURE_ERRORS_KEYWORD_NAME: FIXTURE_CHAIN_ERRORS,
+        },
+    )
+
+    invoker._run_claude_with_empty_stdin(
+        [],
+        timeout_seconds=DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
+        working_directory=tmp_path,
+    )
+
+    assert (
+        all_observed_runner_keywords[FIXTURE_ENCODING_KEYWORD_NAME]
+        == FIXTURE_CHAIN_ENCODING
+    )
+    assert (
+        all_observed_runner_keywords[FIXTURE_ERRORS_KEYWORD_NAME]
+        == FIXTURE_CHAIN_ERRORS
+    )
+
+
+def test_absent_text_codec_keywords_are_not_invented(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    all_observed_runner_keywords = _install_invoker_codec_seams(
+        monkeypatch,
+        all_chain_codec_keywords={},
+    )
+
+    invoker._run_claude_with_empty_stdin(
+        [],
+        timeout_seconds=DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS,
+        working_directory=tmp_path,
+    )
+
+    assert FIXTURE_ENCODING_KEYWORD_NAME not in all_observed_runner_keywords
+    assert FIXTURE_ERRORS_KEYWORD_NAME not in all_observed_runner_keywords

package/scripts/test_resolve_worker_spawn_codec.py

@@ -0,0 +1,101 @@
+"""Behavioral tests for text codec keyword forwarding in worker-spawn headless overrides."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import resolve_worker_spawn as dispatcher
+from codec_forwarding_test_support import (
+    FIXTURE_CHAIN_ENCODING,
+    FIXTURE_CHAIN_ERRORS,
+    FIXTURE_ENCODING_KEYWORD_NAME,
+    FIXTURE_ERRORS_KEYWORD_NAME,
+    install_codec_seams,
+)
+from dev_env_scripts_constants.grok_worker_constants import (
+    DEFAULT_WORKER_TIMEOUT_SECONDS,
+    UTF8_ENCODING,
+)
+
+FIXTURE_CHAIN_STDOUT = '{"tier":"claude","status":"done"}'
+FIXTURE_PROMPT_TEXT = "do the work"
+
+
+def _install_dispatcher_codec_seams(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    all_chain_codec_keywords: dict[str, str],
+) -> dict[str, object]:
+    return install_codec_seams(
+        monkeypatch,
+        all_chain_codec_keywords=all_chain_codec_keywords,
+        chain_stdout=FIXTURE_CHAIN_STDOUT,
+        runner_host=dispatcher,
+        runner_attribute_name="spawn_claude_runner",
+    )
+
+
+def _run_headless_with_prompt(
+    *,
+    prompt_file: Path,
+    working_directory: Path,
+    timeout_seconds: int = DEFAULT_WORKER_TIMEOUT_SECONDS,
+) -> None:
+    prompt_stdin = prompt_file.open(encoding=UTF8_ENCODING)
+    try:
+        dispatcher._run_claude_with_headless_overrides(
+            [],
+            timeout_seconds=timeout_seconds,
+            working_directory=working_directory,
+            prompt_stdin=prompt_stdin,
+        )
+    finally:
+        prompt_stdin.close()
+
+
+def test_forwards_text_codec_keywords_to_subprocess_runner(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    prompt_file = tmp_path / "prompt.txt"
+    prompt_file.write_text(FIXTURE_PROMPT_TEXT, encoding=UTF8_ENCODING)
+    all_observed_runner_keywords = _install_dispatcher_codec_seams(
+        monkeypatch,
+        all_chain_codec_keywords={
+            FIXTURE_ENCODING_KEYWORD_NAME: FIXTURE_CHAIN_ENCODING,
+            FIXTURE_ERRORS_KEYWORD_NAME: FIXTURE_CHAIN_ERRORS,
+        },
+    )
+
+    _run_headless_with_prompt(
+        prompt_file=prompt_file,
+        working_directory=tmp_path,
+    )
+
+    assert (
+        all_observed_runner_keywords[FIXTURE_ENCODING_KEYWORD_NAME]
+        == FIXTURE_CHAIN_ENCODING
+    )
+    assert (
+        all_observed_runner_keywords[FIXTURE_ERRORS_KEYWORD_NAME]
+        == FIXTURE_CHAIN_ERRORS
+    )
+
+
+def test_absent_text_codec_keywords_are_not_invented(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    prompt_file = tmp_path / "prompt.txt"
+    prompt_file.write_text(FIXTURE_PROMPT_TEXT, encoding=UTF8_ENCODING)
+    all_observed_runner_keywords = _install_dispatcher_codec_seams(
+        monkeypatch,
+        all_chain_codec_keywords={},
+    )
+
+    _run_headless_with_prompt(
+        prompt_file=prompt_file,
+        working_directory=tmp_path,
+    )
+
+    assert FIXTURE_ENCODING_KEYWORD_NAME not in all_observed_runner_keywords
+    assert FIXTURE_ERRORS_KEYWORD_NAME not in all_observed_runner_keywords

package/skills/autoconverge/SKILL.md

@@ -161,13 +161,18 @@ orchestrating session's own steps, and the script's agent-prompt text carries
 ```
 Workflow({
   scriptPath: "<this skill dir>/workflow/converge.mjs",
-  args: { owner: "<O>", repo: "<R>", prNumber: <N>, bugbotDisabled: false, copilotDisabled: false }
+  args: { owner: "<O>", repo: "<R>", prNumber: <N>, bugbotDisabled: false, copilotDisabled: false, homeDirectory: "<HOME>" }
 })
 ```
 
 `scriptPath` is the absolute path to `workflow/converge.mjs` inside this skill's
 own directory (on this install,
-`<home>/.claude/skills/autoconverge/workflow/converge.mjs`). Set
+`<home>/.claude/skills/autoconverge/workflow/converge.mjs`). `homeDirectory` is
+the absolute path to the directory that holds `.claude` (resolve it once from
+`$HOME`, or `$env:USERPROFILE` on Windows, with forward slashes). The workflow
+runs in a sandbox with no access to environment variables, so the run reads the
+home directory from this arg to build the path to the codex-review scripts the
+Codex gate calls; leave it out and the Codex gate cannot find those scripts. Set
 `bugbotDisabled: true` only when the user has opted Cursor Bugbot out for the
 run; otherwise the workflow detects an opt-out or an unreachable Bugbot on its
 own. Set `copilotDisabled: true` when the step 5 quota pre-check exits non-zero,
@@ -189,7 +194,7 @@ Write it again when the result lands, so the handoff carries the final run id an
 names the teardown phase the fresh session picks up from.
 
 The workflow returns
-`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, cleanAuditNote, reuseNote, deferredPrs }`,
+`{ converged, rounds, finalSha, blocker, standardsNote, copilotNote, codexNote, cleanAuditNote, reuseNote, deferredPrs }`,
 plus a `userReview` field on a `blocker: "user-review"` return. `cleanAuditNote` is
 non-null when the environment refused the CLEAN bugteam review post and the run
 recorded the bypass — see
@@ -359,6 +364,7 @@ ready again — then run the checkpoints.
    Blocker: <blocker>        # only when blocked
    Standards: <standardsNote> # only when a round deferred code-standard findings
    Copilot: <copilotNote>     # only when Copilot was down or out of quota
+   Codex: <codexNote>         # only when the Codex gate was bypassed (codex_down or opt-out)
    Clean-audit: <cleanAuditNote> # only when the CLEAN bugteam post was bypassed
    Reuse: <reuseNote>         # only when the reuse pass identified an improvement
    ```

package/skills/autoconverge/reference/convergence.md

@@ -135,7 +135,8 @@ any bot threads with a deferral note, and reports the deferral in
   the weekly usage probe via `is_codex_review_required` (shared threshold
   constant — no inline percent), and the wrapper's `codex_down` class.
 - Opt-out token or `codex_down` → set `codexDown`, no stamp, move to the
-  convergence check with `--codex-down`.
+  convergence check with `--codex-down`. A `codex_down` classification also
+  records a `codexNote` so the skip stays visible in the final report.
 - Usage at/below threshold or null → skip with no stamp; the machine checklist
   applies the same rule.
 - Above threshold → run the codex-review wrapper against the PR base branch.

package/skills/autoconverge/reference/multi-pr.md

@@ -72,6 +72,7 @@ Workflow({
   scriptPath: "<this skill dir>/workflow/converge_multi.mjs",
   args: {
     convergeScriptPath: "<this skill dir>/workflow/converge.mjs",
+    homeDirectory: "<HOME>",
     prs: [
       { owner: "<O>", repo: "<R>", prNumber: <N1>, repoPath: "<abs worktree 1>", bugbotDisabled: false, copilotDisabled: false },
       { owner: "<O>", repo: "<R>", prNumber: <N2>, repoPath: "<abs worktree 2>", bugbotDisabled: false, copilotDisabled: false }
@@ -82,7 +83,11 @@ Workflow({
 
 `convergeScriptPath` is the absolute path to `workflow/converge.mjs` in this same
 skill directory; each `repoPath` is the absolute path of the worktree that PR is
-checked out in. The workflow runs in the background and notifies the session on
+checked out in. `homeDirectory` is the absolute path to the directory that holds
+`.claude` (resolve it once from `$HOME`, or `$env:USERPROFILE` on Windows, with
+forward slashes); the fan-out forwards it to every child run, which needs it to
+build the codex-review scripts path because the workflow sandbox has no access to
+environment variables. The workflow runs in the background and notifies the session on
 completion; watch live progress with `/workflows`, where each PR's child run
 appears under its own group.
 

package/skills/autoconverge/reference/stop-conditions.md

@@ -88,16 +88,22 @@ Each reviewer-down condition below skips its own convergence-check gate. The fla
   `--copilot-down` (the Copilot review gate and the pending-requested-reviews
   gate bypassed), then mark-ready. `copilotNote` records the bypass for the
   final report.
-- **Terminal Codex gate skipped or down** — the conditional-required Codex gate
-  runs after Bugbot and Copilot. When `CLAUDE_REVIEWS_DISABLED` lists `codex`
-  (`reviews_disabled.py --reviewer codex` exit 0), the gate sets `codexDown` and
-  advances with no review. When the weekly usage probe reports `percent_left`
-  null or at/below the shared threshold (`is_codex_review_required` false), the
-  gate skips without a stamp; the convergence check applies the same rule. When
-  the wrapper classifies `codex_down`, the gate sets `codexDown` and advances.
-  A clean required run stamps `codexCleanAt` for `--codex-clean-at`. Non-code-standard
-  findings re-enter CONVERGE through the existing fix path. Standards-only findings
-  defer a follow-up, stamp `codexCleanAt`, and advance to FINALIZE (no fix push).
+- **Terminal Codex gate skipped (opt-out, usage, or `codex_down`)** — the
+  conditional-required Codex gate runs after Bugbot and Copilot. When
+  `CLAUDE_REVIEWS_DISABLED` lists `codex` (`reviews_disabled.py --reviewer codex`
+  exit 0), the gate sets `codexDown` and advances with no review. When the weekly
+  usage probe reports `percent_left` null or at/below the shared threshold
+  (`is_codex_review_required` false), the gate skips without a stamp; the
+  convergence check applies the same rule. When the codex-review wrapper
+  classifies `codex_down` — a Codex CLI error, or a review that ran past its
+  `CONFIG.codexReviewTimeoutSeconds` budget — the gate skips the same way: it sets
+  `codexDown`, records a `codexNote` so the skip stays visible in the final
+  report, clears `codexCleanAt`, and advances to `FINALIZE` (mark-ready with the
+  gate bypassed) so a Codex outage does not block convergence; Codex runs again on
+  the next convergence. A clean required run stamps `codexCleanAt` for
+  `--codex-clean-at`. Non-code-standard findings re-enter `CONVERGE` through the
+  existing fix path. Standards-only findings defer a follow-up, stamp
+  `codexCleanAt`, and advance to `FINALIZE` (no fix push).
 - **A lens agent dies** — when one parallel reading lens returns null (a terminal
   agent failure), the round proceeds on the surviving lenses. A real defect it
   would have caught surfaces in a later round or at the convergence check. A dead

package/skills/autoconverge/workflow/converge.clean-audit.test.mjs

@@ -655,7 +655,7 @@ test('the workflow declares cleanAuditNote and assembles it into every result vi
   assert.match(convergeSource, /let cleanAuditNote = null/);
   assert.match(
     convergeSource,
-    /const assembleResult = \(outcomeFields\) => \(\{\n\s*\.\.\.outcomeFields,\n\s*standardsNote,\n\s*copilotNote,\n\s*cleanAuditNote,\n\s*reuseNote,\n\s*deferredPrs,\n\s*\}\)/,
+    /const assembleResult = \(outcomeFields\) => \(\{\n\s*\.\.\.outcomeFields,\n\s*standardsNote,\n\s*copilotNote,\n\s*codexNote,\n\s*cleanAuditNote,\n\s*reuseNote,\n\s*deferredPrs,\n\s*\}\)/,
   );
   const assembleCalls = convergeSource.match(/return assembleResult\(/g) || [];
   assert.ok(